Getting started

npm install @agentads/sdk
# or
yarn add @agentads/sdk
# or
pnpm add @agentads/sdk

# .env.local
AGENTADS_KEY=pub_live_xxxxxxxxxxxxxxxxxxxx

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

// Drop-in replacement — same API, same streaming
const model = withAgentAds(openai('gpt-4o'), {
  publisherApiKey: process.env.AGENTADS_KEY!,
})

// Use exactly like before
const result = await generateText({ model, prompt: userMessage })
// result.text now includes a contextual ad if matched
// → "...your answer...

---
**Sponsored:** Clerk — Auth in 5 minutes..."

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

export function ChatMessage({ query, response }: { query: string; response: string }) {
  return (
    <div>
      <p>{response}</p>

      {/* Renders a sponsored card after each assistant message */}
      <AgentAd
        publisherApiKey={process.env.NEXT_PUBLIC_AGENTADS_KEY!}
        query={query}
        response={response}
      />
    </div>
  )
}

// components/messages.tsx
import { AgentAd } from '@agentads/sdk/react'

export function Messages({ messages }: { messages: Message[] }) {
  return messages.map((msg, i) => {
    const prevMsg = messages[i - 1]
    return (
      <div key={msg.id}>
        <MessageBubble message={msg} />

        {/* Show ad after each assistant response */}
        {msg.role === 'assistant' && (
          <AgentAd
            publisherApiKey={process.env.NEXT_PUBLIC_AGENTADS_KEY!}
            query={prevMsg?.role === 'user' ? prevMsg.content : ''}
            response={msg.content}
          />
        )}
      </div>
    )
  })
}

const res = await fetch('https://api.tryagentads.com/bid', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Publisher-Key': 'pub_live_...',
  },
  body: JSON.stringify({
    query: userMessage,
    response: aiResponse.slice(0, 200),
    format: 'suffix',   // 'suffix' | 'citation' | 'followup'
  }),
  signal: AbortSignal.timeout(50),
})

const data = await res.json()
// data.filled === true → data.ad has headline, description, cta, clickUrl
// data.filled === false → no auction winner

import requests

try:
    r = requests.post(
        'https://api.tryagentads.com/bid',
        headers={'X-Publisher-Key': 'pub_live_...'},
        json={'query': user_message, 'response': ai_response[:200]},
        timeout=0.05  # 50ms
    )
    data = r.json()
    if data.get('filled') and data.get('ad'):
        ad = data['ad']
        sponsored = f"\n\n---\nSponsored: {ad['headline']} — {ad['cta']}: {ad['clickUrl']}"
        response_text += sponsored
except requests.exceptions.Timeout:
    pass  # No ad — always safe to ignore

<!-- AgentAds Conversion Pixel -->
<script>
(function() {
  var params = new URLSearchParams(window.location.search);
  var tid = params.get('aads_tid');
  var token = params.get('aads_token');
  if (!tid || !token) return;
  new Image().src =
    'https://api.tryagentads.com/v1/convert' +
    '?tid=' + encodeURIComponent(tid) +
    '&token=' + encodeURIComponent(token) +
    '&value=VALUE_CENTS';  // replace with order value, e.g. 4900 for $49
})();
</script>

pip install agentads-nat

# config.yaml
functions:
  monetize:
    _type: agentads_monetize
    publisher_api_key: ${AGENTADS_API_KEY}
    format: suffix        # suffix | citation | followup
    timeout_ms: 50        # never blocks your agent

workflow:
  _type: react_agent
  tool_names: [your_tools, monetize]
  llm_name: your_llm

export AGENTADS_API_KEY=pub_live_xxx
nat run --config_file config.yaml --input "What CRM should I use?"

from agentads_nat import AgentAdsConfig, monetize_output

config = AgentAdsConfig(publisher_api_key="pub_live_xxx")

# Your agent produces a response
response = await my_agent(query)

# One line to monetize
result = await monetize_output(config, response, query=query)
# → response + contextual ad appended (or unchanged on no-fill)

openshell policy set agentads --policy policies/agentads.yaml --wait
# Allows only POST /v1/bid to api.tryagentads.com