AP2 Shopping Agent Implementation
Before writing code
Fetch live docs:
- Fetch
https://ap2-protocol.org/specification/ for Shopping Agent responsibilities
- Web-search
site:github.com google-agentic-commerce AP2 samples roles shopping_agent for reference implementation
- Web-search
site:github.com google-agentic-commerce AP2 samples python src roles for source code structure
- 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:
- Receives user intent — Understands what the user wants to buy
- Creates Intent Mandates — Formalizes user intent into structured mandates
- Discovers merchants — Finds merchants that can fulfill the intent
- Negotiates with merchants — Presents mandates, receives Cart Mandates
- Coordinates with Credentials Provider — Gets payment methods, handles tokenization
- Manages user interaction — Presents options, collects confirmations
- 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.