Universal-Commerce-Protocol · 0x8000-0000 · Jan 14, 2026 · Jan 11, 2026 · Jan 11, 2026 · Jan 12, 2026
diff --git a/a2a/README.md b/a2a/README.md
@@ -14,66 +14,210 @@
    limitations under the License.
 -->
 
-# Example Business Agent
+# A2A Business Agent with UCP Extension
+
+This sample demonstrates how to build an AI-powered shopping assistant using **[Universal Commerce Protocol (UCP)](https://ucp.dev)** - 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](https://google.github.io/adk-docs/)** (Agent Development Kit) to build the AI agent and **[A2A Protocol](https://google.github.io/A2A/)** (Agent-to-Agent) for agent discovery and communication.
+
+<table>
+<tr><td colspan="2" align="center"><b>Key Features</b></td></tr>
+<tr><td>🛒</td><td><b>UCP Checkout Capability:</b> Implements <code>dev.ucp.shopping.checkout</code> for checkout, line items, totals, and order creation with standardized status lifecycle (<code>incomplete</code> → <code>ready_for_complete</code> → <code>completed</code>).</td></tr>
+<tr><td>📦</td><td><b>UCP Fulfillment Capability:</b> Implements <code>dev.ucp.shopping.fulfillment</code> for shipping address collection, delivery options, and fulfillment method selection.</td></tr>
+<tr><td>💳</td><td><b>UCP Payment Handling:</b> Supports <code>PaymentInstrument</code> types with configurable payment handlers and merchant business configuration via UCP profile.</td></tr>
+<tr><td>🤝</td><td><b>Capability Negotiation:</b> Client and merchant exchange UCP profiles at <code>/.well-known/ucp</code> to agree on supported features before transactions begin.</td></tr>
+<tr><td>🤖</td><td><b>Google ADK Agent:</b> Gemini 2.5 Flash model with 8 shopping tools (search, checkout, payment) demonstrating how to build UCP-aware agents.</td></tr>
+<tr><td>🔗</td><td><b>A2A Protocol:</b> Agent discovery via <code>/.well-known/agent-card.json</code> and JSON-RPC 2.0 communication - showing UCP as an A2A extension.</td></tr>
+<tr><td>💻</td><td><b>React Chat Client:</b> TypeScript UI that renders UCP data types (Checkout, LineItem, PaymentResponse, OrderConfirmation) with proper capability handling.</td></tr>
+</table>
+
+## Demo
+
+<p align="center">
+<b>Complete Shopping Flow</b><br/>
+<i>Product search → Add items to Checkout → Payment → Order confirmation</i>
+<br/><br/>
+<img src="assets/ucp_a2a_demo.gif" alt="UCP A2A Demo" width="800" />
+<br/><br/>
+<a href="https://github.com/user-attachments/assets/8d3d17f5-dbcc-4cc8-91b9-2b7d48b3f2df">▶️ Watch the full demo video</a>
+</p>
+
+## Architecture
+
+<p align="center">
+<b>System Architecture</b><br/>
+<i>How Client, A2A Protocol, Business Agent, and Store interact</i>
+<br/><br/>
+<img src="assets/architecture_diagram.jpeg" alt="Architecture Diagram" width="900" />
+</p>
+
+**Key points:**
+- **Client** sends requests with `UCP-Agent` header containing its profile URL
+- **Business 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:
+
+- [ ] Python 3.13+ with [UV](https://docs.astral.sh/uv/)
+- [ ] Node.js 18+
+- [ ] [Gemini API Key](https://aistudio.google.com/apikey)
+
+### 1. Start the Business Agent
+
+```bash
+cd a2a/business_agent
+uv sync
+cp env.example .env
+```
+
+Edit `.env` and add your `GOOGLE_API_KEY`, then start the agent:
+
+```bash
+uv run business_agent
+```
+
+**Expected output:**
+```
+INFO:     Started server process
+INFO:     Uvicorn running on http://0.0.0.0:10999
+```
+
+This starts the business agent on port 10999. You can verify by accessing:
+- **Agent Card:** http://localhost:10999/.well-known/agent-card.json
+- **UCP Profile:** http://localhost:10999/.well-known/ucp
+
+<details>
+<summary>📸 <b>Server Endpoints (click to expand)</b></summary>
+<br/>
+<table>
+<tr>
+<td width="50%" align="center">
+<b>Agent Card</b><br/><code>/.well-known/agent-card.json</code>
+<br/><br/>
+<img src="assets/agent_card.png" alt="Agent Card" width="400" />
+<br/><i>Declares UCP extension with capabilities</i>
+</td>
+<td width="50%" align="center">
+<b>UCP Profile</b><br/><code>/.well-known/ucp</code>
+<br/><br/>
+<img src="assets/well_known.png" alt="UCP Profile" width="400" />
+<br/><i>Defines supported capabilities & payment handlers</i>
+</td>
+</tr>
+</table>
+</details>
+
+### 2. Start the Chat Client
+
+In a new terminal:
+
+```bash
+cd a2a/chat-client
+npm install
+npm run dev
+```
+
+**Expected output:**
+```
+VITE v5.x.x ready
+➜ Local: http://localhost:3000/
+```
 
-This is an example Business A2A Agent that implements UCP Extension.
-The extension allows the business agent to respond to the client applications
-with UCP defined data types.
+The Chat Client UCP Profile can be found at http://localhost:3000/profile/agent-profile.json
+
+### 3. Try It Out
+
+<table>
+<tr>
+<td width="50%" align="center">
+<img src="assets/ucp_a2a_demo.gif" alt="Demo" width="400" />
+<br/><a href="https://github.com/user-attachments/assets/8d3d17f5-dbcc-4cc8-91b9-2b7d48b3f2df">▶️ Watch full video</a>
+</td>
+<td width="50%" valign="top">
 
-A simple chat client is also provided to interact with the business agent that
-consumes the A2A interface exposed by the business agent.
+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
 
-The example uses a mock inmemory RetailStore to simulate a business store.
+</td>
+</tr>
+</table>
 
-### Pre-requisites:
+## What is UCP?
 
-1. Python 3.13
-2. UV
-3. Gemini API Key (The agent uses Gemini model to generate responses)
+**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.
 
-### Agent Quick Start
+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
 
-1. Clone the UCP Python SDK repository.
+[Learn more about UCP](https://ucp.dev)
+
+## Technology Stack
 
-   `git clone https://github.com/Universal-Commerce-Protocol/python-sdk`
-2. Clone the samples repository.
-3. `cd a2a/business_agent`
-4. Update the `ucp-sdk` dependency to the cloned path in pyproject.toml file.
-5. Run `uv sync`
-6. Update the env.example file with your Gemini API key and rename it to .env
-7. Run `uv run business_agent`
-8. This starts the business agent on port 10999. You can verify by accessing
-the agent card at http://localhost:10999/.well-known/agent-card.json
-9. The business agent's UCP Profile can be found at
-http://localhost:10999/.well-known/ucp
+| Technology | Purpose | Used For |
+|------------|---------|----------|
+| **[Google ADK](https://google.github.io/adk-docs/)** | Agent Framework | AI agent with tools, Gemini LLM integration, session management |
+| **[A2A Protocol](https://a2a-protocol.org/latest/)** | Communication | Agent discovery via Agent Card, JSON-RPC messaging, task management |
+| **[UCP](https://ucp.dev)** | Commerce Standard | Standardized product, checkout, payment, and order data types |
+
+## Components
 
-### Chat Client
+### Business Agent (`business_agent/`)
+
+AI shopping assistant built with Google ADK, exposed via A2A interface with UCP extension.
+
+| File | Purpose |
+|------|---------|
+| `agent.py` | ADK Agent with Gemini 2.5 Flash + 8 shopping tools |
+| `agent_executor.py` | Bridges ADK ↔ A2A protocol |
+| `store.py` | Mock RetailStore (products, checkouts, orders) |
+| `data/ucp.json` | UCP Profile served at `/.well-known/ucp` |
+
+### Chat Client (`chat-client/`)
+
+React UI (TypeScript, Vite, Tailwind) that communicates via A2A and renders UCP data types.
+
+| File | Purpose |
+|------|---------|
+| `App.tsx` | A2A messaging + state management |
+| `components/` | ProductCard, Checkout, PaymentMethodSelector |
+| `profile/agent_profile.json` | Client's UCP capabilities |
 
-**Prerequisites:**  Node.js
+## Mock Store
 
-1. cd chat-client
-2. Install dependencies:
-   `npm install`
-3. Run the app:
-   `npm run dev`
-4. The Chat Client UCP Profile can be found at
-http://localhost:3000/profile/agent-profile.json
+The business agent uses an in-memory `RetailStore` to simulate a real backend:
 
-## Example interaction:
+- **Products** - Loaded from `data/products.json` (cookies, chips, fruits, etc.)
+- **Checkouts** - Session-based checkout management with line items
+- **Orders** - Created when checkout completes successfully
+- **Payments** - Mock processor simulates payment flow
 
-1. Launch the browser and navigate to http://localhost:3000/
-2. In the Chat interface, 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 response.
+Prices are in USD, tax is calculated at 10%, and shipping costs vary by method.
 
-### Disclaimer
+## Related Resources
 
-This is an example implementation for demonstration purposes and is not
-intended for production use.
+- [UCP Specification](https://ucp.dev/specification/overview/)
+- [Google ADK Documentation](https://google.github.io/adk-docs/)
+- [A2A Protocol Specification](https://a2a-protocol.org/latest/specification/)
+- [UCP Python SDK](https://github.com/Universal-Commerce-Protocol/python-sdk)
+
+## Disclaimer
+
+This is an example implementation for demonstration purposes and is not intended for production use.
diff --git a/a2a/assets/agent_card.png b/a2a/assets/agent_card.png
diff --git a/a2a/assets/architecture_diagram.jpeg b/a2a/assets/architecture_diagram.jpeg
diff --git a/a2a/assets/ucp_a2a_demo.gif b/a2a/assets/ucp_a2a_demo.gif
diff --git a/a2a/assets/well_known.png b/a2a/assets/well_known.png
diff --git a/a2a/business_agent/README.md b/a2a/business_agent/README.md
@@ -26,12 +26,8 @@ Example agent implementing A2A Extension for UCP
 
 ## Quick Start
 
-1. Clone the UCP Python SDK repository.
-
-   `git clone https://github.com/Universal-Commerce-Protocol/python-sdk`
-2. Update the `ucp-sdk` dependency to the cloned path in pyproject.toml file.
-3. Run `uv sync`
-4. Update the env.example file with your Gemini API key and rename it to .env
-5. Run `uv run business_agent`
-6. This starts the business agent on port 10999. You can verify by accessing
+1. Run `uv sync`
+2. Copy env.example to .env and update it with relevant Gemini API key.
+3. Run `uv run business_agent`
+4. This starts the business agent on port 10999. You can verify by accessing
 the agent card at http://localhost:10999/.well-known/agent-card.json
diff --git a/a2a/business_agent/pyproject.toml b/a2a/business_agent/pyproject.toml
@@ -9,7 +9,7 @@ dependencies = [
     "google-adk[a2a]>=1.22.0",
     "uvicorn>=0.35.0",
     "httpx>=0.28.1",
-    "ucp-sdk",
+    "ucp-sdk==0.1.0",
 ]
 
 [project.scripts]
@@ -23,6 +23,3 @@ dev = [
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
-
-[tool.uv.sources]
-ucp-sdk = { path = "../../../sdk/python/", editable = true }