Execute Agent (Deprecated)

POST 
/agent-studio/public-api/agents/:agentId/execute

deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

Deprecated endpoint - use POST /agent/:agentId/execute instead.

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.

Request

Version stringrequired

API Version

Available optionsv3

agentId stringrequired

source string

application/json

application/json

Body

Bodyrequired

messagestringrequired

Message to send to the agent

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.

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.

attachmentsobject[]

Attachments for the message

locationIdstringrequired

Location ID

contactIdstring

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

Example (auto)

{
  "message": "How can you help me with my marketing?",
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "inputVariables": {
    "customerName": "John Doe",
    "orderNumber": "ORD-12345"
  },
  "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "attachments": [
    {
      "type": "image",
      "imageUrl": "https://example.com/image.png"
    }
  ],
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "contactId": "cid_abc123def456"
}

application/json

Agent executed successfully

application/json

Schema

Schema

successbooleanrequired

Success status

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.

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.

responsestringrequired

Agent response text

typestringrequired

Response type

nextExpectedInputstringrequired

Expected input type for next interaction

goalCompletionbooleanrequired

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

executionStatusstringrequired

Execution status

flowSwitchbooleanrequired

Whether flow was switched

attachmentsarrayrequired

Response attachments

generativeOutputsarrayrequired

Generated outputs

Example (auto)

{
  "success": true,
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "interactionId": "m9n8o7p6q5r4s3t2u1v0w9x8",
  "response": "I can help you with various tasks...",
  "type": "text",
  "nextExpectedInput": "text",
  "goalCompletion": false,
  "executionStatus": "completed",
  "flowSwitch": false,
  "attachments": [],
  "generativeOutputs": []
}