@adzenai/ai

AI-powered ad integration for CopilotKit and AG-UI agents. Delivers contextual sponsored placements inside AI chat streams without modifying or delaying assistant responses.

Install

npm install @adzenai/ai @adzenai/core

Prerequisites

You need an Adzen API key. Contact Adzen to set up a publisher account and obtain your key.

Quick Start

Server-side: pipe AG-UI events through the middleware

import { AdzenAsyncMiddleware } from "@adzenai/ai/copilotkit";

const adzen = new AdzenAsyncMiddleware({
  apiKey: process.env.ADZEN_API_KEY!,
  location: process.env.ADZEN_LOCATION,
});

for await (const event of agentEventStream) {
  const downstream = await adzen.processEvent(event);
  for (const evt of downstream) {
    emitToClient(evt);
  }
}

Client-side: render ad cards

import { AdzenCard, dispatchPlacementEvents } from "@adzenai/ai/copilotkit/react";

// Bridge AG-UI placement events to the browser
dispatchPlacementEvents(events);

// Render below each assistant message
<AdzenCard messageId={msg.id} />

AdzenCard returns null when no ad is available — safe to render unconditionally.

Exports

| Path | Environment | Provides | | --- | --- | --- | | @adzenai/ai | Any | Core type re-exports (AdzenPlacement, ProcessResponse, ProcessResponseAd) | | @adzenai/ai/copilotkit | Server or client | AdzenAsyncMiddleware, AdzenAsyncConfig | | @adzenai/ai/copilotkit/react | Browser (React 18+) | AdzenCard, useAdzenPlacement, dispatchPlacementEvent(s) |

How It Works

1. AdzenAsyncMiddleware buffers assistant text from AG-UI events.
2. On message completion, it calls the Adzen /process API to match a contextual ad.
3. If matched, an adzen_placement custom event is appended to the downstream stream.
4. dispatchPlacementEvents() bridges these to browser CustomEvents.
5. AdzenCard picks up the placement and renders it with automatic impression tracking.

Impression beacons are fired as client-side GET requests directly to the delivery API — no server-side proxy needed.

The middleware is additive only — it never modifies, blocks, or delays the original event stream. All failures degrade silently.

Configuration

new AdzenAsyncMiddleware({
  apiKey: string;           // required — Adzen API key
  endpointUrl?: string;     // default: "https://api.adzen.ai/v1/ai"
  timeoutMs?: number;       // default: 3000
  adUnitPosition?: string;  // default: "chin"
  location?: string;        // optional — DMA location code for geo-targeting
  conversationId?: string;  // optional — links impressions to conversation context
});

License

MIT