Execute Agent

Executes the specified agent and returns a non-streaming JSON response with the complete agent output. The agent must be in active status and belong to the specified location. locationId is required in the request body.

Session Management:

• For the first message in a new session, do not include the executionId in the request payload.
• The API will return an executionId along with the agent response, which uniquely identifies this conversation session.
• To continue the conversation within the same session, include the executionId from the previous response in subsequent requests. This allows the agent to maintain conversation context and history across multiple interactions.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:agent-studio.write

Auth methods:OAuthPrivate Integration

Token type:Sub-Account Token

Request​

Headers

Versionstringrequired

API Version

Available optionsv3

Example:v3

Path Parameters

agentIdstringrequired

Agent ID to execute (must be in active status and belong to the location)

Example:p1q2r3s4t5u6v7w8x9y0z1a2

Query Parameters

sourcestring

Origin channel attributed to this execution for auditing (e.g. public_api, internal)

Example:api

Body

application/json

messagestringrequired

Message to send to the agent

Example:How can you help me with my marketing?

executionIdstring

Unique session identifier that maintains conversational context across multiple interactions within the same agent session. Omit this field for the first message in a new session. Include the executionId returned from the previous response to maintain context in subsequent messages.

Example:a1b2c3d4e5f6g7h8i9j0k1l2

inputVariablesobject

Input variables to pass to the agent. These should match the input variables defined in the agent configuration.

versionIdstring

Published version ID to execute. If not provided, the latest published production version will be used.

Example:b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d

attachmentsobject[]

Attachments for the message

Show child attributes

locationIdstringrequired

Location ID

Example:C2QujeCh8ZnC7al2InWR

contactIdstring

Contact ID to associate with this execution. When provided, contact data will be hydrated and made available to the agent.

Example:cid_abc123def456

Response

200

application/json

Agent executed successfully

successbooleanrequired

Success status

Example:true

executionIdstringrequired

Unique session identifier that maintains conversational context across multiple interactions within the same agent session. Use this ID in subsequent requests to continue the conversation.

Example:a1b2c3d4e5f6g7h8i9j0k1l2

interactionIdstringrequired

Unique identifier for a single interaction cycle, consisting of one user input and the corresponding agent response. Each message exchange generates a new interactionId.

Example:m9n8o7p6q5r4s3t2u1v0w9x8

responsestringrequired

Agent response text

Example:I can help you with various tasks...

typestringrequired

Response type

Example:text

nextExpectedInputstringrequired

Expected input type for next interaction

Example:text

goalCompletionbooleanrequired

When end node is added in the graph, this will be true if the agent reached the end node in the graph

Example:false

executionStatusstringrequired

Execution status

Example:completed

flowSwitchbooleanrequired

Whether flow was switched

Example:false

attachmentsarrayrequired

Response attachments

Example:[]

generativeOutputsarrayrequired

Generated outputs

Example:[]