ap2-merchant-agent

AP2 Merchant Agent Implementation

Before writing code

Fetch live docs:

1. Fetch https://ap2-protocol.org/specification/ for Merchant Endpoint responsibilities
2. Web-search site:github.com google-agentic-commerce AP2 samples roles merchant_agent for reference implementation
3. Web-search site:github.com google-agentic-commerce AP2 merchant cart mandate for Cart Mandate creation
4. Fetch SDK docs for merchant-side agent patterns

Conceptual Architecture

What the Merchant Agent Does

The Merchant Agent (ME) represents the seller in AP2 transactions:

1. Receives Intent Mandates from Shopping Agents
2. Searches product catalog for matching items
3. Creates Cart Mandates with specific product offers, prices, and totals
4. Signs Cart Mandates with the merchant entity's signature
5. Handles clarification requests when intent is ambiguous
6. Supports the payment flow by forwarding to Payment Processor

Agent Card

The Merchant Agent's Agent Card advertises:

• AP2 extension support with supported payment methods
• Skills related to product search, cart creation, order management
• Product categories and capabilities
• Authentication requirements for Shopping Agents

Key Responsibilities

Intent Processing

• Parse incoming Intent Mandates from Shopping Agents
• Match intent against product catalog
• Determine if the intent can be fulfilled within constraints
• Decide whether to proceed, request clarification, or reject

Cart Mandate Creation

• Select matching products from catalog
• Calculate prices, taxes, shipping, and totals
• Build the Cart Mandate with W3C Payment Request API structure
• Include all line items with individual pricing
• Sign the Cart Mandate with the merchant entity's key

Merchant Signature

The merchant signature is critical:

• It's an entity-level signature (the merchant organization, not the AI agent)
• It guarantees product availability at the stated prices
• It commits the merchant to fulfillment
• Key management must be handled at the organization level