> ## 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. # Run agent with streaming response > Dynamically configures and executes an agent while streaming the interaction in real-time via Server-Sent Events (SSE). Intelligently manages agent versioning by reusing existing agents with matching configurations or creating new versions when configurations differ. Combines the flexibility of inline configuration with real-time streaming, making it ideal for dynamic agent interactions with live feedback. The stream provides continuous updates including message chunks, tool executions, and status changes until completion or timeout. ## OpenAPI ````yaml post /v2/agents/stream-run 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/stream-run: post: tags: - Agents summary: Run agent with streaming response description: >- Dynamically configures and executes an agent while streaming the interaction in real-time via Server-Sent Events (SSE). Intelligently manages agent versioning by reusing existing agents with matching configurations or creating new versions when configurations differ. Combines the flexibility of inline configuration with real-time streaming, making it ideal for dynamic agent interactions with live feedback. The stream provides continuous updates including message chunks, tool executions, and status changes until completion or timeout. operationId: StreamRunAgent requestBody: required: true content: application/json: schema: type: object properties: key: type: string minLength: 1 pattern: ^[A-Za-z][A-Za-z0-9]*([._-][A-Za-z0-9]+)*$ description: >- 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. 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. model: anyOf: - type: string description: >- 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. - type: object properties: id: type: string description: >- A model ID string (e.g., `openai/gpt-4o` or `anthropic/claude-haiku-4-5-20251001`). Only models that support tool calling can be used with agents. parameters: type: object properties: name: type: string description: >- The name to display on the trace. If not specified, the default system name will be used. frequency_penalty: type: - number - 'null' description: >- Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. max_tokens: type: - integer - 'null' description: >- `[Deprecated]`. The maximum number of tokens that can be generated in the chat completion. This value can be used to control costs for text generated via API. This value is now `deprecated` in favor of `max_completion_tokens`, and is not compatible with o1 series models. max_completion_tokens: type: - integer - 'null' exclusiveMinimum: 0 description: >- An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens presence_penalty: type: - number - 'null' description: >- Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. response_format: oneOf: - type: object properties: type: type: string enum: - text required: - type title: Text description: >- Default response format. Used to generate text responses - type: object properties: type: type: string enum: - json_object required: - type title: JSON object description: >- JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - type: object properties: type: enum: - json_schema type: string json_schema: type: object properties: description: type: string description: >- A description of what the response format is for, used by the model to determine how to respond in the format. name: type: string description: >- The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: description: >- The schema for the response format, described as a JSON Schema object. strict: type: boolean default: false description: >- Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is true. required: - name required: - type - json_schema title: JSON schema description: >- JSON Schema response format. Used to generate structured JSON responses description: >- An object specifying the format that the model must output reasoning_effort: type: string enum: - none - minimal - low - medium - high - xhigh description: >- Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - `xhigh` is currently only supported for `gpt-5.1-codex-max`. Any of "none", "minimal", "low", "medium", "high", "xhigh". verbosity: type: string description: >- Adjusts response verbosity. Lower levels yield shorter answers. seed: type: - number - 'null' description: >- If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result. stop: anyOf: - type: string - type: array items: type: string maxItems: 4 - type: 'null' description: >- Up to 4 sequences where the API will stop generating further tokens. thinking: oneOf: - $ref: >- #/components/schemas/ThinkingConfigDisabledSchema - $ref: >- #/components/schemas/ThinkingConfigEnabledSchema - $ref: >- #/components/schemas/ThinkingConfigAdaptiveSchema discriminator: propertyName: type mapping: disabled: $ref: >- #/components/schemas/ThinkingConfigDisabledSchema enabled: $ref: >- #/components/schemas/ThinkingConfigEnabledSchema adaptive: $ref: >- #/components/schemas/ThinkingConfigAdaptiveSchema temperature: type: - number - 'null' minimum: 0 maximum: 2 description: >- What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. top_p: type: - number - 'null' minimum: 0 maximum: 1 description: >- An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. top_k: type: - number - 'null' description: >- Limits the model to consider only the top k most likely tokens at each step. tool_choice: anyOf: - type: string enum: - none - auto - required - type: object properties: type: type: string enum: - function description: >- The type of the tool. Currently, only function is supported. function: type: object properties: name: type: string description: The name of the function to call. required: - name required: - function description: >- Controls which (if any) tool is called by the model. parallel_tool_calls: type: boolean description: >- Whether to enable parallel function calling during tool use. modalities: type: - array - 'null' items: type: string enum: - text - audio description: >- Output types that you would like the model to generate. Most models are capable of generating text, which is the default: ["text"]. The gpt-4o-audio-preview model can also be used to generate audio. To request that this model generate both text and audio responses, you can use: ["text", "audio"]. guardrails: type: array items: type: object properties: id: anyOf: - type: string enum: - orq_pii_detection - orq_sexual_moderation - orq_harmful_moderation description: The key of the guardrail. - type: string description: >- Unique key or identifier of the evaluator execute_on: type: string enum: - input - output description: >- Determines whether the guardrail runs on the input (user message) or output (model response). required: - id - execute_on description: A list of guardrails to apply to the request. fallbacks: type: array items: type: object properties: model: type: string description: Fallback model identifier example: openai/gpt-4o-mini required: - model description: >- Array of fallback models to use if primary model fails cache: type: object properties: ttl: type: number minimum: 1 maximum: 259200 default: 1800 description: >- Time to live for cached responses in seconds. Maximum 259200 seconds (3 days). example: 3600 type: type: string enum: - exact_match required: - type description: Cache configuration for the request. load_balancer: oneOf: - type: object properties: type: type: string enum: - weight_based models: type: array items: type: object properties: model: type: string description: Model identifier for load balancing example: openai/gpt-4o weight: type: number minimum: 0.001 maximum: 1 default: 0.5 description: >- Weight assigned to this model for load balancing example: 0.7 required: - model required: - type - models description: Load balancer configuration for the request. example: type: weight_based models: - model: openai/gpt-4o weight: 0.7 - model: anthropic/claude-3-5-sonnet weight: 0.3 timeout: type: object properties: call_timeout: type: number minimum: 1 description: Timeout value in milliseconds example: 30000 required: - call_timeout description: >- Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured. description: >- Model behavior parameters that control how the model generates responses. Common parameters: `temperature` (0-1, randomness), `max_completion_tokens` (max output length), `top_p` (sampling diversity). Advanced: `frequency_penalty`, `presence_penalty`, `response_format` (JSON/structured), `reasoning_effort`, `seed` (reproducibility). Support varies by model - consult AI Gateway documentation. retry: type: object properties: count: type: number minimum: 1 maximum: 5 default: 3 description: Number of retry attempts (1-5) example: 3 on_codes: type: array items: type: number minimum: 100 maximum: 599 minItems: 1 default: - 429 description: HTTP status codes that trigger retry logic example: - 429 - 500 - 502 - 503 - 504 description: >- Retry configuration for model requests. Retries are triggered for specific HTTP status codes (e.g., 500, 429, 502, 503, 504). Supports configurable retry count (1-5) and custom status codes. required: - id description: |- Model configuration with parameters and retry settings. title: Model Configuration description: >- Model configuration for this execution. Can override the agent manifest defaults if the agent already exists. fallback_models: type: array items: anyOf: - type: string description: >- A fallback model ID string (e.g., `openai/gpt-4o-mini`). Will be used if the primary model request fails. Must support tool calling. - type: object properties: id: type: string description: >- A fallback model ID string. Must support tool calling. parameters: type: object properties: name: type: string description: >- The name to display on the trace. If not specified, the default system name will be used. frequency_penalty: type: - number - 'null' description: >- Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. max_tokens: type: - integer - 'null' description: >- `[Deprecated]`. The maximum number of tokens that can be generated in the chat completion. This value can be used to control costs for text generated via API. This value is now `deprecated` in favor of `max_completion_tokens`, and is not compatible with o1 series models. max_completion_tokens: type: - integer - 'null' exclusiveMinimum: 0 description: >- An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens presence_penalty: type: - number - 'null' description: >- Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. response_format: oneOf: - type: object properties: type: type: string enum: - text required: - type title: Text description: >- Default response format. Used to generate text responses - type: object properties: type: type: string enum: - json_object required: - type title: JSON object description: >- JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - type: object properties: type: enum: - json_schema type: string json_schema: type: object properties: description: type: string description: >- A description of what the response format is for, used by the model to determine how to respond in the format. name: type: string description: >- The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: description: >- The schema for the response format, described as a JSON Schema object. strict: type: boolean default: false description: >- Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is true. required: - name required: - type - json_schema title: JSON schema description: >- JSON Schema response format. Used to generate structured JSON responses description: >- An object specifying the format that the model must output reasoning_effort: type: string enum: - none - minimal - low - medium - high - xhigh description: >- Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - `xhigh` is currently only supported for `gpt-5.1-codex-max`. Any of "none", "minimal", "low", "medium", "high", "xhigh". verbosity: type: string description: >- Adjusts response verbosity. Lower levels yield shorter answers. seed: type: - number - 'null' description: >- If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result. stop: anyOf: - type: string - type: array items: type: string maxItems: 4 - type: 'null' description: >- Up to 4 sequences where the API will stop generating further tokens. thinking: oneOf: - $ref: >- #/components/schemas/ThinkingConfigDisabledSchema - $ref: >- #/components/schemas/ThinkingConfigEnabledSchema - $ref: >- #/components/schemas/ThinkingConfigAdaptiveSchema discriminator: propertyName: type mapping: disabled: $ref: >- #/components/schemas/ThinkingConfigDisabledSchema enabled: $ref: >- #/components/schemas/ThinkingConfigEnabledSchema adaptive: $ref: >- #/components/schemas/ThinkingConfigAdaptiveSchema temperature: type: - number - 'null' minimum: 0 maximum: 2 description: >- What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. top_p: type: - number - 'null' minimum: 0 maximum: 1 description: >- An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. top_k: type: - number - 'null' description: >- Limits the model to consider only the top k most likely tokens at each step. tool_choice: anyOf: - type: string enum: - none - auto - required - type: object properties: type: type: string enum: - function description: >- The type of the tool. Currently, only function is supported. function: type: object properties: name: type: string description: The name of the function to call. required: - name required: - function description: >- Controls which (if any) tool is called by the model. parallel_tool_calls: type: boolean description: >- Whether to enable parallel function calling during tool use. modalities: type: - array - 'null' items: type: string enum: - text - audio description: >- Output types that you would like the model to generate. Most models are capable of generating text, which is the default: ["text"]. The gpt-4o-audio-preview model can also be used to generate audio. To request that this model generate both text and audio responses, you can use: ["text", "audio"]. guardrails: type: array items: type: object properties: id: anyOf: - type: string enum: - orq_pii_detection - orq_sexual_moderation - orq_harmful_moderation description: The key of the guardrail. - type: string description: >- Unique key or identifier of the evaluator execute_on: type: string enum: - input - output description: >- Determines whether the guardrail runs on the input (user message) or output (model response). required: - id - execute_on description: A list of guardrails to apply to the request. fallbacks: type: array items: type: object properties: model: type: string description: Fallback model identifier example: openai/gpt-4o-mini required: - model description: >- Array of fallback models to use if primary model fails cache: type: object properties: ttl: type: number minimum: 1 maximum: 259200 default: 1800 description: >- Time to live for cached responses in seconds. Maximum 259200 seconds (3 days). example: 3600 type: type: string enum: - exact_match required: - type description: Cache configuration for the request. load_balancer: oneOf: - type: object properties: type: type: string enum: - weight_based models: type: array items: type: object properties: model: type: string description: Model identifier for load balancing example: openai/gpt-4o weight: type: number minimum: 0.001 maximum: 1 default: 0.5 description: >- Weight assigned to this model for load balancing example: 0.7 required: - model required: - type - models description: Load balancer configuration for the request. example: type: weight_based models: - model: openai/gpt-4o weight: 0.7 - model: anthropic/claude-3-5-sonnet weight: 0.3 timeout: type: object properties: call_timeout: type: number minimum: 1 description: Timeout value in milliseconds example: 30000 required: - call_timeout description: >- Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured. description: >- Optional model parameters specific to this fallback model. Overrides primary model parameters if this fallback is used. retry: type: object properties: count: type: number minimum: 1 maximum: 5 default: 3 description: Number of retry attempts (1-5) example: 3 on_codes: type: array items: type: number minimum: 100 maximum: 599 minItems: 1 default: - 429 description: HTTP status codes that trigger retry logic example: - 429 - 500 - 502 - 503 - 504 description: >- Retry configuration for this fallback model. Allows customizing retry count (1-5) and HTTP status codes that trigger retries. required: - id description: >- Fallback model configuration with optional parameters and retry settings. title: Fallback Model Configuration description: >- Fallback model for automatic failover when primary model request fails. Supports optional parameter overrides. Can be a simple model ID string or a configuration object with model-specific parameters. Fallbacks are tried in order. description: >- Optional array of fallback models used when the primary model fails. Fallbacks are attempted in order. All models must support tool calling. role: type: string minLength: 1 description: Specifies the agent's function and area of expertise. instructions: type: string minLength: 1 description: >- Provides context and purpose for the agent. Combined with the system prompt template to generate the agent's instructions. 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 format message containing the task for the agent to perform. 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. path: type: string description: >- Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project. example: Default description: type: string minLength: 1 description: A brief summary of the agent's purpose. system_prompt: type: - string - 'null' minLength: 1 description: >- A custom system prompt template for the agent. If omitted, the default template is used. memory_stores: type: array items: type: string default: [] title: Memory stores description: >- Array of memory store identifiers that are accessible to the agent. Accepts both memory store IDs and keys. knowledge_bases: type: array items: type: object properties: knowledge_id: type: string description: Unique identifier of the knowledge base to search example: customer-knowledge-base required: - knowledge_id default: [] description: Knowledge base configurations for the agent to access team_of_agents: type: array items: type: object properties: key: type: string description: The unique key of the agent within the workspace role: type: string description: >- The role of the agent in this context. This is used to give extra information to the leader to help it decide which agent to hand off to. required: - key default: [] description: >- The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks. settings: type: object properties: tools: type: array items: oneOf: - type: object properties: type: type: string enum: - google_search requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Google search tool description: Performs Google searches to retrieve web content - type: object properties: type: type: string enum: - web_scraper requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Web scraper tool description: Scrapes and extracts content from web pages - type: object properties: type: type: string enum: - call_sub_agent requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Call sub agent tool description: Delegates tasks to specialized sub-agents - type: object properties: type: type: string enum: - retrieve_agents requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Retrieve agents tool description: Retrieves available agents in the system - type: object properties: type: type: string enum: - query_memory_store requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Query memory store tool description: Queries agent memory stores for context - type: object properties: type: type: string enum: - write_memory_store requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Write memory store tool description: Writes information to agent memory stores - type: object properties: type: type: string enum: - retrieve_memory_stores requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Retrieve memory stores tool description: Lists available memory stores - type: object properties: type: type: string enum: - delete_memory_document requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Delete memory document tool description: Deletes documents from memory stores - type: object properties: type: type: string enum: - retrieve_knowledge_bases requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Retrieve knowledge bases tool description: Lists available knowledge bases - type: object properties: type: type: string enum: - query_knowledge_base requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Query knowledge base tool description: Queries knowledge bases for information - type: object properties: type: type: string enum: - current_date requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Current date tool description: Returns the current date and time - type: object properties: type: type: string enum: - http key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI _id: type: string display_name: type: string description: type: string description: >- A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision. http: type: object properties: blueprint: type: object properties: url: type: string description: The URL to send the request to. method: type: string enum: - GET - POST - PUT - DELETE description: The HTTP method to use. headers: type: object additionalProperties: anyOf: - type: string - type: object properties: value: type: string encrypted: type: boolean default: false required: - value default: Content-Type: value: application/json encrypted: false description: >- The headers to send with the request. Can be a string value or an object with value and encrypted properties. body: type: object additionalProperties: {} description: The body to send with the request. required: - url - method description: >- The blueprint for the HTTP request. The `arguments` field will be used to replace the placeholders in the `url`, `headers`, `body`, and `arguments` fields. arguments: type: object additionalProperties: type: object properties: type: type: string enum: - string - number - boolean description: The type of the argument. description: type: string description: A description of the argument. send_to_model: type: boolean default: true description: >- Whether to send the argument to the model. If set to false, the argument will not be sent to the model and needs to be provided by the user or it will be left blank. default_value: anyOf: - type: string - type: number - type: boolean description: The default value of the argument. required: - type - description description: >- The arguments to send with the request. The keys will be used to replace the placeholders in the `blueprint` field. required: - blueprint requires_approval: type: boolean default: false required: - type - key - description - http title: HTTP Tool (Run) description: >- HTTP tool with inline definition for on-the-fly creation in run endpoint - type: object properties: type: type: string enum: - code key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI _id: type: string display_name: type: string description: type: string description: >- A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision. code_tool: type: object properties: parameters: type: object properties: type: type: string enum: - object description: The type must be "object" properties: type: object additionalProperties: {} description: >- The properties of the function parameters required: type: array items: type: string description: Array of required parameter names required: - type - properties - required additionalProperties: {} description: >- The parameters the functions accepts, described as a JSON Schema object. See the `OpenAI` [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. language: type: string enum: - python code: type: string minLength: 1 description: The code to execute. required: - language - code requires_approval: type: boolean default: false required: - type - key - description - code_tool title: Code Tool (Run) description: >- Code execution tool with inline definition for on-the-fly creation in run endpoint - type: object properties: type: type: string enum: - function key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI _id: type: string display_name: type: string description: type: string 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. description: type: string description: >- A description of what the function does, used by the model to choose when and how to call the function. strict: type: boolean description: >- Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Currently only compatible with `OpenAI` models. parameters: type: object properties: type: type: string enum: - object description: The type must be "object" properties: type: object additionalProperties: {} description: >- The properties of the function parameters required: type: array items: type: string description: Array of required parameter names required: - type - properties - required additionalProperties: {} description: >- The parameters the functions accepts, described as a JSON Schema object. See the `OpenAI` [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. required: - name requires_approval: type: boolean default: false required: - type - key - function title: Function Tool (Run) description: >- Function tool with inline definition for on-the-fly creation in run endpoint - type: object properties: type: enum: - json_schema type: string key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI _id: type: string display_name: type: string description: type: string description: >- A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision. json_schema: type: object properties: name: type: string minLength: 1 maxLength: 64 description: >- The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. description: type: string description: >- A description of what the response format is for. This will be shown to the user. schema: type: object properties: type: type: string description: The JSON Schema type properties: type: object additionalProperties: {} description: The properties of the JSON Schema object required: type: array items: type: string description: Array of required property names required: - type - properties - required additionalProperties: {} description: >- The schema for the response format, described as a JSON Schema object. See the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. strict: type: boolean description: >- Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. Only compatible with `OpenAI` models. required: - name - description - schema requires_approval: type: boolean default: false required: - type - key - description - json_schema title: JSON Schema Tool (Run) description: >- JSON Schema tool with inline definition for on-the-fly creation in run endpoint - type: object properties: type: enum: - mcp type: string key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI _id: type: string display_name: type: string description: type: string description: >- A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision. mcp: type: object properties: server_url: type: string format: uri description: The MCP server URL (cached for execution) headers: type: object additionalProperties: type: object properties: value: type: string encrypted: type: boolean default: false required: - value default: {} description: >- HTTP headers for MCP server requests with encryption support tools: type: array items: type: object properties: id: type: string default: 01KRM5REDK2E8QG6RVZ0Z6FHEB name: type: string description: type: string schema: type: object properties: type: type: string enum: - object properties: type: object additionalProperties: {} required: type: array items: type: string required: - type required: - name - schema description: >- Array of tools available from the MCP server connection_type: type: string enum: - http - sse description: The connection type used by the MCP server template_variables: type: - array - 'null' items: type: string description: >- Names of template variables detected in server_url and headers. Used by the FE to prompt for one-time values on sync/refresh. readOnly: true required: - server_url - tools - connection_type requires_approval: type: boolean default: false required: - type - key - description - mcp title: MCP Tool (Run) description: >- MCP tool with inline definition for on-the-fly creation in run endpoint description: >- Tool configuration for agent run operations. Built-in tools only require a type and requires_approval, while custom tools (HTTP, Code, Function, JSON Schema, MCP) support full inline definitions for on-the-fly creation. title: Agent Tool Input (Run) default: [] description: Tools available to the agent tool_approval_required: type: string enum: - all - respect_tool - none default: none 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. 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 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 metadata: type: object additionalProperties: {} description: >- Optional metadata for the agent run as key-value pairs that will be included in traces engine: type: string enum: - text - jinja - mustache default: text description: >- Template engine for variable interpolation. Text uses {{variable}} syntax, Jinja supports loops/conditionals/filters, Mustache uses {{#section}} syntax. stream_timeout_seconds: type: number minimum: 1 maximum: 3600 description: >- Stream timeout in seconds (1-3600). Default: 1800 (30 minutes) required: - key - model - role - instructions - message - path - settings responses: '200': description: >- Server-Sent Event stream successfully established. Delivers real-time agent execution events including message fragments, tool invocations, intermediate results, and completion status. Stream terminates with [DONE] sentinel upon completion. 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: Model not found content: application/json: schema: type: object properties: message: type: string required: - message deprecated: true components: schemas: ThinkingConfigDisabledSchema: type: object properties: type: type: string enum: - disabled description: Disables the thinking mode capability required: - type title: Thinking config disabled description: Disables the thinking mode capability ThinkingConfigEnabledSchema: type: object properties: type: type: string enum: - enabled description: Enables or disables the thinking mode capability budget_tokens: type: number description: >- Determines how many tokens the model can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. Must be ≥1024 and less than `max_tokens`. thinking_level: type: string enum: - low - medium - high description: >- The level of reasoning the model should use. This setting is supported only by `gemini-3` models. If budget_tokens is specified and `thinking_level` is available, `budget_tokens` will be ignored. required: - type - budget_tokens title: Thinking config enabled description: Enables the thinking mode capability ThinkingConfigAdaptiveSchema: type: object properties: type: type: string enum: - adaptive description: >- Lets the model dynamically determine when and how much to use extended thinking based on the complexity of each request. Supported on Claude Opus 4.6 and Sonnet 4.6. required: - type title: Thinking config adaptive description: >- Enables adaptive thinking mode where the model dynamically determines thinking depth 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 ````