Skip to main content
POST
/
v2
/
agents
/
stream-run
{
  "key": "simple-agent-1",
  "role": "Assistant",
  "description": "A helpful assistant for general tasks",
  "instructions": "Be helpful and concise",
  "settings": {
    "max_iterations": 3,
    "max_execution_time": 300,
    "tool_approval_required": "none",
    "tools": [
      {
        "requires_approval": false,
        "display_name": "current_date",
        "type": "current_date"
      }
    ]
  },
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "What's today's date and day of the week?"
      }
    ]
  },
  "model": "openai/gpt-4o",
  "path": "Default/agents",
  "memory_stores": [],
  "team_of_agents": []
}

data: {"type":"agents.execution_started","data":{"agent_task_id":"01K631TNQZ9VWENJV91YS1JQXC","agent_manifest_id":"01K62T62KVJHRE0P9PX4VN2JHD","agent_key":"simple-agent-1","workspace_id":"cbd7b74a-4f2f-43b6-b3f9-19353c40dd62"},"timestamp":"2025-09-26T13:01:33.860Z"}

data: {"type":"event.agents.started","data":{"inputMessage":{"role":"user","parts":[{"kind":"text","text":"What's today's date and day of the week?"}],"metadata":{}},"modelId":"0707a18f-e3a0-44b6-9f24-4d5d28e0cdea","instructions":"Be helpful and concise","system_prompt":"You are an AI agent with access to tools to help complete user tasks...","settings":{"max_iterations":3,"max_execution_time":300,"tool_approval_required":"none","tools":[{"id":"01JKG6QJ5FGHCWA7RVMMZB82QY","action_type":"current_date","display_name":"Current Date & Time","requires_approval":false}]},"agent_manifest_id":"01K62T62KVJHRE0P9PX4VN2JHD","agent_key":"simple-agent-1"},"timestamp":"2025-09-26T13:01:33.863Z"}

data: {"type":"event.agents.thought","data":{"agent_id":"01K62T62KVJHRE0P9PX4VN2JHD","message_difference":{"2":{"messageId":"01K631TRNHF7XQ9HN7R9YX5GQR","role":"agent","parts":[{"kind":"tool_call","tool_name":"current_date","tool_call_id":"toolu_01USVfbcLCA5TawuUNRNiaqS","arguments":{"timezone":"UTC"}}],"metadata":{}}},"choice":{"finish_reason":"tool_calls","index":0,"message":{"content":null,"tool_calls":[{"id":"toolu_01USVfbcLCA5TawuUNRNiaqS","type":"function","function":{"name":"current_date","arguments":"{\"timezone\":\"UTC\"}"}}],"role":"assistant"}},"choiceIndex":2,"iteration":1,"accumulated_execution_time":0},"timestamp":"2025-09-26T13:01:36.817Z"}

data: {"type":"event.agents.execution_named","data":{"name":"Getting current date and providing information","agent_manifest_id":"01K62T62KVJHRE0P9PX4VN2JHD"},"timestamp":"2025-09-26T13:01:36.816Z"}

data: {"type":"event.agents.action_review_requested","data":{"agent_id":"01K62T62KVJHRE0P9PX4VN2JHD","action_id":"01K631TTTF9JAE0GKZXYWGSTTZ","requires_approval":false,"tool":{"id":"01JKG6QJ5FGHCWA7RVMMZB82QY","action_type":"current_date","display_name":"Current Date & Time","requires_approval":false},"input":{"timezone":"UTC"},"agent_tool_call_id":"toolu_01USVfbcLCA5TawuUNRNiaqS"},"timestamp":"2025-09-26T13:01:39.023Z"}

