orcaqubits/ap2-shopping-agent
ap2-agentic-payments/skills/ap2-shopping-agent/SKILL.md
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.
$ install --global
skillsauthnpx skillsauth add orcaqubits/agentic-commerce-claude-plugins ap2-shopping-agentInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 9, 2026, 6:41 AM207.3s1 file scanned
SKILL.md
- 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.
- allowed-tools:
- Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
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_agentfor reference implementation - Web-search
site:github.com google-agentic-commerce AP2 samples python src rolesfor 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.
Related Skills
orcaqubits/spree-headless-storefront
development
VerifiedTrustedCommunity
Build with Spree's headless Next.js storefront — the official `spree/storefront` repo (Next.js 16 App Router with Server Actions and Turbopack, React 19 Server Components, Tailwind CSS 4, TypeScript 5, `@spree/sdk`, Sentry), server-only auth (httpOnly JWT cookies + publishable key), MeiliSearch faceted catalog, one-page checkout with Apple/Google Pay/Klarna/Affirm/SEPA, multi-region market routing, GA4 + JSON-LD SEO, and Vercel/Docker deployment. Use when forking or customizing the storefront, or evaluating headless adoption.
27SKILL.mdUpdated May 14, 2026
orcaqubits/spree-extensions
tools
VerifiedTrustedCommunity
Build Spree extensions as Rails engines — gem scaffolding, `bin/rails g spree:extension`, mounting routes/migrations/assets, the modern `prepend` decorator pattern (`*_decorator.rb` with `self.prepended(base)`), generators (`spree:model_decorator`, `spree:controller_decorator`), the four customization surfaces in preference order (Events > Webhooks > Dependencies > Decorators), Spree::Dependencies for swapping service objects, gem release/versioning, and the deprecated Deface engine. Use when building a reusable Spree extension or adding non-trivial customization to an app.
27SKILL.mdUpdated May 14, 2026
orcaqubits/spree-events-webhooks
development
VerifiedTrustedCommunity
Build with Spree's event bus and Webhooks 2.0 — `Spree::Events` publication, `Spree::Subscriber` DSL with `subscribes_to` and `on`, wildcard matching, lifecycle events (`{model}.created/.updated/.deleted` via `publishes_lifecycle_events`), the canonical event catalog (order.*, payment.*, shipment.*, product.*), Webhooks 2.0 endpoints, HMAC-SHA256 signing (`X-Spree-Webhook-Signature`), exponential-backoff retries, and Sidekiq job orchestration. Use when wiring event-driven business logic, building webhook consumers, or replacing ActiveSupport callback chains.
27SKILL.mdUpdated May 14, 2026
orcaqubits/spree-dev-patterns
tools
VerifiedTrustedCommunity
Cross-cutting Spree development patterns — the customization preference hierarchy (Events > Webhooks > Dependencies > Decorators), `Spree::Dependencies` service-object swapping, the `_decorator.rb` + `prepend` + `self.prepended` idiom, idempotent subscribers and webhook receivers, multi-store scoping discipline, prefixed IDs, calculator polymorphism (shipping/promotion/tax share the base), service-object composition with `dry-monads` or simple results, why to avoid `class_eval` reopening and Deface, and Spree-on-Rails idioms (Hotwire/Turbo Stimulus, ActiveStorage, Action Cable, Sidekiq). Use when designing the architecture of a Spree extension or solving cross-cutting concerns.
27SKILL.mdUpdated May 14, 2026