Ap2 Shopping Agent

---
name: ap2-shopping-agent
description: >
  Build an AP2 Shopping Agent — the main orchestrator that handles user
  requests, creates mandates, coordinates with merchants and credentials
  providers, and manages the transaction flow. Use when implementing the
  Shopping Agent role.
---

# AP2 Shopping Agent Implementation

## Before writing code

**Fetch live docs**:
1. Fetch `https://ap2-protocol.org/specification/` for Shopping Agent responsibilities
2. Web-search `site:github.com google-agentic-commerce AP2 samples roles shopping_agent` for reference implementation
3. Web-search `site:github.com google-agentic-commerce AP2 samples python src roles` for source code structure
4. Fetch SDK docs for agent framework classes (Google ADK)

## Conceptual Architecture

### What the Shopping Agent Does

The Shopping Agent (SA) is the **primary orchestrator** of AP2 transactions. It acts as the user's representative, coordinating between all other roles:

1. **Receives user intent** — Understands what the user wants to buy
2. **Creates Intent Mandates** — Formalizes user intent into structured mandates
3. **Discovers merchants** — Finds merchants that can fulfill the intent
4. **Negotiates with merchants** — Presents mandates, receives Cart Mandates
5. **Coordinates with Credentials Provider** — Gets payment methods, handles tokenization
6. **Manages user interaction** — Presents options, collects confirmations
7. **Orchestrates the full flow** — Drives the human-present transaction flow

Note: The Shopping Agent does **not** create Payment Mandates. Payment Mandates are constructed by the **Merchant Payment Processor (MPP)**.

### Agent Card

The Shopping Agent's Agent Card declares:
- AP2 extension support in `capabilities.extensions[]`
- Skills related to shopping (product search, cart management, payment)
- Authentication requirements for users
- Supported input/output modes

### Key Responsibilities

#### Intent Capture
- Parse user's natural language shopping request
- Extract: what to buy, constraints (price, brand, quality), preferences
- Present structured understanding back to user for confirmation
- Create and present Intent Mandate for signing

#### Merchant Interaction
- Discover merchant agents (via Agent Cards or registry)
- Present Intent Mandate to relevant merchants
- Receive and evaluate Cart Mandates
- Handle merchant clarification requests
- Support multi-merchant scenarios (compare offers)

#### Payment Coordination
- Query Credentials Provider for available payment methods
- Present payment options to user
- Request payment method tokenization
- Relay payment context to Merchant/MPP (the MPP constructs the Payment Mandate)
- Handle the trusted device surface attestation flow

#### User Communication
- Display product options clearly
- Show pricing breakdowns
- Present payment method choices
- Redirect to trusted device surface for confirmation
- Deliver receipts and confirmations

### What the Shopping Agent Must NOT Do

Critical security constraints:
- **Never access raw payment credentials** — Only tokenized references (DPANs)
- **Never store PCI data** — Card numbers, CVVs stay with Credentials Provider
- **Never store PII beyond needed scope** — Minimize data retention
- **Never forge user signatures** — Signatures come from user's device
- **Never auto-approve beyond Intent Mandate bounds** — Respect constraints

### Implementation with Google ADK

The reference implementation uses Google ADK:
- ADK agent with Gemini 2.5 Flash for reasoning
- A2A server for receiving user messages
- A2A client for communicating with other agents
- Port 8000 with ADK web UI

### Verbose Mode

Include "verbose" in the initial prompt to enable:
- Detailed agent explanations of each step
- Display of all mandate JSON payloads
- Full DataPart visibility
- Useful for debugging and development

### Best Practices

- Use the LLM for understanding intent, but validate mandates deterministically
- Always present clear summaries to the user before requesting signatures
- Handle timeouts for user responses
- Implement retry logic for failed agent-to-agent communications
- Log all mandate creation and agent interactions
- Support the escalation from autonomous to human-present flows
- Test with multiple merchants to verify comparison logic
- Never bypass the trusted device surface confirmation

Fetch the sample Shopping Agent source code for exact implementation patterns, ADK configuration, and A2A message handling before building.