data: {"type":"event.workflow_events.tool_execution_started","data":{"tool_id":"01JKG6QJ5FGHCWA7RVMMZB82QY","tool_key":"current_date","tool_display_name":"Current Date & Time","action_type":"current_date","tool_arguments":{"timezone":"UTC"},"tool_execution_context":{"action_id":"01K631TTTF9JAE0GKZXYWGSTTZ","agent_tool_call_id":"toolu_01USVfbcLCA5TawuUNRNiaqS","workspace_id":"cbd7b74a-4f2f-43b6-b3f9-19353c40dd62","agent_manifest_id":"01K62T62KVJHRE0P9PX4VN2JHD","agent_execution_id":"01K631TNQZ9VWENJV91YS1JQXC","product":"agents"}},"timestamp":"2025-09-26T13:01:39.029Z"}

data: {"type":"event.workflow_events.tool_execution_finished","data":{"result":{"currentDate":"2025-09-26T13:01:39.030Z"},"tool_execution_context":{"action_id":"01K631TTTF9JAE0GKZXYWGSTTZ","agent_tool_call_id":"toolu_01USVfbcLCA5TawuUNRNiaqS","workspace_id":"cbd7b74a-4f2f-43b6-b3f9-19353c40dd62","agent_manifest_id":"01K62T62KVJHRE0P9PX4VN2JHD","agent_execution_id":"01K631TNQZ9VWENJV91YS1JQXC","product":"agents"}},"timestamp":"2025-09-26T13:01:39.030Z"}

data: {"type":"event.agents.thought","data":{"agent_id":"01K62T62KVJHRE0P9PX4VN2JHD","message_difference":{"3":{"messageId":"01K631TZWQ834RCWD0D1QN455P","role":"tool","parts":[{"kind":"tool_result","tool_call_id":"toolu_01USVfbcLCA5TawuUNRNiaqS","result":{"currentDate":"2025-09-26T13:01:39.030Z"}}],"metadata":{}},"4":{"messageId":"01K631TZWQ93QY494FSGCTPG69","role":"agent","parts":[{"kind":"text","text":"Today is Thursday, September 26th, 2025. The current date and time is 2025-09-26T13:01:39.030Z (UTC)."}],"metadata":{}}},"choice":{"finish_reason":"stop","index":0,"message":{"content":"Today is Thursday, September 26th, 2025. The current date and time is 2025-09-26T13:01:39.030Z (UTC).","role":"assistant"}},"choiceIndex":4,"iteration":2,"accumulated_execution_time":5053.7},"timestamp":"2025-09-26T13:01:44.215Z"}

data: {"type":"event.agents.inactive","data":{"last_message":"Today is Thursday, September 26th, 2025. The current date and time is 2025-09-26T13:01:39.030Z (UTC).","finish_reason":"stop"},"timestamp":"2025-09-26T13:01:44.216Z"}

data: [DONE]
The Agents APIs are currently in beta and subject to change. Please report any feedback you might have to the team.

​
SSE Event Types

The stream-run endpoint returns Server-Sent Events (SSE) with the following event types. Each event contains a type, data object, and timestamp.
SSE Event Types
// Agent Lifecycle Events
{
  "type": "agents.execution_started",
  "data": {
    "agent_task_id": "01K631TNQZ9VWENJV91YS1JQXC",
    "agent_manifest_id": "01K62T62KVJHRE0P9PX4VN2JHD",
    "agent_key": "my-agent",
    "workspace_id": "cbd7b74a-4f2f-43b6-b3f9-19353c40dd62"
  },
  "timestamp": "2025-09-26T13:01:33.860Z"
}

{
  "type": "event.agents.started",
  "data": {
    "inputMessage": {
      "role": "user",
      "parts": [{
        "kind": "text",
        "text": "Hello, how can you help me?"
      }],
      "metadata": {}
    },
    "modelId": "0707a18f-e3a0-44b6-9f24-4d5d28e0cdea",
    "instructions": "Be helpful and provide accurate information",
    "system_prompt": "You are an AI assistant...",
    "settings": {
      "max_iterations": 5,
      "max_execution_time": 300,
      "tool_approval_required": "none",
      "tools": []
    },
    "agent_manifest_id": "01K62T62KVJHRE0P9PX4VN2JHD",
    "agent_key": "my-agent"
  },
  "timestamp": "2025-09-26T13:01:33.863Z"
}

