Cymbal Retail Agent - Developer Guide
February 17, 2026 · View on GitHub
TL;DR
- ADK Agent with 8 shopping tools (search, checkout, payment) using Gemini 3.0 Flash
- UCP Integration for standardized commerce data types and capability negotiation
- A2A Protocol for agent discovery and JSON-RPC messaging
About This Guide
This guide is for developers who want to understand how the sample works internally.
Prerequisites: Complete the Quick Start in README.md first.
What you'll learn:
- System architecture and component responsibilities
- How UCP and A2A protocols integrate with ADK
- The checkout state machine and commerce flows
- How to extend and customize the sample
Reading Roadmap
Choose your path based on your goal:
| Goal | Start Here | Then Read |
|---|---|---|
| New to AI agents? | Glossary | This guide → 01-architecture |
| Understand the system | Architecture | 02-adk-agent → 03-ucp-integration |
| Add a new tool | ADK Agent | 06-extending |
| Modify checkout flow | Commerce Flows | 06-extending |
| Customize the UI | Frontend | - |
| Debug an issue | Testing Guide | - |
| Deploy to production | Production Notes | - |
| Use AI assistant | SKILLS.md | Context for Claude Code, Gemini CLI, Cursor, Codex |
Architecture
System architecture — Chat Client (React + A2A Client) communicates via JSON-RPC to the Cymbal Retail Agent (A2A Server → ADKAgentExecutor → ADK Agent → RetailStore). Discovery endpoints expose agent capabilities and UCP profile.
Quick Reference
Key Files
| File | Purpose |
|---|---|
business_agent/src/business_agent/agent.py | ADK agent + 8 tools |
business_agent/src/business_agent/store.py | Checkout state machine |
business_agent/src/business_agent/agent_executor.py | A2A ↔ ADK bridge |
chat-client/App.tsx | React app + A2A messaging |
Endpoints
| Endpoint | Purpose |
|---|---|
GET /.well-known/agent-card.json | A2A agent discovery |
GET /.well-known/ucp | UCP merchant profile |
POST / | A2A JSON-RPC endpoint |
State Keys
| Key | Purpose |
|---|---|
user:checkout_id | Current checkout session |
__ucp_metadata__ | Negotiated capabilities |
__payment_data__ | Payment instrument |
Deep Dive Guides
| Guide | Topics |
|---|---|
| Glossary | Key terms, acronyms, state keys |
| Architecture | System components, data flow |
| ADK Agent | Tools, callbacks, session management |
| UCP Integration | Capabilities, profiles, negotiation |
| Commerce Flows | Checkout lifecycle, payment |
| Frontend | React components, A2A client |
| Extending | Add tools, products, capabilities |
| Testing Guide | Testing, debugging, troubleshooting |
| Production Notes | Security gaps, deployment checklist |