> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Stream agent execution in real-time > Executes an agent and streams the interaction in real-time using Server-Sent Events (SSE). Provides live updates as the agent processes the request, including message chunks, tool calls, and execution status. Perfect for building responsive chat interfaces and monitoring agent progress. The stream continues until the agent completes its task, encounters an error, or reaches the configured timeout (default 30 minutes, configurable 1-3600 seconds). ## OpenAPI ````yaml post /v2/agents/{key}/stream-task openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - name: Guardrail Rules - name: Policies - name: Routing Rules - name: Files description: File upload and retrieval operations. - name: FilesService - name: Projects description: Projects organize resources within a workspace - name: ProjectsService - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: SkillsService - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. - name: ReportingService description: |- ReportingService exposes a single QueryReport RPC that maps allowlisted analytics payloads onto safe rollup queries. Callers never send SQL; the backend picks the rollup family and grain from the metric catalogue, the requested range, and the requested grouping. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/agents/{key}/stream-task: post: tags: - Agents summary: Stream agent execution in real-time description: >- Executes an agent and streams the interaction in real-time using Server-Sent Events (SSE). Provides live updates as the agent processes the request, including message chunks, tool calls, and execution status. Perfect for building responsive chat interfaces and monitoring agent progress. The stream continues until the agent completes its task, encounters an error, or reaches the configured timeout (default 30 minutes, configurable 1-3600 seconds). operationId: StreamAgent parameters: - schema: type: string description: The key or ID of the agent to invoke required: true description: The key or ID of the agent to invoke name: key in: path requestBody: required: true content: application/json: schema: type: object properties: task_id: type: string description: >- 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. message: type: object properties: messageId: type: string description: Optional A2A message ID in ULID format role: anyOf: - type: string enum: - user title: User message description: Message from the end user - type: string enum: - tool title: Tool message description: Message containing tool execution results description: Message role (user or tool for continuing executions) parts: type: array items: oneOf: - allOf: - $ref: '#/components/schemas/TextPart' - description: >- Text content part. Use this to send text messages to the agent. - allOf: - $ref: '#/components/schemas/FilePart' - description: >- File attachment part. Use this to send files (images, documents, etc.) to the agent for processing. - allOf: - $ref: '#/components/schemas/ToolResultPart' - description: >- Tool execution result part. Use this ONLY when providing results for a pending tool call from the agent. The tool_call_id must match the ID from the agent's tool call request. - allOf: - $ref: '#/components/schemas/ErrorPart' - description: >- Error content part. Generated by the system when an error occurs during agent execution. discriminator: propertyName: kind mapping: text: $ref: '#/components/schemas/TextPart' file: $ref: '#/components/schemas/FilePart' tool_result: $ref: '#/components/schemas/ToolResultPart' error: $ref: '#/components/schemas/ErrorPart' title: Public Message Part description: >- Message part that can be provided by users. Use "text" for regular messages, "file" for attachments, or "tool_result" when responding to tool call requests. description: >- A2A message parts (text, file, or tool_result only). Note: Tool role messages must only contain tool_result parts. required: - role - parts title: A2A Message description: >- The A2A message to send to the agent (user input or tool results) variables: type: object additionalProperties: {} description: >- Optional variables for template replacement in system prompt, instructions, and messages identity: type: object properties: id: type: string description: Unique identifier for the contact example: contact_01ARZ3NDEKTSV4RRFFQ69G5FAV display_name: type: string description: Display name of the contact example: Jane Doe email: type: string format: email description: Email address of the contact example: jane.doe@example.com metadata: type: array items: type: object additionalProperties: {} description: >- A hash of key/value pairs containing any other data about the contact example: - department: Engineering role: Senior Developer logo_url: type: string description: URL to the contact's avatar or logo example: https://example.com/avatars/jane-doe.jpg tags: type: array items: type: string description: A list of tags associated with the contact example: - hr - engineering required: - id description: >- Information about the identity making the request. If the identity does not exist, it will be created automatically. contact: type: object properties: id: type: string description: Unique identifier for the contact example: contact_01ARZ3NDEKTSV4RRFFQ69G5FAV display_name: type: string description: Display name of the contact example: Jane Doe email: type: string format: email description: Email address of the contact example: jane.doe@example.com metadata: type: array items: type: object additionalProperties: {} description: >- A hash of key/value pairs containing any other data about the contact example: - department: Engineering role: Senior Developer logo_url: type: string description: URL to the contact's avatar or logo example: https://example.com/avatars/jane-doe.jpg tags: type: array items: type: string description: A list of tags associated with the contact example: - hr - engineering required: - id description: >- @deprecated Use identity instead. Information about the contact making the request. deprecated: true thread: type: object properties: id: type: string description: Unique thread identifier to group related invocations. example: thread_01ARZ3NDEKTSV4RRFFQ69G5FAV tags: type: array items: type: string description: Optional tags to differentiate or categorize threads example: - customer-support - priority-high required: - id description: Thread information to group related requests memory: type: object properties: entity_id: type: string description: >- An entity ID used to link memory stores to a specific user, session, or conversation. This ID is used to isolate and retrieve memories specific to the entity across agent executions. required: - entity_id description: >- Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions. metadata: type: object additionalProperties: {} description: >- Optional metadata for the agent invocation as key-value pairs that will be included in traces engine: type: string enum: - text - jinja - mustache description: >- Override template engine for this invocation. If not provided, uses the agent default. configuration: type: object properties: blocking: type: boolean default: false description: >- Whether to block until the agent task completes. When true, the response will include the full task with messages. When false (default), returns immediately with task ID and status. description: Configuration options for the agent invocation stream_timeout_seconds: type: number minimum: 1 maximum: 3600 description: >- Stream timeout in seconds (1-3600). Default: 1800 (30 minutes) required: - message responses: '200': description: >- 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. content: text/event-stream: schema: type: object properties: data: oneOf: - $ref: >- #/components/schemas/AgentExecutionStartedStreamingEvent - $ref: '#/components/schemas/AgentStartedStreamingEvent' - $ref: '#/components/schemas/AgentThoughtStreamingEvent' - $ref: '#/components/schemas/AgentInactiveStreamingEvent' - $ref: '#/components/schemas/AgentErroredStreamingEvent' - $ref: >- #/components/schemas/ActionReviewRequestedStreamingEvent - $ref: '#/components/schemas/ActionReviewedStreamingEvent' - $ref: >- #/components/schemas/ExecutionReviewRequiredStreamingEvent - $ref: '#/components/schemas/ExecutionReviewedStreamingEvent' - $ref: '#/components/schemas/ExecutionNamedStreamingEvent' - $ref: '#/components/schemas/AgentHandedOffStreamingEvent' - $ref: '#/components/schemas/AgentMessageCreatedStreamingEvent' - $ref: >- #/components/schemas/ToolExecutionStartedStreamingEvent - $ref: >- #/components/schemas/ToolExecutionFinishedStreamingEvent - $ref: '#/components/schemas/ToolExecutionFailedStreamingEvent' - $ref: '#/components/schemas/TimeoutStreamingEvent' - $ref: '#/components/schemas/ErrorStreamingEvent' discriminator: propertyName: type mapping: agents.execution_started: $ref: >- #/components/schemas/AgentExecutionStartedStreamingEvent event.agents.started: $ref: '#/components/schemas/AgentStartedStreamingEvent' event.agents.thought: $ref: '#/components/schemas/AgentThoughtStreamingEvent' event.agents.inactive: $ref: '#/components/schemas/AgentInactiveStreamingEvent' event.agents.errored: $ref: '#/components/schemas/AgentErroredStreamingEvent' event.agents.action_review_requested: $ref: >- #/components/schemas/ActionReviewRequestedStreamingEvent event.agents.action_reviewed: $ref: '#/components/schemas/ActionReviewedStreamingEvent' event.agents.execution_review_required: $ref: >- #/components/schemas/ExecutionReviewRequiredStreamingEvent event.agents.execution_reviewed: $ref: '#/components/schemas/ExecutionReviewedStreamingEvent' event.agents.execution_named: $ref: '#/components/schemas/ExecutionNamedStreamingEvent' event.agents.handed_off: $ref: '#/components/schemas/AgentHandedOffStreamingEvent' event.agents.message-created: $ref: >- #/components/schemas/AgentMessageCreatedStreamingEvent event.workflow_events.tool_execution_started: $ref: >- #/components/schemas/ToolExecutionStartedStreamingEvent event.workflow_events.tool_execution_finished: $ref: >- #/components/schemas/ToolExecutionFinishedStreamingEvent event.workflow_events.tool_execution_failed: $ref: >- #/components/schemas/ToolExecutionFailedStreamingEvent agents.timeout: $ref: '#/components/schemas/TimeoutStreamingEvent' agents.error: $ref: '#/components/schemas/ErrorStreamingEvent' required: - data x-speakeasy-sse-sentinel: '[DONE]' '404': description: Agent not found content: application/json: schema: type: object properties: message: type: string required: - message deprecated: true components: schemas: TextPart: type: object properties: kind: type: string enum: - text text: type: string required: - kind - text title: Text Part description: >- A text content part containing plain text or markdown. Used for agent messages, user input, and text-based responses. FilePart: type: object properties: kind: type: string enum: - file file: anyOf: - type: object properties: bytes: type: string minLength: 1 description: base64 encoded content of the file mimeType: type: string description: Optional mimeType for the file name: type: string description: Optional name for the file required: - bytes title: Binary format description: >- Binary in base64 format. Check in the model's documentation for the supported mime types for the binary format. - type: object properties: uri: type: string description: URL for the File content mimeType: type: string description: Optional mimeType for the file name: type: string description: Optional name for the file required: - uri title: File in URI format description: >- File in URI format. Check in the model's documentation for the supported mime types for the URI format metadata: type: object additionalProperties: {} required: - kind - file title: File Part description: >- A file content part that can contain either base64-encoded bytes or a URI reference. Used for images, documents, and other binary content in agent communications. ToolResultPart: type: object properties: kind: type: string enum: - tool_result tool_call_id: type: string minLength: 1 result: {} metadata: type: object additionalProperties: {} required: - kind - tool_call_id title: Tool Result Part description: >- The result of a tool execution. Contains the tool call ID for correlation and the result data from the tool invocation. ErrorPart: type: object properties: kind: type: string enum: - error error: type: string code: type: number required: - kind - error title: Error Part description: >- An error content part containing error information. Used when an error occurs during agent execution. AgentExecutionStartedStreamingEvent: type: object properties: type: type: string enum: - agents.execution_started timestamp: type: string description: ISO timestamp of the event data: type: object properties: agent_task_id: type: string description: Agent execution task ID (ULID) workspace_id: type: string description: Workspace ID trace_id: type: string description: Trace ID for the workflow run required: - agent_task_id - workspace_id - trace_id required: - type - timestamp - data title: Agent Execution Started Event description: >- Initial event emitted when an agent stream begins. Contains the task ID for tracking, workspace context, and trace ID for observability. AgentStartedStreamingEvent: type: object properties: type: type: string enum: - event.agents.started timestamp: type: string description: ISO timestamp of the event data: type: object properties: workflowRunId: type: string integration_id: type: string inputMessage: type: object properties: messageId: type: string role: type: string enum: - user - agent - tool - system description: Extended A2A message role parts: type: array items: oneOf: - $ref: '#/components/schemas/TextPart' - $ref: '#/components/schemas/ErrorPart' - $ref: '#/components/schemas/DataPart' - $ref: '#/components/schemas/FilePart' - $ref: '#/components/schemas/ToolCallPart' - $ref: '#/components/schemas/ToolResultPart' discriminator: propertyName: kind mapping: text: $ref: '#/components/schemas/TextPart' error: $ref: '#/components/schemas/ErrorPart' data: $ref: '#/components/schemas/DataPart' file: $ref: '#/components/schemas/FilePart' tool_call: $ref: '#/components/schemas/ToolCallPart' tool_result: $ref: '#/components/schemas/ToolResultPart' metadata: type: object additionalProperties: {} required: - role - parts modelId: type: string instructions: type: string system_prompt: type: string settings: type: object properties: max_iterations: type: integer exclusiveMinimum: 0 maximum: 100 minimum: 1 default: 100 description: >- Maximum iterations(llm calls) before the agent will stop executing. max_execution_time: type: integer minimum: 2 exclusiveMinimum: 0 maximum: 600 default: 600 description: >- Maximum time (in seconds) for the agent thinking process. This does not include the time for tool calls and sub agent calls. It will be loosely enforced, the in progress LLM calls will not be terminated and the last assistant message will be returned. max_cost: type: number minimum: 0 default: 0 description: >- Maximum cost in USD for the agent execution. When the accumulated cost exceeds this limit, the agent will stop executing. Set to 0 for unlimited. Only supported in v3 responses tool_approval_required: type: string enum: - all - respect_tool - none default: respect_tool description: >- If all, the agent will require approval for all tools. If respect_tool, the agent will require approval for tools that have the requires_approval flag set to true. If none, the agent will not require approval for any tools. tools: type: array items: type: object properties: id: type: string format: ulid pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ readOnly: true description: The id of the resource key: type: string description: Optional tool key for custom tools action_type: type: string display_name: type: string description: type: string description: Optional tool description requires_approval: type: boolean default: false tool_id: type: string description: >- Nested tool ID for MCP tools (identifies specific tool within MCP server) conditions: type: array items: type: object properties: condition: type: string description: The argument of the tool call to evaluate operator: type: string description: The operator to use value: type: string description: The value to compare against required: - condition - operator - value default: [] timeout: type: number minimum: 1 maximum: 600 default: 120 description: >- Tool execution timeout in seconds (default: 2 minutes, max: 10 minutes) required: - id - action_type default: [] evaluators: type: array items: type: object properties: id: type: string description: Unique key or identifier of the evaluator sample_rate: type: number minimum: 1 maximum: 100 default: 50 description: >- The percentage of executions to evaluate with this evaluator (1-100). For example, a value of 50 means the evaluator will run on approximately half of the executions. execute_on: type: string enum: - input - output description: >- Determines whether the evaluator runs on the agent input (user message) or output (agent response). required: - id - execute_on title: Agent evaluator configuration description: Configuration for an evaluator applied to the agent guardrails: type: array items: type: object properties: id: type: string description: Unique key or identifier of the evaluator sample_rate: type: number minimum: 1 maximum: 100 default: 50 description: >- The percentage of executions to evaluate with this evaluator (1-100). For example, a value of 50 means the evaluator will run on approximately half of the executions. execute_on: type: string enum: - input - output description: >- Determines whether the evaluator runs on the agent input (user message) or output (agent response). required: - id - execute_on title: Agent guardrail configuration description: Configuration for a guardrail applied to the agent default: max_execution_time: 600 max_iterations: 100 max_cost: 0 tool_approval_required: respect_tool tools: [] agent_manifest_id: type: string agent_key: type: string agent_description: type: - string - 'null' agent_source: type: - string - 'null' enum: - internal - external - experiment - null variables: type: object additionalProperties: {} tool_execution_id: type: string is_continuation: type: boolean stream: type: boolean responseId: type: string required: - workflowRunId - inputMessage - modelId - instructions - system_prompt - agent_manifest_id - agent_key required: - type - timestamp - data title: Agent Started Event description: >- Emitted when the agent begins processing. Contains configuration details including the model, instructions, system prompt, and input message. AgentThoughtStreamingEvent: type: object properties: type: type: string enum: - event.agents.thought timestamp: type: string description: ISO timestamp of the event data: type: object properties: agent_id: type: string message_difference: type: object additionalProperties: type: object properties: messageId: type: string role: type: string enum: - user - agent - tool - system parts: type: array items: oneOf: - $ref: '#/components/schemas/TextPart' - $ref: '#/components/schemas/ErrorPart' - $ref: '#/components/schemas/DataPart' - $ref: '#/components/schemas/FilePart' - $ref: '#/components/schemas/ToolCallPart' - $ref: '#/components/schemas/ToolResultPart' discriminator: propertyName: kind mapping: text: $ref: '#/components/schemas/TextPart' error: $ref: '#/components/schemas/ErrorPart' data: $ref: '#/components/schemas/DataPart' file: $ref: '#/components/schemas/FilePart' tool_call: $ref: '#/components/schemas/ToolCallPart' tool_result: $ref: '#/components/schemas/ToolResultPart' metadata: type: object additionalProperties: {} agent_id: type: string agent_execution_id: type: string workspace_id: type: string required: - messageId - role - parts - agent_id - agent_execution_id - workspace_id choice: type: object properties: finish_reason: type: - string - 'null' enum: - stop - length - tool_calls - content_filter - function_call - null description: The reason the model stopped generating tokens. index: type: number default: 0 description: The index of the choice in the list of choices. message: type: object properties: content: type: - string - 'null' refusal: type: - string - 'null' tool_calls: type: array items: type: object properties: index: type: number id: type: string type: type: string enum: - function function: type: object properties: name: type: string description: >- The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. arguments: type: string description: >- The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. thought_signature: type: string description: >- Encrypted representation of the model internal reasoning state during function calling. Required by Gemini 3 models when continuing a conversation after a tool call. role: type: string enum: - assistant reasoning: type: - string - 'null' description: Internal thought process of the model reasoning_signature: type: - string - 'null' description: >- The signature holds a cryptographic token which verifies that the thinking block was generated by the model, and is verified when thinking is part of a multiturn conversation. This value should not be modified and should always be sent to the API when the reasoning is redacted. Currently only supported by `Anthropic`. redacted_reasoning: type: string description: >- Occasionally the model's internal reasoning will be flagged by the safety systems of the provider. When this occurs, the provider will encrypt the reasoning. These redacted reasoning is decrypted when passed back to the API, allowing the model to continue its response without losing context. audio: type: - object - 'null' properties: id: type: string expires_at: type: integer data: type: string transcript: type: string required: - id - expires_at - data - transcript description: >- If the audio output modality is requested, this object contains data about the audio response from the model. description: A chat completion message generated by the model. logprobs: type: - object - 'null' properties: content: type: - array - 'null' items: type: object properties: token: type: string description: The token. logprob: type: number description: >- The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely. bytes: type: - array - 'null' items: type: number description: >- A list of integers representing the UTF-8 bytes representation of the token. top_logprobs: type: array items: type: object properties: token: type: string description: The token. logprob: type: number description: >- The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely. bytes: type: - array - 'null' items: type: number description: >- A list of integers representing the UTF-8 bytes representation of the token. required: - token - logprob - bytes description: >- List of the most likely tokens and their log probability, at this token position. required: - token - logprob - bytes - top_logprobs description: >- A list of message content tokens with log probability information. refusal: type: - array - 'null' items: type: object properties: token: type: string description: The token. logprob: type: number description: >- The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely. bytes: type: - array - 'null' items: type: number description: >- A list of integers representing the UTF-8 bytes representation of the token. top_logprobs: type: array items: type: object properties: token: type: string description: The token. logprob: type: number description: >- The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely. bytes: type: - array - 'null' items: type: number description: >- A list of integers representing the UTF-8 bytes representation of the token. required: - token - logprob - bytes description: >- List of the most likely tokens and their log probability, at this token position. required: - token - logprob - bytes - top_logprobs description: >- A list of message refusal tokens with log probability information. required: - content - refusal description: Log probability information for the choice. required: - finish_reason - message choiceIndex: type: number iteration: type: number accumulated_execution_time: type: number responseId: type: string usage: type: object properties: completion_tokens: type: number description: Number of tokens in the generated completion. prompt_tokens: type: number description: Number of tokens in the prompt. total_tokens: type: number description: >- Total number of tokens used in the request (prompt + completion). prompt_tokens_details: type: - object - 'null' properties: cached_tokens: type: - integer - 'null' cache_creation_tokens: type: - integer - 'null' audio_tokens: type: - integer - 'null' description: >- The number of audio input tokens consumed by the request. completion_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: - number - 'null' accepted_prediction_tokens: type: - number - 'null' rejected_prediction_tokens: type: - number - 'null' audio_tokens: type: - integer - 'null' description: >- The number of audio output tokens produced by the response. description: Usage statistics for the completion request. required: - agent_id - message_difference - iteration - accumulated_execution_time required: - type - timestamp - data title: Agent Thought Event description: >- Emitted during agent reasoning. Contains the incremental message changes, model choices, iteration count, and token usage for this processing step. AgentInactiveStreamingEvent: type: object properties: type: type: string enum: - event.agents.inactive timestamp: type: string description: ISO timestamp of the event data: type: object properties: last_message: type: string last_message_full: type: object properties: messageId: type: string role: type: string enum: - user - agent - tool - system description: Extended A2A message role parts: type: array items: oneOf: - $ref: '#/components/schemas/TextPart' - $ref: '#/components/schemas/ErrorPart' - $ref: '#/components/schemas/DataPart' - $ref: '#/components/schemas/FilePart' - $ref: '#/components/schemas/ToolCallPart' - $ref: '#/components/schemas/ToolResultPart' discriminator: propertyName: kind mapping: text: $ref: '#/components/schemas/TextPart' error: $ref: '#/components/schemas/ErrorPart' data: $ref: '#/components/schemas/DataPart' file: $ref: '#/components/schemas/FilePart' tool_call: $ref: '#/components/schemas/ToolCallPart' tool_result: $ref: '#/components/schemas/ToolResultPart' metadata: type: object additionalProperties: {} required: - role - parts description: Full last message in A2A format (for backwards compatibility) finish_reason: type: string enum: - stop - length - tool_calls - content_filter - function_call - max_iterations - max_time description: The reason why the agent execution became inactive pending_tool_calls: type: array items: type: object properties: id: type: string type: type: string enum: - function function: type: object properties: name: type: string arguments: type: string required: - id - type - function description: >- Tool calls that are pending user response (for function_call finish reason) usage: type: object properties: completion_tokens: type: number description: Number of tokens in the generated completion. prompt_tokens: type: number description: Number of tokens in the prompt. total_tokens: type: number description: >- Total number of tokens used in the request (prompt + completion). prompt_tokens_details: type: - object - 'null' properties: cached_tokens: type: - integer - 'null' cache_creation_tokens: type: - integer - 'null' audio_tokens: type: - integer - 'null' description: >- The number of audio input tokens consumed by the request. completion_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: - number - 'null' accepted_prediction_tokens: type: - number - 'null' rejected_prediction_tokens: type: - number - 'null' audio_tokens: type: - integer - 'null' description: >- The number of audio output tokens produced by the response. time_to_first_token: type: number description: Token usage from the last agent message billing: type: object properties: total_cost: type: number minimum: 0 input_cost: type: number minimum: 0 output_cost: type: number minimum: 0 billable: type: boolean integration_id: type: - string - 'null' required: - total_cost - input_cost - output_cost - billable - integration_id description: Billing information for the agent execution workflowRunId: type: string responseId: type: string description: ID of the response tracking this execution required: - last_message - finish_reason - workflowRunId required: - type - timestamp - data title: Agent Inactive Event description: >- Emitted when the agent completes processing or pauses for input. Contains the final message, finish reason (stop, tool_calls, max_iterations, etc.), and any pending tool calls awaiting user response. AgentErroredStreamingEvent: type: object properties: type: type: string enum: - event.agents.errored timestamp: type: string description: ISO timestamp of the event data: type: object properties: error: type: string code: type: number responseId: type: string description: ID of the response tracking this execution workflowRunId: type: string required: - error - code - workflowRunId required: - type - timestamp - data title: Agent Errored Event description: >- Emitted when an error occurs during agent execution. Contains the error message and HTTP status code indicating the failure type. ActionReviewRequestedStreamingEvent: type: object properties: type: type: string enum: - event.agents.action_review_requested timestamp: type: string description: ISO timestamp of the event data: type: object properties: agent_id: type: string action_id: type: string requires_approval: type: boolean tool: type: object properties: id: type: string format: ulid pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ readOnly: true description: The id of the resource key: type: string description: Optional tool key for custom tools action_type: type: string display_name: type: string description: type: string description: Optional tool description requires_approval: type: boolean default: false tool_id: type: string description: >- Nested tool ID for MCP tools (identifies specific tool within MCP server) conditions: type: array items: type: object properties: condition: type: string description: The argument of the tool call to evaluate operator: type: string description: The operator to use value: type: string description: The value to compare against required: - condition - operator - value default: [] timeout: type: number minimum: 1 maximum: 600 default: 120 description: >- Tool execution timeout in seconds (default: 2 minutes, max: 10 minutes) required: - id - action_type input: type: object additionalProperties: {} agent_tool_call_id: type: string responseId: type: string required: - agent_id - action_id - requires_approval - tool - input - agent_tool_call_id required: - type - timestamp - data title: Action Review Requested Event description: >- Emitted when a tool action requires approval before execution. Contains the tool details, input arguments, and whether approval is mandatory. ActionReviewedStreamingEvent: type: object properties: type: type: string enum: - event.agents.action_reviewed timestamp: type: string description: ISO timestamp of the event data: type: object properties: agent_id: type: string action_id: type: string agent_tool_call_id: type: string review: type: string enum: - approved - rejected mock_output: type: object additionalProperties: {} review_source: type: string reviewed_by_id: type: string workflowRunId: type: string required: - agent_id - action_id - agent_tool_call_id - review - workflowRunId required: - type - timestamp - data title: Action Reviewed Event description: >- Emitted after a tool action has been reviewed. Contains the review decision (approved/rejected), optional mock output for rejected actions, and reviewer information. ExecutionReviewRequiredStreamingEvent: type: object properties: type: type: string enum: - event.agents.execution_review_required timestamp: type: string description: ISO timestamp of the event data: type: object properties: {} required: - type - timestamp - data title: Execution Review Required Event description: >- Emitted when the entire agent execution requires human review before proceeding. The execution will pause until reviewed. ExecutionReviewedStreamingEvent: type: object properties: type: type: string enum: - event.agents.execution_reviewed timestamp: type: string description: ISO timestamp of the event data: type: object properties: {} required: - type - timestamp - data title: Execution Reviewed Event description: >- Emitted after the agent execution has been reviewed. The execution will resume processing after this event. ExecutionNamedStreamingEvent: type: object properties: type: type: string enum: - event.agents.execution_named timestamp: type: string description: ISO timestamp of the event data: type: object properties: name: type: string agent_manifest_id: type: string required: - name - agent_manifest_id required: - type - timestamp - data title: Execution Named Event description: >- Emitted when the agent execution is assigned a human-readable name, typically generated based on the conversation content. AgentHandedOffStreamingEvent: type: object properties: type: type: string enum: - event.agents.handed_off timestamp: type: string description: ISO timestamp of the event data: type: object properties: agent_id: type: string input: type: string required: - agent_id - input required: - type - timestamp - data title: Agent Handed Off Event description: >- Emitted when control is transferred to a sub-agent. Contains the target agent ID and the input message for the handoff. AgentMessageCreatedStreamingEvent: type: object properties: type: type: string enum: - event.agents.message-created timestamp: type: string description: ISO timestamp of the event data: type: object properties: workflowRunId: type: string spanId: type: string parentId: type: string message: type: array items: type: object properties: messageId: type: string role: type: string enum: - user - tool parts: type: array items: oneOf: - $ref: '#/components/schemas/TextPart' - $ref: '#/components/schemas/ErrorPart' - $ref: '#/components/schemas/DataPart' - $ref: '#/components/schemas/FilePart' - $ref: '#/components/schemas/ToolCallPart' - $ref: '#/components/schemas/ToolResultPart' discriminator: propertyName: kind mapping: text: $ref: '#/components/schemas/TextPart' error: $ref: '#/components/schemas/ErrorPart' data: $ref: '#/components/schemas/DataPart' file: $ref: '#/components/schemas/FilePart' tool_call: $ref: '#/components/schemas/ToolCallPart' tool_result: $ref: '#/components/schemas/ToolResultPart' metadata: type: object additionalProperties: {} required: - role - parts required: - workflowRunId - spanId - parentId - message required: - type - timestamp - data title: Agent Message Created Event description: >- Emitted when a new message is added to the conversation. Contains the message content, workflow run ID, and span context for tracing. ToolExecutionStartedStreamingEvent: type: object properties: type: type: string enum: - event.workflow_events.tool_execution_started timestamp: type: string description: ISO timestamp of the event data: type: object properties: tool_id: type: string tool_key: type: string tool_display_name: type: string tool_description: type: - string - 'null' action_type: type: string tool_arguments: type: object additionalProperties: {} tool_execution_context: type: object properties: action_id: type: string agent_tool_call_id: type: string workspace_id: type: string agent_manifest_id: type: string agent_execution_id: type: string product: type: string enum: - remoteconfigs - deployments - experiments - playgrounds - spreadsheets - spreadsheet_run - llm_evaluator - knowledge - router - workflows - external_events - agents - memory-stores - generic - evaluators - otel - ai-chat description: Orquesta product memory: type: object properties: entity_id: type: string required: - entity_id parent_id: type: string variables: type: object additionalProperties: {} secret_keys: type: array items: type: string required: - action_id - agent_tool_call_id - workspace_id - agent_manifest_id - agent_execution_id - product responseId: type: string workflowRunId: type: string stream: type: boolean required: - tool_id - action_type - tool_arguments - tool_execution_context - workflowRunId required: - type - timestamp - data title: Tool Execution Started Event description: >- Emitted when a tool begins execution. Contains the tool ID, name, action type, input arguments, and execution context. ToolExecutionFinishedStreamingEvent: type: object properties: type: type: string enum: - event.workflow_events.tool_execution_finished timestamp: type: string description: ISO timestamp of the event data: type: object properties: result: {} action_type: type: string tool_execution_context: type: object properties: action_id: type: string agent_tool_call_id: type: string workspace_id: type: string agent_manifest_id: type: string agent_execution_id: type: string product: type: string enum: - remoteconfigs - deployments - experiments - playgrounds - spreadsheets - spreadsheet_run - llm_evaluator - knowledge - router - workflows - external_events - agents - memory-stores - generic - evaluators - otel - ai-chat description: Orquesta product memory: type: object properties: entity_id: type: string required: - entity_id parent_id: type: string variables: type: object additionalProperties: {} secret_keys: type: array items: type: string required: - action_id - agent_tool_call_id - workspace_id - agent_manifest_id - agent_execution_id - product responseId: type: string workflowRunId: type: string stream: type: boolean required: - action_type - tool_execution_context - workflowRunId required: - type - timestamp - data title: Tool Execution Finished Event description: >- Emitted when a tool completes execution successfully. Contains the result data, action type, and execution context. ToolExecutionFailedStreamingEvent: type: object properties: type: type: string enum: - event.workflow_events.tool_execution_failed timestamp: type: string description: ISO timestamp of the event data: type: object properties: error: type: object properties: message: type: string stack: type: string required: - message action_type: type: string tool_execution_context: type: object properties: action_id: type: string agent_tool_call_id: type: string workspace_id: type: string agent_manifest_id: type: string agent_execution_id: type: string product: type: string enum: - remoteconfigs - deployments - experiments - playgrounds - spreadsheets - spreadsheet_run - llm_evaluator - knowledge - router - workflows - external_events - agents - memory-stores - generic - evaluators - otel - ai-chat description: Orquesta product memory: type: object properties: entity_id: type: string required: - entity_id parent_id: type: string variables: type: object additionalProperties: {} secret_keys: type: array items: type: string required: - action_id - agent_tool_call_id - workspace_id - agent_manifest_id - agent_execution_id - product responseId: type: string workflowRunId: type: string stream: type: boolean required: - error - action_type - tool_execution_context - workflowRunId required: - type - timestamp - data title: Tool Execution Failed Event description: >- Emitted when a tool execution fails. Contains the error details, action type, and execution context. TimeoutStreamingEvent: type: object properties: type: type: string enum: - agents.timeout timestamp: type: string description: ISO timestamp of the event data: type: object properties: message: type: string required: - message required: - type - timestamp - data title: Timeout Event description: >- Emitted when the agent stream exceeds the configured timeout duration. Contains a message describing the timeout condition. ErrorStreamingEvent: type: object properties: type: type: string enum: - agents.error timestamp: type: string description: ISO timestamp of the event data: type: object properties: error: type: string code: type: string required: - error - code required: - type - timestamp - data title: Error Event description: >- Emitted when a streaming error occurs outside of normal agent execution. Contains the error message and error code for debugging. DataPart: type: object properties: kind: type: string enum: - data data: type: object additionalProperties: {} metadata: type: object additionalProperties: {} required: - kind - data title: Data Part description: >- A structured data part containing JSON-serializable key-value pairs. Used for passing structured information between agents and tools. ToolCallPart: type: object properties: kind: type: string enum: - tool_call tool_name: type: string tool_call_id: type: string minLength: 1 arguments: type: object additionalProperties: {} thought_signature: type: string metadata: type: object additionalProperties: {} required: - kind - tool_name - tool_call_id - arguments title: Tool Call Part description: >- A tool invocation request from an agent. Contains the tool name, unique call ID, and arguments for the tool execution. securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````