Skip to content

DEVELOPER_GUIDE.md

Latest commit

 

History

History
83 lines (62 loc) · 4.57 KB

DEVELOPER_GUIDE.md

File metadata and controls

83 lines (62 loc) · 4.57 KB

Cymbal Retail Agent - Developer Guide

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

Cymbal Retail Agent 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