Buyer Guide Overview¶

The buyer agent automates the full media buying workflow --- from receiving a campaign brief through discovering seller inventory, negotiating pricing, obtaining human approval, and booking confirmed deals. This overview orients you on the end-to-end process and points you to the right guide for each stage.

End-to-End Buyer Workflow¶

A campaign moves through these stages. Negotiation is optional (it depends on your identity tier), and the human approval gate ensures no spend is committed without explicit sign-off.

flowchart LR
    Brief["Campaign Brief"]
    Budget["Budget Allocation"]
    Research["Seller Discovery\n& Research"]
    Negotiate["Negotiation\n(optional)"]
    Approve["Human Approval"]
    Book["Deal Booking"]
    Deliver["Delivery &\nTracking"]

    Brief --> Budget --> Research --> Negotiate --> Approve --> Book --> Deliver

    style Negotiate stroke-dasharray: 5 5

Two Flow Entry Points¶

The buyer supports two distinct entry points depending on your use case:

• DealBookingFlow (campaign flow) --- The full multi-channel path. Starts from a campaign brief, allocates budget, researches across channels in parallel, builds recommendations, and books multiple deals after approval. This is the primary workflow for campaign managers.
• DSPDealFlow (deal flow) --- The lightweight single-deal path. Discovers inventory and books one deal directly. Designed for programmatic DSP integration where the campaign planning happens externally.

Both flows share the same deal state machine, event bus, and DealStore persistence. For architectural details, see Architecture Overview.

Cross-Cutting Concerns¶

Human Approvals¶

The buyer agent enforces a human-in-the-loop approval gate before committing any spend. After channel specialists build their recommendations, the campaign enters the awaiting_approval state. A human reviewer can:

• Approve all recommendations (POST /bookings/{job_id}/approve-all)
• Approve selectively by specifying which product IDs to book (POST /bookings/{job_id}/approve)
• Reject by not approving (the campaign stays in awaiting_approval until approved or timed out)

Set auto_approve: true in the campaign brief to bypass the gate for testing. In production, the approval gate is the safety net that prevents unintended spend.

Logging & Observability¶

Every significant action the buyer takes --- quote requests, negotiation rounds, deal bookings, budget allocations --- is recorded as a structured event on the event bus. This is the buyer's observability layer: it answers "what happened, when, and why" for any workflow execution. Events are correlated by flow_id, deal_id, and session_id, making it straightforward to trace the full history of a campaign or a single deal.

For operational monitoring, query the /events API endpoint or subscribe to events programmatically.

Identity & Access Tiers¶

Your identity tier determines what the buyer can do with a given seller. Public-tier access gets list prices with no negotiation. Seat, Agency, and Advertiser tiers unlock progressively better rates and the ability to negotiate. Identity is resolved per seller connection and affects both pricing and available API operations.

Guide Topics¶

Related¶

For architecture details behind the buyer workflow, see the Architecture Overview. For API endpoint reference, see the API Reference. To get the buyer running locally, start with the Quickstart.