Cymbal Retail Agent with UCP Extension and A2A

This sample demonstrates how to build an AI-powered shopping assistant using Universal Commerce Protocol (UCP) - an open standard that enables interoperability between commerce platforms, merchants, and payment providers.

UCP provides standardized data types for the entire commerce transaction lifecycle: product discovery, checkout sessions, fulfillment options, payment processing, and order confirmation. By implementing UCP, your commerce agent can communicate with any UCP-compatible client or platform using a common vocabulary.

The sample uses Google ADK (Agent Development Kit) to build the AI agent and A2A Protocol (Agent-to-Agent) for agent discovery and communication.

Key Features
🛒	UCP Checkout Capability: Implements dev.ucp.shopping.checkout for checkout, line items, totals, and order creation with standardized status lifecycle (incomplete → ready_for_complete → completed).
📦	UCP Fulfillment Capability: Implements dev.ucp.shopping.fulfillment for shipping address collection, delivery options, and fulfillment method selection.
💳	UCP Payment Handling: Supports PaymentInstrument types with configurable payment handlers and merchant business configuration via UCP profile.
🤝	Capability Negotiation: Client and merchant exchange UCP profiles at /.well-known/ucp to agree on supported features before transactions begin.
🤖	Google ADK Agent: Gemini 3.0 Flash model with 8 shopping tools (search, checkout, payment) demonstrating how to build UCP-aware agents.
🔗	A2A Protocol: Agent discovery via /.well-known/agent-card.json and JSON-RPC 2.0 communication - showing UCP as an A2A extension.
💻	React Chat Client: TypeScript UI that renders UCP data types (Checkout, LineItem, PaymentResponse, OrderConfirmation) with proper capability handling.

Demo

Complete Shopping Flow
Product search → Add items to Checkout → Payment → Order confirmation



▶️ Watch the full demo video

Architecture

System Architecture
How Client, A2A Protocol, Cymbal Retail Agent, and Store interact

Key points:

• Client sends requests with UCP-Agent header containing its profile URL
• Cymbal Retail Agent serves both /.well-known/agent-card.json (A2A) and /.well-known/ucp (UCP Profile)
• Capability Negotiation happens before processing - agent and client agree on supported features
• RetailStore uses UCP SDK types internally for checkout, fulfillment, and payment data

Quick Start

⏱️ Setup time: ~5 minutes

Prerequisites

Before you begin, ensure you have:

• Python 3.13+ with UV
• Node.js 18+
• Gemini API Key

1. Start the Cymbal Retail Agent

cd a2a/business_agent
uv sync
cp env.example .env

Edit .env and add your GOOGLE_API_KEY, then start the agent:

uv run business_agent

Expected output:

INFO:     Started server process
INFO:     Uvicorn running on http://0.0.0.0:10999

This starts the Cymbal Retail Agent on port 10999. You can verify by accessing:

• Agent Card: http://localhost:10999/.well-known/agent-card.json
• UCP Profile: http://localhost:10999/.well-known/ucp

📸 Server Endpoints (click to expand)

Agent Card /.well-known/agent-card.json Declares UCP extension with capabilities

UCP Profile /.well-known/ucp Defines supported capabilities & payment handlers

2. Start the Chat Client

In a new terminal:

cd a2a/chat-client
npm install
npm run dev

Expected output:

VITE v5.x.x ready
➜ Local: http://localhost:3000/

The Chat Client UCP Profile can be found at http://localhost:3000/profile/agent-profile.json

3. Try It Out

▶️ Watch full video

Navigate to http://localhost:3000 Type "show me cookies available in stock" and press enter The agent will return products available in stock Click "Add to Checkout" for any product The agent will ask for required information such as email address, shipping address, etc. Once the required information is provided, click "Complete Payment" The UI shows available mock payment options Select a payment method and click "Confirm Purchase" The agent will create an order and return the order confirmation

Note: This sample is for demonstration purposes only. See Production Notes for security considerations and deployment requirements.

Next Steps

Ready to understand how it works?

Goal	Resource
Understand the architecture	Developer Guide
Deep dive into code	Architecture
Extend the sample	Extending Guide
AI assistant context	SKILLS.md - Context for Claude Code, Gemini CLI, Cursor, Codex

What is UCP?

Universal Commerce Protocol (UCP) is an open standard that enables interoperability between commerce platforms, merchants, and payment providers. It provides standardized data types for commerce transactions.

This sample uses the following UCP capabilities:

• dev.ucp.shopping.checkout - Checkout session management with status lifecycle: incomplete → ready_for_complete → completed
• dev.ucp.shopping.fulfillment - Shipping and delivery handling
• dev.ucp.shopping.discount - Discount and promotional codes

Learn more about UCP

Technology Stack

Technology	Purpose	Used For
Google ADK	Agent Framework	AI agent with tools, Gemini LLM integration, session management
A2A Protocol	Communication	Agent discovery via Agent Card, JSON-RPC messaging, task management
UCP	Commerce Standard	Standardized product, checkout, payment, and order data types

Related Resources

• UCP Specification
• Google ADK Documentation
• A2A Protocol Specification
• UCP Python SDK

Disclaimer

This is an example implementation for demonstration purposes and is not intended for production use.