{
  "type": "event.agents.thought",
  "data": {
    "agent_id": "01K62T62KVJHRE0P9PX4VN2JHD",
    "message_difference": {
      "2": {
        "messageId": "01K631TRNHF7XQ9HN7R9YX5GQR",
        "role": "agent",
        "parts": [{
          "kind": "text",
          "text": "I can help you with various tasks..."
        }],
        "metadata": {},
        "agent_id": "01K62T62KVJHRE0P9PX4VN2JHD",
        "agent_execution_id": "01K631TNQZ9VWENJV91YS1JQXC",
        "workspace_id": "cbd7b74a-4f2f-43b6-b3f9-19353c40dd62",
        "index": 2
      }
    },
    "choice": {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "I can help you with various tasks...",
        "role": "assistant"
      }
    },
    "choiceIndex": 2,
    "iteration": 1,
    "accumulated_execution_time": 1250.5
  },
  "timestamp": "2025-09-26T13:01:36.817Z"
}

{
  "type": "event.agents.inactive",
  "data": {
    "last_message": "I can help you with various tasks including...",
    "finish_reason": "stop"
  },
  "timestamp": "2025-09-26T13:01:44.216Z"
}

{
  "type": "event.agents.errored",
  "data": {
    "error": "Model request failed",
    "code": 500
  },
  "timestamp": "2025-09-26T13:01:44.216Z"
}

// Tool Execution Events
{
  "type": "event.agents.action_review_requested",
  "data": {
    "agent_id": "01K62T62KVJHRE0P9PX4VN2JHD",
    "action_id": "01K631TTTF9JAE0GKZXYWGSTTZ",
    "requires_approval": false,
    "tool": {
      "id": "01JKG6QJ5FGHCWA7RVMMZB82QY",
      "action_type": "current_date",
      "display_name": "Current Date & Time",
      "requires_approval": false
    },
    "input": {
      "timezone": "UTC"
    },
    "agent_tool_call_id": "toolu_01USVfbcLCA5TawuUNRNiaqS"
  },
  "timestamp": "2025-09-26T13:01:39.023Z"
}

{
  "type": "event.agents.action_reviewed",
  "data": {
    "agent_id": "01K62T62KVJHRE0P9PX4VN2JHD",
    "action_id": "01K631TTTF9JAE0GKZXYWGSTTZ",
    "agent_tool_call_id": "toolu_01USVfbcLCA5TawuUNRNiaqS",
    "review": "approved",
    "review_source": "automatic",
    "reviewed_by_id": "system"
  },
  "timestamp": "2025-09-26T13:01:39.025Z"
}

{
  "type": "event.workflow_events.tool_execution_started",
  "data": {
    "tool_id": "01JKG6QJ5FGHCWA7RVMMZB82QY",
    "tool_key": "current_date",
    "tool_display_name": "Current Date & Time",
    "action_type": "current_date",
    "tool_arguments": {
      "timezone": "UTC"
    },
    "tool_execution_context": {
      "action_id": "01K631TTTF9JAE0GKZXYWGSTTZ",
      "agent_tool_call_id": "toolu_01USVfbcLCA5TawuUNRNiaqS",
      "workspace_id": "cbd7b74a-4f2f-43b6-b3f9-19353c40dd62",
      "agent_manifest_id": "01K62T62KVJHRE0P9PX4VN2JHD",
      "agent_execution_id": "01K631TNQZ9VWENJV91YS1JQXC",
      "product": "agents"
    }
  },
  "timestamp": "2025-09-26T13:01:39.029Z"
}

