> ## 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.
# Execute an agent task
> Invoke an agent to perform a task with input messages. Supports tool execution, knowledge retrieval, memory context, and model fallback.
**Related guide**: Build agents guide. See the [Build agents guide](/ai-studio/ai-engineering/build-agents) for a walkthrough with examples.
This endpoint is deprecated. Use the [Responses API](/reference/responses/create-response) instead.
## OpenAPI
````yaml post /v2/agents/{key}/task
openapi: 3.1.0
info:
title: orq.ai API
version: '2.0'
description: orq.ai API documentation
servers:
- url: https://my.orq.ai
security:
- ApiKey: []
tags:
- name: Chunking
description: Split text into smaller chunks for retrieval and generation workflows.
- name: File Systems
description: >-
Create and manage persistent file systems that agents and MCP clients read
from and write to.
- name: Knowledge Bases
description: Create and manage knowledge bases used by agents and retrieval workflows.
- name: Memory Stores
description: Create and manage memory stores, memories, and memory documents.
- name: Evals
description: Run an evaluator against a conversation and its result
- name: Logs
description: >-
OpenTelemetry log query API. Search, filter, aggregate, and facet log
records ingested via OTLP.
- 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: Traces
description: >-
Query and inspect ingested trace data: search trace summaries, aggregate
metrics, and read individual traces and their spans.
- description: List models available through the AI Router.
name: Models
- name: Policies
- name: Alerts
description: >-
Alerts evaluate a Reporting API metric on a fixed interval and fire
notifications through notifiers when the value breaches a threshold. Each
breach opens a trigger that tracks the incident until the value recovers.
- name: Annotation Queues
description: Annotation queues collect spans for human review.
- name: API keys
description: >-
API keys authenticate programmatic access to the workspace. They expose
opaque tokens, per-domain access grants, and budget and rate-limit
constraints.
- name: Audit Logs
description: Audit logs record workspace entity changes and access-relevant events.
- name: Budgets
description: >-
Budgets govern spend, token usage, and request rate across six scopes:
workspace, project, identity, API key, provider, and model. Every
applicable budget is enforced, and the most restrictive limit applies per
dimension.
- name: Files
description: File upload and retrieval operations.
- name: Guardrail Rules
description: >-
Guardrail Rules conditionally enforce evaluators and plugins for AI
Gateway traffic. Rules may be scoped to a project or the whole workspace.
- name: Hub
description: Hub items are reusable templates available to a workspace.
- name: Identities
description: >-
Identities represent end users from your system for usage and engagement
tracking.
- name: Management keys
description: >-
Management keys are workspace-scoped credentials that authenticate
programmatic access to workspace administration surfaces (API keys,
budgets). Unlike project-scoped API keys, a management key always operates
at the workspace level.
- name: MCP Gateway
description: >-
Register upstream MCP servers, discover and sync their tools, and assemble
gateways that expose a curated tool surface to MCP clients.
- name: Model Catalog
description: >-
Browse the orq.ai model catalog: every model orq offers, across every
provider, with pricing, capabilities and benchmark data. List endpoints
only return models that are not deprecated. This API is public, requires
no authentication, and is rate limited to 120 requests per minute per IP.
Responses carry a 5-minute cache-control max-age.
- name: Notifiers
description: Notifier destinations used to send delivery and workflow notifications.
- name: Projects
description: Projects organize resources within a workspace
- name: Routing Rules
description: >-
Routing Rules conditionally select models and enforce request plugins for
AI Gateway traffic. Rules are evaluated by ascending priority and may be
scoped to a project or the whole workspace.
- name: Threads
description: Threads group related trace invocations and their aggregate usage
- name: Skills
description: >-
Skills are modular instructions you can use to codify processes and
conventions
- name: Smart Routers
description: >-
Create and manage workspace Smart Routers. A Smart Router selects a model
from an eligible pool for each request according to a quality, balanced,
or cost profile.
- name: Webhooks
description: >-
Create and manage webhooks that deliver workspace events to external HTTPS
endpoints.
- name: Workspaces
description: >-
A workspace is the tenant. Create is called from a user session during
onboarding; Get, List, and Update are the public management surface.
- name: Workspace Security
description: >-
Workspace-level domain verification and IP allowlist controls. These
operations are restricted to workspace administrators.
- name: Workspace Settings
description: >-
Workspace-level settings managed with a workspace credential. A workspace
is the tenant, so these settings are a singleton — there is nothing to
create or delete, only read and update.
- name: Responses
- description: Run agents on a cron cadence. Minimum firing interval is 1 hour.
name: Agent Schedules
- name: Embeddings
- name: Telemetry
description: >-
Unified query envelope for traces, metrics, and logs. One request shape,
one filter dialect, and one response shape per source, validated by a
per-source registry.
- description: Beta. Run typed classification questions against a classify model.
name: Classify
- description: Search Gateway with managed credits or BYOK.
name: Web Search
externalDocs:
url: https://docs.orq.ai
description: orq.ai Documentation
paths:
/v2/agents/{key}/task:
post:
tags:
- Agents
summary: Execute an agent task
description: >-
Invoke an agent to perform a task with input messages. Supports tool
execution, knowledge retrieval, memory context, and model fallback.
operationId: InvokeAgent
parameters:
- schema:
type: string
description: The key or ID of the agent to invoke
required: true
description: The key or ID of the agent to invoke
name: key
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
task_id:
type: string
description: >-
Optional task ID to continue an existing agent execution.
When provided, the agent will continue the conversation from
the existing task state. The task must be in an inactive
state to continue.
message:
type: object
properties:
messageId:
type: string
description: Optional A2A message ID in ULID format
role:
anyOf:
- type: string
enum:
- user
title: User message
description: Message from the end user
- type: string
enum:
- tool
title: Tool message
description: Message containing tool execution results
description: Message role (user or tool for continuing executions)
parts:
type: array
items:
oneOf:
- allOf:
- $ref: '#/components/schemas/TextPart'
- description: >-
Text content part. Use this to send text
messages to the agent.
- allOf:
- $ref: '#/components/schemas/FilePart'
- description: >-
File attachment part. Use this to send files
(images, documents, etc.) to the agent for
processing.
- allOf:
- $ref: '#/components/schemas/ToolResultPart'
- description: >-
Tool execution result part. Use this ONLY when
providing results for a pending tool call from
the agent. The tool_call_id must match the ID
from the agent's tool call request.
- allOf:
- $ref: '#/components/schemas/ErrorPart'
- description: >-
Error content part. Generated by the system
when an error occurs during agent execution.
discriminator:
propertyName: kind
mapping:
text: '#/components/schemas/TextPart'
file: '#/components/schemas/FilePart'
tool_result: '#/components/schemas/ToolResultPart'
error: '#/components/schemas/ErrorPart'
title: Public Message Part
description: >-
Message part that can be provided by users. Use "text"
for regular messages, "file" for attachments, or
"tool_result" when responding to tool call requests.
description: >-
A2A message parts (text, file, or tool_result only).
Note: Tool role messages must only contain tool_result
parts.
required:
- role
- parts
title: A2A Message
description: >-
The A2A message to send to the agent (user input or tool
results)
variables:
type: object
additionalProperties: {}
description: >-
Optional variables for template replacement in system
prompt, instructions, and messages
identity:
type: object
properties:
id:
type: string
description: Unique identifier for the contact
example: contact_01ARZ3NDEKTSV4RRFFQ69G5FAV
display_name:
type: string
description: Display name of the contact
example: Jane Doe
email:
type: string
format: email
description: Email address of the contact
example: jane.doe@example.com
metadata:
type: array
items:
type: object
additionalProperties: {}
description: >-
A hash of key/value pairs containing any other data
about the contact
example:
- department: Engineering
role: Senior Developer
logo_url:
type: string
description: URL to the contact's avatar or logo
example: https://example.com/avatars/jane-doe.jpg
tags:
type: array
items:
type: string
description: A list of tags associated with the contact
example:
- hr
- engineering
required:
- id
description: >-
Information about the identity making the request. If the
identity does not exist, it will be created automatically.
contact:
type: object
properties:
id:
type: string
description: Unique identifier for the contact
example: contact_01ARZ3NDEKTSV4RRFFQ69G5FAV
display_name:
type: string
description: Display name of the contact
example: Jane Doe
email:
type: string
format: email
description: Email address of the contact
example: jane.doe@example.com
metadata:
type: array
items:
type: object
additionalProperties: {}
description: >-
A hash of key/value pairs containing any other data
about the contact
example:
- department: Engineering
role: Senior Developer
logo_url:
type: string
description: URL to the contact's avatar or logo
example: https://example.com/avatars/jane-doe.jpg
tags:
type: array
items:
type: string
description: A list of tags associated with the contact
example:
- hr
- engineering
required:
- id
description: >-
@deprecated Use identity instead. Information about the
contact making the request.
deprecated: true
thread:
type: object
properties:
id:
type: string
description: Unique thread identifier to group related invocations.
example: thread_01ARZ3NDEKTSV4RRFFQ69G5FAV
tags:
type: array
items:
type: string
description: Optional tags to differentiate or categorize threads
example:
- customer-support
- priority-high
required:
- id
description: Thread information to group related requests
memory:
type: object
properties:
entity_id:
type: string
description: >-
An entity ID used to link memory stores to a specific
user, session, or conversation. This ID is used to
isolate and retrieve memories specific to the entity
across agent executions.
required:
- entity_id
description: >-
Memory configuration for the agent execution. Used to
associate memory stores with specific entities like users or
sessions.
metadata:
type: object
additionalProperties: {}
description: >-
Optional metadata for the agent invocation as key-value
pairs that will be included in traces
engine:
type: string
enum:
- text
- jinja
- mustache
description: >-
Override template engine for this invocation. If not
provided, uses the agent default.
configuration:
type: object
properties:
blocking:
type: boolean
default: false
description: >-
Whether to block until the agent task completes. When
true, the response will include the full task with
messages. When false (default), returns immediately with
task ID and status.
description: Configuration options for the agent invocation
required:
- message
title: A2A Invoke Request
description: >-
Request body for invoking an existing agent (stream-task
endpoint). Used to start a new task or continue an existing
conversation.
responses:
'200':
description: >-
Agent task successfully initiated. Returns the task details
including task ID, execution status, and initial response. Use the
task ID to track execution progress and retrieve full 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: '#/components/schemas/TextPart'
error: '#/components/schemas/ErrorPart'
data: '#/components/schemas/DataPart'
file: '#/components/schemas/FilePart'
tool_call: '#/components/schemas/ToolCallPart'
tool_result: '#/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:
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: '#/components/schemas/TextPart'
error: '#/components/schemas/ErrorPart'
data: '#/components/schemas/DataPart'
file: '#/components/schemas/FilePart'
tool_call: '#/components/schemas/ToolCallPart'
tool_result: '#/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 orq.ai-specific
features.
securitySchemes:
ApiKey:
type: http
scheme: bearer
bearerFormat: JWT
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.