The Open Standard for Generative UI
docs(react-headless): document eveAdapter alongside the other six stream adapters (#1275)
Ankit Dasbba1d2515fa5
diff --git a/docs/content/docs/agent/reference/adapters-and-formats.mdx b/docs/content/docs/agent/reference/adapters-and-formats.mdxindex 9d80a3c81..e417aa9b4 100644--- a/docs/content/docs/agent/reference/adapters-and-formats.mdx+++ b/docs/content/docs/agent/reference/adapters-and-formats.mdx@@ -36,6 +36,7 @@ import {openAIResponsesAdapter,vercelAIAdapter,langGraphAdapter,+ eveAdapter,openAIMessageFormat,openAIConversationMessageFormat,vercelAIMessageFormat,@@ -45,7 +46,7 @@ import {```<Callout type="warn">- All six stream adapters are **factory functions** — always call them with `()`. `streamAdapter:+ All seven stream adapters are **factory functions** — always call them with `()`. `streamAdapter:openAIAdapter()` is correct; a bare `streamAdapter: openAIAdapter` is wrong.</Callout>@@ -354,13 +355,13 @@ interface StreamProtocolAdapter {}```-`fetchLLM` calls `parse` on the `Response` your route returns and consumes the yielded AG-UI events. All six bundled adapters are factories you call to get an instance — `agUIAdapter()`, `openAIAdapter()`, `openAIReadableStreamAdapter()`, `openAIResponsesAdapter()`, `vercelAIAdapter()`, `langGraphAdapter()`; only `langGraphAdapter()` accepts options.+`fetchLLM` calls `parse` on the `Response` your route returns and consumes the yielded AG-UI events. All seven bundled adapters are factories you call to get an instance — `agUIAdapter()`, `openAIAdapter()`, `openAIReadableStreamAdapter()`, `openAIResponsesAdapter()`, `vercelAIAdapter()`, `langGraphAdapter()`, `eveAdapter()`; only `langGraphAdapter()` and `eveAdapter()` accept options.<Callout type="info">The line-oriented adapters log and skip malformed lines. `vercelAIAdapter()` delegates validationto the Vercel AI SDK and rejects invalid UIMessage chunks. Provider-level failures should be- surfaced as a `RUN_ERROR` event (the OpenAI Responses, Vercel AI SDK, and LangGraph adapters do- this for their error events).+ surfaced as a `RUN_ERROR` event (the OpenAI Responses, Vercel AI SDK, LangGraph, and Eve adapters+ do this for their error events).</Callout>### Selection guide@@ -374,6 +375,7 @@ Start from your provider and how the route streams its reply. The stream adapter| OpenAI **Responses / Conversations** API SSE | `openAIResponsesAdapter()` | `openAIConversationMessageFormat` || **Vercel AI SDK v6** UIMessage SSE (`toUIMessageStreamResponse()`) | `vercelAIAdapter()` | `vercelAIMessageFormat` || **LangGraph** named-event SSE (`event: messages\ndata: …`) | `langGraphAdapter()` | `langGraphMessageFormat` |+| **Vercel Eve** session stream (NDJSON harness events) | `eveAdapter()` | — (Eve keeps the transcript) || Already AG-UI events (your route emits AG-UI SSE directly) | `agUIAdapter()` | `identityMessageFormat` (default) |Wrapping Anthropic, or any provider with no bundled adapter? You have two paths: translate to AG-UI events server-side and use `agUIAdapter()`, or re-emit your provider's stream as OpenAI Completions SSE and use `openAIAdapter()`.@@ -485,9 +487,28 @@ const llm = fetchLLM({- **Wire shape:** LangGraph **named-event** SSE — `event: <type>\ndata: <json>\n\n` blocks, in the `messages` stream mode. Handles the `messages`, `metadata`, `updates`, `error`, and `end` event types; other event types (`values`, `debug`, `tasks`, `checkpoints`, `custom`) are ignored.- **What it handles:** AI message chunks → `TEXT_MESSAGE_*`; both streamed (`tool_call_chunks`) and complete (`tool_calls`) tool calls → `TOOL_CALL_*`; `error` events → `RUN_ERROR`. It closes out any open message/tool calls on the `end` event (or at stream end if no `end` arrives).- **Options** (`LangGraphAdapterOptions`):- - `onInterrupt?: (interrupt: unknown) => void` — invoked with the `__interrupt__` payload when a LangGraph interrupt surfaces in an `updates` event. This is the only adapter that takes options.+ - `onInterrupt?: (interrupt: unknown) => void` — invoked with the `__interrupt__` payload when a LangGraph interrupt surfaces in an `updates` event. `eveAdapter()` is the other adapter that takes options.- **When to use:** Your backend streams from a LangGraph deployment. Pair with `langGraphMessageFormat`.+### `eveAdapter`++```ts+import { eveAdapter, type ChatLLM } from "@openuidev/react-ui";++const llm: ChatLLM = {+ // Deliver the latest user turn to the Eve session and return its NDJSON+ // stream — see the Vercel Eve runtime page for the full session bridge.+ send: ({ messages, signal }) => deliverTurnAndOpenStream(messages, signal),+ streamProtocol: eveAdapter(),+};+```++- **Wire shape:** Vercel Eve's newline-delimited JSON session stream (`GET /eve/v1/session/:id/stream`) — one harness event per line, no `data:` prefix.+- **What it handles:** `actions.requested` → `TOOL_CALL_START` / `TOOL_CALL_ARGS` / `TOOL_CALL_END`; `action.result` → `TOOL_CALL_RESULT`; `message.appended` → `TEXT_MESSAGE_CONTENT` (with `message.completed` as the fallback for steps that streamed no deltas); `input.requested` → a `CUSTOM` event named `eve.input.requested` (exported as `EVE_INPUT_REQUESTED_EVENT`); `turn.failed` / `session.failed` → `RUN_ERROR`. Tool calls and text share one assistant message id. Parsing stops at the turn boundary (`session.completed`, `session.waiting`, `session.failed`).+- **Options** (`EveAdapterOptions`):+ - `onEvent?: (event: EveStreamEvent) => void` — receives every raw Eve event before translation, including types the adapter does not map (`session.started`, `reasoning.appended`, …).+- **When to use:** Your browser talks to an Eve session directly (or through a same-origin proxy such as `withEve()`) and you want Eve's turns rendered by `AgentInterface`. Eve keeps the conversation server-side, so there is no paired message format: `send` delivers only the latest user turn and returns the session stream. See [Vercel Eve](/docs/agent/agent-runtimes/vercel-eve) for the complete bridge.+### AG-UI event vocabularyEvery stream adapter normalizes its provider's stream into the same set of **AG-UI events** — the agent↔UI event protocol OpenUI streams internally (from the `@ag-ui/core` package). These events progressively build the assistant message as they arrive.diff --git a/docs/content/docs/api-reference/react-headless.mdx b/docs/content/docs/api-reference/react-headless.mdxindex ee902f6f3..2f3705991 100644--- a/docs/content/docs/api-reference/react-headless.mdx+++ b/docs/content/docs/api-reference/react-headless.mdx@@ -19,9 +19,12 @@ import {openAIReadableStreamAdapter,vercelAIAdapter,agUIAdapter,+ langGraphAdapter,+ eveAdapter,openAIMessageFormat,openAIConversationMessageFormat,vercelAIMessageFormat,+ langGraphMessageFormat,identityMessageFormat,processStreamedMessage,MessageProvider,@@ -137,6 +140,8 @@ function openAIResponsesAdapter(): StreamProtocolAdapter; // OpenAI Responses stfunction openAIReadableStreamAdapter(): StreamProtocolAdapter; // OpenAI ReadableStreamfunction vercelAIAdapter(): StreamProtocolAdapter; // Vercel AI SDK v6 UIMessage streamfunction agUIAdapter(): StreamProtocolAdapter; // AG-UI protocol stream+function langGraphAdapter(options?: LangGraphAdapterOptions): StreamProtocolAdapter; // LangGraph named-event SSE+function eveAdapter(options?: EveAdapterOptions): StreamProtocolAdapter; // Vercel Eve NDJSON session stream```Related type:@@ -155,6 +160,7 @@ Converters referenced in integration guides:const openAIMessageFormat: MessageFormat; // Chat Completions formatconst openAIConversationMessageFormat: MessageFormat; // Responses/Conversations item formatconst vercelAIMessageFormat: MessageFormat; // Vercel AI SDK v6 UIMessage format+const langGraphMessageFormat: MessageFormat; // LangGraph / LangChain message formatconst identityMessageFormat: MessageFormat; // Pass-through (no conversion)```diff --git a/packages/react-headless/AGENTS.md b/packages/react-headless/AGENTS.mdindex 4e689e05a..ed01179eb 100644--- a/packages/react-headless/AGENTS.md+++ b/packages/react-headless/AGENTS.md@@ -30,6 +30,8 @@ Build order: **`react-headless`** → `react-lang` → `react-ui`. This package| `src/stream/adapters/openai-completions.ts` | Adapter for OpenAI Chat Completions streaming (`ChatCompletionChunk`). || `src/stream/adapters/openai-responses.ts` | Adapter for OpenAI Responses API streaming (`ResponseStreamEvent`). || `src/stream/adapters/openai-readable-stream.ts` | Adapter for OpenAI SDK's `Stream.toReadableStream()` — parses NDJSON (no SSE prefix) `ChatCompletionChunk` objects. |+| `src/stream/adapters/langgraph.ts` | Adapter for LangGraph named-event SSE (`event: messages` blocks); `onInterrupt` option. |+| `src/stream/adapters/eve.ts` | Adapter for Vercel Eve NDJSON session streams; `onEvent` option, exports `EVE_INPUT_REQUESTED_EVENT`. || `src/stream/adapters/openai-message-format.ts` | `MessageFormat` for OpenAI Completions (`ChatCompletionMessageParam[]` ↔ AG-UI). || `src/stream/adapters/openai-conversation-message-format.ts` | `MessageFormat` for OpenAI Responses/Conversations API (`ResponseInputItem[]` ↔ AG-UI). || `src/types/` | Shared types: `message.ts` (re-exports from `@ag-ui/core`), `messageFormat.ts`, `stream.ts`. |diff --git a/packages/react-headless/README.md b/packages/react-headless/README.mdindex 4397958f5..c07a2879d 100644--- a/packages/react-headless/README.md+++ b/packages/react-headless/README.md@@ -35,7 +35,7 @@ Use `@openuidev/react-headless` when you want OpenUI's chat behavior without Ope- **`ChatProvider`** manages threads, messages, and streaming state through a Zustand store.- **Selector hooks** expose thread and thread-list state without coupling you to a layout.-- **Streaming adapters** parse SSE or SDK responses from OpenAI, Vercel AI SDK, AG-UI, or custom backends.+- **Streaming adapters** parse SSE or SDK responses from OpenAI, Vercel AI SDK, AG-UI, LangGraph, Vercel Eve, or custom backends.- **Message formats** convert between your API shape and OpenUI's internal AG-UI shape.## Quick Start@@ -191,6 +191,8 @@ const llm = fetchLLM({ url: "/api/chat", streamAdapter: openAIAdapter() });| `openAIResponsesAdapter()` | Parses OpenAI Responses API streaming (`ResponseStreamEvent`) || `openAIReadableStreamAdapter()` | Parses OpenAI SDK's `Stream.toReadableStream()` NDJSON output || `vercelAIAdapter()` | Parses Vercel AI SDK v6 and v7 UIMessage streams |+| `langGraphAdapter()` | Parses LangGraph named-event SSE (`event: messages` + `data: {json}`); takes `{ onInterrupt }` |+| `eveAdapter()` | Parses Vercel Eve NDJSON session streams; takes `{ onEvent }` |For a Vercel AI SDK route, use its stream adapter and message format together:@@ -242,6 +244,7 @@ const llm = fetchLLM({| `openAIMessageFormat` | Converts to/from OpenAI `ChatCompletionMessageParam[]` || `openAIConversationMessageFormat` | Converts to/from OpenAI Responses API `ResponseInputItem[]` || `vercelAIMessageFormat` | Converts to/from Vercel AI SDK v6 and v7 `UIMessage[]` |+| `langGraphMessageFormat` | Converts to/from LangGraph's LangChain-style messages (`human` / `ai` / `tool` / `system`) |### Custom format