{
  "type": "event.workflow_events.tool_execution_finished",
  "data": {
    "result": {
      "currentDate": "2025-09-26T13:01:39.030Z"
    },
    "tool_execution_context": {
      "action_id": "01K631TTTF9JAE0GKZXYWGSTTZ",
      "agent_tool_call_id": "toolu_01USVfbcLCA5TawuUNRNiaqS",
      "workspace_id": "cbd7b74a-4f2f-43b6-b3f9-19353c40dd62",
      "agent_manifest_id": "01K62T62KVJHRE0P9PX4VN2JHD",
      "agent_execution_id": "01K631TNQZ9VWENJV91YS1JQXC",
      "product": "agents"
    }
  },
  "timestamp": "2025-09-26T13:01:39.030Z"
}

{
  "type": "event.workflow_events.tool_execution_failed",
  "data": {
    "error": "Tool execution timeout",
    "tool_execution_context": {
      "action_id": "01K631TTTF9JAE0GKZXYWGSTTZ",
      "agent_tool_call_id": "toolu_01USVfbcLCA5TawuUNRNiaqS",
      "workspace_id": "cbd7b74a-4f2f-43b6-b3f9-19353c40dd62",
      "agent_manifest_id": "01K62T62KVJHRE0P9PX4VN2JHD",
      "agent_execution_id": "01K631TNQZ9VWENJV91YS1JQXC",
      "product": "agents"
    }
  },
  "timestamp": "2025-09-26T13:01:45.030Z"
}

// Execution Control Events
{
  "type": "event.agents.execution_review_required",
  "data": {},
  "timestamp": "2025-09-26T13:01:40.000Z"
}

{
  "type": "event.agents.execution_reviewed",
  "data": {},
  "timestamp": "2025-09-26T13:01:41.000Z"
}

{
  "type": "event.agents.execution_named",
  "data": {
    "name": "Getting current date and providing information",
    "agent_manifest_id": "01K62T62KVJHRE0P9PX4VN2JHD"
  },
  "timestamp": "2025-09-26T13:01:36.816Z"
}

{
  "type": "event.agents.handed_off",
  "data": {
    "agent_id": "01K62T62KVJHRE0P9PX4VN2JHD",
    "input": "Continuing with weather analysis task"
  },
  "timestamp": "2025-09-26T13:01:45.000Z"
}

// Special Events
{
  "type": "agents.timeout",
  "data": {
    "message": "Agent execution exceeded maximum time limit"
  },
  "timestamp": "2025-09-26T13:06:00.000Z"
}

{
  "type": "agents.error",
  "data": {
    "error": "Rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED"
  },
  "timestamp": "2025-09-26T13:01:45.000Z"
}

// Stream Termination
[DONE]
Stream responses use Server-Sent Events (SSE). Use an appropriate SSE client for proper handling.

​
Examples

{
  "key": "simple-agent-1",
  "role": "Assistant",
  "description": "A helpful assistant for general tasks",
  "instructions": "Be helpful and concise",
  "settings": {
    "max_iterations": 3,
    "max_execution_time": 300,
    "tool_approval_required": "none",
    "tools": [
      {
        "requires_approval": false,
        "display_name": "current_date",
        "type": "current_date"
      }
    ]
  },
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "What's today's date and day of the week?"
      }
    ]
  },
  "model": "openai/gpt-4o",
  "path": "Default/agents",
  "memory_stores": [],
  "team_of_agents": []
}

data: {"type":"agents.execution_started","data":{"agent_task_id":"01K631TNQZ9VWENJV91YS1JQXC","agent_manifest_id":"01K62T62KVJHRE0P9PX4VN2JHD","agent_key":"simple-agent-1","workspace_id":"cbd7b74a-4f2f-43b6-b3f9-19353c40dd62"},"timestamp":"2025-09-26T13:01:33.860Z"}

