Sign in
OpenAPI 3.1.0raw.githubusercontent.com2026-08-202766453.1 MB

2cd7e7f7bcb4

Agents

Create response

Create an agent response for a given message. Return the complete conversation including messages, tool interactions, and token usage.

post/v2/agents/{agent_key}/responses

Path parameters

agent_keystring required

The unique key of identifier of the agent to invoke

The unique key of identifier of the agent to invoke

Request body

task_idstring

Optional task ID to continue an existing agent execution. When provided, the agent will continue the conversation from the existing task state. The task must be in an inactive state to continue.

variablesobject

Optional variables for template replacement in system prompt, instructions, and messages

metadataobject

Optional metadata for the agent invocation as key-value pairs that will be included in traces

engine'text' | 'jinja' | 'mustache'

Override template engine for this invocation. If not provided, uses the agent default.

backgroundboolean

If true, returns immediately without waiting for completion. If false (default), waits until the agent becomes inactive or errors.

streamboolean

If true, returns Server-Sent Events (SSE) streaming response with real-time events. If false (default), returns standard JSON response.

Example request

{
  "identity": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "metadata": [
      {
        "department": "Engineering",
        "role": "Senior Developer"
      }
    ],
    "logo_url": "https://example.com/avatars/jane-doe.jpg",
    "tags": [
      "hr",
      "engineering"
    ]
  },
  "contact": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "metadata": [
      {
        "department": "Engineering",
        "role": "Senior Developer"
      }
    ],
    "logo_url": "https://example.com/avatars/jane-doe.jpg",
    "tags": [
      "hr",
      "engineering"
    ]
  },
  "thread": {
    "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "tags": [
      "customer-support",
      "priority-high"
    ]
  }
}

Response

Agent response successfully created and completed. Returns the full conversation including all messages, tool interactions, model used, and token usage statistics. In background mode, returns immediately with initial task details. In streaming mode, returns Server-Sent Events (SSE) with real-time events.

_idstring required

The unique response ID

task_idstring required

The agent execution task ID

created_atstring required

ISO timestamp of response creation

modelstring required

Model used in provider/model format

finish_reason'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call' | 'max_iterations' | 'max_time'

The reason why the agent stopped generating