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_idCurrent 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_RESULTTemporary 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
incompleteMissing required info
Add email, address, or items
ready_for_completeReady for payment
User confirms payment
completedOrder 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.
ADK (Agent Development Kit) A2A (Agent-to-Agent Protocol) UCP (Universal Commerce Protocol) 
