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": {},
"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": {}
}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.
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": {},
"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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The key or ID of the agent to invoke
Body
The A2A message to send to the agent (user input or tool results)
Show child attributes
Show child attributes
Message role (user or tool for continuing executions)
user A2A message parts (text, file, or tool_result only)
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.
Optional A2A message ID in ULID format
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.
Information about the contact making the request. If the contact does not exist, it will be created automatically.
Show child attributes
Show child attributes
Unique identifier for the contact
"contact_01ARZ3NDEKTSV4RRFFQ69G5FAV"
Display name of the contact
"Jane Doe"
Email address of the contact
URL to the contact's avatar or logo
"https://example.com/avatars/jane-doe.jpg"
A list of tags associated with the contact
["hr", "engineering"]
Thread information to group related requests
Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.
Show child attributes
Show child attributes
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.
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.
Response format following the Agent-to-Agent (A2A) protocol. Returned when starting or continuing an agent task execution.
The unique ID of the created agent execution task
The correlation ID for this execution (used for tracking)
A2A entity type identifier
task Current task status information
Show child attributes
Show child attributes
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.
submitted, working, input-required, auth-required, completed, failed, canceled, rejected ISO 8601 timestamp of when the status was updated
Optional A2A message providing additional context about the current status
Show child attributes
Show child attributes
message Role of the message sender in the A2A protocol. Values: user (end user), agent (AI agent), tool (tool execution result), system (system instructions/prompts).
user, agent, tool, system A text content part containing plain text or markdown. Used for agent messages, user input, and text-based responses.
Was this page helpful?