Skip to main content
POST
/
v2
/
agents
/
{agent_key}
/
responses
cURL
curl --request POST \
  --url 'https://api.orq.ai/v2/agents/customer_support/responses' \
  --header 'Authorization: Bearer $ORQ_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Hi! I am testing your capabilities. Can you describe what you can do?"
        }
      ]
    }
  }'
{
  "_id": "<string>",
  "task_id": "<string>",
  "output": [
    {
      "messageId": "<string>",
      "role": "user",
      "parts": [
        "<any>"
      ],
      "metadata": {}
    }
  ],
  "created_at": "<string>",
  "model": "<string>",
  "usage": {
    "completion_tokens": 123,
    "prompt_tokens": 123,
    "total_tokens": 123,
    "prompt_tokens_details": {
      "cached_tokens": 123,
      "audio_tokens": 123
    },
    "completion_tokens_details": {
      "reasoning_tokens": 123,
      "accepted_prediction_tokens": 123,
      "rejected_prediction_tokens": 123,
      "audio_tokens": 123
    }
  }
}
If the background parameter is set to true, the service will return a response immediately without waiting for the agent’s execution to complete.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
agent_key
string
required

The unique key of identifier of the agent to invoke

Body

application/json
​
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

​
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

​
background
boolean
default:false

If true, returns immediately without waiting for completion. If false (default), waits until the agent becomes inactive or errors.

Response

200 - application/json

Agent response successfully created and completed. Returns the full conversation including all messages, tool interactions, model used, and token usage statistics. In background mode, returns immediately with initial task details.

​
_id
string
required

The unique response ID

​
task_id
string
required

The agent execution task ID

​
output
object[]
required

Array of messages from the agent execution

​
created_at
string
required

ISO timestamp of response creation

​
model
string
required

Model used in provider/model format

​
usage
object | null

Token usage from the agent execution