Responses API

Chat completions are the default API, and all other pages of this section describe them. The Responses API is an alternative for rich chat interfaces.

The Responses API follows the OpenAI Responses specification. Instead of one stream of text, it delivers a response as a list of output items: reasoning, tool activity, the answer and requests for external tools. This makes it a good fit for chat interfaces that show these parts separately. Both APIs run the same agents.

Send a request

POST ${RUNTIME_BASE_URL}/v1/responses
Authorization: Bearer ${RUNTIME_TOKEN}
X-Tenant-ID: ${TENANT_ID}
Content-Type: application/json
Accept: text/event-stream

{
  "model": "support.agent.spare-parts",
  "input": "Which spare parts are compatible with machine 4711?",
  "stream": true,
  "previous_response_id": null,
  "store": true
}

Field	Description
model	Instance ID from GET /v1/instances
input	A string, or a list of input items (messages and function_call_output items)
stream	Must be true. Non-streaming requests are rejected with 400.
previous_response_id	ID of the previous response, to continue a conversation
store	true lets the service keep the conversation state. With false, each request must contain the full history in input.
tools	Optional functions your application provides

Stream structure

Each event has a type and an increasing sequence_number. Use the sequence_number to order events.

response.created
response.in_progress
  ├─ output_index 0: reasoning                   (the model's thinking)
  ├─ output_index 1: agent_runtime:function_call (tool run by the service, shown for transparency)
  ├─ output_index 2: message                     (answer text with citations)
  └─ output_index 3: function_call               (external tool, run by your application)
response.completed | response.failed

Every item is opened by response.output_item.added, filled by delta events and closed by response.output_item.done. The final response.completed or response.failed event contains the complete response with all items.

Item types

Item type	What it is	What your client does
message	The answer	Render the text from response.output_text.delta. On response.output_text.done, replace the buffer with the final text.
reasoning	The model’s thinking	Render it collapsed, separate from the answer. A response can contain several reasoning items.
agent_runtime:function_call	A tool the service runs itself	Show it as activity, including its result or error. Never execute it.
function_call	An external tool	Run it in your application, then send the result. See below.

Citations

Sources are sent as response.output_text.annotation.added events of type url_citation with url and title. Use annotation_index for numbered references. The complete list is repeated in response.output_text.done.

Guardrails

If a guardrail blocks the turn, response.output_text.done carries an empty text and the message gets a refusal content part with the message for the user. Remove any text already shown and display the refusal instead. The response still ends with response.completed.

Errors

Situation	Events	Client behavior
A tool failed, the agent continues	response.output_item.done with status: "failed" and an error on the tool item	Show the failed tool, keep streaming
The response cannot continue	error, then response.failed	Keep the partial answer, show an error and offer a retry

Continue a conversation

Keep the id of the last response (for example resp_8f2c…) and send it as previous_response_id with the next input:

Turn	Request	Response
1	input: "…"	resp_A
2	previous_response_id: "resp_A", input: "…"	resp_B

External tools

Send your tool definitions in tools:

{
  "type": "function",
  "name": "ask_multiple_choice",
  "description": "Ask the user to pick one option from a list.",
  "parameters": {
    "type": "object",
    "properties": {
      "question": { "type": "string" },
      "options": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["question", "options"]
  }
}

When the agent calls the tool, the response contains a function_call item with name, arguments and call_id, and then ends. Run the function and continue with its result:

{
  "model": "support.agent.spare-parts",
  "previous_response_id": "resp_8f2c…",
  "stream": true,
  "input": [
    { "type": "function_call_output", "call_id": "call_abc123", "output": "A-104 Support Bracket" }
  ]
}

Feedback

To rate an answer with the feedback API, send the response id as meta.message_id.

Client checklist

1. Order events by sequence_number and ignore unknown event and item types.
2. Keep a map from output_index to item. Several items can occur in one response.
3. Show agent_runtime:function_call items, but never execute them.
4. Execute only items of type function_call, and answer each with a function_call_output.
5. On a refusal, remove the displayed text and show the refusal.
6. On response.completed, store the response id for the next turn.
7. On response.failed, keep the partial answer and offer a retry.