Integration guide

One blind matchup — two anonymous models, one connection — framed in five wire protocols through a pluggable adapter layer (server/src/adapters/). Three of the five also parse their protocol's own request body, so a stock AG-UI, OpenAI, or AI SDK client can call the arena with no translation layer. Pick the protocol that matches your stack — and if your client fans a compare view out into one request per model, see slot join.

One stream, five framings

Every protocol carries the identical internal sequence over two slots (A, B); only the framing differs. Each frame is schema-validated (publicArenaEventSchema) before it is written.

Which protocols accept their own request body

All five read the same four arena fields through one arenaPropsSchema (request-adapter.ts), so slot join works on every path, not only the native one.

Selecting a protocol

selectProtocol resolves response framing and request parsing from one decision, so the client that asks for a protocol's framing is the one allowed to post its body. Precedence: ?protocol= query param → Accept media type → default native SSE. An unknown ?protocol= falls back to SSE. The arena is also served at POST /chat/completions and POST /v1/chat/completions, where the OpenAI protocol is implied by the path — an OpenAI client appends the path to a base URL and can never send ?protocol=.

Model A vs B, and voting

Slot join: one matchup over two requests

Everything above assumes the default shape — both slots interleaved on one connection. A chat UI with a compare view does not send that shape: it fans a multi-model turn out into one request per model, each with a single answer channel and a shared conversation id. Open WebUI v0.10 is the measured case. Served naively it garbles both answers into one column, or produces two unrelated matchups and two half-votes.

Native SSE default

?protocol=sse · sse.ts. One event:/data: pair per event; no trailing sentinel.

event: matchup_started
data: {"type":"matchup_started","matchupId":"m1","matchupToken":"eyJ….sig",
       "conversationId":"c1","turnIndex":0,"slots":["A","B"]}

event: token
data: {"type":"token","slot":"A","token":"He"}

event: matchup_done
data: {"type":"matchup_done"}

AG-UI

?protocol=ag-ui · ag-ui.ts · SSE, one data: line per typed AG-UI event. Two slots become two text messages in one run.

data: {"type":"RUN_STARTED","threadId":"c1","runId":"m1"}
data: {"type":"CUSTOM","name":"arena_matchup","value":{"matchupId":"m1","matchupToken":"eyJ….sig",
       "slots":["A","B"],"mode":"matchup","votable":true,"conversationId":"c1","turnIndex":0}}
data: {"type":"TEXT_MESSAGE_START","messageId":"m1:A","role":"assistant","slot":"A"}
data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1:B","delta":"Yo","slot":"B"}
data: {"type":"CUSTOM","name":"slot_error","value":{"slot":"B","message":"boom"}}
data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1:B","delta":"\n\n[omni-arena:slot-error] boom\n","slot":"B"}
data: {"type":"TEXT_MESSAGE_END","messageId":"m1:A","slot":"A"}
data: {"type":"RUN_FINISHED","threadId":"c1","runId":"m1"}

A2UI

?protocol=a2ui · a2ui.ts · NDJSON, one flat JSON object per line, versioned a2ui/1. Two side-by-side surfaces.

{"v":"a2ui/1","kind":"surface_init","matchupId":"m1","matchupToken":"eyJ….sig","conversationId":"c1",
 "turnIndex":0,"surfaces":["A","B"],"mode":"matchup","votable":true}
{"v":"a2ui/1","kind":"text_append","surface":"A","text":"He"}
{"v":"a2ui/1","kind":"error","surface":"B","message":"boom"}
{"v":"a2ui/1","kind":"surface_done","surface":"A"}
{"v":"a2ui/1","kind":"session_done"}

Vercel AI SDK

?protocol=vercel-ai · vercel-ai.ts · AI SDK UI Message Stream over SSE (header x-vercel-ai-ui-message-stream: v1), trailing data: [DONE]. A stock useChat can both post to and render it unchanged.

data: {"type":"start"}
data: {"type":"data-arena-meta","data":{"matchupId":"m1","matchupToken":"eyJ….sig",
       "conversationId":"c1","turnIndex":0,"mainSlot":"A","dataSlot":"B"}}
data: {"type":"text-start","id":"m1"}
data: {"type":"text-delta","id":"m1","delta":"He"}
data: {"type":"data-arena-b-delta","data":{"text":"Yo"}}
data: {"type":"data-arena-error","data":{"slot":"B","message":"boom"}}
data: {"type":"text-end","id":"m1"}
data: {"type":"finish"}
data: [DONE]

OpenAI-compatible SSE

?protocol=openai · openai-sse.ts · chat.completion.chunk frames, trailing data: [DONE]. Every frame lists both slots in slot order: choices[0] is always A, choices[1] always B. Point a client at {base} and it works: POST /chat/completions and /v1/chat/completions serve the arena with this protocol implied by the path, and GET /models answers the connection probe.

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1770000000,
       "model":"omni-arena","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null},
                                       {"index":1,"delta":{"role":"assistant"},"finish_reason":null}],
       "omni_arena":{"matchupId":"m1","matchupToken":"eyJ….sig","conversationId":"c1",
                     "turnIndex":0,"mode":"matchup","votable":true}}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1770000000,
       "model":"omni-arena","choices":[{"index":0,"delta":{"content":"He"},"finish_reason":null},
                                       {"index":1,"delta":{},"finish_reason":null}]}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1770000000,
       "model":"omni-arena","choices":[{"index":0,"delta":{},"finish_reason":null},
                                       {"index":1,"delta":{},"finish_reason":"stop"}]}
data: [DONE]

Reference example apps

Integration into a real third-party app

The examples above are purpose-built scaffolds. integrations/vercel-ai-chatbot/ answers the harder question — does arena mode survive inside an app that was never written for it?

Three more integrations exercise the other adapters against real upstream apps, and each documents what it found:

What the adapters look like in a real app

Both Next.js integrations photograph themselves: every image below is the real app against the real server. Regenerate a set with npm run screenshots in that integration's directory, which drives it with Playwright against a key-free provider.

Vercel AI SDK, inside vercel/ai-chatbot

AG-UI, inside assistant-ui's with-ag-ui example

AG-UI, inside CopilotKit's stock chat UI