Skip to main content

Context & Relevance

The quality of ads your users see depends heavily on how much context you provide. Better context = higher relevance = more clicks = more revenue.

What to send as context​

The context field in decideFromContext() should be the user's current message or query. Optionally, add user_intent for additional signal.

// Basic — just the user message
await client.decideFromContext({
  context: userMessage,
});

// Better — with intent context
await client.decideFromContext({
  context: userMessage,
  user_intent: 'User is comparing project management tools for a 10-person team',
});

Developer controls​

You have full control over what ads appear in your agent:

Category filtering​

// Only show ads from specific categories
await client.decideFromContext({
  context: userMessage,
  categories: ['IAB13', 'IAB22'], // Personal Finance, Shopping
});

// Block specific categories
await client.decideFromContext({
  context: userMessage,
  blocked_categories: ['IAB25', 'IAB26'], // Sensitive categories
});

Quality thresholds​

await client.decideFromContext({
  context: userMessage,
  min_quality_score: 0.7,     // Only high-quality ads
  min_relevance_score: 0.5,   // Only relevant matches
});

Advertiser blocking​

await client.decideFromContext({
  context: userMessage,
  blocked_advertisers: ['advertiser-uuid-to-block'],
});

How matching works​

  1. Embedding generation — Your context is embedded using OpenAI text-embedding-3-small (1536 dimensions)
  2. Cosine similarity — Compared against all active campaign embeddings via pgvector
  3. Threshold filtering — Results below 0.25 similarity are dropped
  4. Cohere reranking — Top candidates are reranked with a cross-encoder model
  5. Quality-adjusted auction — Final ranking considers bid, quality score, and relevance

Tips for higher relevance​

  • Pass the full user message, not a summary
  • Include user_intent when you know the user's goal
  • Use category filtering to keep ads on-topic for your agent's domain
  • Set quality thresholds to maintain trust with your users
  • Send feedback after showing ads — it improves the matching system over time