Skip to main content
POST
/
api
/
v1
/
agent
/
{id}
/
chat
Run Agent
curl --request POST \
  --url https://api.example.com/api/v1/agent/{id}/chat
Runs the agent with the given input and returns a Server-Sent Events stream when stream is true. All requests require Authorization: Bearer <token>.

​
Path Parameters

ParameterTypeDescription
idstringThe agent’s unique identifier

​
Request Body

{
  "message": "Summarize our Q4 sales data",
  "conversation_id": "conv_abc123",
  "message_id": "msg_abc123",
  "stream": true,
  "verbose": true
}
FieldTypeRequiredDescription
messagestringyesThe user’s input
conversation_idstringyesConversation ID for multi-turn context
message_idstringyesStable unique ID for this user message
streamboolnoReturn SSE events when true; default is true
verboseboolnoInclude nested tool/sub-agent events
Generate message_id once per user action and reuse it when retrying that same submit after a timeout or reconnect. Do not generate a new message ID for every network retry. Advanced request fields accepted by the backend include attachment_ids, knowledge_bases, retrieval_options, skills, artifacts, context_refs, prompt_blocks, memory_policy, model, temperature, max_tokens, top_p, frequency_penalty, presence_penalty, max_turns, reasoning_effort, reasoning_summary, image_detail, enable_planning, enable_reflection, enable_query_rewrite, selected_tools, client_timezone, session_context, source, source_id, source_metadata, and call_id. knowledge_bases performs request-scoped KB search before the model call and injects matching snippets as hidden system_context. Model-callable retrieval is handled through the normal tool system when a retrieval tool is registered or assigned to the agent. memory_policy controls prompt-time memory injection for this run: 
{
  "memory_policy": {
    "archival_mode": "tool_only",
    "archival_limit": 10,
    "archival_min_score": null,
    "include_user_core": true,
    "include_agent_core": true
  }
}
archival_mode defaults to tool_only, which keeps archival memory out of the prompt unless the agent recalls it. Set it to auto to inject bounded archival matches for the current message as hidden current-turn system_reminders. Core user and agent memory are included by default and can be disabled with include_user_core / include_agent_core. call_id is a client correlation value stored with the conversation run. The server still generates the canonical runtime call_id / root_call_id used for streaming and cancellation. prompt_blocks supplies request-time model-only context: 
{
  "prompt_blocks": [
    {
      "name": "selected_account",
      "message": "user",
      "type": "static",
      "mode": "real_time",
      "scope": "turn",
      "tags": ["selection", "context"],
      "body": "Acme Corp, ARR $120k, renewal in 31 days"
    }
  ]
}
Inline blocks are wrapped and persisted with the hidden model input for this turn. They are not shown as the user-visible message in normal chat timelines.

​
Response (SSE Stream)

id: 0
data: {"type": "start", "call_id": "call_1", "parent_call_id": null, "root_call_id": "call_1", "content": {"name": "my-assistant", "role": "agent", "input": "Summarize our Q4 sales data"}, "metadata": {"display_name": "my-assistant", "content_type": "markdown"}, "seq": 0, "timestamp": "2026-04-28T14:30:00Z"}

id: 1
data: {"type": "delta", "call_id": "call_1", "parent_call_id": null, "root_call_id": "call_1", "content": "Based on the Q4 data", "metadata": {"content_type": "markdown"}, "seq": 1, "timestamp": "2026-04-28T14:30:01Z"}

id: 2
data: {"type": "delta", "call_id": "call_1", "parent_call_id": null, "root_call_id": "call_1", "content": ", total revenue was...", "metadata": {"content_type": "markdown"}, "seq": 2, "timestamp": "2026-04-28T14:30:01Z"}

id: 3
data: {"type": "artifact_completed", "call_id": "call_1", "parent_call_id": null, "root_call_id": "call_1", "content": {"artifact_type": "draft_email", "artifact_id": "art_abc123", "status": "complete", "stream_status": "complete", "has_renderable_payload": true, "renderable_unit_count": 1, "renderable_unit_type": "field", "conversation_id": "conv_abc123"}, "metadata": {"content_type": "json", "source_type": "artifact"}, "seq": 3, "timestamp": "2026-04-28T14:30:01Z"}

id: 4
data: {"type": "end", "call_id": "call_1", "parent_call_id": null, "root_call_id": "call_1", "content": {"result": "Based on the Q4 data, total revenue was...", "duration": 1.23, "success": true}, "metadata": {"content_type": "markdown"}, "seq": 4, "timestamp": "2026-04-28T14:30:02Z"}
Text is streamed through delta events, and the final response arrives in the root end event. There is no content event type. Tools and artifacts may also stream live delta events with exact content types: tool_progress, tool_result_delta, artifact_progress, and artifact_result_delta. Progress describes what is happening; result deltas are partial output that may be replaced by the final result. Do not use UI hints such as show_in_panel as stream classifiers. Artifacts stream as structured lifecycle events (artifact_started, artifact_progress, artifact_completed, artifact_error). Do not parse inline artifact markers from text deltas; fetch the persisted artifact by artifact_id. seq is the JSON payload ordering field. AgentFlow also emits SSE id: lines when an event has event_id, sse_id, or seq; persist the latest SSE id for reconnect hints and recover UI state from the durable conversation snapshot stream.

​
Error Events

If an error occurs during execution, an error event is streamed: 
data: {"type": "error", "call_id": "call_1", "parent_call_id": null, "root_call_id": "call_1", "content": {"error_message": "Tool execution timed out", "error_type": "TimeoutError"}, "metadata": {"content_type": "json"}, "seq": 2, "timestamp": "2026-04-28T14:30:02Z"}