> ## 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 > Invokes an agent to perform a task with the provided input message. The agent will process the request using its configured model and tools, maintaining context through memory stores if configured. Supports automatic model fallback on primary model failure, tool execution, knowledge base retrieval, and continuation of previous conversations. Returns a task response that can be used to track execution status and retrieve results. ## 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://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/{key}/task: post: tags: - Agents summary: Execute an agent task description: >- Invokes an agent to perform a task with the provided input message. The agent will process the request using its configured model and tools, maintaining context through memory stores if configured. Supports automatic model fallback on primary model failure, tool execution, knowledge base retrieval, and continuation of previous conversations. Returns a task response that can be used to track execution status and retrieve results. 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: $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 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 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: $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: 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 ````