Quick reference for key terms used throughout this documentation.
- A2A = How agents talk to each other (discovery + messaging)
- UCP = Standard data types for commerce (Checkout, LineItem, Payment)
- ADK = Google's framework for building AI agents
| Term | Definition | Example in This Sample |
|---|
| A2A | Agent-to-Agent Protocol - How AI agents discover and communicate with each other | /.well-known/agent-card.json endpoint |
| UCP | Universal Commerce Protocol - Standard data types for commerce transactions | Checkout, LineItem, PaymentInstrument |
| ADK | Agent Development Kit - Google's framework for building agents with tools | Agent(), ToolContext, Runner |
| Agent | In this sample: the Cymbal Retail Agent service (includes LLM + tools + state) | The backend running on port 10999 |
| Tool | A Python function the LLM can invoke to perform actions | search_shopping_catalog(), add_to_checkout() |
| Capability | A feature set the agent supports, declared in UCP profile | dev.ucp.shopping.checkout |
| Negotiation | Client and merchant agreeing on shared capabilities before transacting | Happens when first message is sent |
| Term | What It Does | Where to Find It |
|---|
| Agent Card | JSON file declaring agent identity and capabilities | /.well-known/agent-card.json |
| UCP Profile | JSON file declaring commerce capabilities and payment handlers | /.well-known/ucp |
| JSON-RPC 2.0 | Message format used for A2A communication | Request/response structure in A2A calls |
| UCP-Agent Header | HTTP header containing client's profile URL | Sent with every A2A request |
State is stored in ADK's session service (in-memory by default).
| Key | Purpose | Lifetime |
|---|
user:checkout_id | Current checkout session ID | Until checkout completed or session expires |
__ucp_metadata__ | Negotiated capabilities from client/merchant profiles | Set once per session |
__payment_data__ | Payment instrument for current checkout | Set during payment flow |
__session_extensions__ | Active A2A extensions for this session | Set once per session |
temp:LATEST_TOOL_RESULT | Temporary storage for last UCP tool response | Cleared after each agent response |
Naming conventions:
user: prefix — User-scoped data (persists across turns)__ prefix — System/internal data (managed by framework)temp: prefix — Temporary data (cleared after use)
The checkout follows a 3-state lifecycle:
Figure 1: Checkout state transitions from incomplete → ready_for_complete → completed
| State | Meaning | What's Needed to Progress |
|---|
incomplete | Missing required info | Add email, address, or items |
ready_for_complete | Ready for payment | User confirms payment |
completed | Order placed successfully | Terminal state - checkout finalized |
| Component | Role | File |
|---|
| Agent | Orchestrates LLM and tools | agent.py |
| Tool | Individual function the LLM can call | Defined in agent.py |
| ToolContext | Provides state access to tools | Passed to each tool function |
| Runner | Executes agent with session management | InMemoryRunner |
| Session | Stores conversation history and state | InMemorySessionService |
| Callback | Hook to modify tool/agent output | after_tool_callback, after_agent_callback |
Figure 2: Vertical stack from Chat Client through A2A Server, Agent Executor, ADK Agent, to RetailStore
| Acronym | Full Name | Context |
|---|
| A2A | Agent-to-Agent | Protocol for agent communication |
| UCP | Universal Commerce Protocol | Commerce data standard |
| ADK | Agent Development Kit | Google's agent framework |
| LLM | Large Language Model | Gemini 3.0 Flash in this sample |
| SDK | Software Development Kit | UCP Python SDK |
Official documentation for the core technologies used in this sample.