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 when `DEFAULT_LLM_MODEL`/`MANAGER_LLM_MODEL` use the `anthropic/` prefix (the default).
`OPENAI_API_KEY`	`str`	`None`	OpenAI API key. Required when using the `openai/` provider prefix.
`GOOGLE_API_KEY`	`str`	`None`	Google API key. Required when using the `gemini/` provider prefix.
`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.
`OPENAI_COMPATIBLE_LLM_API_KEY`	`str`	`None`	API key for a custom OpenAI-compatible endpoint (optional — some endpoints don't require one).
`OPENAI_COMPATIBLE_LLM_API_BASE_URL`	`str`	`None`	Base URL for a custom OpenAI-compatible endpoint; when set, `DEFAULT_LLM_MODEL`/`MANAGER_LLM_MODEL` are sent as-is to that endpoint instead of being routed by provider prefix.

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

Supported Providers¶

Provider	Model Format	API Key Variable	Install Extra
Anthropic (default)	`anthropic/claude-sonnet-4-5-20250929`	`ANTHROPIC_API_KEY`	`crewai[anthropic]`
OpenAI	`openai/gpt-4o`	`OPENAI_API_KEY`	none — the `openai` SDK is a core CrewAI dependency
Google Gemini	`gemini/gemini-2.5-flash`	`GOOGLE_API_KEY`	`crewai[google-genai]`
Azure OpenAI	`azure/my-deployment`	`AZURE_API_KEY`, `AZURE_API_BASE`	none — uses the same core `openai` SDK client
AWS Bedrock	`bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0`	AWS credentials	`crewai[bedrock]`

For other providers, see the CrewAI LLM documentation.

Custom OpenAI-Compatible Endpoints¶

For endpoints that don't have one of the native provider prefixes above — NVIDIA NIM, Ollama, HuggingFace TGI, vLLM, LM Studio, and similar — set OPENAI_COMPATIBLE_LLM_API_BASE_URL. This pins the request to CrewAI's native OpenAI-compatible client regardless of the model id's shape, so DEFAULT_LLM_MODEL/MANAGER_LLM_MODEL should be set to the raw model id the endpoint expects (no provider prefix). OPENAI_COMPATIBLE_LLM_API_KEY is optional — omit it for endpoints, such as a local Ollama server, that don't require one.

Example — NVIDIA NIM:

OPENAI_COMPATIBLE_LLM_API_KEY=nvapi-xxxxx
OPENAI_COMPATIBLE_LLM_API_BASE_URL=https://integrate.api.nvidia.com/v1
DEFAULT_LLM_MODEL=meta/llama-3.1-70b-instruct
MANAGER_LLM_MODEL=meta/llama-3.1-70b-instruct

Example — Ollama, local or self-hosted:

OPENAI_COMPATIBLE_LLM_API_BASE_URL=http://localhost:11434/v1
DEFAULT_LLM_MODEL=llama3
MANAGER_LLM_MODEL=llama3

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)	0.2	Analytical precision
Execution Agent (L3)	0.1	Precise booking execution

Storage¶

All buyer state is persisted in a single SQLite database configured by DATABASE_URL. See Storage Layer for the store-by-store reference.

Variable	Type	Default	Description
`DATABASE_URL`	`str`	`sqlite:///./ad_buyer.db`	SQLite connection string shared by all domain stores.

DATABASE_URL=sqlite:///./ad_buyer.db

SQLite supports a single writer: run one agent instance per database file.

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 with `SGP_ENFORCE=true` = the gate fails closed (no sellers pass discovery).
`SGP_BASE_URL`	`str`	`https://api.safeguardprivacy.com`	SGP base URL. Staging: `https://api.safeguardprivacy-demo.com`.
`SGP_ENFORCE`	`bool`	`False`	When `True`, the canonical booking pipeline excludes sellers without verified IAB buyer-agent approval at discovery, emitting `sgp.vendor_gate` events; SGP transport errors fail closed. When `False` (default): zero SGP calls, behavior unchanged.
`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