FLflowable
Agent Instances

Start an agent instance

post/agent-runtime/agent-instances

Request

Request body

agentDefinitionIdstring

The id of the definition for starting the agent instance

agentDefinitionKeystring

The key of the definition for starting the agent instance

tenantIdstring

The tenant id of the definition for starting the agent instance

operationKeystring

The operation key to execute from the agent

overrideDefinitionTenantIdstring

The tenant id that should be used for the agent instance

Example request

{
  "payload": [
    {
      "name": "myVariable",
      "type": "string",
      "valueUrl": "http://...."
    }
  ]
}

Response

Indicates the agent instance was started.

idstring required

The unique identifier of an agent instance

agentDefinitionIdstring required

The id of the agent definition that was used to start the agent instance.

agentDefinitionKeystring required

The key of the agent definition that was used to start the agent instance.

agentDefinitionNamestring required

The name of the agent definition that was used to start the agent instance.

referenceIdstring

The id of the CMMN or BPMN model backing the agent instance behavior.

referenceTypestring

The type of the model that backs the agent instance behavior (e.g. CMMN or BPMN).

callbackIdstring

The id of the CMMN or BPMN instance that should be called back when the agent is done.

callbackTypestring

The type of the callback (e.g. CMMN or BPMN).

callbackScopeIdstring

The callback scope id for this agent instance.

startTimeinteger required

The time the instance was started.

startUserIdstring

The user that started the agent instance.

tenantIdstring

The tenant id of the instance

plainTextInvocationResultstring
durationMsinteger

Wall-clock duration of the invocation in milliseconds.

promptTokenCountinteger

Aggregated prompt tokens used by the invocation.

outputTokenCountinteger

Aggregated output tokens produced by the invocation.

Example response

{
  "executionTrace": {
    "id": "agent-instance-1",
    "definitionId": "agent-definition-1",
    "definitionName": "Customer Support Agent",
    "definitionKey": "customerSupportAgent",
    "invocations": [
      {
        "id": "invoc-1",
        "operationKey": "processUserRequest",
        "promptTokenCount": 150,
        "outputTokenCount": 75,
        "exchanges": [
          {
            "id": "exchange-1",
            "type": "user",
            "subType": "gpt-4.1-2025-04-14",
            "userId": "admin",
            "promptTokenCount": 50,
            "outputTokenCount": 25,
            "parts": [
              {
                "id": "part-1",
                "type": "input",
                "subType": "request",
                "content": "What is the weather today?",
                "invocationSequence": 1
              }
            ]
          }
        ]
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.