Skip to content

Architecture Overview

The buyer agent is a multi-layer system that combines a FastAPI service layer with CrewAI agent orchestration and an OpenDirect protocol client.

System Architecture

graph TB
    User["User / Campaign Manager"]

    subgraph BuyerAgent["Ad Buyer Agent"]
        API["FastAPI API Layer
(port 8001)"]
        Flow["CrewAI Flow Engine
(DealBookingFlow)"]

        subgraph Agents["CrewAI Agent Hierarchy"]
            Portfolio["Portfolio Manager Agent
(budget allocation)"]
            Branding["Branding Specialist
(display/video)"]
            CTV["CTV Specialist
(streaming)"]
            Mobile["Mobile Specialist
(app inventory)"]
            Performance["Performance Specialist
(remarketing)"]
        end

        subgraph Clients["Protocol Clients"]
            Unified["UnifiedClient
(protocol switch)"]
            MCPClient["IABMCPClient
(MCP SDK / SSE)"]
            A2AClient["A2AClient
(JSON-RPC 2.0)"]
            ODClient["OpenDirect Client
(httpx)"]
        end

        State["Flow State
(BookingState)"]
    end

    subgraph SellerAgent["Seller Agent"]
        SellerMCP["MCP Server
(/mcp/sse)"]
        SellerA2A["A2A Server
(/a2a/*/jsonrpc)"]
        SellerAPI["OpenDirect 2.1 API"]
        Catalog["Product Catalog"]
        Booking["Booking Engine"]
    end

    User -->|"campaign brief"| API
    API -->|"background task"| Flow
    Flow --> Portfolio
    Portfolio -->|"channel budgets"| Branding
    Portfolio -->|"channel budgets"| CTV
    Portfolio -->|"channel budgets"| Mobile
    Portfolio -->|"channel budgets"| Performance
    Branding --> Unified
    CTV --> Unified
    Mobile --> Unified
    Performance --> Unified
    Unified -->|"structured tools"| MCPClient
    Unified -->|"natural language"| A2AClient
    MCPClient -->|"MCP / SSE"| SellerMCP
    A2AClient -->|"JSON-RPC"| SellerA2A
    SellerMCP --> Catalog
    SellerMCP --> Booking
    SellerA2A --> Catalog
    SellerA2A --> Booking
    Flow --> State
    ODClient -->|"OpenDirect HTTP"| SellerAPI
    SellerAPI --> Catalog
    SellerAPI --> Booking
    API -->|"status / results"| User

Component Summary

Component Role Key File
FastAPI API HTTP endpoints, authentication, job management interfaces/api/main.py
DealBookingFlow Event-driven CrewAI flow orchestrating the full booking lifecycle flows/deal_booking_flow.py
Portfolio Manager Agent Allocates budget across channels based on objectives crews/portfolio_crew.py
Channel Specialist Agents Research inventory and build recommendations per channel crews/channel_crews.py
UnifiedClient Protocol-switching client for MCP and A2A seller communication clients/unified_client.py
IABMCPClient MCP SDK client with Streamable HTTP transport clients/mcp_client.py
A2AClient JSON-RPC 2.0 client for conversational agent-to-agent requests clients/a2a_client.py
OpenDirectClient Async HTTP client for IAB OpenDirect 2.1 seller APIs clients/opendirect_client.py
BookingState Pydantic state model tracking the full flow lifecycle models/flow_state.py
Settings Environment-based configuration via pydantic-settings config/settings.py

Seller Communication Protocols

The buyer communicates with seller agents through three protocols, managed by the UnifiedClient:

CrewAI Tools --> UnifiedClient --> IABMCPClient --> Seller MCP Server (/mcp/sse) --> Seller Tools
CrewAI Tools --> UnifiedClient --> A2AClient   --> Seller A2A Server (/a2a/*/jsonrpc) --> NL Processing --> Seller Tools
Human        --> REST API      --> Buyer Agent  --> (MCP or A2A) --> Seller Agent
Protocol Transport Use Case
MCP Streamable HTTP (SSE) Automated workflows -- structured tool calls, deterministic
A2A JSON-RPC 2.0 Discovery and negotiation -- natural language, multi-turn
REST Standard HTTP Operator dashboards and legacy integration

MCP is the default. The UnifiedClient can switch protocols per-request or operate in dual-protocol mode via connect_both().

See Protocol Overview for full details.

Full Ecosystem

graph LR
    CM["Campaign Manager"]
    Buyer["Ad Buyer Agent
(port 8001)"]
    Seller["Ad Seller Agent
(port 8000)"]
    Pub["Publisher Inventory"]

    CM -->|"brief + approve"| Buyer
    Buyer -->|"MCP / A2A / OpenDirect"| Seller
    Seller -->|"catalog + booking"| Pub
    Seller -->|"results + confirmations"| Buyer
    Buyer -->|"status + booked lines"| CM

The buyer agent acts as an automated media buyer. It receives campaign requirements from a user or campaign manager, uses AI agents to plan and research, and executes deals against one or more seller agents using MCP (primary), A2A (conversational), or OpenDirect 2.1 REST (legacy).

See also: Seller Agent Architecture