Chat completions

The chat completions API is compatible with the OpenAI chat completions format. Existing OpenAI client libraries can be used by pointing them to ${RUNTIME_BASE_URL}/v1 and adding the X-Tenant-ID header.

The complete, interactive API reference of the Agent Runtime is available at ${RUNTIME_BASE_URL}/docs.

List available agents

Every published agent or team is an instance. Get the list first:

GET ${RUNTIME_BASE_URL}/v1/instances
Authorization: Bearer ${RUNTIME_TOKEN}
X-Tenant-ID: ${TENANT_ID}

{
  "data": [
    {
      "id": "support-assistant.agent.support-assistant-agent",
      "name": "Support Assistant Agent",
      "type": "agent_instance",
      "metadata": { "description": "Agent with retrieval capabilities for troubleshooting" }
    }
  ]
}

Use the id as the model in chat requests. See Deployments for how instance IDs are built.

Send a message

POST ${RUNTIME_BASE_URL}/v1/chat/completions

{
  "model": "support-assistant.agent.support-assistant-agent",
  "messages": [
    { "id": "msg-001", "role": "user", "content": "The packaging line camera is drifting." }
  ],
  "stream": false,
  "metadata": {
    "chat_id": "conv-abc-123",
    "message_id": "msg-002",
    "user_id": "john.doe"
  }
}

Field	Description
model	Instance ID from /v1/instances
messages	Conversation history in OpenAI format. Roles: system, user, assistant, tool.
stream	true for Server-Sent Events, see Streaming events
tools	Optional functions your application provides, see External tools
tool_choice	Optional. Forces the use of one external tool.
metadata	IDs that let the service keep the conversation state, see Sessions

Response

{
  "id": "support-assistant.agent.support-assistant-agent-a1b2c3d4",
  "object": "chat.completion",
  "created": 1736650000,
  "model": "support-assistant.agent.support-assistant-agent",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Please confirm the camera model and when the drift started."
      },
      "finish_reason": "stop"
    }
  ]
}

finish_reason is stop for a normal answer and tool_calls if the agent wants your application to run an external tool.

Streaming or not?

	Streaming ("stream": true)	Non-streaming
Text	Arrives token by token	Arrives as one answer
Progress, notifications	Delivered as events	Not included
Citations	Delivered as events	Appended to the answer text
Guardrail replacements	Delivered as replace event	Already applied to the answer
Approval requests	Delivered as confirmation event	Not delivered. Do not use agents with tools that need approval.

Use streaming for interactive chat interfaces. Non-streaming is fine for background processing.