Agent Hierarchy¶

The buyer agent uses a three-level agent hierarchy powered by CrewAI. Each level has a distinct responsibility: strategic orchestration, channel-specific expertise, and functional execution.

Three levels exist because advertising campaigns require decisions at three different scopes. A single agent cannot efficiently reason about both portfolio-wide budget strategy and the mechanics of reserving a line item --- the context windows, LLM costs, and failure modes are fundamentally different at each scope. By separating strategic reasoning (Level 1) from channel expertise (Level 2) and task execution (Level 3), the system keeps each agent focused on a narrow responsibility, reduces per-call token cost by using smaller models where appropriate, and allows channel specialists to run in parallel without blocking the portfolio-level plan.

Overview¶

graph TB
    subgraph Level1["Level 1 — Strategic"]
        PM["Portfolio Manager
(Claude Opus)"]
    end

    subgraph Level2["Level 2 — Channel Specialists"]
        BR["Branding Specialist
(display / video)"]
        CTV["CTV Specialist
(streaming)"]
        MOB["Mobile App Specialist
(app install)"]
        PERF["Performance Specialist
(remarketing)"]
        DSP["DSP Specialist
(deal discovery)"]
    end

    subgraph Level3["Level 3 — Functional Agents"]
        AUD["Audience Planner
(UCP)"]
        RES["Research Agent
(inventory)"]
        EXEC["Execution Agent
(orders / lines)"]
        REP["Reporting Agent
(stats / analysis)
Coming Soon"]
    end

    PM -->|budget allocation| BR
    PM -->|budget allocation| CTV
    PM -->|budget allocation| MOB
    PM -->|budget allocation| PERF
    PM -.->|deal requests| DSP

    BR --> RES
    BR --> EXEC
    BR --> AUD
    CTV --> RES
    CTV --> EXEC
    CTV --> AUD
    MOB --> RES
    MOB --> EXEC
    MOB --> AUD
    PERF --> RES
    PERF --> EXEC
    PERF --> AUD
    DSP --> RES

Level 1 --- Portfolio Manager¶

The Portfolio Manager is the top-level orchestrator. It receives a campaign brief and determines how to allocate budget across channels.

Key file: src/ad_buyer/agents/level1/portfolio_manager.py

Responsibilities:

• Analyze campaign briefs and extract objectives, constraints, and KPIs
• Allocate budget across channels (Branding, CTV, Mobile, Performance)
• Provide channel-specific guidance to specialists
• Monitor overall campaign coherence

from ad_buyer.agents.level1.portfolio_manager import create_portfolio_manager

manager = create_portfolio_manager(
    tools=[],       # Tools added by crews
    verbose=True,
)

Level 2 --- Channel Specialists¶

Each Level 2 agent owns a specific advertising channel. They receive budget allocations from the Portfolio Manager and coordinate Level 3 agents to research inventory and execute bookings.

Key directory: src/ad_buyer/agents/level2/

All channel specialists share these defaults:

Branding Specialist¶

File: src/ad_buyer/agents/level2/branding_agent.py

Focuses on premium display and video placements for upper-funnel brand awareness.

from ad_buyer.agents.level2 import create_branding_agent

agent = create_branding_agent(tools=[...])

CTV Specialist¶

File: src/ad_buyer/agents/level2/ctv_agent.py

Expert in Connected TV and streaming inventory.

Mobile App Specialist¶

File: src/ad_buyer/agents/level2/mobile_app_agent.py

Drives efficient app installs and post-install conversions.

Performance Specialist¶

File: src/ad_buyer/agents/level2/performance_agent.py

Maximizes conversions and ROAS through lower-funnel tactics.

DSP Deal Discovery Specialist¶

File: src/ad_buyer/agents/level2/dsp_agent.py

Discovers inventory and obtains Deal IDs for activation in traditional DSP platforms.

Level 3 --- Functional Agents¶

Level 3 agents are shared across channels. They do not make strategic decisions --- they execute specific functions on behalf of the Level 2 specialists.

Key directory: src/ad_buyer/agents/level3/

All functional agents share these defaults:

Audience Planner (UCP)¶

File: src/ad_buyer/agents/level3/audience_planner_agent.py

Plans and selects audiences using the IAB Tech Lab User Context Protocol (UCP) for real-time audience matching with seller inventory.

Key capabilities:

• Signal analysis using UCP protocol
• Audience segment discovery from seller capabilities
• Coverage estimation for targeting combinations
• Audience expansion recommendations
• Gap analysis when requirements cannot be fully met

Tools used: AudienceDiscoveryTool, AudienceMatchingTool, CoverageEstimationTool

Research Agent¶

File: src/ad_buyer/agents/level3/research_agent.py

Discovers and evaluates advertising inventory across publishers.

Tools used: ProductSearchTool, AvailsCheckTool

Execution Agent¶

File: src/ad_buyer/agents/level3/execution_agent.py

Handles the OpenDirect booking lifecycle.

Tools used: CreateOrderTool, CreateLineTool, ReserveLineTool, BookLineTool

Reporting Agent¶

File: src/ad_buyer/agents/level3/reporting_agent.py

Retrieves and analyzes campaign performance data.

Tools used: GetStatsTool

Crew Coordination¶

Agents are organized into crews --- CrewAI constructs that define which agents work together, what tasks they perform, and how authority flows.

Portfolio Crew¶

File: src/ad_buyer/crews/portfolio_crew.py

The top-level crew uses a hierarchical process with the Portfolio Manager as the manager agent.

from ad_buyer.crews.portfolio_crew import create_portfolio_crew

crew = create_portfolio_crew(
    client=opendirect_client,
    campaign_brief={
        "name": "Q3 Awareness Campaign",
        "objectives": ["brand_awareness", "reach"],
        "budget": 500_000,
        "start_date": "2026-07-01",
        "end_date": "2026-09-30",
        "target_audience": {"age": "25-54", "interests": ["sports", "news"]},
        "kpis": {"viewability": 0.70, "reach": 2_000_000},
    },
)

result = crew.kickoff()

Structure:

Tasks:

1. Budget Allocation --- Analyze the brief, determine optimal channel split
2. Channel Coordination --- Provide targeting and quality guidance per channel

Channel Crews¶

File: src/ad_buyer/crews/channel_crews.py

Each channel has its own crew. The channel specialist acts as the manager, with Research and Execution agents as workers.

from ad_buyer.crews.channel_crews import create_branding_crew

crew = create_branding_crew(
    client=opendirect_client,
    channel_brief={
        "budget": 150_000,
        "start_date": "2026-07-01",
        "end_date": "2026-09-30",
        "target_audience": {"age": "25-54"},
        "objectives": ["brand_awareness"],
    },
    audience_plan={
        "target_demographics": {"age": "25-54", "gender": "all"},
        "target_interests": ["sports", "news", "entertainment"],
    },
)

result = crew.kickoff()

Four channel crew factory functions are available:

All channel crews follow the same two-task pattern:

1. Research Task --- The Research Agent searches inventory matching the channel brief and audience plan, using both research and audience tools
2. Recommendation Task --- The channel specialist reviews findings and selects the best inventory

Execution Flow¶

A typical end-to-end campaign follows this pattern:

sequenceDiagram
    participant User
    participant PM as Portfolio Manager (L1)
    participant CS as Channel Specialist (L2)
    participant RA as Research Agent (L3)
    participant EA as Execution Agent (L3)

    User->>PM: Campaign brief
    PM->>PM: Allocate budget across channels
    PM->>CS: Channel brief + budget

    CS->>RA: Research inventory
    RA-->>CS: Ranked product recommendations
    CS->>CS: Select best inventory
    opt Negotiation (eligible tiers)
        CS->>EA: Negotiate pricing
        EA-->>CS: Negotiated terms
    end
    CS->>EA: Book selected placements
    EA-->>CS: Booking confirmations
    CS-->>PM: Channel results
    PM-->>User: Consolidated plan

Related¶

• Architecture Overview --- Full system architecture
• Tools Reference --- All CrewAI tools available to agents
• DSP Deal Flow --- DSP-specific deal discovery workflow
• Booking Flow --- Detailed booking sequence
• Configuration --- LLM and agent settings