open-responses

What this skill does

# Open Responses

Open Responses is an open-source specification defining a unified HTTP protocol for multi-provider LLM interactions. It standardizes how clients and servers communicate — messages, tool calls, streaming, multimodal inputs, reasoning — so that code written against one provider works with any compliant provider.

> **This is the protocol standard itself, not any specific SDK.** Open Responses is provider-agnostic. Any LLM provider (OpenAI, Anthropic, Gemini, Databricks, Hugging Face, Ollama, etc.) can implement a compliant API.

> **Stateless by default, stateful where needed.** The core protocol does not require server-side session persistence. Multi-turn conversations can be threaded via `previous_response_id`, which instructs the server to reconstruct context from prior responses. However, providers may offer stateful features (e.g., server-side storage, conversation objects) as extensions. The spec notes that item states "do not necessarily mean they are stateful in the sense of being persisted to disk or stored long-term."

### Design Principles

- **Multi-provider compatibility** — one schema, any provider
- **Stateless-first protocol** — context reconstruction via `previous_response_id`; providers may optionally offer persistence
- **Polymorphic items** — all model outputs share a common item structure discriminated by `type`
- **Semantic streaming** — SSE events map directly to state machine transitions
- **Extensible without fragmentation** — vendor-prefixed extensions prevent namespace collisions

**Specification:** https://www.openresponses.org/specification

---

## Reference Files

For detailed schemas, JSON examples, and complete event catalogs, load the appropriate reference file:

| File | Contents | When to Load |
|------|----------|-------------|
| `references/protocol-and-items.md` | HTTP protocol, item types, content types, control parameters, error handling | Implementing or debugging request/response structure |
| `references/state-machines-and-streaming.md` | State machine diagrams, streaming event catalog, complete SSE sequences for text and tool use | Implementing or debugging streaming, state transitions |
| `references/extensions.md` | Custom items, custom events, schema extensions, governance path | Extending the spec with provider-specific features |

To search references for specific topics: grep for `function_call`, `streaming`, `tool_choice`, `previous_response_id`, `vendor:`, or other keywords.

---

## Core Concepts

### Endpoint and Transport

All requests go to `POST /v1/responses` with `Authorization: Bearer <token>` and `Content-Type: application/json`. Non-streaming responses return JSON. Streaming responses use SSE (`text/event-stream`) terminated by `data: [DONE]`.

### Items

Items are polymorphic atomic units discriminated by `type`. **Output items** (those emitted by the model in a response) must include `id`, `type`, and `status` fields. Core output types: `message`, `function_call`, `reasoning`. Providers extend with vendor-prefixed types (e.g., `acme:web_search_call`).

**Input items** (those sent by the client in a request) have different requirements per type. Content types like `input_text`, `input_image`, and `input_file` do not carry `id` or `status`. `function_call_output` items require `call_id` and `output` but treat `id` and `status` as optional.

**Message roles:** `user`, `assistant`, `system`, `developer`. The `system` role is distinct from the `instructions` parameter — it is an inline message item in the input array. The `developer` role is a separate role that providers may handle differently from `system`.

### State Machines and Event Emission

The response and item lifecycles are both finite state machines. Each state constrains which events can be emitted.

#### Response Lifecycle — Events Emitted Per State

```mermaid
stateDiagram-v2
    [*] --> created : response.created
    created --> queued : response.queued
    queued --> in_progress : response.in_progress

    state in_progress {
        direction LR
        note right of in_progress
            Events emittable while in_progress:
            ─────────────────────────────────
            response.output_item.added
            response.content_part.added
            response.output_text.delta
            response.output_text.done
            response.function_call_arguments.delta
            response.function_call_arguments.done
            response.reasoning_summary_text.delta
            response.reasoning_summary_text.done
            response.content_part.done
            response.output_item.done
            vendor:custom_event

            All delta events carry: sequence_number,
            output_index, item_id
            Content-level events also carry: content_index
        end note
    }

    in_progress --> completed : response.completed
    in_progress --> incomplete : response.incomplete\n(item hit token budget)
    in_progress --> failed : response.failed
    completed --> [*]
    incomplete --> [*]
    failed --> [*]
```

> **Note:** If any item ends in `incomplete` status, the containing response MUST also be `incomplete`.

#### Item Lifecycle — Events Emitted Per State

```mermaid
stateDiagram-v2
    [*] --> in_progress : response.output_item.added

    state in_progress {
        direction LR
        note right of in_progress
            Events emittable while item is in_progress:
            ──────────────────────────────────────────
            Message items:
              response.content_part.added
              response.output_text.delta  (repeated)
              response.output_text.done
              response.content_part.done

            Function call items:
              response.function_call_arguments.delta  (repeated)
              response.function_call_arguments.done

            Reasoning items:
              response.reasoning_summary_text.delta  (repeated)
              response.reasoning_summary_text.done
        end note
    }

    in_progress --> completed : response.output_item.done
    in_progress --> incomplete : response.output_item.done
    completed --> [*]
    incomplete --> [*]

    note right of completed : Terminal — no further deltas
    note right of incomplete : Terminal — token budget exhausted
```

#### Event Validity Summary

| Response State | Valid Events |
|---------------|-------------|
| `created` | *(transient — response object just created)* |
| `queued` | *(waiting for model availability)* |
| `in_progress` | All delta events, all custom events, item lifecycle events |
| `completed` | *(terminal — no more events except `[DONE]`)* |
| `incomplete` | *(terminal — no more events except `[DONE]`)* |
| `failed` | *(terminal — no more events except `[DONE]`)* |

| Item State | Valid Events |
|-----------|-------------|
| `in_progress` | Content deltas (`.delta`), content completion (`.done`), part lifecycle |
| `completed` | *(terminal — no further deltas for this item)* |
| `incomplete` | *(terminal — no further deltas for this item)* |

All delta and item events carry `sequence_number` (monotonically increasing), `output_index` (position in response output array), and `item_id`. Content-level events (text, reasoning summary) additionally carry `content_index` (position within a content part). Servers SHOULD NOT use the SSE `id` field.

### Streaming Events

Two categories of SSE events:

- **Delta events** — incremental content: `response.output_text.delta`, `response.function_call_arguments.delta`, `response.output_item.added`, `response.output_item.done`, etc.
- **Lifecycle events** — state transitions: `response.created`, `response.queued`, `response.in_progress`, `response.completed`, `response.incomplete`, `response.failed`

Rule: the `event` SSE header must match the `type` field inside the JSON body.

---

## Tools

Open Responses defines two tool categories based on execution location.

**Externally-hosted tools** — implementation lives outsid