> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run an agent with configuration > Executes an agent using inline configuration or references an existing agent. Supports dynamic agent creation where the system automatically manages agent versioning - reusing existing agents with matching configurations or creating new versions when configurations differ. Ideal for programmatic agent execution with flexible configuration management. The agent processes messages in A2A format with support for memory context, tool execution, and automatic model fallback on failure. ## OpenAPI ````yaml post /v2/agents/run openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - name: Guardrail Rules - name: Policies - name: Routing Rules - name: Files description: File upload and retrieval operations. - name: FilesService - name: Projects description: Projects organize resources within a workspace - name: ProjectsService - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: SkillsService - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. - name: ReportingService description: |- ReportingService exposes a single QueryReport RPC that maps allowlisted analytics payloads onto safe rollup queries. Callers never send SQL; the backend picks the rollup family and grain from the metric catalogue, the requested range, and the requested grouping. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/agents/run: post: tags: - Agents summary: Run an agent with configuration description: >- Executes an agent using inline configuration or references an existing agent. Supports dynamic agent creation where the system automatically manages agent versioning - reusing existing agents with matching configurations or creating new versions when configurations differ. Ideal for programmatic agent execution with flexible configuration management. The agent processes messages in A2A format with support for memory context, tool execution, and automatic model fallback on failure. operationId: RunAgent requestBody: required: true content: application/json: schema: type: object properties: key: type: string minLength: 1 pattern: ^[A-Za-z][A-Za-z0-9]*([._-][A-Za-z0-9]+)*$ description: >- A unique identifier for the agent. This key must be unique within the same workspace and cannot be reused. When executing the agent, this key determines if the agent already exists. If the agent version differs, a new version is created at the end of the execution, except for the task. All agent parameters are evaluated to decide if a new version is needed. task_id: type: string description: >- Optional task ID to continue an existing agent execution. When provided, the agent will continue the conversation from the existing task state. The task must be in an inactive state to continue. model: anyOf: - type: string description: >- A model ID string (e.g., `openai/gpt-4o` or `anthropic/claude-haiku-4-5-20251001`). The agent can be run with a wide range of models with different capabilities, performance characteristics, and price points. Only models that support tool calling (function_calling) can be used to run agents. See (supported models)[/docs/proxy/supported-models] documentation for the complete list of available models. - type: object properties: id: type: string description: >- A model ID string (e.g., `openai/gpt-4o` or `anthropic/claude-haiku-4-5-20251001`). Only models that support tool calling can be used with agents. parameters: type: object properties: name: type: string description: >- The name to display on the trace. If not specified, the default system name will be used. frequency_penalty: type: - number - 'null' description: >- Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. max_tokens: type: - integer - 'null' description: >- `[Deprecated]`. The maximum number of tokens that can be generated in the chat completion. This value can be used to control costs for text generated via API. This value is now `deprecated` in favor of `max_completion_tokens`, and is not compatible with o1 series models. max_completion_tokens: type: - integer - 'null' exclusiveMinimum: 0 description: >- An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens presence_penalty: type: - number - 'null' description: >- Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. response_format: oneOf: - type: object properties: type: type: string enum: - text required: - type title: Text description: >- Default response format. Used to generate text responses - type: object properties: type: type: string enum: - json_object required: - type title: JSON object description: >- JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - type: object properties: type: enum: - json_schema type: string json_schema: type: object properties: description: type: string description: >- A description of what the response format is for, used by the model to determine how to respond in the format. name: type: string description: >- The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: description: >- The schema for the response format, described as a JSON Schema object. strict: type: boolean default: false description: >- Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is true. required: - name required: - type - json_schema title: JSON schema description: >- JSON Schema response format. Used to generate structured JSON responses description: >- An object specifying the format that the model must output reasoning_effort: type: string enum: - none - minimal - low - medium - high - xhigh description: >- Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - `xhigh` is currently only supported for `gpt-5.1-codex-max`. Any of "none", "minimal", "low", "medium", "high", "xhigh". verbosity: type: string description: >- Adjusts response verbosity. Lower levels yield shorter answers. seed: type: - number - 'null' description: >- If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result. stop: anyOf: - type: string - type: array items: type: string maxItems: 4 - type: 'null' description: >- Up to 4 sequences where the API will stop generating further tokens. thinking: oneOf: - $ref: >- #/components/schemas/ThinkingConfigDisabledSchema - $ref: >- #/components/schemas/ThinkingConfigEnabledSchema - $ref: >- #/components/schemas/ThinkingConfigAdaptiveSchema discriminator: propertyName: type mapping: disabled: $ref: >- #/components/schemas/ThinkingConfigDisabledSchema enabled: $ref: >- #/components/schemas/ThinkingConfigEnabledSchema adaptive: $ref: >- #/components/schemas/ThinkingConfigAdaptiveSchema temperature: type: - number - 'null' minimum: 0 maximum: 2 description: >- What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. top_p: type: - number - 'null' minimum: 0 maximum: 1 description: >- An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. top_k: type: - number - 'null' description: >- Limits the model to consider only the top k most likely tokens at each step. tool_choice: anyOf: - type: string enum: - none - auto - required - type: object properties: type: type: string enum: - function description: >- The type of the tool. Currently, only function is supported. function: type: object properties: name: type: string description: The name of the function to call. required: - name required: - function description: >- Controls which (if any) tool is called by the model. parallel_tool_calls: type: boolean description: >- Whether to enable parallel function calling during tool use. modalities: type: - array - 'null' items: type: string enum: - text - audio description: >- Output types that you would like the model to generate. Most models are capable of generating text, which is the default: ["text"]. The gpt-4o-audio-preview model can also be used to generate audio. To request that this model generate both text and audio responses, you can use: ["text", "audio"]. guardrails: type: array items: type: object properties: id: anyOf: - type: string enum: - orq_pii_detection - orq_sexual_moderation - orq_harmful_moderation description: The key of the guardrail. - type: string description: >- Unique key or identifier of the evaluator execute_on: type: string enum: - input - output description: >- Determines whether the guardrail runs on the input (user message) or output (model response). required: - id - execute_on description: A list of guardrails to apply to the request. fallbacks: type: array items: type: object properties: model: type: string description: Fallback model identifier example: openai/gpt-4o-mini required: - model description: >- Array of fallback models to use if primary model fails cache: type: object properties: ttl: type: number minimum: 1 maximum: 259200 default: 1800 description: >- Time to live for cached responses in seconds. Maximum 259200 seconds (3 days). example: 3600 type: type: string enum: - exact_match required: - type description: Cache configuration for the request. load_balancer: oneOf: - type: object properties: type: type: string enum: - weight_based models: type: array items: type: object properties: model: type: string description: Model identifier for load balancing example: openai/gpt-4o weight: type: number minimum: 0.001 maximum: 1 default: 0.5 description: >- Weight assigned to this model for load balancing example: 0.7 required: - model required: - type - models description: Load balancer configuration for the request. example: type: weight_based models: - model: openai/gpt-4o weight: 0.7 - model: anthropic/claude-3-5-sonnet weight: 0.3 timeout: type: object properties: call_timeout: type: number minimum: 1 description: Timeout value in milliseconds example: 30000 required: - call_timeout description: >- Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured. description: >- Model behavior parameters that control how the model generates responses. Common parameters: `temperature` (0-1, randomness), `max_completion_tokens` (max output length), `top_p` (sampling diversity). Advanced: `frequency_penalty`, `presence_penalty`, `response_format` (JSON/structured), `reasoning_effort`, `seed` (reproducibility). Support varies by model - consult AI Gateway documentation. retry: type: object properties: count: type: number minimum: 1 maximum: 5 default: 3 description: Number of retry attempts (1-5) example: 3 on_codes: type: array items: type: number minimum: 100 maximum: 599 minItems: 1 default: - 429 description: HTTP status codes that trigger retry logic example: - 429 - 500 - 502 - 503 - 504 description: >- Retry configuration for model requests. Retries are triggered for specific HTTP status codes (e.g., 500, 429, 502, 503, 504). Supports configurable retry count (1-5) and custom status codes. required: - id description: |- Model configuration with parameters and retry settings. title: Model Configuration description: >- Model configuration for this execution. Can override the agent manifest defaults if the agent already exists. fallback_models: type: array items: anyOf: - type: string description: >- A fallback model ID string (e.g., `openai/gpt-4o-mini`). Will be used if the primary model request fails. Must support tool calling. - type: object properties: id: type: string description: >- A fallback model ID string. Must support tool calling. parameters: type: object properties: name: type: string description: >- The name to display on the trace. If not specified, the default system name will be used. frequency_penalty: type: - number - 'null' description: >- Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. max_tokens: type: - integer - 'null' description: >- `[Deprecated]`. The maximum number of tokens that can be generated in the chat completion. This value can be used to control costs for text generated via API. This value is now `deprecated` in favor of `max_completion_tokens`, and is not compatible with o1 series models. max_completion_tokens: type: - integer - 'null' exclusiveMinimum: 0 description: >- An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens presence_penalty: type: - number - 'null' description: >- Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. response_format: oneOf: - type: object properties: type: type: string enum: - text required: - type title: Text description: >- Default response format. Used to generate text responses - type: object properties: type: type: string enum: - json_object required: - type title: JSON object description: >- JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - type: object properties: type: enum: - json_schema type: string json_schema: type: object properties: description: type: string description: >- A description of what the response format is for, used by the model to determine how to respond in the format. name: type: string description: >- The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. schema: description: >- The schema for the response format, described as a JSON Schema object. strict: type: boolean default: false description: >- Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is true. required: - name required: - type - json_schema title: JSON schema description: >- JSON Schema response format. Used to generate structured JSON responses description: >- An object specifying the format that the model must output reasoning_effort: type: string enum: - none - minimal - low - medium - high - xhigh description: >- Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - `xhigh` is currently only supported for `gpt-5.1-codex-max`. Any of "none", "minimal", "low", "medium", "high", "xhigh". verbosity: type: string description: >- Adjusts response verbosity. Lower levels yield shorter answers. seed: type: - number - 'null' description: >- If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result. stop: anyOf: - type: string - type: array items: type: string maxItems: 4 - type: 'null' description: >- Up to 4 sequences where the API will stop generating further tokens. thinking: oneOf: - $ref: >- #/components/schemas/ThinkingConfigDisabledSchema - $ref: >- #/components/schemas/ThinkingConfigEnabledSchema - $ref: >- #/components/schemas/ThinkingConfigAdaptiveSchema discriminator: propertyName: type mapping: disabled: $ref: >- #/components/schemas/ThinkingConfigDisabledSchema enabled: $ref: >- #/components/schemas/ThinkingConfigEnabledSchema adaptive: $ref: >- #/components/schemas/ThinkingConfigAdaptiveSchema temperature: type: - number - 'null' minimum: 0 maximum: 2 description: >- What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. top_p: type: - number - 'null' minimum: 0 maximum: 1 description: >- An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. top_k: type: - number - 'null' description: >- Limits the model to consider only the top k most likely tokens at each step. tool_choice: anyOf: - type: string enum: - none - auto - required - type: object properties: type: type: string enum: - function description: >- The type of the tool. Currently, only function is supported. function: type: object properties: name: type: string description: The name of the function to call. required: - name required: - function description: >- Controls which (if any) tool is called by the model. parallel_tool_calls: type: boolean description: >- Whether to enable parallel function calling during tool use. modalities: type: - array - 'null' items: type: string enum: - text - audio description: >- Output types that you would like the model to generate. Most models are capable of generating text, which is the default: ["text"]. The gpt-4o-audio-preview model can also be used to generate audio. To request that this model generate both text and audio responses, you can use: ["text", "audio"]. guardrails: type: array items: type: object properties: id: anyOf: - type: string enum: - orq_pii_detection - orq_sexual_moderation - orq_harmful_moderation description: The key of the guardrail. - type: string description: >- Unique key or identifier of the evaluator execute_on: type: string enum: - input - output description: >- Determines whether the guardrail runs on the input (user message) or output (model response). required: - id - execute_on description: A list of guardrails to apply to the request. fallbacks: type: array items: type: object properties: model: type: string description: Fallback model identifier example: openai/gpt-4o-mini required: - model description: >- Array of fallback models to use if primary model fails cache: type: object properties: ttl: type: number minimum: 1 maximum: 259200 default: 1800 description: >- Time to live for cached responses in seconds. Maximum 259200 seconds (3 days). example: 3600 type: type: string enum: - exact_match required: - type description: Cache configuration for the request. load_balancer: oneOf: - type: object properties: type: type: string enum: - weight_based models: type: array items: type: object properties: model: type: string description: Model identifier for load balancing example: openai/gpt-4o weight: type: number minimum: 0.001 maximum: 1 default: 0.5 description: >- Weight assigned to this model for load balancing example: 0.7 required: - model required: - type - models description: Load balancer configuration for the request. example: type: weight_based models: - model: openai/gpt-4o weight: 0.7 - model: anthropic/claude-3-5-sonnet weight: 0.3 timeout: type: object properties: call_timeout: type: number minimum: 1 description: Timeout value in milliseconds example: 30000 required: - call_timeout description: >- Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured. description: >- Optional model parameters specific to this fallback model. Overrides primary model parameters if this fallback is used. retry: type: object properties: count: type: number minimum: 1 maximum: 5 default: 3 description: Number of retry attempts (1-5) example: 3 on_codes: type: array items: type: number minimum: 100 maximum: 599 minItems: 1 default: - 429 description: HTTP status codes that trigger retry logic example: - 429 - 500 - 502 - 503 - 504 description: >- Retry configuration for this fallback model. Allows customizing retry count (1-5) and HTTP status codes that trigger retries. required: - id description: >- Fallback model configuration with optional parameters and retry settings. title: Fallback Model Configuration description: >- Fallback model for automatic failover when primary model request fails. Supports optional parameter overrides. Can be a simple model ID string or a configuration object with model-specific parameters. Fallbacks are tried in order. description: >- Optional array of fallback models used when the primary model fails. Fallbacks are attempted in order. All models must support tool calling. role: type: string minLength: 1 description: Specifies the agent's function and area of expertise. instructions: type: string minLength: 1 description: >- Provides context and purpose for the agent. Combined with the system prompt template to generate the agent's instructions. message: type: object properties: messageId: type: string description: Optional A2A message ID in ULID format role: anyOf: - type: string enum: - user title: User message description: Message from the end user - type: string enum: - tool title: Tool message description: Message containing tool execution results description: Message role (user or tool for continuing executions) parts: type: array items: oneOf: - allOf: - $ref: '#/components/schemas/TextPart' - description: >- Text content part. Use this to send text messages to the agent. - allOf: - $ref: '#/components/schemas/FilePart' - description: >- File attachment part. Use this to send files (images, documents, etc.) to the agent for processing. - allOf: - $ref: '#/components/schemas/ToolResultPart' - description: >- Tool execution result part. Use this ONLY when providing results for a pending tool call from the agent. The tool_call_id must match the ID from the agent's tool call request. - allOf: - $ref: '#/components/schemas/ErrorPart' - description: >- Error content part. Generated by the system when an error occurs during agent execution. discriminator: propertyName: kind mapping: text: $ref: '#/components/schemas/TextPart' file: $ref: '#/components/schemas/FilePart' tool_result: $ref: '#/components/schemas/ToolResultPart' error: $ref: '#/components/schemas/ErrorPart' title: Public Message Part description: >- Message part that can be provided by users. Use "text" for regular messages, "file" for attachments, or "tool_result" when responding to tool call requests. description: >- A2A message parts (text, file, or tool_result only). Note: Tool role messages must only contain tool_result parts. required: - role - parts title: A2A Message description: >- The A2A format message containing the task for the agent to perform. variables: type: object additionalProperties: {} description: >- Optional variables for template replacement in system prompt, instructions, and messages identity: type: object properties: id: type: string description: Unique identifier for the contact example: contact_01ARZ3NDEKTSV4RRFFQ69G5FAV display_name: type: string description: Display name of the contact example: Jane Doe email: type: string format: email description: Email address of the contact example: jane.doe@example.com metadata: type: array items: type: object additionalProperties: {} description: >- A hash of key/value pairs containing any other data about the contact example: - department: Engineering role: Senior Developer logo_url: type: string description: URL to the contact's avatar or logo example: https://example.com/avatars/jane-doe.jpg tags: type: array items: type: string description: A list of tags associated with the contact example: - hr - engineering required: - id description: >- Information about the identity making the request. If the identity does not exist, it will be created automatically. contact: type: object properties: id: type: string description: Unique identifier for the contact example: contact_01ARZ3NDEKTSV4RRFFQ69G5FAV display_name: type: string description: Display name of the contact example: Jane Doe email: type: string format: email description: Email address of the contact example: jane.doe@example.com metadata: type: array items: type: object additionalProperties: {} description: >- A hash of key/value pairs containing any other data about the contact example: - department: Engineering role: Senior Developer logo_url: type: string description: URL to the contact's avatar or logo example: https://example.com/avatars/jane-doe.jpg tags: type: array items: type: string description: A list of tags associated with the contact example: - hr - engineering required: - id description: >- @deprecated Use identity instead. Information about the contact making the request. deprecated: true thread: type: object properties: id: type: string description: Unique thread identifier to group related invocations. example: thread_01ARZ3NDEKTSV4RRFFQ69G5FAV tags: type: array items: type: string description: Optional tags to differentiate or categorize threads example: - customer-support - priority-high required: - id description: Thread information to group related requests memory: type: object properties: entity_id: type: string description: >- An entity ID used to link memory stores to a specific user, session, or conversation. This ID is used to isolate and retrieve memories specific to the entity across agent executions. required: - entity_id description: >- Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions. path: type: string description: >- Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project. example: Default description: type: string minLength: 1 description: A brief summary of the agent's purpose. system_prompt: type: - string - 'null' minLength: 1 description: >- A custom system prompt template for the agent. If omitted, the default template is used. memory_stores: type: array items: type: string default: [] title: Memory stores description: >- Array of memory store identifiers that are accessible to the agent. Accepts both memory store IDs and keys. knowledge_bases: type: array items: type: object properties: knowledge_id: type: string description: Unique identifier of the knowledge base to search example: customer-knowledge-base required: - knowledge_id default: [] description: Knowledge base configurations for the agent to access team_of_agents: type: array items: type: object properties: key: type: string description: The unique key of the agent within the workspace role: type: string description: >- The role of the agent in this context. This is used to give extra information to the leader to help it decide which agent to hand off to. required: - key default: [] description: >- The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks. settings: type: object properties: tools: type: array items: oneOf: - type: object properties: type: type: string enum: - google_search requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Google search tool description: Performs Google searches to retrieve web content - type: object properties: type: type: string enum: - web_scraper requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Web scraper tool description: Scrapes and extracts content from web pages - type: object properties: type: type: string enum: - call_sub_agent requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Call sub agent tool description: Delegates tasks to specialized sub-agents - type: object properties: type: type: string enum: - retrieve_agents requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Retrieve agents tool description: Retrieves available agents in the system - type: object properties: type: type: string enum: - query_memory_store requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Query memory store tool description: Queries agent memory stores for context - type: object properties: type: type: string enum: - write_memory_store requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Write memory store tool description: Writes information to agent memory stores - type: object properties: type: type: string enum: - retrieve_memory_stores requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Retrieve memory stores tool description: Lists available memory stores - type: object properties: type: type: string enum: - delete_memory_document requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Delete memory document tool description: Deletes documents from memory stores - type: object properties: type: type: string enum: - retrieve_knowledge_bases requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Retrieve knowledge bases tool description: Lists available knowledge bases - type: object properties: type: type: string enum: - query_knowledge_base requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Query knowledge base tool description: Queries knowledge bases for information - type: object properties: type: type: string enum: - current_date requires_approval: type: boolean description: >- Whether this tool requires approval before execution required: - type title: Current date tool description: Returns the current date and time - type: object properties: type: type: string enum: - http key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI _id: type: string display_name: type: string description: type: string description: >- A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision. http: type: object properties: blueprint: type: object properties: url: type: string description: The URL to send the request to. method: type: string enum: - GET - POST - PUT - DELETE description: The HTTP method to use. headers: type: object additionalProperties: anyOf: - type: string - type: object properties: value: type: string encrypted: type: boolean default: false required: - value default: Content-Type: value: application/json encrypted: false description: >- The headers to send with the request. Can be a string value or an object with value and encrypted properties. body: type: object additionalProperties: {} description: The body to send with the request. required: - url - method description: >- The blueprint for the HTTP request. The `arguments` field will be used to replace the placeholders in the `url`, `headers`, `body`, and `arguments` fields. arguments: type: object additionalProperties: type: object properties: type: type: string enum: - string - number - boolean description: The type of the argument. description: type: string description: A description of the argument. send_to_model: type: boolean default: true description: >- Whether to send the argument to the model. If set to false, the argument will not be sent to the model and needs to be provided by the user or it will be left blank. default_value: anyOf: - type: string - type: number - type: boolean description: The default value of the argument. required: - type - description description: >- The arguments to send with the request. The keys will be used to replace the placeholders in the `blueprint` field. required: - blueprint requires_approval: type: boolean default: false required: - type - key - description - http title: HTTP Tool (Run) description: >- HTTP tool with inline definition for on-the-fly creation in run endpoint - type: object properties: type: type: string enum: - code key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI _id: type: string display_name: type: string description: type: string description: >- A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision. code_tool: type: object properties: parameters: type: object properties: type: type: string enum: - object description: The type must be "object" properties: type: object additionalProperties: {} description: >- The properties of the function parameters required: type: array items: type: string description: Array of required parameter names required: - type - properties - required additionalProperties: {} description: >- The parameters the functions accepts, described as a JSON Schema object. See the `OpenAI` [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. language: type: string enum: - python code: type: string minLength: 1 description: The code to execute. required: - language - code requires_approval: type: boolean default: false required: - type - key - description - code_tool title: Code Tool (Run) description: >- Code execution tool with inline definition for on-the-fly creation in run endpoint - type: object properties: type: type: string enum: - function key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI _id: type: string display_name: type: string description: type: string function: type: object properties: name: type: string description: >- The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. description: type: string description: >- A description of what the function does, used by the model to choose when and how to call the function. strict: type: boolean description: >- Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Currently only compatible with `OpenAI` models. parameters: type: object properties: type: type: string enum: - object description: The type must be "object" properties: type: object additionalProperties: {} description: >- The properties of the function parameters required: type: array items: type: string description: Array of required parameter names required: - type - properties - required additionalProperties: {} description: >- The parameters the functions accepts, described as a JSON Schema object. See the `OpenAI` [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. required: - name requires_approval: type: boolean default: false required: - type - key - function title: Function Tool (Run) description: >- Function tool with inline definition for on-the-fly creation in run endpoint - type: object properties: type: enum: - json_schema type: string key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI _id: type: string display_name: type: string description: type: string description: >- A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision. json_schema: type: object properties: name: type: string minLength: 1 maxLength: 64 description: >- The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. description: type: string description: >- A description of what the response format is for. This will be shown to the user. schema: type: object properties: type: type: string description: The JSON Schema type properties: type: object additionalProperties: {} description: The properties of the JSON Schema object required: type: array items: type: string description: Array of required property names required: - type - properties - required additionalProperties: {} description: >- The schema for the response format, described as a JSON Schema object. See the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. strict: type: boolean description: >- Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. Only compatible with `OpenAI` models. required: - name - description - schema requires_approval: type: boolean default: false required: - type - key - description - json_schema title: JSON Schema Tool (Run) description: >- JSON Schema tool with inline definition for on-the-fly creation in run endpoint - type: object properties: type: enum: - mcp type: string key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI _id: type: string display_name: type: string description: type: string description: >- A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision. mcp: type: object properties: server_url: type: string format: uri description: The MCP server URL (cached for execution) headers: type: object additionalProperties: type: object properties: value: type: string encrypted: type: boolean default: false required: - value default: {} description: >- HTTP headers for MCP server requests with encryption support tools: type: array items: type: object properties: id: type: string default: 01KRM5RED6CNBR6KDC0GS4KS39 name: type: string description: type: string schema: type: object properties: type: type: string enum: - object properties: type: object additionalProperties: {} required: type: array items: type: string required: - type required: - name - schema description: >- Array of tools available from the MCP server connection_type: type: string enum: - http - sse description: The connection type used by the MCP server template_variables: type: - array - 'null' items: type: string description: >- Names of template variables detected in server_url and headers. Used by the FE to prompt for one-time values on sync/refresh. readOnly: true required: - server_url - tools - connection_type requires_approval: type: boolean default: false required: - type - key - description - mcp title: MCP Tool (Run) description: >- MCP tool with inline definition for on-the-fly creation in run endpoint description: >- Tool configuration for agent run operations. Built-in tools only require a type and requires_approval, while custom tools (HTTP, Code, Function, JSON Schema, MCP) support full inline definitions for on-the-fly creation. title: Agent Tool Input (Run) default: [] description: Tools available to the agent tool_approval_required: type: string enum: - all - respect_tool - none default: none description: >- If all, the agent will require approval for all tools. If respect_tool, the agent will require approval for tools that have the requires_approval flag set to true. If none, the agent will not require approval for any tools. max_iterations: type: integer exclusiveMinimum: 0 maximum: 100 minimum: 1 default: 100 description: >- Maximum iterations(llm calls) before the agent will stop executing. max_execution_time: type: integer minimum: 2 exclusiveMinimum: 0 maximum: 600 default: 600 description: >- Maximum time (in seconds) for the agent thinking process. This does not include the time for tool calls and sub agent calls. It will be loosely enforced, the in progress LLM calls will not be terminated and the last assistant message will be returned. max_cost: type: number minimum: 0 default: 0 description: >- Maximum cost in USD for the agent execution. When the accumulated cost exceeds this limit, the agent will stop executing. Set to 0 for unlimited. Only supported in v3 responses evaluators: type: array items: type: object properties: id: type: string description: Unique key or identifier of the evaluator sample_rate: type: number minimum: 1 maximum: 100 default: 50 description: >- The percentage of executions to evaluate with this evaluator (1-100). For example, a value of 50 means the evaluator will run on approximately half of the executions. execute_on: type: string enum: - input - output description: >- Determines whether the evaluator runs on the agent input (user message) or output (agent response). required: - id - execute_on title: Agent evaluator configuration description: Configuration for an evaluator applied to the agent guardrails: type: array items: type: object properties: id: type: string description: Unique key or identifier of the evaluator sample_rate: type: number minimum: 1 maximum: 100 default: 50 description: >- The percentage of executions to evaluate with this evaluator (1-100). For example, a value of 50 means the evaluator will run on approximately half of the executions. execute_on: type: string enum: - input - output description: >- Determines whether the evaluator runs on the agent input (user message) or output (agent response). required: - id - execute_on title: Agent guardrail configuration description: Configuration for a guardrail applied to the agent metadata: type: object additionalProperties: {} description: >- Optional metadata for the agent run as key-value pairs that will be included in traces engine: type: string enum: - text - jinja - mustache default: text description: >- Template engine for variable interpolation. Text uses {{variable}} syntax, Jinja supports loops/conditionals/filters, Mustache uses {{#section}} syntax. required: - key - model - role - instructions - message - path - settings responses: '200': description: >- Agent execution initiated successfully. Returns task details including the task ID, execution status, and agent response. The task ID can be used to track execution progress and retrieve results. content: application/json: schema: type: object properties: id: type: string description: The unique ID of the created agent execution task contextId: type: string description: The correlation ID for this execution (used for tracking) kind: type: string enum: - task description: A2A entity type identifier status: type: object properties: state: type: string enum: - submitted - working - input-required - auth-required - completed - failed - canceled - rejected title: Task State description: >- Current state of the agent task execution. Values: submitted (queued), working (executing), input-required (awaiting user input), completed (finished successfully), failed (error occurred). Note: auth-required, canceled, and rejected statuses are defined for A2A protocol compatibility but are not currently supported in task execution. timestamp: type: string description: ISO 8601 timestamp of when the status was updated message: type: object properties: kind: type: string enum: - message messageId: type: string role: type: string enum: - user - agent - tool - system title: Extended Message Role description: >- Role of the message sender in the A2A protocol. Values: user (end user), agent (AI agent), tool (tool execution result), system (system instructions/prompts). parts: type: array items: oneOf: - $ref: '#/components/schemas/TextPart' - $ref: '#/components/schemas/ErrorPart' - $ref: '#/components/schemas/DataPart' - $ref: '#/components/schemas/FilePart' - $ref: '#/components/schemas/ToolCallPart' - $ref: '#/components/schemas/ToolResultPart' discriminator: propertyName: kind mapping: text: $ref: '#/components/schemas/TextPart' error: $ref: '#/components/schemas/ErrorPart' data: $ref: '#/components/schemas/DataPart' file: $ref: '#/components/schemas/FilePart' tool_call: $ref: '#/components/schemas/ToolCallPart' tool_result: $ref: '#/components/schemas/ToolResultPart' required: - kind - messageId - role - parts title: Task Status Message description: >- Optional A2A message providing additional context about the current status required: - state title: Task Status description: Current task status information messages: type: array description: >- Array of messages in the task conversation. Only present when blocking mode is enabled. items: $ref: '#/components/schemas/ExtendedMessage' metadata: type: object additionalProperties: {} description: >- Task metadata containing workspace_id and trace_id for feedback and tracking required: - id - contextId - kind - status title: A2A Task Response description: >- Response format following the Agent-to-Agent (A2A) protocol. Returned when starting or continuing an agent task execution. deprecated: true components: schemas: ThinkingConfigDisabledSchema: type: object properties: type: type: string enum: - disabled description: Disables the thinking mode capability required: - type title: Thinking config disabled description: Disables the thinking mode capability ThinkingConfigEnabledSchema: type: object properties: type: type: string enum: - enabled description: Enables or disables the thinking mode capability budget_tokens: type: number description: >- Determines how many tokens the model can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. Must be ≥1024 and less than `max_tokens`. thinking_level: type: string enum: - low - medium - high description: >- The level of reasoning the model should use. This setting is supported only by `gemini-3` models. If budget_tokens is specified and `thinking_level` is available, `budget_tokens` will be ignored. required: - type - budget_tokens title: Thinking config enabled description: Enables the thinking mode capability ThinkingConfigAdaptiveSchema: type: object properties: type: type: string enum: - adaptive description: >- Lets the model dynamically determine when and how much to use extended thinking based on the complexity of each request. Supported on Claude Opus 4.6 and Sonnet 4.6. required: - type title: Thinking config adaptive description: >- Enables adaptive thinking mode where the model dynamically determines thinking depth TextPart: type: object properties: kind: type: string enum: - text text: type: string required: - kind - text title: Text Part description: >- A text content part containing plain text or markdown. Used for agent messages, user input, and text-based responses. FilePart: type: object properties: kind: type: string enum: - file file: anyOf: - type: object properties: bytes: type: string minLength: 1 description: base64 encoded content of the file mimeType: type: string description: Optional mimeType for the file name: type: string description: Optional name for the file required: - bytes title: Binary format description: >- Binary in base64 format. Check in the model's documentation for the supported mime types for the binary format. - type: object properties: uri: type: string description: URL for the File content mimeType: type: string description: Optional mimeType for the file name: type: string description: Optional name for the file required: - uri title: File in URI format description: >- File in URI format. Check in the model's documentation for the supported mime types for the URI format metadata: type: object additionalProperties: {} required: - kind - file title: File Part description: >- A file content part that can contain either base64-encoded bytes or a URI reference. Used for images, documents, and other binary content in agent communications. ToolResultPart: type: object properties: kind: type: string enum: - tool_result tool_call_id: type: string minLength: 1 result: {} metadata: type: object additionalProperties: {} required: - kind - tool_call_id title: Tool Result Part description: >- The result of a tool execution. Contains the tool call ID for correlation and the result data from the tool invocation. ErrorPart: type: object properties: kind: type: string enum: - error error: type: string code: type: number required: - kind - error title: Error Part description: >- An error content part containing error information. Used when an error occurs during agent execution. DataPart: type: object properties: kind: type: string enum: - data data: type: object additionalProperties: {} metadata: type: object additionalProperties: {} required: - kind - data title: Data Part description: >- A structured data part containing JSON-serializable key-value pairs. Used for passing structured information between agents and tools. ToolCallPart: type: object properties: kind: type: string enum: - tool_call tool_name: type: string tool_call_id: type: string minLength: 1 arguments: type: object additionalProperties: {} thought_signature: type: string metadata: type: object additionalProperties: {} required: - kind - tool_name - tool_call_id - arguments title: Tool Call Part description: >- A tool invocation request from an agent. Contains the tool name, unique call ID, and arguments for the tool execution. ExtendedMessage: type: object properties: kind: type: string enum: - message messageId: type: string description: Unique identifier for the message role: type: string enum: - user - agent - tool - system title: Extended Message Role description: >- Role of the message sender in the A2A protocol. Values: user (end user), agent (AI agent), tool (tool execution result), system (system instructions/prompts). parts: type: array items: oneOf: - $ref: '#/components/schemas/TextPart' - $ref: '#/components/schemas/ErrorPart' - $ref: '#/components/schemas/DataPart' - $ref: '#/components/schemas/FilePart' - $ref: '#/components/schemas/ToolCallPart' - $ref: '#/components/schemas/ToolResultPart' discriminator: propertyName: kind mapping: text: $ref: '#/components/schemas/TextPart' error: $ref: '#/components/schemas/ErrorPart' data: $ref: '#/components/schemas/DataPart' file: $ref: '#/components/schemas/FilePart' tool_call: $ref: '#/components/schemas/ToolCallPart' tool_result: $ref: '#/components/schemas/ToolResultPart' description: Array of message parts (text, file, tool_call, tool_result) taskId: type: string description: Associated task ID if applicable contextId: type: string description: Correlation ID for execution tracking metadata: type: object additionalProperties: {} description: Additional message metadata required: - kind - messageId - role - parts title: Extended A2A Message description: >- Extended Agent-to-Agent protocol message with support for tool calls and tool results. Extends the base A2A message format with Orquesta-specific features. securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````