Skip to main content
POST
/
v2
/
agents
/
{key}
/
task
Execute an agent task
curl --request POST \
  --url https://api.orq.ai/v2/agents/{key}/task \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "<string>"
      }
    ],
    "messageId": "<string>"
  },
  "task_id": "<string>",
  "variables": {},
  "identity": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "[email protected]",
    "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": "[email protected]",
    "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"
    ]
  },
  "memory": {
    "entity_id": "<string>"
  },
  "metadata": {}
}
'
{
  "id": "<string>",
  "contextId": "<string>",
  "kind": "task",
  "status": {
    "state": "submitted",
    "timestamp": "<string>",
    "message": {
      "kind": "message",
      "messageId": "<string>",
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "<string>"
        }
      ]
    }
  },
  "metadata": {}
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
key
string
required

The key or ID of the agent to invoke

Body

application/json
​
message
A2A Message · object
required

The A2A message to send to the agent (user input or tool results)

​
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.

​
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.

​
contact
object
deprecated

@deprecated Use identity instead. Information about the contact making the request.

​
thread
object

Thread information to group related requests

​
memory
object

Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.

​
metadata
object

Optional metadata for the agent invocation as key-value pairs that will be included in traces

Response

200 - application/json

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.

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
enum<string>
required

A2A entity type identifier

Available options:
task
​
status
Task Status · object
required

Current task status information

​
metadata
object

Task metadata containing workspace_id and trace_id for feedback and tracking