Action required: Entity management is moving from Workspaces to Projects. Migrate your entities now. See how to move entities in our guide.
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": {}
}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": {}
}Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
The key or ID of the agent to invoke
The A2A message to send to the agent (user input or tool results)
Show child attributes
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.
Optional variables for template replacement in system prompt, instructions, and messages
Show child attributes
Information about the contact making the request. If the contact does not exist, it will be created automatically.
Show child attributes
Thread information to group related requests
Show child attributes
Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.
Show child attributes
Optional metadata for the agent invocation as key-value pairs that will be included in traces
Show child attributes
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
Task metadata containing workspace_id and trace_id for feedback and tracking
Show child attributes
Was this page helpful?