Skip to content

Quickstart

Get the buyer agent running locally, verify it works, and optionally connect to a seller agent for a full end-to-end booking.

Prerequisites

  • Python 3.11 or later
  • pip

Installation

Clone the repository and install dependencies:

cd ad_buyer_system
pip install -e ".[dev]"

For production (no dev/test extras):

pip install -e .

Configuration

Create a .env file in the project root with your LLM API key:

# Minimum — just set your LLM provider key
ANTHROPIC_API_KEY=sk-ant-...
Full configuration options 
# LLM — set the API key for your chosen provider
ANTHROPIC_API_KEY=sk-ant-...              # For Anthropic (default)
# OPENAI_API_KEY=sk-xxxxx                 # For OpenAI / Azure
# COHERE_API_KEY=xxxxx                    # For Cohere

# Inbound API key for this service (leave empty to disable auth in dev)
API_KEY=

# OpenDirect seller connection
OPENDIRECT_BASE_URL=http://localhost:3000/api/v2.1
OPENDIRECT_TOKEN=              # OAuth bearer token (optional)
OPENDIRECT_API_KEY=            # API key for seller (optional)

# Multi-seller mode (comma-separated URLs)
SELLER_ENDPOINTS=

# LLM model overrides — uses provider/model format (native Anthropic, OpenAI, Gemini, Azure, Bedrock)
DEFAULT_LLM_MODEL=anthropic/claude-sonnet-4-5-20250929
MANAGER_LLM_MODEL=anthropic/claude-opus-4-20250514
# DEFAULT_LLM_MODEL=openai/gpt-4o         # OpenAI example
# DEFAULT_LLM_MODEL=ollama/llama3          # Local Ollama example

# Environment
ENVIRONMENT=development
LOG_LEVEL=INFO

All settings are loaded from environment variables or the .env file via pydantic-settings.

LLM Provider Flexibility

CrewAI supports native integrations with Anthropic (default), OpenAI, Google Gemini, Azure OpenAI, and AWS Bedrock. Set DEFAULT_LLM_MODEL and MANAGER_LLM_MODEL using provider/model-name format and provide the matching API key. Install the matching extra: pip install "crewai[anthropic]". Agent prompts are tuned for Claude but work with any capable model. See the CrewAI LLM docs for provider details.

Run the Server

uvicorn ad_buyer.interfaces.api.main:app --reload --port 8001

The API will be available at http://localhost:8001.

Verify It Works

curl http://localhost:8001/health

Expected response:

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

Browse the API Docs

The buyer agent serves interactive API documentation:

First API Calls

These calls work without a seller agent running.

List Bookings

curl http://localhost:8001/bookings

On a fresh server, this returns an empty list:

{"jobs": [], "total": 0}

Run with a Seller Agent

The buyer agent connects to seller agents to discover inventory and book deals. This section walks through a full booking workflow with both agents running together.

Prerequisites

  • Buyer agent installed and running (steps above)
  • Seller agent installed and running --- follow the Seller Agent Quickstart

Default Ports

The seller agent runs on port 3000 by default, the buyer agent on port 8001. The buyer's OPENDIRECT_BASE_URL should point to the seller's API (e.g. http://localhost:3000/api/v2.1).

Start Both Agents

1. Start the seller agent (in a separate terminal):

cd seller_agent
uvicorn seller_agent.api.main:app --reload --port 3000

Verify: curl http://localhost:3000/health

2. Start the buyer agent (in another terminal):

cd ad_buyer_system
uvicorn ad_buyer.interfaces.api.main:app --reload --port 8001

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

Booking Workflow

1. Create a booking --- submit a campaign brief to the buyer agent:

curl -X POST http://localhost:8001/bookings \
  -H "Content-Type: application/json" \
  -d '{
    "brief": {
      "name": "Summer Campaign 2026",
      "objectives": ["brand_awareness", "reach"],
      "budget": 50000,
      "start_date": "2026-07-01",
      "end_date": "2026-08-31",
      "target_audience": {
        "demographics": {"age": "25-54"},
        "interests": ["travel", "outdoor"]
      },
      "kpis": {"target_cpm": 12, "viewability": 70},
      "channels": ["branding", "ctv"]
    },
    "auto_approve": false
  }'

Response:

{
  "job_id": "a1b2c3d4-...",
  "status": "pending",
  "message": "Booking workflow started. Use GET /bookings/{job_id} to check status."
}

2. Check status --- poll until the status reaches awaiting_approval:

curl http://localhost:8001/bookings/a1b2c3d4-...

3. Approve recommendations:

# Approve all recommendations
curl -X POST http://localhost:8001/bookings/a1b2c3d4-.../approve-all

# Or approve specific products
curl -X POST http://localhost:8001/bookings/a1b2c3d4-.../approve \
  -H "Content-Type: application/json" \
  -d '{"approved_product_ids": ["prod_001", "prod_003"]}'

4. View results:

curl http://localhost:8001/bookings/a1b2c3d4-...

The response now includes booked_lines with confirmed deal details from the seller.

Next Steps