Sign in
OpenAPI 3.1.0raw.githubusercontent.com2026-08-202766453.1 MB

2cd7e7f7bcb4

Agents

Execute an agent task

Invoke an agent to perform a task with input messages. Supports tool execution, knowledge retrieval, memory context, and model fallback.

post/v2/agents/{key}/task

Path parameters

keystring required

The key or ID of the agent to invoke

The key or ID of the agent to invoke

Request body

task_idstring

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.

variablesobject

Optional variables for template replacement in system prompt, instructions, and messages

metadataobject

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.

Example request

{
  "identity": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "metadata": [
      {
        "department": "Engineering",
        "role": "Senior Developer"
      }
    ],
    "logo_url": "https://example.com/avatars/jane-doe.jpg",
    "tags": [
      "hr",
      "engineering"
    ]
  },
  "contact": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "metadata": [
      {
        "department": "Engineering",
        "role": "Senior Developer"
      }
    ],
    "logo_url": "https://example.com/avatars/jane-doe.jpg",
    "tags": [
      "hr",
      "engineering"
    ]
  },
  "thread": {
    "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "tags": [
      "customer-support",
      "priority-high"
    ]
  }
}

Response

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.

idstring required

The unique ID of the created agent execution task

contextIdstring required

The correlation ID for this execution (used for tracking)

kind'task' required

A2A entity type identifier

metadataobject

Task metadata containing workspace_id and trace_id for feedback and tracking