data: {"type":"event.agents.started","data":{"inputMessage":{"role":"user","parts":[{"kind":"text","text":"What's today's date and day of the week?"}],"metadata":{}},"modelId":"0707a18f-e3a0-44b6-9f24-4d5d28e0cdea","instructions":"Be helpful and concise","system_prompt":"You are an AI agent with access to tools to help complete user tasks...","settings":{"max_iterations":3,"max_execution_time":300,"tool_approval_required":"none","tools":[{"id":"01JKG6QJ5FGHCWA7RVMMZB82QY","action_type":"current_date","display_name":"Current Date & Time","requires_approval":false}]},"agent_manifest_id":"01K62T62KVJHRE0P9PX4VN2JHD","agent_key":"simple-agent-1"},"timestamp":"2025-09-26T13:01:33.863Z"}

data: {"type":"event.agents.thought","data":{"agent_id":"01K62T62KVJHRE0P9PX4VN2JHD","message_difference":{"2":{"messageId":"01K631TRNHF7XQ9HN7R9YX5GQR","role":"agent","parts":[{"kind":"tool_call","tool_name":"current_date","tool_call_id":"toolu_01USVfbcLCA5TawuUNRNiaqS","arguments":{"timezone":"UTC"}}],"metadata":{}}},"choice":{"finish_reason":"tool_calls","index":0,"message":{"content":null,"tool_calls":[{"id":"toolu_01USVfbcLCA5TawuUNRNiaqS","type":"function","function":{"name":"current_date","arguments":"{\"timezone\":\"UTC\"}"}}],"role":"assistant"}},"choiceIndex":2,"iteration":1,"accumulated_execution_time":0},"timestamp":"2025-09-26T13:01:36.817Z"}

data: {"type":"event.agents.execution_named","data":{"name":"Getting current date and providing information","agent_manifest_id":"01K62T62KVJHRE0P9PX4VN2JHD"},"timestamp":"2025-09-26T13:01:36.816Z"}

data: {"type":"event.agents.action_review_requested","data":{"agent_id":"01K62T62KVJHRE0P9PX4VN2JHD","action_id":"01K631TTTF9JAE0GKZXYWGSTTZ","requires_approval":false,"tool":{"id":"01JKG6QJ5FGHCWA7RVMMZB82QY","action_type":"current_date","display_name":"Current Date & Time","requires_approval":false},"input":{"timezone":"UTC"},"agent_tool_call_id":"toolu_01USVfbcLCA5TawuUNRNiaqS"},"timestamp":"2025-09-26T13:01:39.023Z"}

data: {"type":"event.workflow_events.tool_execution_started","data":{"tool_id":"01JKG6QJ5FGHCWA7RVMMZB82QY","tool_key":"current_date","tool_display_name":"Current Date & Time","action_type":"current_date","tool_arguments":{"timezone":"UTC"},"tool_execution_context":{"action_id":"01K631TTTF9JAE0GKZXYWGSTTZ","agent_tool_call_id":"toolu_01USVfbcLCA5TawuUNRNiaqS","workspace_id":"cbd7b74a-4f2f-43b6-b3f9-19353c40dd62","agent_manifest_id":"01K62T62KVJHRE0P9PX4VN2JHD","agent_execution_id":"01K631TNQZ9VWENJV91YS1JQXC","product":"agents"}},"timestamp":"2025-09-26T13:01:39.029Z"}

data: {"type":"event.workflow_events.tool_execution_finished","data":{"result":{"currentDate":"2025-09-26T13:01:39.030Z"},"tool_execution_context":{"action_id":"01K631TTTF9JAE0GKZXYWGSTTZ","agent_tool_call_id":"toolu_01USVfbcLCA5TawuUNRNiaqS","workspace_id":"cbd7b74a-4f2f-43b6-b3f9-19353c40dd62","agent_manifest_id":"01K62T62KVJHRE0P9PX4VN2JHD","agent_execution_id":"01K631TNQZ9VWENJV91YS1JQXC","product":"agents"}},"timestamp":"2025-09-26T13:01:39.030Z"}

