---
title: "Run agent with streaming response"
method: POST
path: "/v2/agents/stream-run"
tags: ["Agents"]
deprecated: true
---

# Run agent with streaming response

`POST /v2/agents/stream-run`

> **Deprecated.**

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.

## Request body

- object
  - `key` string, required — A unique identifier for the agent. This key must be unique within the same workspace and cannot be reused. When executing the agent, this key determines if the agent already exists. If the agent version differs, a new version is created at the end of the execution, except for the task. All agent parameters are evaluated to decide if a new version is needed.
  - `task_id` string — Optional task ID to continue an existing agent execution. When provided, the agent will continue the conversation from the existing task state. The task must be in an inactive state to continue.
  - `model` union, required — Model configuration for this execution. Can override the agent manifest defaults if the agent already exists.
    - string — 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.
    - object — Model configuration with parameters and retry settings.
      - `id` string, required — 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` object — 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.
        - `name` string — The name to display on the trace. If not specified, the default system name will be used.
        - `frequency_penalty` number, nullable — 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` integer, nullable — `[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` integer, nullable — An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens
        - `presence_penalty` number, nullable — 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` union — An object specifying the format that the model must output
          - object — Default response format. Used to generate text responses
            - `type` 'text', required
          - object — 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` 'json_object', required
          - object — JSON Schema response format. Used to generate structured JSON responses
            - `type` 'json_schema', required
            - `json_schema` object, required
              - …
        - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' — 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` string — Adjusts response verbosity. Lower levels yield shorter answers.
        - `seed` number, nullable — 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` union — Up to 4 sequences where the API will stop generating further tokens.
          - string
          - string[]
        - `thinking` union
          - ThinkingConfigDisabledSchema — Disables the thinking mode capability
            - `type` 'disabled', required — Disables the thinking mode capability
          - ThinkingConfigEnabledSchema — Enables the thinking mode capability
            - `type` 'enabled', required — Enables or disables the thinking mode capability
            - `budget_tokens` number, required — 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` 'minimal' | 'low' | 'medium' | 'high' — 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.
          - ThinkingConfigAdaptiveSchema — Enables adaptive thinking mode where the model dynamically determines thinking depth
            - `type` 'adaptive', required — 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.
        - `temperature` number, nullable — 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` number, nullable — 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` number, nullable — Limits the model to consider only the top k most likely tokens at each step.
        - `tool_choice` union — Controls which (if any) tool is called by the model.
          - 'none' | 'auto' | 'required'
          - object
            - `type` 'function' — The type of the tool. Currently, only function is supported.
            - `function` object, required
              - …
        - `parallel_tool_calls` boolean — Whether to enable parallel function calling during tool use.
        - `modalities` string[], nullable — 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` object[] — A list of guardrails to apply to the request.
          - `id` union, required
            - 'orq_pii_detection' | 'orq_secret_detection' | 'orq_sexual_moderation' | 'orq_harmful_moderation' — The key of the guardrail.
            - string — Unique key or identifier of the evaluator
          - `execute_on` 'input' | 'output', required — Determines whether the guardrail runs on the input (user message) or output (model response).
        - `plugins` union[] — Request-scoped transforms applied to the text exchanged with the model. Supports `pii_redaction`, which replaces PII with placeholders before the provider sees it and restores the original values in the response, and `response_healing`, which repairs malformed JSON in non-streaming output.
          - union
            - PIIRedactionPluginAuto
              - …
            - PIIRedactionPluginEn
              - …
            - PIIRedactionPluginNl
              - …
            - ResponseHealingPlugin
              - …
        - `fallbacks` object[] — Array of fallback models to use if primary model fails
          - `model` string, required — Fallback model identifier
        - `cache` object — Cache configuration for the request.
          - `ttl` number — Time to live for cached responses in seconds. Maximum 259200 seconds (3 days).
          - `type` 'exact_match', required
        - `load_balancer` object — Load balancer configuration for the request.
          - `type` 'weight_based', required
          - `models` object[], required
            - `model` string, required — Model identifier for load balancing
            - `weight` number — Weight assigned to this model for load balancing
        - `timeout` object — 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.
          - `call_timeout` number, required — Timeout value in milliseconds
        - `cache_control` object — Provider-level prompt caching configuration applied to the request. Creates a cache control breakpoint covering the request content. Only supported by `Anthropic` Claude models.
          - `type` 'ephemeral', required — Create a cache control breakpoint at this content block. Accepts only the value "ephemeral".
          - `ttl` '5m' | '1h' — The time-to-live for the cache control breakpoint. This may be one of the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. Only supported by `Anthropic` Claude models.
        - `prompt_cache_key` string — Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the legacy `user` field for prompt caching.
      - `retry` object — 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.
        - `count` number — Number of retry attempts (1-5)
        - `on_codes` number[] — HTTP status codes that trigger retry logic
  - `fallback_models` union[] — Optional array of fallback models used when the primary model fails. Fallbacks are attempted in order. All models must support tool calling.
    - union — 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.
      - string — A fallback model ID string (e.g., `openai/gpt-4o-mini`). Will be used if the primary model request fails. Must support tool calling.
      - object — Fallback model configuration with optional parameters and retry settings.
        - `id` string, required — A fallback model ID string. Must support tool calling.
        - `parameters` object — Optional model parameters specific to this fallback model. Overrides primary model parameters if this fallback is used.
          - `name` string — The name to display on the trace. If not specified, the default system name will be used.
          - `frequency_penalty` number, nullable — 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` integer, nullable — `[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` integer, nullable — An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens
          - `presence_penalty` number, nullable — 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` union — An object specifying the format that the model must output
            - object — Default response format. Used to generate text responses
              - …
            - object — 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.
              - …
            - object — JSON Schema response format. Used to generate structured JSON responses
              - …
          - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' — 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` string — Adjusts response verbosity. Lower levels yield shorter answers.
          - `seed` number, nullable — 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` union — Up to 4 sequences where the API will stop generating further tokens.
            - string
            - string[]
          - `thinking` union
            - ThinkingConfigDisabledSchema — Disables the thinking mode capability
              - …
            - ThinkingConfigEnabledSchema — Enables the thinking mode capability
              - …
            - ThinkingConfigAdaptiveSchema — Enables adaptive thinking mode where the model dynamically determines thinking depth
              - …
          - `temperature` number, nullable — 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` number, nullable — 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` number, nullable — Limits the model to consider only the top k most likely tokens at each step.
          - `tool_choice` union — Controls which (if any) tool is called by the model.
            - 'none' | 'auto' | 'required'
            - object
              - …
          - `parallel_tool_calls` boolean — Whether to enable parallel function calling during tool use.
          - `modalities` string[], nullable — 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` object[] — A list of guardrails to apply to the request.
            - `id` union, required
              - …
            - `execute_on` 'input' | 'output', required — Determines whether the guardrail runs on the input (user message) or output (model response).
          - `plugins` union[] — Request-scoped transforms applied to the text exchanged with the model. Supports `pii_redaction`, which replaces PII with placeholders before the provider sees it and restores the original values in the response, and `response_healing`, which repairs malformed JSON in non-streaming output.
            - union
              - …
          - `fallbacks` object[] — Array of fallback models to use if primary model fails
            - `model` string, required — Fallback model identifier
          - `cache` object — Cache configuration for the request.
            - `ttl` number — Time to live for cached responses in seconds. Maximum 259200 seconds (3 days).
            - `type` 'exact_match', required
          - `load_balancer` object — Load balancer configuration for the request.
            - `type` 'weight_based', required
            - `models` object[], required
              - …
          - `timeout` object — 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.
            - `call_timeout` number, required — Timeout value in milliseconds
          - `cache_control` object — Provider-level prompt caching configuration applied to the request. Creates a cache control breakpoint covering the request content. Only supported by `Anthropic` Claude models.
            - `type` 'ephemeral', required — Create a cache control breakpoint at this content block. Accepts only the value "ephemeral".
            - `ttl` '5m' | '1h' — The time-to-live for the cache control breakpoint. This may be one of the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. Only supported by `Anthropic` Claude models.
          - `prompt_cache_key` string — Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the legacy `user` field for prompt caching.
        - `retry` object — Retry configuration for this fallback model. Allows customizing retry count (1-5) and HTTP status codes that trigger retries.
          - `count` number — Number of retry attempts (1-5)
          - `on_codes` number[] — HTTP status codes that trigger retry logic
  - `role` string, required — Specifies the agent's function and area of expertise.
  - `instructions` string, required — Provides context and purpose for the agent. Combined with the system prompt template to generate the agent's instructions.
  - `message` object, required — The A2A format message containing the task for the agent to perform.
    - `messageId` string — Optional A2A message ID in ULID format
    - `role` union, required — Message role (user or tool for continuing executions)
      - 'user' — Message from the end user
      - 'tool' — Message containing tool execution results
    - `parts` union[], required — A2A message parts (text, file, or tool_result only). Note: Tool role messages must only contain tool_result parts.
      - union — 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.
        - object — Text content part. Use this to send text messages to the agent.
          - `kind` 'text', required
          - `text` string, required
        - object — File attachment part. Use this to send files (images, documents, etc.) to the agent for processing.
          - `kind` 'file', required
          - `file` union, required
            - object — Binary in base64 format. Check in the model's documentation for the supported mime types for the binary format.
              - …
            - object — File in URI format. Check in the model's documentation for the supported mime types for the URI format
              - …
          - `metadata` object
        - object — 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.
          - `kind` 'tool_result', required
          - `tool_call_id` string, required
          - `result` unknown
          - `metadata` object
        - object — Error content part. Generated by the system when an error occurs during agent execution.
          - `kind` 'error', required
          - `error` string, required
          - `code` number
  - `variables` object — Optional variables for template replacement in system prompt, instructions, and messages
  - `identity` object — Information about the identity making the request. If the identity does not exist, it will be created automatically.
    - `id` string, required — Unique identifier for the contact
    - `display_name` string — Display name of the contact
    - `email` string, email — Email address of the contact
    - `metadata` object[] — A hash of key/value pairs containing any other data about the contact
    - `logo_url` string — URL to the contact's avatar or logo
    - `tags` string[] — A list of tags associated with the contact
  - `contact` object — @deprecated Use identity instead. Information about the contact making the request.
    - `id` string, required — Unique identifier for the contact
    - `display_name` string — Display name of the contact
    - `email` string, email — Email address of the contact
    - `metadata` object[] — A hash of key/value pairs containing any other data about the contact
    - `logo_url` string — URL to the contact's avatar or logo
    - `tags` string[] — A list of tags associated with the contact
  - `thread` object — Thread information to group related requests
    - `id` string, required — Unique thread identifier to group related invocations.
    - `tags` string[] — Optional tags to differentiate or categorize threads
  - `memory` object — Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.
    - `entity_id` string, required — 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.
  - `path` string, required — 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.
  - `description` string — A brief summary of the agent's purpose.
  - `system_prompt` string, nullable — A custom system prompt template for the agent. If omitted, the default template is used.
  - `memory_stores` string[] — Array of memory store identifiers that are accessible to the agent. Accepts both memory store IDs and keys.
  - `knowledge_bases` object[] — Knowledge base configurations for the agent to access
    - `knowledge_id` string, required — Unique identifier of the knowledge base to search
  - `team_of_agents` object[] — The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks.
    - `key` string, required — The unique key of the agent within the workspace
    - `role` string — 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.
  - `settings` object, required
    - `tools` union[] — Tools available to the agent
      - union — 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.
        - object — Performs Google searches to retrieve web content
          - `type` 'google_search', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Scrapes and extracts content from web pages
          - `type` 'web_scraper', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Delegates tasks to specialized sub-agents
          - `type` 'call_sub_agent', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Retrieves available agents in the system
          - `type` 'retrieve_agents', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Queries agent memory stores for context
          - `type` 'query_memory_store', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Writes information to agent memory stores
          - `type` 'write_memory_store', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Lists available memory stores
          - `type` 'retrieve_memory_stores', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Deletes documents from memory stores
          - `type` 'delete_memory_document', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Lists available knowledge bases
          - `type` 'retrieve_knowledge_bases', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Queries knowledge bases for information
          - `type` 'query_knowledge_base', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Returns the current date and time
          - `type` 'current_date', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Consult a secondary model for advice on the current task
          - `type` 'advisor', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Delegate a subtask to a secondary model for execution
          - `type` 'sidekick', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — Executes model-written Python code. Uses provider-native code execution when the model supports it, otherwise a secure orq-managed sandbox.
          - `type` 'code_interpreter', required
          - `requires_approval` boolean — Whether this tool requires approval before execution
          - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time.
        - object — HTTP tool with inline definition for on-the-fly creation in run endpoint
          - `type` 'http', required
          - `key` string, required — Unique key of the tool as it will be displayed in the UI
          - `_id` string
          - `display_name` string
          - `description` string, required — 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` object, required
            - `blueprint` object, required — 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` object — The arguments to send with the request. The keys will be used to replace the placeholders in the `blueprint` field.
          - `requires_approval` boolean
          - `timeout` number — Tool execution timeout in seconds for this agent (max: 10 minutes). Overrides the timeout configured on the tool definition.
        - object — Code execution tool with inline definition for on-the-fly creation in run endpoint
          - `type` 'code', required
          - `key` string, required — Unique key of the tool as it will be displayed in the UI
          - `_id` string
          - `display_name` string
          - `description` string, required — 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` object, required
            - `parameters` object — 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` 'python', required
            - `code` string, required — The code to execute.
          - `requires_approval` boolean
          - `timeout` number — Tool execution timeout in seconds for this agent (max: 2 minutes, the code sandbox cap). Overrides the timeout configured on the tool definition.
        - object — Function tool with inline definition for on-the-fly creation in run endpoint
          - `type` 'function', required
          - `key` string, required — Unique key of the tool as it will be displayed in the UI
          - `_id` string
          - `display_name` string
          - `description` string
          - `function` object, required
            - `name` string, required — 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` string — A description of what the function does, used by the model to choose when and how to call the function.
            - `strict` boolean — 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` object — 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.
              - …
          - `requires_approval` boolean
        - object — JSON Schema tool with inline definition for on-the-fly creation in run endpoint
          - `type` 'json_schema', required
          - `key` string, required — Unique key of the tool as it will be displayed in the UI
          - `_id` string
          - `display_name` string
          - `description` string, required — 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` object, required
            - `name` string, required — 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` string, required — A description of what the response format is for. This will be shown to the user.
            - `schema` object, required — 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` boolean — 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.
          - `requires_approval` boolean
        - object — MCP tool with inline definition for on-the-fly creation in run endpoint
          - `type` 'mcp', required
          - `key` string, required — Unique key of the tool as it will be displayed in the UI
          - `_id` string
          - `display_name` string
          - `description` string, required — 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` object, required
            - `server_url` string, uri, required — The MCP server URL (cached for execution)
            - `headers` object — HTTP headers for MCP server requests with encryption support
            - `tools` object[], required — Array of tools available from the MCP server
              - …
            - `connection_type` 'http' | 'sse', required — The connection type used by the MCP server
            - `template_variables` string[], nullable — Names of template variables detected in server_url and headers. Used by the FE to prompt for one-time values on sync/refresh.
          - `requires_approval` boolean
    - `tool_approval_required` 'all' | 'respect_tool' | 'none' — 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` integer — Maximum iterations(llm calls) before the agent will stop executing.
    - `max_execution_time` integer — 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` number — 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
    - `chat_exposed` boolean — When enabled, this agent is exposed as a selectable target in AI Chat for users to consume.
    - `evaluators` object[] — Configuration for an evaluator applied to the agent
      - `id` string, required — Unique key or identifier of the evaluator
      - `sample_rate` number — 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` 'input' | 'output', required — Determines whether the evaluator runs on the agent input (user message) or output (agent response).
    - `guardrails` object[] — Configuration for a guardrail applied to the agent
      - `id` string, required — Unique key or identifier of the evaluator
      - `sample_rate` number — 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` 'input' | 'output', required — Determines whether the evaluator runs on the agent input (user message) or output (agent response).
  - `metadata` object — Optional metadata for the agent run as key-value pairs that will be included in traces
  - `engine` 'text' | 'jinja' | 'mustache' — Template engine for variable interpolation. Text uses {{variable}} syntax, Jinja supports loops/conditionals/filters, Mustache uses {{#section}} syntax.
  - `stream_timeout_seconds` number — Stream timeout in seconds (1-3600). Default: 1800 (30 minutes)

## Response `200`

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.

## Other responses

- `404` — Model not found

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/versions/41c02aedc7c0/schema)