Ask an agent

POST /v1/agent/chat/completions runs one of your agents on a message and returns the agent's answer. The agent works as it does in the app: with its instructions, its knowledge and its actions.

Scope: agents:run.

Request

curl "$AGENTWORKS_API_URL/v1/agent/chat/completions" \
  -H "Authorization: Bearer $AGENTWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "AGENT_ID",
    "messages": [
      { "id": "m1", "role": "user", "parts": [ { "type": "text", "text": "Which invoices are overdue?" } ] }
    ]
  }'

The agent works on the text of the last user message.

Response

{
  "messages": [
    { "id": "…", "role": "assistant", "content": "…" }
  ]
}

The call returns when the run has finished.

Good to know

• Streaming is not available on this endpoint; "stream": true answers 400.
• Each call starts a fresh run. Continuing an earlier conversation is not available; sending conversationId answers 400.
• An unknown or inaccessible agentId answers 400.
• If the agent needs an approval, a person decides it in the app. A key cannot approve.
• Requests from a browser are refused. Call this endpoint from your server.
• For work that takes longer, or that you want on the board, use tasks and runs instead.