> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unpod.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Adapters Reference

> The DialogAdapter protocol, every bundled adapter signature, auto-wrapping rules, and error surfaces.

Reference for the brain slot. For worked examples and guidance, see
[Bring Your Agent](https://docs.unpod.ai/agent-sdk/bring-your-agent.md); this page is the contract.

## The DialogAdapter protocol

Defined in `unpod.adapters.base`. Runtime-checkable - any object with these
three methods passes `isinstance(obj, DialogAdapter)`; no base class required.

```python theme={null}
class DialogAdapter(Protocol):
    async def turn(self, text: str, context: dict | None = None) -> str:
        """Return a complete response string. NOT called during live calls."""

    async def stream(
        self, text: str, context: dict | None = None, language: str | None = None
    ) -> AsyncIterator[str]:
        """Yield response tokens. HOT PATH - session.run() calls this on
        every user turn and streams tokens directly to the voice bridge.
        `language` is the per-turn language code (from `UserTextEvent.extra`),
        forwarded by `session.run()`. Custom adapters MUST accept the kwarg
        even if they ignore it."""

    def assist(self, text: str) -> None:
        """Inject a system instruction before the next turn."""
```

> [!WARNING]
>
> `stream()` now receives a `language` keyword argument on every turn. Any custom
> adapter whose `stream()` does not accept `language=...` raises `TypeError` on the
> first user turn. Add `language: str | None = None` to the signature.

> [!WARNING]
>
> `session.run()` calls only `stream()`. A single-chunk `stream()` fallback
> (await the full reply, yield once) produces choppy, high-latency audio with no
> error anywhere. See
> [Streaming is the hot path](https://docs.unpod.ai/agent-sdk/bring-your-agent.md#streaming-is-the-hot-path).

## Auto-wrapping

The `ctx.session.dialog_machine` setter accepts, in order:

1. A superdialog `DialogMachine` or `LLMAgent` - wrapped in a
   `SuperDialogAdapter` automatically.
2. Any object satisfying the `DialogAdapter` protocol - used as-is.
3. Anything else - raises `TypeError`.

## Bundled adapters

All importable from `unpod.adapters`:
`AnthropicAdapter`, `DialogAdapter`, `HTTPAdapter`, `LangChainAdapter`,
`MCPAdapter`, `OpenAIAdapter`, `SuperDialogAdapter`.

### Constructor signatures

| Adapter | Constructor | Wraps |
| - | - | - |
| `OpenAIAdapter` | `(client, model="gpt-4o-mini", system_prompt=None)` | `openai.AsyncOpenAI` client |
| `AnthropicAdapter` | `(client, model="claude-haiku-4-5-20251001", system_prompt=None, max_tokens=1024)` | `anthropic.AsyncAnthropic` client |
| `LangChainAdapter` | `(chain, input_key="messages")` | LangChain Runnable with `ainvoke`/`astream` |
| `HTTPAdapter` | `(url, headers=None, timeout_s=10.0)` | A remote HTTP endpoint, any language |
| `MCPAdapter` | `(server_url, tools=None, llm="anthropic/claude-haiku-4-5", headers=None)` | An MCP server (preview - see below) |
| `SuperDialogAdapter` | `(dm)` | superdialog `DialogMachine` or `LLMAgent` |

### Streaming behavior

| Adapter | `stream()` behavior |
| - | - |
| `OpenAIAdapter` | Real token streaming via `chat.completions.create(stream=True)` |
| `AnthropicAdapter` | Real token streaming via `messages.stream()` |
| `LangChainAdapter` | Real streaming via the chain's `.astream()` |
| `SuperDialogAdapter` | Delegates to `dm.turn(text, stream=True[, language=…])` - `language` is passed through only when the wrapped machine's `turn()` accepts it |
| `HTTPAdapter` | **Single chunk** - one POST round-trip, full reply yielded once |
| `MCPAdapter` | Falls back to `turn()`, which is not implemented yet |

### `assist()` semantics

| Adapter | What `assist(text)` does |
| - | - |
| `OpenAIAdapter` / `LangChainAdapter` | Injects the instruction into the conversation history |
| `AnthropicAdapter` | Injects as a user/assistant message pair - the Anthropic API does not accept mid-conversation system messages |
| `HTTPAdapter` | Queues the instruction; sent as `system_instructions` in the next request body |
| `MCPAdapter` | Queues the instruction (pending full implementation) |
| `SuperDialogAdapter` | Delegates to the DialogMachine's `assist()` |

### SuperDialogAdapter extras

Beyond the protocol, `SuperDialogAdapter` exposes the wrapped agent's controls:

```python theme={null}
adapter.set_llm("anthropic/claude-haiku-4-5")        # swap the runtime model
adapter.switch_flow("billing", preserve_memory=False) # graph engine only (FlowSet)
adapter.is_complete                                   # reached a terminal state?
adapter.state                                         # current state (dict)
```

`is_complete` and `state` work on both engines; on the Playbook engine `state`
returns `{"checkpoint": ..., "slots": ..., "ended": ...}`. `switch_flow` applies
only to the legacy graph engine (a `DialogMachine` built from a `FlowSet`).
See [SuperDialog](https://docs.unpod.ai/superdialog/introduction.md) for the agent itself.

## Error surfaces

| Failure | What you see |
| - | - |
| Assigning a non-adapter to `dialog_machine` | `TypeError` from the setter, immediately |
| `HTTPAdapter` endpoint returns non-2xx | `httpx.HTTPStatusError` (the adapter calls `raise_for_status()`) |
| `HTTPAdapter` endpoint slower than `timeout_s` | `httpx.TimeoutException` |
| `MCPAdapter` without the `mcp` package | `ImportError` - install with `unpod[mcp]` |
| `MCPAdapter` with the package | `NotImplementedError` - full MCP orchestration is not implemented yet |
| `LangChainAdapter` with a chain expecting a different input shape | No error - the chain receives `{input_key: history}` and may silently misbehave; set `input_key` to match your chain |
| Lazy `stream()` in a custom adapter | No error - choppy, delayed audio on calls |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.