> ## 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. # Update agent > Modifies an existing agent's configuration with partial updates. Supports updating any aspect of the agent including model assignments (primary and fallback), instructions, tools, knowledge bases, memory stores, and execution parameters. Only the fields provided in the request body will be updated; all other fields remain unchanged. Changes take effect immediately for new agent invocations. ## OpenAPI ````yaml patch /v2/agents/{agent_key} 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/{agent_key}: patch: tags: - Agents summary: Update agent description: >- Modifies an existing agent's configuration with partial updates. Supports updating any aspect of the agent including model assignments (primary and fallback), instructions, tools, knowledge bases, memory stores, and execution parameters. Only the fields provided in the request body will be updated; all other fields remain unchanged. Changes take effect immediately for new agent invocations. operationId: UpdateAgent parameters: - schema: type: string description: The unique key of the agent to update required: true description: The unique key of the agent to update name: agent_key in: path requestBody: required: true content: application/json: schema: type: object properties: key: type: string pattern: ^[A-Za-z][A-Za-z0-9]*([._-][A-Za-z0-9]+)*$ display_name: type: string project_id: type: string role: type: string minLength: 1 description: type: string minLength: 1 description: A brief description of what the agent does instructions: type: string system_prompt: type: - string - 'null' minLength: 1 description: >- A custom system prompt template for the agent. If omitted, the default template is used. 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 agent execution. Can be a simple model ID string or a configuration object with optional behavior parameters and retry settings. 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. settings: type: object properties: max_iterations: type: integer exclusiveMinimum: 0 maximum: 100 minimum: 1 max_execution_time: type: integer minimum: 2 exclusiveMinimum: 0 maximum: 600 max_cost: type: number minimum: 0 tool_approval_required: type: string enum: - all - respect_tool - none tools: type: array items: anyOf: - 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 default: http description: HTTP tool type key: type: string description: The key of the pre-created HTTP tool id: type: string description: The ID of the pre-created HTTP tool requires_approval: type: boolean default: false description: >- Whether this tool requires approval before execution title: HTTP Tool description: >- Executes HTTP requests to interact with external APIs and web services. Must reference a pre-created HTTP tool by key or id. - type: object properties: type: type: string enum: - code default: code description: Code execution tool type key: type: string description: The key of the pre-created code tool id: type: string description: The ID of the pre-created code tool requires_approval: type: boolean default: false description: >- Whether this tool requires approval before execution title: Code Execution Tool description: >- Executes code snippets in a sandboxed environment. Must reference a pre-created code tool by key or id. - type: object properties: type: type: string enum: - function default: function description: Function tool type key: type: string description: The key of the pre-created function tool id: type: string description: The ID of the pre-created function tool requires_approval: type: boolean default: false description: >- Whether this tool requires approval before execution title: Function Tool description: >- Calls custom function tools defined in the agent configuration. Must reference a pre-created function tool by key or id. - type: object properties: type: type: string enum: - json_schema default: json_schema description: JSON Schema tool type key: type: string description: The key of the pre-created JSON Schema tool id: type: string description: The ID of the pre-created JSON Schema tool requires_approval: type: boolean default: false description: >- Whether this tool requires approval before execution title: JSON Schema Tool description: >- Enforces structured output format using JSON Schema. Must reference a pre-created JSON Schema tool by key or id. - type: object properties: type: type: string enum: - mcp default: mcp description: MCP tool type key: type: string description: The key of the parent MCP tool id: type: string description: The ID of the parent MCP tool tool_id: type: string description: >- The ID of the specific nested tool within the MCP server requires_approval: type: boolean default: false description: >- Whether this tool requires approval before execution required: - tool_id title: MCP Tool description: >- Executes tools from Model Context Protocol (MCP) servers. Specify the parent MCP tool using "key" or "id", and the specific nested tool using "tool_id". example: type: mcp id: 01KA84ND5J0SWQMA2Q8HY5WZZZ tool_id: 01KXYZ123456789 requires_approval: false - type: object properties: type: type: string pattern: ^[a-z][a-z0-9_-]*:.+$ description: Provider-prefixed tool type requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Provider Built-in Tool description: >- Provider-specific built-in tools that are passed through to the provider. Must be prefixed with the provider name (e.g., openai:web_search, anthropic:web_search_20250305, google:google_search). example: type: openai:web_search description: >- Tool configuration for agent create/update operations. Built-in tools only require a type, while custom tools (HTTP, Code, Function, JSON Schema, MCP) must reference pre-created tools by key or id. Provider-prefixed tools (e.g., openai:web_search) are passed through to the provider. title: Agent Tool Input (CRUD) 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 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 memory_stores: type: array items: type: string description: >- Array of memory store identifiers. 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 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 title: Team of agents description: >- The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks. skills: type: - array - 'null' items: type: string description: >- List of skills that the agent can utilize. This field allows you to specify which skills the agent has access to, enabling more complex and dynamic behavior. variables: type: object additionalProperties: {} description: Extracted variables from agent instructions engine: type: string enum: - text - jinja - mustache a2a: type: object properties: agent_url: type: string format: uri description: Update the A2A agent endpoint URL card_url: type: string format: uri description: Update the explicit agent card URL headers: type: object description: >- Update HTTP headers for authentication. **Credential preservation**: Use empty string ("") for encrypted header values to keep existing credentials without re-entry. Provide new values to rotate credentials. Omit headers entirely to remove them. additionalProperties: type: object properties: value: type: string maxLength: 2048 description: >- Header value. **Update behavior**: Provide empty string ("") to preserve existing encrypted value without re-entering credentials. Provide new value to rotate. Omit header entirely to remove. encrypted: type: boolean default: false required: - value title: Update A2A Configuration description: >- Update A2A agent configuration (only applicable to A2A agents) versionIncrement: type: string enum: - major - minor - patch description: >- Optional semantic version bump to create after a successful publish. versionDescription: type: string maxLength: 300 description: Optional description stored with the created version. responses: '200': description: >- Agent configuration successfully updated. Returns the complete updated agent manifest reflecting all changes made. content: application/json: schema: type: object properties: _id: type: string key: type: string pattern: ^[A-Za-z][A-Za-z0-9]*([._-][A-Za-z0-9]+)*$ description: Unique identifier for the agent within the workspace display_name: type: string project_id: type: string created_by_id: type: - string - 'null' updated_by_id: type: - string - 'null' created: type: string updated: type: string status: type: string enum: - live - draft - pending - published description: >- The status of the agent. `Live` is the latest version of the agent. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version. version: type: string description: Current semantic version of the agent manifest. 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 memory_stores: type: array items: type: string default: [] description: >- Array of memory store identifiers. Accepts both memory store IDs and keys. 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. skills: type: array items: type: string description: >- List of skills that the agent can utilize. This field allows you to specify which skills the agent has access to, enabling more complex and dynamic behavior. metrics: type: object properties: total_cost: type: number minimum: 0 default: 0 default: total_cost: 0 variables: type: object additionalProperties: {} description: Extracted variables from agent instructions 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 description: Agent knowledge bases reference source: type: string enum: - internal - external - experiment engine: type: string enum: - text - jinja - mustache default: text type: type: string enum: - internal - a2a default: internal description: >- Agent type: internal (Orquesta-managed) or a2a (external A2A-compliant) role: type: string minLength: 1 description: type: string system_prompt: type: - string - 'null' minLength: 1 instructions: 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: [] model: type: object properties: id: type: string description: The database ID of the primary model integration_id: type: - string - 'null' description: >- Optional integration ID for custom model configurations 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 (snake_case) stored as part of the agent configuration. These become the default parameters used when the agent is executed. Commonly used: temperature (0-1, controls randomness), max_completion_tokens (response length), top_p (nucleus sampling). Advanced: frequency_penalty, presence_penalty, response_format (JSON/structured output), reasoning_effort (for o1/thinking models), seed (reproducibility), stop sequences. Model-specific support varies. Runtime parameters in agent execution requests can override these defaults. 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. Allows customizing retry count (1-5) and HTTP status codes that trigger retries. Default codes: [429]. Common codes: 500 (internal error), 429 (rate limit), 502/503/504 (gateway errors). fallback_models: type: - array - 'null' 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 (string IDs or config objects) that will be used automatically in order if the primary model fails required: - id a2a: type: object properties: agent_url: type: string format: uri description: >- The A2A agent endpoint URL (e.g., https://example.com/agent/a2a) card_url: type: string format: uri description: >- Optional explicit URL to fetch agent card. Defaults to {agent_url}/card if not provided headers: type: object description: >- HTTP headers for A2A agent requests with encryption support (max 20 headers). **Update behavior**: Empty string values preserve existing encrypted headers, allowing partial updates without credential re-entry. additionalProperties: type: object properties: value: type: string maxLength: 2048 description: >- Header value. **Update behavior**: Provide empty string ("") to preserve existing encrypted value without re-entering credentials. Provide new value to rotate. Omit header entirely to remove. encrypted: type: boolean default: false required: - value cached_card: description: >- Cached agent card from discovery. Refreshed periodically. required: - agent_url title: A2A Agent Configuration description: >- A2A configuration with agent endpoint and authentication. Only present for A2A agents. required: - _id - key - project_id - status - path - skills - role - description - instructions - model '404': description: >- Agent not found. The specified agent key does not exist in the workspace or you do not have permission to modify it. content: application/json: schema: type: object properties: message: type: string required: - message 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 securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````