---
title: "Execute an agent task"
method: POST
path: "/v2/agents/{key}/task"
tags: ["Agents"]
deprecated: true
---

# Execute an agent task

`POST /v2/agents/{key}/task`

> **Deprecated.**

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.

## Path parameters

- `key` string, required — The key or ID of the agent to invoke

## Request body

- object — Request body for invoking an existing agent (stream-task endpoint). Used to start a new task or continue an existing conversation.
  - `task_id` string — Optional task ID to continue an existing agent execution. When provided, the agent will continue the conversation from the existing task state. The task must be in an inactive state to continue.
  - `message` object, required — The A2A message to send to the agent (user input or tool results)
    - `messageId` string — Optional A2A message ID in ULID format
    - `role` union, required — Message role (user or tool for continuing executions)
      - 'user' — Message from the end user
      - 'tool' — Message containing tool execution results
    - `parts` union[], required — A2A message parts (text, file, or tool_result only). Note: Tool role messages must only contain tool_result parts.
      - union — Message part that can be provided by users. Use "text" for regular messages, "file" for attachments, or "tool_result" when responding to tool call requests.
        - object — Text content part. Use this to send text messages to the agent.
          - `kind` 'text', required
          - `text` string, required
        - object — File attachment part. Use this to send files (images, documents, etc.) to the agent for processing.
          - `kind` 'file', required
          - `file` union, required
            - object — Binary in base64 format. Check in the model's documentation for the supported mime types for the binary format.
              - …
            - object — File in URI format. Check in the model's documentation for the supported mime types for the URI format
              - …
          - `metadata` object
        - object — Tool execution result part. Use this ONLY when providing results for a pending tool call from the agent. The tool_call_id must match the ID from the agent's tool call request.
          - `kind` 'tool_result', required
          - `tool_call_id` string, required
          - `result` unknown
          - `metadata` object
        - object — Error content part. Generated by the system when an error occurs during agent execution.
          - `kind` 'error', required
          - `error` string, required
          - `code` number
  - `variables` object — Optional variables for template replacement in system prompt, instructions, and messages
  - `identity` object — Information about the identity making the request. If the identity does not exist, it will be created automatically.
    - `id` string, required — Unique identifier for the contact
    - `display_name` string — Display name of the contact
    - `email` string, email — Email address of the contact
    - `metadata` object[] — A hash of key/value pairs containing any other data about the contact
    - `logo_url` string — URL to the contact's avatar or logo
    - `tags` string[] — A list of tags associated with the contact
  - `contact` object — @deprecated Use identity instead. Information about the contact making the request.
    - `id` string, required — Unique identifier for the contact
    - `display_name` string — Display name of the contact
    - `email` string, email — Email address of the contact
    - `metadata` object[] — A hash of key/value pairs containing any other data about the contact
    - `logo_url` string — URL to the contact's avatar or logo
    - `tags` string[] — A list of tags associated with the contact
  - `thread` object — Thread information to group related requests
    - `id` string, required — Unique thread identifier to group related invocations.
    - `tags` string[] — Optional tags to differentiate or categorize threads
  - `memory` object — Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.
    - `entity_id` string, required — An entity ID used to link memory stores to a specific user, session, or conversation. This ID is used to isolate and retrieve memories specific to the entity across agent executions.
  - `metadata` object — Optional metadata for the agent invocation as key-value pairs that will be included in traces
  - `engine` 'text' | 'jinja' | 'mustache' — Override template engine for this invocation. If not provided, uses the agent default.
  - `configuration` object — Configuration options for the agent invocation
    - `blocking` boolean — 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.

## Response `200`

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.

- object — Response format following the Agent-to-Agent (A2A) protocol. Returned when starting or continuing an agent task execution.
  - `id` string, required — The unique ID of the created agent execution task
  - `contextId` string, required — The correlation ID for this execution (used for tracking)
  - `kind` 'task', required — A2A entity type identifier
  - `status` object, required — Current task status information
    - `state` 'submitted' | 'working' | 'input-required' | 'auth-required' | 'completed' | 'failed' | 'canceled' | 'rejected', required — 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` string — ISO 8601 timestamp of when the status was updated
    - `message` object — Optional A2A message providing additional context about the current status
      - `kind` 'message', required
      - `messageId` string, required
      - `role` 'user' | 'agent' | 'tool' | 'system', required — 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` union[], required
        - union
          - TextPart — A text content part containing plain text or markdown. Used for agent messages, user input, and text-based responses.
            - `kind` 'text', required
            - `text` string, required
          - ErrorPart — An error content part containing error information. Used when an error occurs during agent execution.
            - `kind` 'error', required
            - `error` string, required
            - `code` number
          - DataPart — A structured data part containing JSON-serializable key-value pairs. Used for passing structured information between agents and tools.
            - `kind` 'data', required
            - `data` object, required
            - `metadata` object
          - FilePart — 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.
            - `kind` 'file', required
            - `file` union, required
              - …
            - `metadata` object
          - ToolCallPart — A tool invocation request from an agent. Contains the tool name, unique call ID, and arguments for the tool execution.
            - `kind` 'tool_call', required
            - `tool_name` string, required
            - `tool_call_id` string, required
            - `arguments` object, required
            - `thought_signature` string
            - `metadata` object
          - ToolResultPart — The result of a tool execution. Contains the tool call ID for correlation and the result data from the tool invocation.
            - `kind` 'tool_result', required
            - `tool_call_id` string, required
            - `result` unknown
            - `metadata` object
  - `messages` ExtendedMessage[] — Array of messages in the task conversation. Only present when blocking mode is enabled.
    - `kind` 'message', required
    - `messageId` string, required — Unique identifier for the message
    - `role` 'user' | 'agent' | 'tool' | 'system', required — 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` union[], required — Array of message parts (text, file, tool_call, tool_result)
      - union
        - TextPart — A text content part containing plain text or markdown. Used for agent messages, user input, and text-based responses.
          - `kind` 'text', required
          - `text` string, required
        - ErrorPart — An error content part containing error information. Used when an error occurs during agent execution.
          - `kind` 'error', required
          - `error` string, required
          - `code` number
        - DataPart — A structured data part containing JSON-serializable key-value pairs. Used for passing structured information between agents and tools.
          - `kind` 'data', required
          - `data` object, required
          - `metadata` object
        - FilePart — 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.
          - `kind` 'file', required
          - `file` union, required
            - object — Binary in base64 format. Check in the model's documentation for the supported mime types for the binary format.
              - …
            - object — File in URI format. Check in the model's documentation for the supported mime types for the URI format
              - …
          - `metadata` object
        - ToolCallPart — A tool invocation request from an agent. Contains the tool name, unique call ID, and arguments for the tool execution.
          - `kind` 'tool_call', required
          - `tool_name` string, required
          - `tool_call_id` string, required
          - `arguments` object, required
          - `thought_signature` string
          - `metadata` object
        - ToolResultPart — The result of a tool execution. Contains the tool call ID for correlation and the result data from the tool invocation.
          - `kind` 'tool_result', required
          - `tool_call_id` string, required
          - `result` unknown
          - `metadata` object
    - `taskId` string — Associated task ID if applicable
    - `contextId` string — Correlation ID for execution tracking
    - `metadata` object — Additional message metadata
  - `metadata` object — Task metadata containing workspace_id and trace_id for feedback and tracking

---

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