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.
--- 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/ap2/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 Checkout 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 Checkout 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.--- 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/ap2/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 Checkout 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 Checkout 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.
Imported from the listed AgentSkill.sh category. Complete supplied package files and notices are retained. Required external tools and credentials are not installed. No bundled code was executed during import. Individual agent task behavior has not been tested.