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["Buyer Deal Specialist
(deal discovery)"]
    end

    subgraph Level3["Level 3 — Functional Agents"]
        AUD["Audience Planner
(Agentic Audiences / 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.

Buyer Deal Discovery Specialist¶

File: src/ad_buyer/agents/level2/buyer_deal_specialist_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 (Agentic Audiences / UCP)¶

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

The Audience Planner composes audience targets for a campaign by selecting and arranging references across three IAB-standardized audience types. It is the only agent in the buyer that owns the audience surface end-to-end --- from brief ingestion through the deal request that goes to sellers.

The three audience types¶

Taxonomies are vendored at data/taxonomies/ with version + sha256 + fetched_at tracked in taxonomies.lock.json. License attribution per IAB CC-BY 3.0 / 4.0 is preserved alongside each taxonomy file.

Composable overlay model¶

A campaign carries one primary audience and zero or more constraint, extension, or exclusion audiences. Each is an AudienceRef carrying its type, taxonomy, version, and identifier (or embedding URI for agentic refs).

AudiencePlan
  primary:     AudienceRef(type=standard,   id="3-7",        version="1.1")
  constraints: [AudienceRef(type=contextual, id="IAB1-2",     version="3.1")]
  extensions:  [AudienceRef(type=agentic,    ref="emb://...", version="draft-2026-01")]
  exclusions:  []

The planner mixes types freely --- a Standard primary narrowed by a Contextual constraint and broadened by an Agentic extension is the canonical shape.

Reasoning loop¶

Configuration¶

Tools¶

• TaxonomyLookupTool --- resolve a string against vendored Standard / Contextual taxonomies (no network)
• AudienceDiscoveryTool --- query sellers for available segments matching a ref
• AudienceMatchingTool --- score a candidate AudienceRef against seller capabilities
• CoverageEstimationTool --- project unique reach for a composed plan
• EmbeddingMintTool --- mint or reference an Agentic embedding. Honors EMBEDDING_MODE (mock | local | advertiser | hybrid) per the locked Embedding Strategy decision (see docs/decisions/EMBEDDING_STRATEGY_2026-04-25.md in the agent_range parent repo).

Embedding provenance¶

Every agentic AudienceRef carries compliance_context.embedding_provenance so downstream consumers know where the bytes came from:

• local_buyer --- buyer's local sentence-transformers model
• advertiser_supplied --- advertiser provided the vector verbatim
• hosted_external --- third-party hosted embedding service (not enabled by default)
• mock --- deterministic SHA256-seeded fallback for CI / demos

This is the forensic anchor for cross-repo wire correlation and unblocks future privacy-regime fan-out (see the consent surface review at docs/reports/CONSENT_SURFACE_REVIEW_2026-04-25.md in the agent_range parent repo).

Where the plan goes¶

The AudiencePlan rides on CampaignPlan and propagates into InventoryRequirements, DealParams, QuoteRequest, and DealBookingRequest. Sellers receive the full plan and evaluate each ref against their package capabilities --- see the seller media-kit docs for how packages declare which audience types they support, and docs/architecture/capability-negotiation.md in the agent_range parent repo for the pre-flight + structured-rejection contract.

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
• Buyer Deal Flow --- Buyer deal discovery workflow
• Booking Flow --- Detailed booking sequence
• Configuration --- LLM and agent settings