Configuration Reference¶

The buyer agent is configured through environment variables loaded via pydantic-settings. Settings are defined in a single Settings class and can be set via a .env file, shell environment variables, or directly in code.

Key file: src/ad_buyer/config/settings.py

Quick Start¶

Create a .env file in the project root:

# Required
ANTHROPIC_API_KEY=sk-ant-...

# Seller communication
SELLER_ENDPOINTS=http://localhost:8000
IAB_SERVER_URL=http://localhost:8001

# Optional overrides
DEFAULT_LLM_MODEL=anthropic/claude-sonnet-4-5-20250929
MANAGER_LLM_MODEL=anthropic/claude-opus-4-20250514
LOG_LEVEL=INFO

Access settings in code:

from ad_buyer.config.settings import settings

print(settings.default_llm_model)
print(settings.get_seller_endpoints())

Environment Variables¶

API Keys¶

Variable	Type	Default	Description
`ANTHROPIC_API_KEY`	`str`	`""`	Anthropic API key for Claude models. Required for agent functionality.
`API_KEY`	`str`	`""`	Inbound API key for authenticating requests to this service. When empty, authentication is disabled (development mode).

Development mode

When API_KEY is empty, the buyer agent's API endpoints are unauthenticated. Set a value in production to require X-Api-Key headers on incoming requests.

Seller Endpoints¶

Variable	Type	Default	Description
`SELLER_ENDPOINTS`	`str`	`""`	Comma-separated list of seller MCP/A2A server URLs.
`IAB_SERVER_URL`	`str`	`http://localhost:8001`	Primary IAB agentic-direct server URL. Used as the default `base_url` for flows and clients.

Parse seller endpoints as a list:

endpoints = settings.get_seller_endpoints()
# ["http://seller1.example.com:8000", "http://seller2.example.com:8000"]

OpenDirect (Legacy)¶

Variable	Type	Default	Description
`OPENDIRECT_BASE_URL`	`str`	`http://localhost:3000/api/v2.1`	Base URL for the OpenDirect 2.1 REST API.
`OPENDIRECT_TOKEN`	`str`	`None`	Bearer token for OpenDirect authentication.
`OPENDIRECT_API_KEY`	`str`	`None`	API key for OpenDirect authentication.

Legacy mode

OpenDirect settings support single-server mode for backwards compatibility. For multi-seller workflows, use SELLER_ENDPOINTS with the MCP/A2A protocol clients instead.

LLM Configuration¶

Variable	Type	Default	Description
`DEFAULT_LLM_MODEL`	`str`	`anthropic/claude-sonnet-4-5-20250929`	Model for Level 2 channel specialists and Level 3 functional agents.
`MANAGER_LLM_MODEL`	`str`	`anthropic/claude-opus-4-20250514`	Model for the Level 1 Portfolio Manager. Opus is used for strategic reasoning.
`LLM_TEMPERATURE`	`float`	`0.3`	Default temperature for LLM calls. Individual agents may override this.
`LLM_MAX_TOKENS`	`int`	`4096`	Maximum token output for LLM responses.

Models are specified in provider/model-name format using CrewAI's native provider integrations. Install the matching extra (e.g., pip install "crewai[anthropic]") and set the API key. No code changes required to switch providers.

# Use a different model provider
DEFAULT_LLM_MODEL=openai/gpt-4o
MANAGER_LLM_MODEL=anthropic/claude-opus-4-20250514

Agent temperature overrides:

While LLM_TEMPERATURE sets the global default, each agent type uses a tuned temperature:

Agent	Temperature	Rationale
Portfolio Manager (L1)	0.3	Balanced strategic reasoning
Channel Specialists (L2)	0.5	Creative inventory selection
Audience Planner (L3)	0.3	Precise audience strategy
Research Agent (L3)	0.2	Data-focused, minimal creativity
Reporting Agent (L3) (Coming Soon)	0.2	Analytical precision
Execution Agent (L3)	0.1	Precise booking execution

Storage Backend¶

The pluggable storage backend (used by campaigns, orders, sessions, conversions, optimization, experiments, pacing) is selected with STORAGE_TYPE. The legacy DealStore always uses SQLite directly via DATABASE_URL. See Storage Backends for the full reference.

Variable	Type	Default	Description
`STORAGE_TYPE`	`str`	`sqlite`	Backend selector — `sqlite`, `redis`, or `hybrid` (Postgres + Redis).
`DATABASE_URL`	`str`	`sqlite:///./ad_buyer.db`	SQLite or PostgreSQL connection string. For `hybrid`, use `postgresql+asyncpg://user:pass@host/db`.
`REDIS_URL`	`str`	`None`	Redis connection URL — required for `redis` and `hybrid`; optional otherwise.
`POSTGRES_POOL_MIN`	`int`	`2`	Minimum asyncpg connection pool size (hybrid only).
`POSTGRES_POOL_MAX`	`int`	`10`	Maximum asyncpg connection pool size (hybrid only).

# SQLite (default — single-instance, dev/demos)
STORAGE_TYPE=sqlite
DATABASE_URL=sqlite:///./ad_buyer.db

