How it works

Additive by design: Adzen adds to the stream and never changes it.

Adzen sits alongside CopilotKit as AG-UI middleware. It intercepts the AG-UI event stream, matches ads to assistant output, and renders sponsored placements — all without modifying or blocking content.

The integration is additive only: Adzen adds adzen_placement custom events to the stream. The original event stream passes through unchanged with zero added latency to the text flow.

Package exports

Public API summary

Generic ad fetching (@adzenai/ai)

AdzenAsyncMiddleware delegates its ad fetch to fetchAdzenAd, so async middleware and generic fetching share identical behavior.

Server-side / middleware

React

Types (from @adzenai/core)

Architecture

AG-UI event flow

Backend Agent
  │
  │  AG-UI events (RUN_STARTED, TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT,
  │                TEXT_MESSAGE_END, RUN_FINISHED, CUSTOM_EVENT, ...)
  ▼
AdzenAsyncMiddleware.processEvent(event)
  │
  ├─ RUN_STARTED         → captures threadId as conversation_id
  ├─ TEXT_MESSAGE_START   → creates buffer for messageId
  ├─ TEXT_MESSAGE_CONTENT → appends delta to buffer
  ├─ TEXT_MESSAGE_END     → triggers ad fetch, emits adzen_placement if matched
  ├─ CUSTOM_EVENT (final) → fallback content source for non-text agents
  ├─ RUN_FINISHED        → waits for all pending ad fetches to settle
  └─ all other events    → passed through unchanged
  │
  ▼
Downstream events (original events + adzen_placement custom events)
  │
  ▼
dispatchPlacementEvents() → bridges to browser CustomEvents
  │
  ▼
useAdzenPlacement() → maintains Map<messageId, AdzenPlacement>
  │
  ▼
AdzenCard → renders ad, tracks viewability, fires impression GET beacons

Ad fetch lifecycle

1. RUN_STARTED captures threadId as conversation_id (if present).
2. TEXT_MESSAGE_START creates a buffer keyed by messageId.
3. TEXT_MESSAGE_CONTENT events accumulate text in the buffer.
4. TEXT_MESSAGE_END triggers a POST to the Adzen /process API with the complete message text, message_id, and optionally location and conversation_id.
5. If the API returns ads, the middleware maps the first ad to AdzenPlacement and appends an adzen_placement custom event to the downstream array.
6. If the API returns an empty ads array, times out, or fails, no placement event is emitted.
7. RUN_FINISHED is held until all pending ad fetches settle via Promise.allSettled.

Streaming event flow

AdzenStreamMiddleware proxies the LLM response stream instead of buffering it. processStream() takes the AG-UI event iterable plus the upstream LLM response body:

Upstream LLM response
  │
  ├─ tee() branch 1 → parsed into AG-UI events → processStream(events, ...)
  └─ tee() branch 2 → passed as options.upstreamBody
                        │
                        ▼
  RUN_STARTED        → creates AdzenStreamClient; if prefetch, dispatches
                       POST /process with the prompt without awaiting it
  TEXT_MESSAGE_START → connect(messageId, upstreamBody) opens POST /stream,
                       piping branch 2 as the request body
  TEXT_MESSAGE_*     → SSE ad events drained and emitted as adzen_inline_ad
  TEXT_MESSAGE_END   → finalize() awaits the SSE response
  RUN_FINISHED       → polls /placements once, then aborts and cleans up

Each adzen_inline_ad event carries a content_offset, the position in the message where the ad belongs. getInlineAdSegments(messageId, content) uses it to render the ad directly after that text instead of at the end of the message, so the ad renders on the line below the text it follows.

Each adzen_inline (and adzen_ad_anchor) event carries an absolute content_offset: the exact UTF-16 index in the accumulated assistant text where the ad should be inserted, cumulative for the message and landing on a \n\n block boundary. The middleware uses that offset verbatim, so placement is deterministic and independent of stream timing. Because the unit is UTF-16 code units (the same as String.length/.slice), multi-byte characters do not shift placement and no re-encoding is needed.

When an adzen_ad_anchor carries a content_offset, that value is the authoritative reservation. An anchor with no ad after it is cleared at the next message, so nothing renders and no gap appears.

Inline ads are deduped by their placement instance — the (ad_id, paragraph_index) pair — not by ad_id alone. The same ad may appear more than once in a response, each at a different paragraph, so keying by ad_id would drop every showing after the first. paragraph_index is the identity key; content_offset remains the position anchor.

Offsets are snapped forward to the next paragraph break before the content is split. Deltas are token-sized, so a raw offset usually lands mid-word; splitting there would cut a sentence in half and break Markdown constructs that span the boundary. Segments are therefore always whole paragraphs, which lets each one be passed to a Markdown renderer independently. Ads anchored inside a paragraph that is still streaming render at the end of the message until that paragraph closes.

One ad per paragraph break. Snapping makes collisions common: every ad anchored inside the same paragraph resolves to that paragraph’s end, so several ads can share one offset. Each ad after the first is therefore moved to the next free break, with the end of the content usable as a final slot. An ad with no free slot is not rendered — and so fires no impression — until the message grows enough to hold it.

Request metadata travels in headers (X-API-Key, X-Message-Id, X-Conversation-Id, Idempotency-Key, and optionally X-Profile-Id and X-Location) because the body carries the LLM stream.

The optional 2-step prefetch sends the user prompt to /process before the stream opens. Its response is intentionally discarded and never rendered.

The prefetch is dispatched but not awaited. Only the ordering matters — the request leaves before /stream opens. Awaiting it would hold every AG-UI event behind a full ad-matching round trip, during which the LLM keeps streaming into the tee’s buffer; the assistant message would then appear in one burst instead of streaming. Any prefetch still in flight is awaited by finalize() at TEXT_MESSAGE_END, so nothing is left dangling.

Server-side requirement

This flow passes a ReadableStream as the fetch request body. Only Chromium implements fetch upload streams, and it requires HTTP/2; Safari and Firefox coerce a stream body to the literal string "[object ReadableStream]". Node 18+ (undici) supports it over HTTP/1.1 via chunked transfer encoding.

AdzenStreamClient feature-detects support at module load. If unavailable it emits an adzen_error with code request_streams_unsupported, cancels the body, and makes no request — so an unsupported runtime degrades silently rather than sending an invalid request.

Impression tracking

AdzenCard fires two impression beacons as client-side GET requests directly to the delivery API:

1. Render impression — fired on mount when the ad first becomes available. GET to render_impression_url.
2. View impression — fired after the ad is fully visible in the viewport for the configured threshold (default 1000ms). GET to view_impression_url.

No server-side proxy or authentication headers are needed. The impression URLs are pre-built by the API with all required identifiers baked in. A single retry after 1 second is attempted on failure.

Ad decision boundaries

A final custom event is detected when the event has type of CUSTOM_EVENT/CUSTOM/CustomEvent and either final: true, isFinal: true, or a name containing assistant_final or final_output.

Concurrent message handling

The middleware maintains a Map<string, MessageBuffer> keyed by messageId. This supports:

• Multiple concurrent assistant messages (multi-agent scenarios)
• An ID is generated automatically when messageId is missing
• Stale buffer eviction (entries older than timeoutMs * 2 are removed on the next TEXT_MESSAGE_START)

Silent degradation

Adzen is designed to be invisible on failure:

The assistant text stream is never delayed or modified, regardless of ad API behavior.

Supported runtime conditions

Next

• Integration walkthrough — step-by-step wiring guide
• Configuration — environment variables, adapter options, timeouts
• Quick start — quick-start for existing apps