Skip to content

README.md

Latest commit

 

History

History
207 lines (154 loc) · 8.91 KB

README.md

File metadata and controls

207 lines (154 loc) · 8.91 KB

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

UCP A2A Demo

▶️ Watch the full demo video

Architecture

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

Architecture Diagram

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:

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:

📸 Server Endpoints (click to expand)
Agent Card
/.well-known/agent-card.json

Agent Card
Declares UCP extension with capabilities 		UCP Profile
/.well-known/ucp

UCP Profile
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

Demo
▶️ Watch full video
  1. Navigate to http://localhost:3000
  2. Type "show me cookies available in stock" and press enter
  3. The agent will return products available in stock
  4. Click "Add to Checkout" for any product
  5. The agent will ask for required information such as email address, shipping address, etc.
  6. Once the required information is provided, click "Complete Payment"
  7. The UI shows available mock payment options
  8. Select a payment method and click "Confirm Purchase"
  9. 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

Disclaimer

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