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.

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