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

contact
object

Information about the contact making the request. If the contact does not exist, it will be created automatically.

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 created successfully

A2A Task response format

id
string
required

The ID of the created agent execution task

contextId
string
required

The correlation ID for this execution

kind
enum<string>
required

A2A entity type

Available options:
task
status
object
required

Task status information

metadata
object

Task metadata containing workspace_id and trace_id for feedback