Agents

Stream agent execution in real-time

Stream an existing agent execution in real-time via SSE, providing live message chunks, tool calls, and status updates until completion.

post/v2/agents/{key}/stream-task

Path parameters

keystring required

The key or ID 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.

stream_timeout_secondsnumber

Stream timeout in seconds (1-3600). Default: 1800 (30 minutes)

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

Server-Sent Event stream successfully established. Returns real-time events including agent messages, tool calls, status updates, and completion signals. The stream ends with a [DONE] sentinel value.

Changes

Changed in 12 of the 256 revisions of this API.1419

Jul 20, 2026736c0b011bfb2See the full diff
- ○
  the timeout response's property default value 120 was removed for the status 200
  response-property-default-value-removed
- ○
  the timeout response's property default value 120 was removed for the status 200
  response-property-default-value-removed
Jul 17, 20262f27caf6888c3See the full diff
- ○
  added the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/chat_exposed to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/tools/items/configuration to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property data/oneOf[subschema #6: Action Review Requested Event]/data/tool/configuration to the response with the 200 status
  response-optional-property-added
This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 16, 2026bee257c5b2483See the full diff
- ●
  removed the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/chat_exposed from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/tools/items/configuration from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/oneOf[subschema #6: Action Review Requested Event]/data/tool/configuration from the response with the 200 status
  response-optional-property-removed
This revision also has 49 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 16, 2026801f61a5a0563See the full diff
- ○
  added the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/chat_exposed to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/tools/items/configuration to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property data/oneOf[subschema #6: Action Review Requested Event]/data/tool/configuration to the response with the 200 status
  response-optional-property-added
This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 16, 202642d5d20625273See the full diff
- ●
  removed the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/chat_exposed from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/tools/items/configuration from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/oneOf[subschema #6: Action Review Requested Event]/data/tool/configuration from the response with the 200 status
  response-optional-property-removed
This revision also has 49 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 10, 20268ecb8a66eb1d3See the full diff
- ○
  added the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/chat_exposed to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/tools/items/configuration to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property data/oneOf[subschema #6: Action Review Requested Event]/data/tool/configuration to the response with the 200 status
  response-optional-property-added
This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 10, 20265f95063ab4fd3See the full diff
- ●
  removed the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/chat_exposed from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/tools/items/configuration from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/oneOf[subschema #6: Action Review Requested Event]/data/tool/configuration from the response with the 200 status
  response-optional-property-removed
This revision also has 43 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 7, 2026320d42e024f23See the full diff
- ○
  added the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/chat_exposed to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/tools/items/configuration to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property data/oneOf[subschema #6: Action Review Requested Event]/data/tool/configuration to the response with the 200 status
  response-optional-property-added
This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 7, 2026ca19e06a2b613See the full diff
- ●
  removed the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/chat_exposed from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/tools/items/configuration from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/oneOf[subschema #6: Action Review Requested Event]/data/tool/configuration from the response with the 200 status
  response-optional-property-removed
This revision also has 38 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 7, 2026a15e7903ecca3See the full diff
- ○
  added the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/chat_exposed to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property data/oneOf[subschema #2: Agent Started Event]/data/settings/tools/items/configuration to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property data/oneOf[subschema #6: Action Review Requested Event]/data/tool/configuration to the response with the 200 status
  response-optional-property-added
This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 256 revisions, 71 have no diff computed.

Full history (12 revisions)