Adzen on CopilotKit — Developer Guide

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

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.

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 with ad_unit_position and timestamp appended.
2. View impression — fired after the ad is fully visible in the viewport for the configured threshold (default 1000ms). GET to view_impression_url with ad_unit_position, viewability_ms, and timestamp appended.

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

The final custom event detection uses the same heuristic as production SDK integrations: the event must have 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)
• Fallback ID generation when messageId is missing (__adzen_fallback_${timestamp}_${counter})
• 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 Steps

• Integration Walkthrough — step-by-step wiring guide
• Configuration — environment variables, adapter options, timeouts
• Run the Demo — see the integration in action
• Add Adzen to CopilotKit — quick-start for existing apps