git:20260309.786511c to git:20260914.08f85a3

---

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.

allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

---

# AP2 Merchant Agent Implementation

## Before writing code

**Fetch live docs**:

2. Web-search `site:github.com google-agentic-commerce AP2 samples roles merchant_agent` for reference implementation

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

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

- Select matching products from catalog

- Calculate prices, taxes, shipping, and totals

- Include all line items with individual pricing

#### 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

```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

- The Shopping Agent compares offers on behalf of the user

- The merchant should respond quickly to be competitive

### Best Practices

- 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