Examples with grpcurl

In the following, we assume

• a running solution accessible via the the cloud end point (started via Flowstate or VM Pool)
• Ready-to-use grpcurl
• inctl auth login has been completed
• jq is installed on the system

First, from the SDK directory, build the required transitively closed protobuf descriptor file set of the executive service:

bazel build //intrinsic/executive/proto:executive_service_proto_descriptor_set

For simplicity, we create an alias for calling gRPC services via grpcurl.

# Change the following according to your project.
PROJECT=intrinsic-prod-us
# Change the following according to your organization.
ORGANIZATION=intrinsic@${PROJECT}
TOKEN="$(inctl auth print-api-key --org ${ORGANIZATION})"
# Extract the following from the portal URL to access the frontend, after the project name.
VM="vmp-3f30-abcdefg"

alias grpcurl-executive="grpcurl -H 'x-server-name:${VM}' -H 'authorization:Bearer ${TOKEN}' -protoset 'bazel-bin/intrinsic/executive/proto/executive_service_proto_descriptor_set_transitive_set_sci.proto.bin' -d @ 'www.endpoints.${PROJECT}.cloud.goog:443'"

Create operation

The following calls CreateOperation to load a new behavior tree.

grpcurl-executive intrinsic_proto.executive.ExecutiveService/CreateOperation <<EOM
{
  "behavior_tree": {
    "name": "My BT",
    "root": {
      "task": {
        "call_behavior": {
          "skill_id": "ai.intrinsic.sleep_for"
        }
      }
    }
  }
}
EOM

The behavior tree in the request is the most relevant part to change.

info

In this JSON input we leave the parameters empty. In general, this will not be the case. However, this will require to have a transitively closed protobuf file descriptor set (an extended version of the one the alias contains) that contains all skills' parameter message types (to be able to parse the JSON) into a suitable binary representation.

{
 "name": "07657e5d443d6bf507657e5d443d66d6",
 "metadata": {
   "@type": "type.googleapis.com/intrinsic_proto.executive.RunMetadata",
   "behaviorTree": {
     "name": "My BT",
     "root": {
       "task": {
         "state": "ACCEPTED",
         "callBehavior": {
           "skillId": "ai.intrinsic.sleep_for"
         }
       },
       "state": "ACCEPTED",
       "id": 537724197
     },
     "state": "ACCEPTED",
     "blackboardScope": "PROCESS_TREE",
     "treeId": "MyBT-07657e5d443d61b707657e5d443d6c98"
   },
   "behaviorTreeState": "ACCEPTED",
   "logContext": {
     "executiveSessionId": "14529320044448798879"
   },
   "worldId": "world"
 }
}

The most relevant part is the name. This operation name will be used for other service calls. The metadata will be a RunMetadata proto. See the section on RunMetadata below for details.

List operations

To list operations, use the following call.

grpcurl-executive intrinsic_proto.executive.ExecutiveService/ListOperations <<< ""

The response contains a list of all current operations.

Get operation

To retrieve specifics for an operation known by name, you can use the following call.

grpcurl-executive intrinsic_proto.executive.ExecutiveService/GetOperation <<EOM
{
  "name": "07657e5d443d6bf507657e5d443d66d6"
}
EOM

Start operation

An operation that is in ACCEPTED state (after CreateOperation) can be started with the following call.

grpcurl-executive intrinsic_proto.executive.ExecutiveService/StartOperation <<EOM
{
  "name": "07657e5d443d6bf507657e5d443d66d6"
}
EOM

Optional parameters are execution mode (whether to run normally or step-wise) and from which node in the tree to start (for selective execution).

Assume we create the following tree for selective step-wise execution:

grpcurl-executive intrinsic_proto.executive.ExecutiveService/CreateOperation <<EOM
{
  "behavior_tree": {
    "name": "My BT",
    "tree_id": "my_tree_id_7e6e12",
    "root": {
      "sequence": {
        "children": [
          {
            "id": 1,
            "task": {
              "call_behavior": {
                "skill_id": "ai.intrinsic.sleep_for"
              }
            }
          },
          {
            "id": 2,
            "sub_tree": {
              "tree": {
                "root": {
                  "sequence": {
                    "children": [
                      {
                        "id": 21,
                        "task": {
                          "call_behavior": {
                            "skill_id": "ai.intrinsic.sleep_for"
                          }
                        }
                      },
                      {
                        "id": 22,
                        "task": {
                          "call_behavior": {
                            "skill_id": "ai.intrinsic.sleep_for"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}
EOM

Then you could start from the second node (which is given the explicit id 2) for step-wise execution (it would automatically suspend after executing the node with id 21).

grpcurl-executive intrinsic_proto.executive.ExecutiveService/StartOperation <<EOM
{
  "name": "07657e5d443d6bf507657e5d443d66d6",
  "start_tree_id": "my_tree_id_7e6e12",
  "start_node_id": 2,
  "execution_mode": "EXECUTION_MODE_STEP_WISE"
}
EOM

Suspend operation

The following call suspends a RUNNING tree.

grpcurl-executive intrinsic_proto.executive.ExecutiveService/SuspendOperation <<EOM
{
  "name": "07657e5d443d6bf507657e5d443d66d6"
}
EOM

Resume operation

The following call resumes a SUSPENDED tree.

grpcurl-executive intrinsic_proto.executive.ExecutiveService/ResumeOperation <<EOM
{
  "name": "07657e5d443d6bf507657e5d443d66d6"
}
EOM

Cancel operation

The following call cancels a tree (which can be, e.g., RUNNING or SUSPENDING). Note that misbehaving skills not reacting to a cancellation request can delay or even prevent cancellation of a BT.

grpcurl-executive intrinsic_proto.executive.ExecutiveService/CancelOperation <<EOM
{
  "name": "07657e5d443d6bf507657e5d443d66d6"
}
EOM

Delete operation

An operation in a resting state (ACCEPTED, SUSPENDED, CANCELED, SUCCEEDED, FAILED) can be deleted.

grpcurl-executive intrinsic_proto.executive.ExecutiveService/DeleteOperation <<EOM
{
  "name": "07657e5d443d6bf507657e5d443d66d6"
}
EOM

RunMetadata

The RunMetadata is available from the metadata field of an executive operation. It contains details about the execution and is updated continuously while the operation runs.

Examples of information available from RunMetadata:

• the executing/executed behavior tree with current node states
• current state of the behavior tree (e.g. succeeded, running)
• execution mode (e.g. normal, stepwise)
• start time of the execution
• total execution time

We can query the RunMetadata by retrieving the operation through ListOperations or GetOperation (see above). This can be done while the operation runs or after it has completed.

To provide an example, we can fetch the current execution time of an operation by using grpcurl-executive defined above and filtering the result with jq.

grpcurl-executive intrinsic_proto.executive.ExecutiveService/GetOperation <<EOM | jq .metadata.executionTime
{
  "name": "07657e5d443d6bf507657e5d443d66d6"
}
EOM

This will return the (current) value of the execution time metadata:

"12.151440476s"