data: {"type":"event.agents.thought","data":{"agent_id":"01K62T62KVJHRE0P9PX4VN2JHD","message_difference":{"3":{"messageId":"01K631TZWQ834RCWD0D1QN455P","role":"tool","parts":[{"kind":"tool_result","tool_call_id":"toolu_01USVfbcLCA5TawuUNRNiaqS","result":{"currentDate":"2025-09-26T13:01:39.030Z"}}],"metadata":{}},"4":{"messageId":"01K631TZWQ93QY494FSGCTPG69","role":"agent","parts":[{"kind":"text","text":"Today is Thursday, September 26th, 2025. The current date and time is 2025-09-26T13:01:39.030Z (UTC)."}],"metadata":{}}},"choice":{"finish_reason":"stop","index":0,"message":{"content":"Today is Thursday, September 26th, 2025. The current date and time is 2025-09-26T13:01:39.030Z (UTC).","role":"assistant"}},"choiceIndex":4,"iteration":2,"accumulated_execution_time":5053.7},"timestamp":"2025-09-26T13:01:44.215Z"}

data: {"type":"event.agents.inactive","data":{"last_message":"Today is Thursday, September 26th, 2025. The current date and time is 2025-09-26T13:01:39.030Z (UTC).","finish_reason":"stop"},"timestamp":"2025-09-26T13:01:44.216Z"}

data: [DONE]

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
key
string
required

A unique identifier for the agent. This key must be unique within the same workspace and cannot be reused. When executing the agent, this key determines if the agent already exists. If the agent version differs, a new version is created at the end of the execution, except for the task. All agent parameters are evaluated to decide if a new version is needed.

Minimum length: 1
​
model
required

Model configuration for this execution. Can override the agent manifest defaults if the agent already exists.

A model ID string (e.g., openai/gpt-4o or anthropic/claude-haiku-4-5-20251001). The agent can be run with a wide range of models with different capabilities, performance characteristics, and price points. Only models that support tool calling (function_calling) can be used to run agents. See (supported models)[/docs/proxy/supported-models] documentation for the complete list of available models.

​
role
string
required

Specifies the agent's function and area of expertise.

Minimum length: 1
​
instructions
string
required

Provides context and purpose for the agent. Combined with the system prompt template to generate the agent's instructions.

Minimum length: 1
​
message
object
required

The A2A format message containing the task for the agent to perform.

​
path
string
required

Entity storage path in the format: project/folder/subfolder/...

The first element identifies the project, followed by nested folders (auto-created as needed).

With project-based API keys, the first element is treated as a folder name, as the project is predetermined by the API key.

Example:

"Default"

​
settings
object
required
​
task_id
string

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.

​
fallback_models
(string | Fallback Model Configuration · object)[]

Optional array of fallback models used when the primary model fails. Fallbacks are attempted in order. All models must support tool calling.

​
variables
object

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

​
contact
object

Information about the contact making the request. If the contact does not exist, it will be created automatically.

​
thread
object

Thread information to group related requests

​
memory
object

Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.

​
description
string

A brief summary of the agent's purpose.

Minimum length: 1
​
system_prompt
string

A custom system prompt template for the agent. If omitted, the default template is used.

Minimum length: 1
​
memory_stores
string[]

Array of memory store identifiers that are accessible to the agent. Accepts both memory store IDs and keys.

​
knowledge_bases
object[]

Knowledge base configurations for the agent to access

​
team_of_agents
object[]

The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks.

​
metadata
object

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

​
stream_timeout_seconds
number

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

Required range: 1 <= x <= 3600

Response

SSE stream of agent events

​
data
object
required
  • Option 1
  • Option 2
  • Option 3
  • Option 4
  • Option 5
  • Option 6
  • Option 7
  • Option 8
  • Option 9
  • Option 10
  • Option 11
  • Option 12
  • Option 13
  • Option 14
  • Option 15
  • Option 16
  • Option 17