AP2 Merchant Agent Implementation

---
name: ap2-merchant-agent
description: >
  Build an AP2 Merchant Agent — the seller-side agent that receives intent
  mandates, searches product catalogs, creates signed cart mandates, and
  represents the merchant in agentic transactions. Use when implementing the
  Merchant Endpoint role.
---

# AP2 Merchant Agent Implementation

## Before writing code

**Fetch live docs**:
1. Fetch `https://ap2-protocol.org/ap2/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 Checkout 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 Checkout Mandates** with specific product offers, prices, and totals
4. **Signs Checkout 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

#### Checkout Mandate Creation
- Select matching products from catalog
- Calculate prices, taxes, shipping, and totals
- Build the Checkout Mandate with W3C Payment Request API structure
- Include all line items with individual pricing
- Sign the Checkout 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

#### Escalation Decisions
When facing ambiguous intent, the merchant can:
- **Offer choices** — Present multiple matching products for user selection
- **Ask clarifications** — Request more specific requirements
- **Force human-present** — Require the user to confirm directly
- **Reject** — Decline the intent if it can't be fulfilled

### Catalog Integration

The Merchant Agent needs access to:
- **Product catalog** — Names, descriptions, SKUs, images
- **Inventory** — Real-time stock availability
- **Pricing** — Current prices, discounts, taxes
- **Shipping** — Available shipping methods, costs, timeframes
- **Policies** — Return policy, refund period, terms

### Payment Method Advertisement

Checkout Mandates include supported payment methods:
```json
"method_data": [
  {
    "supportedMethods": "https://processor.example.com/pay",
    "data": { "merchant_id": "..." }
  }
]
```

### Multi-Merchant Scenarios

A Shopping Agent may contact multiple merchants:
- Each merchant independently evaluates the Intent Mandate
- Each returns their own Checkout Mandate
- The Shopping Agent compares offers on behalf of the user
- The merchant should respond quickly to be competitive

### Best Practices

- Sign Checkout Mandates at the entity level, not the agent level
- Include all items with clear descriptions and prices
- Respond to Intent Mandates promptly — the Shopping Agent may be comparing merchants
- Handle out-of-stock gracefully with alternatives or clear messaging
- Implement proper key management for merchant signing keys
- Validate incoming Intent Mandates for authenticity
- Keep catalog data fresh — stale prices cause disputes
- Log all Checkout Mandate creation for audit trail

Fetch the specification for exact Merchant Agent requirements, Checkout Mandate creation process, and signing formats before implementing.