@agentads/sdk

Monetize your AI app. Append a single contextual ad after each LLM response, keep 70% of every ad dollar.

npm install @agentads/sdk

Quickstart

Get an API key at app.tryagentads.com, then:

import { fetchAd } from '@agentads/sdk'

const ad = await fetchAd({
  publisherApiKey: process.env.AGENTADS_API_KEY!,
  query: userMessage,
  response: assistantText,
})

if (ad) {
  // append `ad.headline`, `ad.description`, `ad.ctaText`, `ad.clickUrl`
}

The auction has a hard 50 ms timeout. If no ad wins, fetchAd returns null — safe to ignore.

Wrap any AI SDK

Use withAgentAds() to wrap a model object (Vercel AI SDK, OpenAI SDK, anything with a doGenerate or doStream method). The wrapped model auto-appends an ad to each response.

import { withAgentAds } from '@agentads/sdk'
import { openai } from '@ai-sdk/openai'

const model = withAgentAds(openai('gpt-4o'), {
  publisherApiKey: process.env.AGENTADS_API_KEY!,
})

// use `model` exactly like before — ads attach automatically

React component

import { AgentAd } from '@agentads/sdk/react'

<AgentAd
  publisherApiKey={process.env.NEXT_PUBLIC_AGENTADS_KEY!}
  query={userMessage}
  response={assistantText}
/>

Renders nothing on no-fill. No layout shift.

API

fetchAd(options) → Promise<Ad | null>

| Option | Type | Default | | --- | --- | --- | | publisherApiKey | string | — (required) | | query | string | — | | response | string | — | | apiUrl | string | https://api.tryagentads.com | | timeout | number (ms) | 50 |

Returns:

type Ad = {
  id: string
  headline: string
  description: string
  ctaText: string
  destinationUrl: string
  clickUrl: string  // tracked click URL
}

Returns null on no-fill, timeout, invalid key, or network error. The SDK never throws.

withAgentAds(model, { publisherApiKey, apiUrl? })

Proxies the model. Intercepts doGenerate and doStream results and appends a Sponsored: block to .text if an ad wins the auction.

Bundle size

• @agentads/sdk — 1.7 KB raw / ~800 B gzipped
• @agentads/sdk/react — 3.7 KB raw / ~1.3 KB gzipped

React is an optional peer dep. The main entrypoint has zero runtime deps.

License

MIT — built by AgentAds.