# Redis (ephemeral-heavy, no durable Postgres)
STORAGE_TYPE=redis
REDIS_URL=redis://localhost:6379/0

# Hybrid (recommended for production multi-instance)
STORAGE_TYPE=hybrid
DATABASE_URL=postgresql+asyncpg://buyer:pass@db.example.com:5432/ad_buyer
REDIS_URL=redis://cache.example.com:6379/0

Redis is also used for CrewAI memory persistence and session caching whenever REDIS_URL is set, regardless of STORAGE_TYPE. When REDIS_URL is unset, CrewAI uses in-memory storage.

The Redis (pip install -e ".[redis]") and asyncpg (pip install -e ".[postgres]") drivers are optional extras. Install ".[production]" to get both.

CrewAI Settings¶

Variable	Type	Default	Description
`CREW_MEMORY_ENABLED`	`bool`	`True`	Enable CrewAI agent memory across tasks.
`CREW_VERBOSE`	`bool`	`True`	Enable verbose logging for crew execution. Set to `False` in production.
`CREW_MAX_ITERATIONS`	`int`	`15`	Maximum iterations per crew task before forced completion.

# Production settings
CREW_MEMORY_ENABLED=True
CREW_VERBOSE=False
CREW_MAX_ITERATIONS=10

CORS¶

Variable	Type	Default	Description
`CORS_ALLOWED_ORIGINS`	`str`	`http://localhost:3000,http://localhost:8080`	Comma-separated list of allowed CORS origins.

Parse as a list:

origins = settings.get_cors_origins()
# ["http://localhost:3000", "http://localhost:8080"]

# Production
CORS_ALLOWED_ORIGINS=https://dashboard.example.com,https://app.example.com

IAB Diligence Platform Approval¶

Optional integration that gates deal requests against the buyer's IAB Diligence Platform vendor portfolio. Inert when SGP_API_KEY is empty.

Variable	Type	Default	Description
`SGP_API_KEY`	`str`	`""`	API key with the `iab:buyerAgent` scope. Empty = integration disabled.
`SGP_BASE_URL`	`str`	`https://api.safeguardprivacy.com`	SGP base URL. Staging: `https://api.safeguardprivacy-demo.com`.
`SGP_ENFORCE`	`bool`	`False`	When `True`, NOT APPROVED vendors are filtered out at discovery and Deal ID generation is blocked for them. SGP transport errors halt the flow.
`SGP_UNKNOWN_VENDOR_POLICY`	`str`	`block`	Behavior when the vendor is not in the buyer's SGP portfolio (HTTP 404). One of `block`, `warn`, `allow`.
`SGP_CACHE_TTL_SECONDS`	`int`	`900`	Per-domain cache lifetime for approval lookups.

See the IAB Diligence Platform Approval integration guide for endpoint contract, behavior matrix, and troubleshooting.

Environment¶

Variable	Type	Default	Description
`ENVIRONMENT`	`str`	`development`	Runtime environment identifier.
`LOG_LEVEL`	`str`	`INFO`	Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.

Settings Class¶

The full Settings class for reference:

from ad_buyer.config.settings import Settings, get_settings

# Singleton (cached)
settings = get_settings()

# Or create a fresh instance (useful for testing)
test_settings = Settings(
    anthropic_api_key="test-key",
    database_url="sqlite:///./test.db",
    environment="testing",
)

The get_settings() function returns a cached singleton via @lru_cache. This means environment variable changes after first access require a process restart.

.env File Resolution¶

The settings module uses python-dotenv to find a .env file. It searches upward from the current working directory. This means the .env file can live in the project root or any parent directory.

project-root/
  .env              <-- found automatically
  src/
    ad_buyer/
      config/
        settings.py  <-- searches upward from cwd

Multiple environments

For different environments, use separate .env files and set the working directory accordingly, or override variables directly in the shell environment. Shell variables take precedence over .env values.

Example Configurations¶

Development (Minimal)¶

ANTHROPIC_API_KEY=sk-ant-...

Everything else uses defaults: local SQLite database, localhost seller, Sonnet for agents, Opus for manager, verbose logging enabled.

Production¶

ANTHROPIC_API_KEY=sk-ant-...
API_KEY=your-service-api-key

SELLER_ENDPOINTS=https://seller1.example.com,https://seller2.example.com
IAB_SERVER_URL=https://primary-seller.example.com

DATABASE_URL=postgresql://buyer:pass@db.example.com:5432/ad_buyer
REDIS_URL=redis://cache.example.com:6379/0

CREW_VERBOSE=False
CREW_MAX_ITERATIONS=10

CORS_ALLOWED_ORIGINS=https://dashboard.example.com
ENVIRONMENT=production
LOG_LEVEL=WARNING

Testing¶

ANTHROPIC_API_KEY=test-key
API_KEY=test-api-key
DATABASE_URL=sqlite:///./test_ad_buyer.db
ENVIRONMENT=testing
LOG_LEVEL=DEBUG
CREW_VERBOSE=True
CREW_MAX_ITERATIONS=5

Agent Hierarchy --- How LLM settings map to agent levels
Architecture Overview --- System component overview
Authentication --- API key setup for inbound requests