--- title: "Start an agent instance" method: POST path: "/agent-runtime/agent-instances" tags: ["Agent Instances"] --- # Start an agent instance `POST /agent-runtime/agent-instances` ## Request - Base URL: `http://localhost:8090/agent-api` - URL: `http://localhost:8090/agent-api/agent-runtime/agent-instances` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Request body - AgentInstanceCreateRequest - `agentDefinitionId` string: The id of the definition for starting the agent instance - `agentDefinitionKey` string: The key of the definition for starting the agent instance - `tenantId` string: The tenant id of the definition for starting the agent instance - `operationKey` string: The operation key to execute from the agent - `overrideDefinitionTenantId` string: The tenant id that should be used for the agent instance - `payload` EngineRestVariable[]: Payload variables passed to the agent when starting a new instance - `name` string: Name of the variable - `type` string: Type of the variable. - `value` object: Value of the variable. - `valueUrl` string ## Response `201` Indicates the agent instance was started. - AgentInstanceResponse: The response for an agent instance - `id` string, required: The unique identifier of an agent instance - `agentDefinitionId` string, required: The id of the agent definition that was used to start the agent instance. - `agentDefinitionKey` string, required: The key of the agent definition that was used to start the agent instance. - `agentDefinitionName` string, required: The name of the agent definition that was used to start the agent instance. - `referenceId` string: The id of the CMMN or BPMN model backing the agent instance behavior. - `referenceType` string: The type of the model that backs the agent instance behavior (e.g. CMMN or BPMN). - `callbackId` string: The id of the CMMN or BPMN instance that should be called back when the agent is done. - `callbackType` string: The type of the callback (e.g. CMMN or BPMN). - `callbackScopeId` string: The callback scope id for this agent instance. - `startTime` integer, required: The time the instance was started. - `startUserId` string: The user that started the agent instance. - `tenantId` string: The tenant id of the instance - `jsonInvocationResult` JsonNode - `string` boolean - `valueNode` boolean - `missingNode` boolean - `short` boolean - `double` boolean - `bigDecimal` boolean - `bigInteger` boolean - `textual` boolean - `boolean` boolean - `container` boolean - `object` boolean - `binary` boolean - `number` boolean - `nodeType` 'ARRAY' | 'BINARY' | 'BOOLEAN' | 'MISSING' | 'NULL' | 'NUMBER' | 'OBJECT' | 'POJO' | 'STRING' - `long` boolean - `pojo` boolean - `int` boolean - `integralNumber` boolean - `floatingPointNumber` boolean - `array` boolean - `empty` boolean - boolean - `float` boolean - `embeddedValue` boolean - `plainTextInvocationResult` string - `durationMs` integer: Wall-clock duration of the invocation in milliseconds. - `promptTokenCount` integer: Aggregated prompt tokens used by the invocation. - `outputTokenCount` integer: Aggregated output tokens produced by the invocation. - `executionTrace` AgentInstanceTimelineResponse: Complete timeline view of an agent instance with all its invocations, exchanges and parts - `id` string, required: The unique identifier of the agent instance - `definitionId` string, required: The ID of the agent definition that was used to start this instance - `definitionName` string: The name of the agent definition - `definitionKey` string: The key of the agent definition - `invocations` AgentInvocationTimelineResponse[]: List of all invocations that occurred within this agent instance - `id` string, required: The unique identifier of the invocation - `startTime` integer: The time when the invocation started - `endTime` integer: The time when the invocation ended - `operationKey` string: The key of the operation that was invoked - `promptTokenCount` integer: The number of prompt tokens consumed during this invocation - `outputTokenCount` integer: The number of output tokens generated during this invocation - `exchanges` AgentExchangeTimelineResponse[]: List of all exchanges that occurred during this invocation - `id` string, required: The unique identifier of the exchange - `startTime` integer: The time when the exchange started - `endTime` integer: The time when the exchange ended - `duration` Duration - `seconds` integer - `zero` boolean - `nano` integer - `negative` boolean - `positive` boolean - `units` TemporalUnit[] - `durationEstimated` boolean - `duration` Duration (recursive) - `timeBased` boolean - `dateBased` boolean - `type` 'user' | 'assistant' | 'tool' | 'chatModel', required: The type of the exchange - `subType` string, required: The sub-type providing additional context based on the type (e.g., tool name, model name) - `userId` string: The ID of the user who initiated the exchange - `promptTokenCount` integer: The number of prompt tokens consumed during this exchange - `outputTokenCount` integer: The number of output tokens generated during this exchange - `transactionOrder` integer: The sequence number of this exchange within the invocation - `parts` AgentExchangePartTimelineResponse[]: List of all parts that make up this exchange - `id` string, required: The unique identifier of the exchange part - `type` 'input' | 'output' | 'toolInput' | 'toolOutput', required: The type of the part - `subType` 'request' | 'response' | 'technical' | 'system' | 'toolCall' | 'arguments': The sub-type providing additional context based on the type - `content` string: The content of the part, which can be a string or JSON object depending on the type - `invocationSequence` integer: The sequence number of this part within the invocation ## Other responses - `400`: Indicates the agent instance could not be started due to some invalid arguments. - `404`: Indicates the agent-definition was not found. --- [API](https://skmtc.dev/flowable/apis/flowable-agent-engine-rest-api.md) - [All operations](https://skmtc.dev/flowable/apis/flowable-agent-engine-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/flowable/apis/flowable-agent-engine-rest-api/revisions/54fc1189496f?raw)