Architecture

• System Architecture
  • Request Lifecycle
  • Transport Parity
• Protocol Comparison
• Registered Tools
• Multi-Tenancy
• Database
• Adapter Pattern
• Authentication
• AI Integration
• Error Handling
• Source Code Organization
• Further Reading

System Architecture

The Sales Agent is a single-process FastAPI application behind an nginx reverse proxy. It serves MCP, A2A, and REST protocols through a shared business logic layer.

As of v1.5.0, the application uses a unified process model. The previous multi-process architecture (separate MCP, A2A, and Admin processes on ports 8001/8091) was replaced by a single FastAPI app on port 8080.

                    ┌───────────────────────────┐
                    │      AI Buying Agents      │
                    └────────────┬──────────────┘
                                 │
                    ┌────────────▼──────────────┐
                    │    nginx (port 8000)       │
                    │    Reverse Proxy / SSL     │
                    └────────────┬──────────────┘
                                 │
          ┌──────────────────────▼──────────────────────┐
          │         FastAPI Unified App (port 8080)      │
          │                                              │
          │  /mcp/   → FastMCP (StreamableHTTP)          │
          │  /a2a    → A2A Server (JSON-RPC 2.0)         │
          │  /admin  → Flask Admin UI (OIDC SSO)         │
          │  /api/v1 → REST API (FastAPI)                │
          ├──────────────────────────────────────────────┤
          │         Auth & Identity Resolution            │
          │    UnifiedAuthMiddleware (ASGI)               │
          │    Token → AuthContext → ResolvedIdentity     │
          ├──────────────────────────────────────────────┤
          │         Business Logic (_impl functions)      │
          │    Transport-agnostic implementation          │
          ├──────────────────────────────────────────────┤
          │         Adapter Layer                         │
          │    GAM │ Kevel │ Triton │ Broadstreet │ Mock  │
          └──────────────────────┬─────────────────────┘
                                 │
                    ┌────────────▼──────────────┐
                    │    Ad Server APIs          │
                    │  + PostgreSQL 17            │
                    └───────────────────────────┘

Request Lifecycle

1. An AI agent sends a request to http://host:8000/{protocol-path}.
2. nginx proxies to the FastAPI app on port 8080.
3. FastAPI routes to the correct sub-application based on URL prefix.
4. UnifiedAuthMiddleware extracts the token from x-adcp-auth or Authorization: Bearer.
5. The middleware creates an AuthContext and stores it in the ASGI scope.
6. The transport layer resolves AuthContext into a ResolvedIdentity (tenant + principal).
7. The transport layer calls the _impl function with the ResolvedIdentity.
8. The _impl function executes business logic via the database and ad server adapter.
9. The response is serialized back through the transport layer.

Transport Parity

All three protocols call the same _impl business logic functions. This ensures identical behavior regardless of protocol. Seven structural test guards enforce this:

• No transport-specific imports in _impl modules
• All _impl functions accept ResolvedIdentity (not transport-specific contexts)
• _impl functions raise AdCPError (not transport-specific errors like ToolError)

Protocol Comparison

Registered Tools

The Sales Agent registers 11 tools, accessible identically via MCP, A2A, and REST:

Signal tools (get_signals, activate_signal) are not part of the Sales Agent. These are handled by dedicated signals agents in the AdCP ecosystem.

Multi-Tenancy

All tenant-scoped entities use composite primary keys (tenant_id, entity_id). Every database query is scoped to the current tenant via the ResolvedIdentity.

Database

PostgreSQL 17 with SQLAlchemy 2.0 and Alembic (156 migration files).

Migrations run automatically on startup unless SKIP_MIGRATIONS=true is set. Back up your database before upgrading versions.

Adapter Pattern

The AdServerAdapter base class (src/adapters/base.py) defines the interface all adapters implement.

Xandr (src/adapters/xandr.py) exists in the codebase but is incomplete.

Authentication

Four levels of authentication:

1. Super Admin – Unrestricted access. Identified by SUPER_ADMIN_EMAILS or SUPER_ADMIN_DOMAINS env vars.
2. OIDC SSO – Admin UI users authenticate via per-tenant OIDC (Google, Microsoft, Okta, Auth0, Keycloak).
3. Tenant Admin – Manages a single publisher’s configuration.
4. Principal Token – AI agents authenticate via x-adcp-auth or Bearer token, identifying both tenant and advertiser.

Per-tenant SSO configured through the Admin UI is the recommended authentication method. Global OAuth via environment variables (GOOGLE_CLIENT_ID, etc.) is deprecated.

AI Integration

The Sales Agent uses Pydantic AI (>= 0.3.0) for AI features, configured per-tenant through the Admin UI.

Supported providers:

Gemini API keys are configured per-tenant through the Admin UI under Settings > AI Configuration. The global GEMINI_API_KEY environment variable serves as a fallback default.

Error Handling

All errors extend AdCPError with three fields: message, recovery, and details.

Recovery hints use RecoveryHint = Literal["transient", "correctable", "terminal"]:

• transient – Retry after a delay (e.g., adapter timeout, rate limit)
• correctable – Fix the input and retry (e.g., validation error, missing field)
• terminal – Cannot succeed as-is (e.g., insufficient permissions)

See Error Codes for the complete catalog.

Source Code Organization

src/
  app.py                       — FastAPI entry point (unified app)
  core/
    tools/                     — MCP tool implementations
      discovery.py             — get_adcp_capabilities
      products.py              — get_products
      media_buy.py             — create_media_buy, update_media_buy
      media_buy_list.py        — get_media_buys
      media_buy_delivery.py    — get_media_buy_delivery
      creatives.py             — sync_creatives, list_creatives
      creative_formats.py      — list_creative_formats
      properties.py            — list_authorized_properties
      performance.py           — update_performance_index
    schemas/                   — Pydantic request/response schemas
    database/                  — SQLAlchemy models, Alembic migrations
    auth_middleware.py         — UnifiedAuthMiddleware (ASGI)
    exceptions.py              — AdCPError hierarchy
    resolved_identity.py       — ResolvedIdentity dataclass
  adapters/
    base.py                    — AdServerAdapter abstract base
    gam/                       — Google Ad Manager (production)
    mock_ad_server.py          — Mock adapter (testing)
    kevel.py                   — Kevel adapter
    triton_digital.py          — Triton Digital adapter
    broadstreet/               — Broadstreet adapter (in development)
  a2a_server/                  — A2A protocol implementation
  admin/
    app.py                     — Flask app factory
    blueprints/                — ~26 Flask blueprints
  services/
    ai/
      agents/                  — AI agents (naming, review, ranking, policy)
      config.py                — TenantAIConfig
      factory.py               — AIServiceFactory
  routes/
    api_v1.py                  — REST API endpoints

Further Reading

• Quick Start – Docker setup
• Tool Reference – All MCP tools
• Error Codes – Error catalog
• Deployment Overview – Docker, Fly.io, GCP
• Glossary – Key terms