Skip to content

Developer Setup Guide

Set up the buyer agent infrastructure, connect to seller agents and SSPs, and generate credentials for your media buying team to use in Claude Desktop.

Prerequisites

  • Python 3.11+
  • Docker (for deployment)
  • Seller agent URLs (at least one seller must be reachable)
  • SSP API keys (optional: PubMatic, Magnite, Index Exchange)
  • Anthropic API key

Step 1: Deploy the Buyer Agent

# Clone and install
git clone https://github.com/IABTechLab/buyer-agent.git
cd buyer-agent
pip install -e .

# Or with Docker
cd infra/docker
docker compose up

Step 2: Configure Environment

Create a .env file:

# Required
ANTHROPIC_API_KEY=sk-ant-...

# IAB agentic-direct server
IAB_SERVER_URL=http://localhost:8001

# Storage (SQLite)
DATABASE_URL=sqlite:///./ad_buyer.db

# Environment
ENVIRONMENT=development
LOG_LEVEL=INFO

Step 3: Connect to Sellers

Set the SELLER_ENDPOINTS variable to a comma-separated list of seller agent MCP URLs:

# Single seller
SELLER_ENDPOINTS=http://localhost:8000

# Multiple sellers
SELLER_ENDPOINTS=http://espn.example.com,http://conde.example.com,http://nytimes.example.com

Each URL should point to a running seller agent. The buyer will use these endpoints for inventory discovery, deal negotiation, and order management.

Verify seller connectivity

With the seller agent running on its default port, check:

curl http://localhost:8000/health

This returns a healthy status when the seller is up. After the buyer agent is running, call the health_check MCP tool from your connected MCP client for per-service detail — including how many seller endpoints are configured (database, seller_connections with an endpoint count, and event_bus).

Step 4: Configure SSP Connectors (Optional)

If your media buyers need to import deals from SSPs directly, configure the connector credentials (see SSP Connector Setup for the per-SSP variables):

# Example: PubMatic
PUBMATIC_API_TOKEN=your-bearer-token
PUBMATIC_SEAT_ID=your-seat-id

The buyer agent's SSP connector tools (list_ssp_connectors, import_deals_ssp, test_ssp_connection) can be called by the business team once credentials are in place.

Step 5: Configure Optional Services

# CORS (if browser clients need access)
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8080

# LLM model overrides (optional)
DEFAULT_LLM_MODEL=anthropic/claude-sonnet-4-5-20250929
MANAGER_LLM_MODEL=anthropic/claude-opus-4-8

Step 6: Start the Server

uvicorn ad_buyer.interfaces.api.main:app --host 0.0.0.0 --port 8001

Verify: curl http://localhost:8001/health

Step 7: Generate Operator Credentials

Mint an operator key for your business team. Keys are hashed into the database, so the CLI must run with the same DATABASE_URL as the server:

uv run ad-buyer create-operator-key --label "Business team"

The full key is printed once — store it in your secret manager. Useful companions:

uv run ad-buyer list-operator-keys
uv run ad-buyer delete-operator-key --label "Business team"

There is no keyless mode: every REST route except /health, /docs, /redoc, and /openapi.json, and every MCP tool except health_check, answers 401 without a key. Requests may carry it as either X-Api-Key: <key> or Authorization: Bearer <key>.

The deprecated API_KEY env var still authenticates for one release, but only while no operator key has ever been minted. See the v2.5.0 upgrade guide.

Step 8: Hand Off

Give your media buying team:

  1. MCP URL: http://your-server:8001/mcp/ (Streamable HTTP, canonical — or your public URL)
  2. API key: the operator key printed by ad-buyer create-operator-key

They'll connect Claude Desktop using the Claude Desktop Setup Guide and complete the business configuration (deal templates, approval thresholds, seller API keys) through the interactive setup wizard.

Verify the Full Setup

# Health check
curl http://localhost:8001/health

# MCP smoke test (add -H "X-API-Key: $API_KEY" if API_KEY is set)
curl -s -X POST http://localhost:8001/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}'
# Legacy SSE (older clients only): curl -N http://localhost:8001/mcp-sse/sse

Expected health response:

{
  "status": "healthy",
  "version": "1.0.0"
}

For a configured/missing breakdown of the setup itself, call the get_setup_status MCP tool from a connected client (there is no REST setup-status route). For per-service health detail, call the health_check MCP tool.