1. Tổng quan
Trong lớp học lập trình này, bạn sẽ chạy một tác nhân ADK đặt vé xem phim của nhiều người bán vé xem phim bằng cách sử dụng 2 giao thức thương mại nguồn mở:
- UCP (Giao thức thương mại toàn cầu): Một tiêu chuẩn để các tác nhân khám phá người bán, tìm kiếm danh mục và quản lý quy trình thanh toán.
- AP2 (Giao thức thanh toán bằng tác nhân): Một giao thức để uỷ quyền thanh toán an toàn, có thể xác minh bằng cách sử dụng các lệnh được ký bằng mật mã.
Ứng dụng minh hoạ CineAgent kết nối với 2 người bán vé xem phim giả lập có các chức năng khác nhau (chọn ghế, định dạng chuyên biệt và phương thức thanh toán) và điều phối toàn bộ quy trình đặt vé từ tìm kiếm đến thanh toán.
Kiến thức bạn sẽ học được
- Cách hoạt động của tính năng khám phá người bán UCP thông qua
/.well-known/ucp - Cách một tác nhân ADK sử dụng UCP để tìm kiếm danh mục và tạo quy trình thanh toán
- Cách các chỉ thị AP2 (CheckoutMandate, PaymentMandate) bảo mật giao dịch
- Cách giao thức UCP và AP2 hai đầu hoạt động để bảo mật hoạt động thương mại điện tử dựa trên tác nhân
Bạn cần có
- Một dự án trên Google Cloud đã bật tính năng thanh toán
- Một trình duyệt web như Chrome
- Python 3.11 trở lên và uv, nếu bạn chạy mã trên máy của mình thay vì Cloud Shell
Lớp học lập trình này dành cho các nhà phát triển có trình độ trung cấp và đã quen thuộc với Python và Google Cloud. Bạn sẽ mất khoảng 30 phút để hoàn thành lớp học lập trình này.
Các tài nguyên được tạo trong lớp học lập trình này sẽ có chi phí dưới 5 USD.
2. Tìm hiểu về giao thức UCP và AP2
Trước khi bắt đầu xây dựng tác nhân, hãy tìm hiểu hai giao thức giúp hoạt động thương mại tác nhân an toàn này trở nên khả thi.
Lớp học lập trình này sử dụng UCP phiên bản 2026-08-25 với UCP Python SDK và AP2 phiên bản 0.2 với AP2 Python SDK.
Giao thức thương mại toàn cầu (UCP)
UCP chuẩn hoá cách các tác nhân AI tương tác với người bán. Mô hình này giải quyết vấn đề về việc các tác nhân phải tìm hiểu API tuỳ chỉnh cho từng cửa hàng bằng cách giới thiệu một mô hình tài nguyên được chuẩn hoá.
Cách hoạt động:
- Khám phá: Mọi người bán tuân thủ UCP đều hiển thị một hồ sơ tại một vị trí tiêu chuẩn:
/.well-known/ucp. Ví dụ: điểm cuối UCP của Everlane.Khi một tác nhân đọc hồ sơ này, tác nhân sẽ tìm kiếm:- Khả năng: Các tính năng cốt lõi độc lập mà doanh nghiệp hỗ trợ, chẳng hạn như tìm kiếm trong danh mục hoặc thanh toán.
- Dịch vụ: Các lớp giao tiếp cấp thấp được dùng để trao đổi dữ liệu. Ví dụ: API REST, MCP (Giao thức ngữ cảnh mô hình), A2A (Giao thức Agent2Agent).
- Tiện ích: Nếu cần hành vi chuyên biệt, người bán có thể xác định Tiện ích tuỳ chỉnh trong hồ sơ này.
- Khoá: Khoá ký công khai của người bán mà các tác nhân dùng để kiểm tra chữ ký của người bán.
- Thao tác: Sau khi phát hiện, tác nhân sẽ sử dụng điểm cuối dịch vụ được cung cấp để thực hiện các thao tác. Trong lớp học lập trình này, chúng ta sẽ sử dụng Giao thức ngữ cảnh mô hình (MCP) làm phương thức truyền tải dịch vụ. Tác nhân thực hiện các lệnh gọi JSON-RPC 2.0 đến điểm cuối này để gọi các chức năng đã phát hiện: tìm kiếm sản phẩm, tạo quy trình thanh toán và hoàn tất giao dịch mua.

Giao thức thanh toán bằng tác nhân (AP2)
AP2 chuẩn hoá cách các nhân viên uỷ quyền thanh toán thay mặt người dùng. Giải pháp này giải quyết vấn đề bảo mật khi nhân viên xử lý thông tin xác thực thanh toán nhạy cảm.
Cách hoạt động:
- Chữ ký của người bán: Khi một tác nhân tạo quy trình thanh toán bằng Giao thức UCP, người bán sẽ ký vào quy trình thanh toán (mục hàng và tổng số tiền) rồi trả về chữ ký trong
ap2.merchant_authorization. Tính năng này hoạt động như một cam kết giữ giá. Nếu người bán thay đổi giá sau khi ký, chữ ký sẽ không còn khớp nữa. - Lệnh uỷ quyền thanh toán và Lệnh uỷ quyền thanh toán: Sau khi xác minh nội dung của quy trình thanh toán, người dùng (hoặc tác nhân thay mặt người dùng) sẽ ký hai lệnh uỷ quyền.
CheckoutMandatechứa quy trình thanh toán do người bán ký và cho người bán biết rằng người dùng đã phê duyệt quy trình này.PaymentMandatesẽ uỷ quyền thanh toán số tiền cho lượt thanh toán đó. Cả hai đều tham chiếu đến một hàm băm của quy trình thanh toán đã ký và mang theo chữ ký mật mã của người dùng. - Xác minh chữ ký: Người bán nhận được cả hai uỷ quyền. Thư viện này xác minh chữ ký của người dùng trên
CheckoutMandatevà kiểm tra để đảm bảo rằng quy trình thanh toán bên trong đó có chữ ký riêng của người bán.PaymentMandatesẽ chuyển đến bên thanh toán (nhà cung cấp thông tin đăng nhập hoặc đơn vị xử lý thanh toán), bên này sẽ xác minh trước khi chuyển tiền. Nếu mọi thứ đều hợp lệ, giao dịch sẽ diễn ra.
Hệ thống "khoá kép" này đảm bảo rằng người bán không thể tính phí quá mức và nhân viên không thể chi tiêu mà không được phép. Uỷ quyền là thông tin xác thực SD-JWT (JWT công bố có chọn lọc), giúp bảo vệ quyền riêng tư của người dùng bằng cách chỉ tiết lộ những trường mà mỗi bên cần. Trong AP2 phiên bản 0.2, CheckoutMandate sẽ thay thế CartMandate trong AP2 phiên bản 0.1.

3. Thiết lập môi trường
Thiết lập dự án trên Google Cloud
Tạo một dự án trên Google Cloud
- Trong Google Cloud Console, trên trang chọn dự án, hãy chọn hoặc tạo một dự án trên đám mây của Google Cloud.
- Đảm bảo bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trên một dự án hay không.
Khởi động Cloud Shell
Cloud Shell là một môi trường dòng lệnh chạy trong Google Cloud và được tải sẵn các công cụ cần thiết.
- Nhấp vào Kích hoạt Cloud Shell ở đầu Cloud Console.
- Sau khi kết nối với Cloud Shell, hãy xác minh thông tin xác thực của bạn:
gcloud auth list - Xác nhận rằng dự án của bạn đã được định cấu hình:
gcloud config get project - Nếu dự án của bạn không được thiết lập như mong đợi, hãy thiết lập dự án:
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
Bật API
Chạy lệnh sau để bật các API cần thiết:
gcloud services enable aiplatform.googleapis.com
Thiết lập cấu trúc thư mục
Sao chép và dán các lệnh sau để tạo một thư mục cho lớp học lập trình này, với một thư mục agent_payments bên trong cho mã của tác nhân:
mkdir -p ~/adk-agent-commerce/agent_payments
cd ~/adk-agent-commerce
Truy cập các mô hình Gemini
Sao chép và dán lệnh sau để tạo agent_payments/.env bằng dự án trên đám mây và vị trí của bạn, đồng thời để ADK gọi Gemini thông qua dự án Google Cloud của bạn. Tác nhân Cine sử dụng Gemini để quyết định nên gọi công cụ nào. ADK sẽ tự động tải tệp này, vì vậy, các chế độ cài đặt cũng hoạt động trong các thiết bị đầu cuối mới.
cat > ~/adk-agent-commerce/agent_payments/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_ENTERPRISE=True
EOF
Cài đặt các phần phụ thuộc
Google Cloud Shell được cài đặt sẵn uv để quản lý môi trường và các phần phụ thuộc.
- Tạo tệp
pyproject.tomlở thư mục gốc của thư mụcadk-agent-commercerồi thêm nội dung sau vào tệp đó. Tệp này xác định siêu dữ liệu và các phần phụ thuộc của dự án.
[project]
name = "agent-payments-demo"
version = "0.1.0"
description = "CineAgent booking agent using UCP and AP2"
requires-python = ">=3.11"
dependencies = [
"google-adk",
"fastapi",
"uvicorn",
"httpx",
"ucp-sdk",
"ap2 @ git+https://github.com/google-agentic-commerce/AP2.git@main",
]
AP2 SDK cài đặt từ kho lưu trữ GitHub vì chưa được xuất bản trên PyPI. (Gói ap2 trên PyPI là một dự án không liên quan.)
- Chạy lệnh sau để tạo môi trường ảo và cài đặt tất cả các phần phụ thuộc:
uv sync
uv tạo một môi trường Python riêng biệt cho lớp học lập trình này, vì vậy bạn không cần kích hoạt bất cứ thứ gì. Thêm tiền tố uv run vào các lệnh Python.
4. Xác định nhân viên hỗ trợ
Trước khi viết bất kỳ logic nào cho công cụ, hãy xác định chính tác nhân trong một tệp có tên là agent.py. Tác nhân này sẽ đóng vai trò là công cụ điều phối cho quy trình đặt vé xem phim.
Tạo agent_payments/agent.py:
"""CineAgent — movie ticket booking agent using UCP and AP2."""
from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from google.adk.tools import FunctionTool
from agent_payments.tools import (
discover_theaters,
search_movies,
get_movie_detail,
create_checkout,
complete_purchase,
)
root_agent = Agent(
model=Gemini(
model="gemini-3.8-flash",
retry_options=types.HttpRetryOptions(attempts=5),
),
name="cineagent",
description="Movie ticket booking agent using UCP and AP2.",
instruction="""You are CineAgent, a movie ticket booking assistant.
You help users find and book movie tickets across multiple theaters
using UCP (Universal Commerce Protocol) and AP2 (Agent Payments).
**Your tools:**
- discover_theaters: Find theaters and what they support
- search_movies: Search movies across all theaters
- get_movie_detail: Get showtimes at a specific theater
- create_checkout: Start a checkout session
- complete_purchase: Finalize with AP2 mandate signing
**Rules:**
- Always call discover_theaters first if you haven't yet
- Keep responses concise — summarize and suggest next steps
- Prices from tools are in cents (1500 = $15.00)
- Never invent data — only state what tools return
""",
tools=[
discover_theaters,
search_movies,
get_movie_detail,
create_checkout,
FunctionTool(complete_purchase, require_confirmation=True),
],
)
Giải thích mã
Hãy phân tích những gì đang diễn ra trong định nghĩa tác nhân này:
model=Gemini(...): Chúng tôi đang sử dụng Gemini 3.8 Flash để suy luận và sử dụng công cụ.instruction: Đây là câu lệnh hướng dẫn hành vi của trợ lý. Tệp này hướng dẫn rõ ràng cho trợ lý ảo cách sử dụng UCP và AP2, liệt kê các công cụ có sẵn và đặt các quy tắc quan trọng như "Không bao giờ bịa dữ liệu" và "Giá tính bằng xu".tools: Đây là danh sách các hàm Python (mà chúng ta sẽ tạo tiếp theo) mà tác nhân có thể chọn gọi dựa trên yêu cầu của người dùng.require_confirmation: Bạn có thể bao bọc mọi công cụ bằngFunctionTool(my_function,require_confirmation=True). Khi được kích hoạt, tác nhân sẽ tạm dừng và chờ bạn phê duyệt bằng cách trả lời "có" hoặc "không" trước khi thực thi công cụ. Tại đây, trước khi thực thi công cụcomplete_purchase, tác nhân sẽ tạm dừng để chờ người dùng xác nhận.
Danh sách công cụ
Định nghĩa tác nhân khai báo những gì chúng ta cần xây dựng. Mỗi công cụ liên kết với một thao tác cụ thể trong giao thức UCP hoặc AP2:
Công cụ | Ý nghĩa | Hành động theo giao thức |
| Tìm người bán và khả năng của họ | Cụm từ tìm kiếm |
| Tìm kiếm danh mục của nhiều người bán | JSON-RPC đến điểm cuối MCP |
| Xem lịch chiếu tại một người bán cụ thể | JSON-RPC đến điểm cuối MCP |
| Bắt đầu một phiên thanh toán | JSON-RPC đến điểm cuối MCP |
| Uỷ quyền thanh toán và hoàn tất đơn đặt hàng | Ký AP2 Mandates và gửi đến MCP |
Mô hình Gemini sẽ quyết định thời điểm gọi từng công cụ dựa trên cuộc trò chuyện. Công việc tiếp theo của chúng ta là triển khai chức năng của từng công cụ trong tools.py.
5. Xây dựng các công cụ cho trợ lý ảo: Khám phá và duyệt web
Bây giờ, hãy triển khai các công cụ mà tác nhân sẽ dùng để duyệt xem và khám phá phim. Mỗi công cụ sẽ bao bọc một thao tác UCP.
Tạo một tệp mới có tên là agent_payments/tools.py rồi sao chép và dán đoạn mã sau:
"""Agent tools — each one wraps a UCP or AP2 operation."""
import json
from .ucp_client import UCPClient
from .ap2_handler import AP2Handler
# Initialize clients directly
_merchant_urls = ["http://localhost:8081", "http://localhost:8082"]
_ap2 = AP2Handler()
_ucp = UCPClient(platform_keys=[_ap2.public_key])
Tìm hiểu về chế độ thiết lập
Để lớp học lập trình này tập trung vào việc xây dựng tác nhân, chúng ta sẽ sử dụng 2 lớp trợ giúp là UCPClient và AP2Handler. Chúng ta sẽ xem xét các lớp này trong một bước sau.
- Quảng cáo khi mở ứng dụng là gì?: Đây là các lớp trợ giúp nhỏ mà chúng tôi đã viết cho lớp học lập trình này để trao đổi với các người bán mô phỏng. Các SDK chính thức cung cấp các phần giao thức: UCP SDK có các mô hình dữ liệu cho mọi giản đồ UCP và AP2 SDK tạo và xác minh các uỷ quyền đã ký. Không có SDK nào bao gồm một ứng dụng khách để gọi người bán, vì vậy, các trình trợ giúp này sẽ xử lý phần đó.
- Hiện tại, hãy coi chúng là các đối tượng trợ giúp:
_ucp.discover(url): Tìm nạp và xác thực hồ sơ của người bán._ucp.mcp_call(url, method, params): Gửi yêu cầu JSON-RPC 2.0 đến điểm cuối MCP của người bán.
Khám phá các rạp chiếu phim
Công cụ này là bước đầu tiên trong quy trình UCP. Thư viện này tìm thấy những người bán hiện có và những người bán hỗ trợ.
Thêm vào tools.py:
async def discover_theaters() -> str:
"""Discover available theater merchants and their capabilities via UCP."""
theaters = []
for url in _merchant_urls:
info = await _ucp.discover(url)
theaters.append(
{
"url": url,
"name": info["name"],
"capabilities": info["capabilities"],
"payment_handlers": info["payment_handlers"],
}
)
return json.dumps(theaters, indent=2)
Chức năng của chế độ này:
- Thao tác này lặp lại danh sách URL của người bán do máy chủ cung cấp. Trong lớp học lập trình này, chúng ta sẽ thiết lập 2 người bán mô phỏng ở phần sau.
- Đối với mỗi URL, nó sẽ gọi
_ucp.discover(url), chạm vào điểm cuối/.well-known/ucp. - API này thu thập tên, chức năng và trình xử lý thanh toán vào một danh sách tóm tắt.
- Thao tác này trả về danh sách dưới dạng chuỗi JSON để tác nhân đọc.
Tìm kiếm Phim
Công cụ này tìm kiếm trên tất cả người bán được phát hiện và hợp nhất kết quả. Điều này rất quan trọng vì cùng một bộ phim có thể đang chiếu ở nhiều rạp với nhiều định dạng (IMAX, Dolby) và mức giá khác nhau.
Thêm vào tools.py:
async def search_movies(query: str = "") -> str:
"""Search for movies across all theaters. Use '' to browse all."""
all_movies = {}
for url, merchant in _ucp.merchants.items():
result = await _ucp.mcp_call(
url, "search_catalog", {"catalog": {"query": query}}
)
for product in result.get("products", []):
mid = product["id"]
if mid not in all_movies:
all_movies[mid] = {
"id": mid,
"title": product["title"],
"categories": [
c["value"] for c in product.get("categories", [])
],
"theaters": {},
}
showtimes = []
for v in product.get("variants", []):
opts = {o["name"]: o["label"] for o in v.get("options", [])}
showtimes.append(
{
"id": v["id"],
"format": opts.get("format", "Standard"),
"time": opts.get("time", ""),
"price": v.get("price", {}),
"seats": v.get("metadata", {}).get(
"seats_available", 0
),
}
)
all_movies[mid]["theaters"][url] = {
"name": merchant["name"],
"showtimes": showtimes,
}
return json.dumps(list(all_movies.values()), indent=2)
Chức năng của chế độ này:
- Thao tác này sẽ lặp lại tất cả các rạp chiếu phim đã được phát hiện.
- Thao tác này sẽ gửi yêu cầu JSON-RPC danh mục tìm kiếm (
_ucp.mcp_call(url, "search_catalog", {"catalog": {"query": query}})) đến điểm cuối MCP của người bán. - Sau đó, ứng dụng sẽ dọn dẹp một chút để phân tích kết quả nhằm tìm phim và "biến thể" của phim (biến thể này thể hiện các suất chiếu và định dạng cụ thể). Nhóm các bộ phim theo mã nhận dạng để người dùng không thấy các mục phim trùng lặp.
Lấy thông tin chi tiết về phim
Công cụ này lấy thông tin chi tiết đầy đủ về danh mục cho một bộ phim cụ thể tại một rạp chiếu phim cụ thể.
Thêm vào tools.py:
async def get_movie_detail(movie_id: str, merchant_url: str) -> str:
"""Get detailed showtimes for a movie at a specific theater."""
result = await _ucp.mcp_call(
merchant_url, "lookup_catalog", {"catalog": {"ids": [movie_id]}}
)
return json.dumps(result, indent=2)
Chức năng của chế độ này:
- Thao tác này gọi phương thức
lookup_catalogtrên điểm cuối MCP của người bán, truyềnmovie_idcụ thể vàocatalog.ids. Thao tác này sẽ trả về thông tin chi tiết như giờ chiếu và tình trạng còn ghế của rạp chiếu phim cụ thể đó.
6. Xây dựng các công cụ dựa trên tác nhân: Thanh toán
Những công cụ này xử lý quy trình thanh toán và quy trình mua. Đây là nơi giao thức AP2 phát huy tác dụng để đảm bảo các giao dịch an toàn.
Tạo quy trình thanh toán
Công cụ này bắt đầu một phiên thanh toán tại một rạp chiếu phim cụ thể vào một giờ chiếu cụ thể.
Thêm vào tools.py:
async def create_checkout(
merchant_url: str, showtime_id: str, quantity: int = 1
) -> str:
"""Create a checkout session for tickets at a theater."""
result = await _ucp.mcp_call(merchant_url, "create_checkout", {
"checkout": {
"line_items": [
{"item": {"id": showtime_id}, "quantity": quantity}
],
"context": {"address_country": "US", "currency": "USD"},
}
})
return json.dumps(result, indent=2)
Chức năng của chế độ này:
- Thao tác này sẽ gọi phương thức
create_checkouttrên điểm cuối MCP của người bán. - Nó sẽ truyền
showtime_idvàquantitymà người dùng yêu cầu. - Nhà bán hàng trả về một quy trình thanh toán được ký bằng khoá của nhà bán hàng.
Lưu ý: Nếu bạn kiểm tra dữ liệu phản hồi, trường ap2.merchant_authorization sẽ chứa chữ ký mật mã của người bán đối với quy trình thanh toán, khoá giá được báo giá. Họ không thể thay đổi thông tin này sau khi nhập!
Hoàn tất giao dịch mua
Công cụ này sẽ thực hiện 3 việc sau:
- Chúng tôi nhận được yêu cầu thanh toán và xác minh chữ ký của người bán trên yêu cầu đó.
- Tạo và ký CheckoutMandate và PaymentMandate bằng AP2 SDK.
- Gửi cả hai uỷ quyền này cho người bán để hoàn tất giao dịch mua.
Thêm vào tools.py:
async def complete_purchase(checkout_id: str, merchant_url: str) -> str:
"""Complete purchase with AP2 payment authorization."""
merchant = _ucp.merchants[merchant_url]
# 1. Get the checkout and verify the merchant's signature on it
checkout = await _ucp.mcp_call(
merchant_url, "get_checkout", {"id": checkout_id}
)
checkout_jwt = _ap2.verify_merchant_authorization(checkout, merchant["keys"])
if not checkout_jwt:
return json.dumps({"error": "Merchant signature is missing or invalid"})
# 2. Create and sign the CheckoutMandate and PaymentMandate
# In production, this step asks the user to approve on a trusted device
# (biometric or device auth). In this demo, the agent signs with a local key.
checkout_mandate, payment_mandate = _ap2.create_mandates(
checkout, checkout_jwt, merchant["name"]
)
# 3. Send both mandates to the merchant to complete the purchase
result = await _ucp.mcp_call(merchant_url, "complete_checkout", {
"id": checkout_id,
"checkout": {
"payment": {
"instruments": [{
"id": "instr_1",
"handler_id": merchant["payment_handlers"][0],
"type": "card",
"selected": True,
"credential": {
"type": "ap2_payment_mandate",
"token": payment_mandate,
},
}],
},
"ap2": {"checkout_mandate": checkout_mandate},
},
})
return json.dumps(result, indent=2)
Tại sao có hai yêu cầu? CheckoutMandate chứng minh cho người bán rằng người dùng đã phê duyệt chính xác quy trình thanh toán này, ở mức giá mà người bán đã ký. PaymentMandate chứng minh cho bên thanh toán rằng người dùng đã uỷ quyền cho khoản phí này. Quy trình này như sau:
Merchant signs checkout -> User signs mandates -> Merchant and payment side verify -> Order completes.
Điểm kiểm tra: Đầy đủ tools.py
Giờ đây, tools.py hoàn chỉnh của bạn sẽ có 5 hàm công cụ và quá trình khởi tạo cấp mô-đun cho các ứng dụng UCP và AP2. Hãy xác minh rằng ứng dụng có dạng như sau:
"""Agent tools — each one wraps a UCP or AP2 operation."""
import json
from .ucp_client import UCPClient
from .ap2_handler import AP2Handler
# Initialize clients directly
_merchant_urls = ["http://localhost:8081", "http://localhost:8082"]
_ap2 = AP2Handler()
_ucp = UCPClient(platform_keys=[_ap2.public_key])
async def discover_theaters() -> str:
"""Discover available theater merchants and their capabilities via UCP."""
theaters = []
for url in _merchant_urls:
info = await _ucp.discover(url)
theaters.append(
{
"url": url,
"name": info["name"],
"capabilities": info["capabilities"],
"payment_handlers": info["payment_handlers"],
}
)
return json.dumps(theaters, indent=2)
async def search_movies(query: str = "") -> str:
"""Search for movies across all theaters. Use '' to browse all."""
all_movies = {}
for url, merchant in _ucp.merchants.items():
result = await _ucp.mcp_call(
url, "search_catalog", {"catalog": {"query": query}}
)
for product in result.get("products", []):
mid = product["id"]
if mid not in all_movies:
all_movies[mid] = {
"id": mid,
"title": product["title"],
"categories": [
c["value"] for c in product.get("categories", [])
],
"theaters": {},
}
showtimes = []
for v in product.get("variants", []):
opts = {o["name"]: o["label"] for o in v.get("options", [])}
showtimes.append(
{
"id": v["id"],
"format": opts.get("format", "Standard"),
"time": opts.get("time", ""),
"price": v.get("price", {}),
"seats": v.get("metadata", {}).get(
"seats_available", 0
),
}
)
all_movies[mid]["theaters"][url] = {
"name": merchant["name"],
"showtimes": showtimes,
}
return json.dumps(list(all_movies.values()), indent=2)
async def get_movie_detail(movie_id: str, merchant_url: str) -> str:
"""Get detailed showtimes for a movie at a specific theater."""
result = await _ucp.mcp_call(
merchant_url, "lookup_catalog", {"catalog": {"ids": [movie_id]}}
)
return json.dumps(result, indent=2)
async def create_checkout(
merchant_url: str, showtime_id: str, quantity: int = 1
) -> str:
"""Create a checkout session for tickets at a theater."""
result = await _ucp.mcp_call(merchant_url, "create_checkout", {
"checkout": {
"line_items": [
{"item": {"id": showtime_id}, "quantity": quantity}
],
"context": {"address_country": "US", "currency": "USD"},
}
})
return json.dumps(result, indent=2)
async def complete_purchase(checkout_id: str, merchant_url: str) -> str:
"""Complete purchase with AP2 payment authorization."""
merchant = _ucp.merchants[merchant_url]
# 1. Get the checkout and verify the merchant's signature on it
checkout = await _ucp.mcp_call(
merchant_url, "get_checkout", {"id": checkout_id}
)
checkout_jwt = _ap2.verify_merchant_authorization(checkout, merchant["keys"])
if not checkout_jwt:
return json.dumps({"error": "Merchant signature is missing or invalid"})
# 2. Create and sign the CheckoutMandate and PaymentMandate
# In production, this step asks the user to approve on a trusted device
# (biometric or device auth). In this demo, the agent signs with a local key.
checkout_mandate, payment_mandate = _ap2.create_mandates(
checkout, checkout_jwt, merchant["name"]
)
# 3. Send both mandates to the merchant to complete the purchase
result = await _ucp.mcp_call(merchant_url, "complete_checkout", {
"id": checkout_id,
"checkout": {
"payment": {
"instruments": [{
"id": "instr_1",
"handler_id": merchant["payment_handlers"][0],
"type": "card",
"selected": True,
"credential": {
"type": "ap2_payment_mandate",
"token": payment_mandate,
},
}],
},
"ap2": {"checkout_mandate": checkout_mandate},
},
})
return json.dumps(result, indent=2)
7. Đảm bảo có thể chạy
Với người bán UCP thực tế, bạn chỉ cần gửi cho nhân viên hỗ trợ URL của họ là xong. Trong lớp học lập trình này, chúng ta cần 2 thứ để kiểm thử cục bộ:
- Người bán mô phỏng: các máy chủ cục bộ mô phỏng điểm cuối UCP để bạn có thể kiểm thử
- Trợ giúp giao thức: trình bao bọc mỏng gọi người bán qua HTTP và sử dụng UCP cũng như AP2 SDK cho dữ liệu và chữ ký giao thức
Lưu ý: Bạn không cần đọc kỹ mã này. Các tệp này mô phỏng nhà bán hàng thực tế và ví của người dùng. Sao chép nguyên trạng.
Trợ giúp giao thức
UCP SDK cung cấp các mô hình dữ liệu, còn AP2 SDK ký và xác minh các lệnh, nhưng không có SDK nào bao gồm một ứng dụng khách để giao tiếp với người bán. Hai tệp này sẽ bổ sung cho khoảng trống đó. Chúng có tên là ucp_client.py và ap2_handler.py để không che khuất gói ap2.
Tạo agent_payments/ucp_client.py:
"""UCP client: discovers merchants and calls their MCP tools."""
import uuid
import httpx
from ucp_sdk.models.schemas.profile import BusinessSchema
# The platform (this agent) identifies itself with a UCP profile URL
PLATFORM_PROFILE = "https://cineagent.example/.well-known/ucp"
class UCPClient:
def __init__(self, platform_keys: list[dict]):
self.client = httpx.AsyncClient(timeout=30)
self.platform_keys = platform_keys
self.merchants = {} # url -> merchant info dict
async def discover(self, merchant_url: str) -> dict:
"""Fetch and validate a merchant's UCP profile from /.well-known/ucp."""
resp = await self.client.get(f"{merchant_url}/.well-known/ucp")
resp.raise_for_status()
profile = BusinessSchema.model_validate(resp.json())
ucp = profile.ucp
info = {
"name": merchant_url.split("//")[-1],
"mcp_endpoint": str(ucp.services["dev.ucp.shopping"][0].endpoint),
"capabilities": list(ucp.capabilities or {}),
"payment_handlers": [
h.id for handlers in ucp.payment_handlers.values() for h in handlers
],
"keys": [k.model_dump(exclude_none=True) for k in profile.keys or []],
}
self.merchants[merchant_url] = info
return info
async def mcp_call(
self, merchant_url: str, tool_name: str, arguments: dict
) -> dict:
"""Call a merchant's MCP tool via JSON-RPC 2.0."""
merchant = self.merchants[merchant_url]
meta = {
"ucp-agent": {
"profile": PLATFORM_PROFILE,
# Mock shortcut: a real merchant reads the platform's public
# keys from the profile URL above instead
"keys": self.platform_keys,
},
"idempotency-key": str(uuid.uuid4()),
}
resp = await self.client.post(
merchant["mcp_endpoint"],
json={
"jsonrpc": "2.0",
"id": uuid.uuid4().hex,
"method": "tools/call",
"params": {
"name": tool_name,
"arguments": {"meta": meta, **arguments},
},
},
)
resp.raise_for_status()
data = resp.json()
if "error" in data:
raise Exception(f"MCP error: {data['error']}")
return data["result"]["structuredContent"]
async def close(self):
await self.client.aclose()
Tạo agent_payments/ap2_handler.py:
"""AP2 mandate handler: verifies the merchant's signature and signs mandates."""
import json
import time
from jwcrypto.jwk import JWK
from jwcrypto.jws import JWS
from ap2.sdk.mandate import MandateClient
from ap2.sdk.utils import b64url_decode, b64url_encode, compute_sha256_b64url
from ap2.sdk.generated.checkout_mandate import CheckoutMandate
from ap2.sdk.generated.payment_mandate import PaymentMandate
from ap2.sdk.generated.types.amount import Amount
from ap2.sdk.generated.types.merchant import Merchant
from ap2.sdk.generated.types.payment_instrument import PaymentInstrument
class AP2Handler:
def __init__(self):
# The user's signing key. In production, this key stays in a wallet or
# on a trusted device, and the user approves each signature.
self.key = JWK.generate(kty="EC", crv="P-256", kid="cineagent-user-key")
self.public_key = json.loads(self.key.export_public())
self.mandates = MandateClient()
def verify_merchant_authorization(
self, checkout: dict, merchant_keys: list[dict]
) -> str | None:
"""Check the merchant's signature on a checkout.
The signature is the merchant's price guarantee: if anything in the
checkout changes, the signature no longer matches. Returns the signed
checkout as a JWT, or None if the signature is missing or invalid.
"""
signature = checkout.get("ap2", {}).get("merchant_authorization")
if not signature:
return None
header, _, sig = signature.split(".") # detached JWS: header..signature
payload = {k: v for k, v in checkout.items() if k != "ap2"}
canonical = json.dumps(
payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False
)
checkout_jwt = f"{header}.{b64url_encode(canonical.encode())}.{sig}"
kid = json.loads(b64url_decode(header))["kid"]
key = next((k for k in merchant_keys if k["kid"] == kid), None)
if not key:
return None
try:
jws = JWS()
jws.deserialize(checkout_jwt)
jws.verify(JWK(**key))
except Exception:
return None
return checkout_jwt
def create_mandates(
self, checkout: dict, checkout_jwt: str, merchant_name: str
) -> tuple[str, str]:
"""Create and sign a CheckoutMandate and a PaymentMandate.
Both mandates reference the hash of the merchant-signed checkout, so
the user's approval is bound to exactly this cart and price.
"""
checkout_hash = compute_sha256_b64url(checkout_jwt)
total = next(t["amount"] for t in checkout["totals"] if t["type"] == "total")
now = int(time.time())
checkout_mandate = CheckoutMandate(
checkout_jwt=checkout_jwt,
checkout_hash=checkout_hash,
iat=now,
exp=now + 600,
)
payment_mandate = PaymentMandate(
transaction_id=checkout_hash,
payee=Merchant(id=merchant_name, name=merchant_name),
payment_amount=Amount(amount=total, currency=checkout["currency"]),
payment_instrument=PaymentInstrument(
id="instr_1", type="card", description="Demo card"
),
iat=now,
exp=now + 600,
)
# Sign each mandate as an SD-JWT with the user's key
return (
self.mandates.create(payloads=[checkout_mandate], issuer_key=self.key),
self.mandates.create(payloads=[payment_mandate], issuer_key=self.key),
)
Nhà bán hàng mô phỏng
Tạo agent_payments/merchants.py:
"""Mock UCP merchant servers: two theaters with different capabilities."""
import json
import time
import uuid
import multiprocessing
from datetime import datetime, timezone, timedelta
import uvicorn
from fastapi import FastAPI
from jwcrypto.jwk import JWK
from jwcrypto.jws import JWS
from ap2.sdk.mandate import MandateClient
from ap2.sdk.utils import compute_sha256_b64url
from ap2.sdk.generated.checkout_mandate import CheckoutMandate
from ap2.sdk.generated.payment_mandate import PaymentMandate
from ucp_sdk.models.schemas.common.payment_ap2_mandate import Checkout
from ucp_sdk.models.schemas.profile import BusinessSchema
from ucp_sdk.models.schemas.shopping.catalog_lookup import LookupResponse
from ucp_sdk.models.schemas.shopping.catalog_search import SearchResponse
UCP_VERSION = "2026-08-25"
UCP_SPEC = f"https://ucp.dev/{UCP_VERSION}"
# ── Theater data ────────────────────────────────────────────
THEATERS = {
8081: {
"name": "Meridian Cinemas",
"movies": [
{
"id": "opp",
"title": "Oppenheimer",
"categories": ["Drama", "History"],
"showtimes": [
{"id": "st_opp_7pm_imax", "format": "IMAX", "time": "7:00 PM", "price": 2200, "seats": 45},
{"id": "st_opp_930pm", "format": "Standard", "time": "9:30 PM", "price": 1500, "seats": 80},
],
},
{
"id": "dune3",
"title": "Dune: Part Three",
"categories": ["Sci-Fi", "Action"],
"showtimes": [
{"id": "st_dune_8pm_imax", "format": "IMAX", "time": "8:00 PM", "price": 2200, "seats": 30},
],
},
],
},
8082: {
"name": "StarLight Theaters",
"movies": [
{
"id": "opp",
"title": "Oppenheimer",
"categories": ["Drama", "History"],
"showtimes": [
{"id": "st_opp_6pm_atmos", "format": "Dolby Atmos", "time": "6:00 PM", "price": 1800, "seats": 60},
],
},
{
"id": "spider",
"title": "Spider-Verse",
"categories": ["Animation", "Action"],
"showtimes": [
{"id": "st_spider_4pm", "format": "Standard", "time": "4:00 PM", "price": 1200, "seats": 100},
],
},
],
},
}
def create_app(port):
theater = THEATERS[port]
app = FastAPI()
sessions = {}
checkout_jwts = {} # checkout id -> merchant-signed checkout JWT
# The merchant's signing key. Its public half is published in the profile.
key = JWK.generate(kty="EC", crv="P-256", kid=f"merchant-{port}")
def _capability(name, path, schema, **extra):
return {name: [{
"version": UCP_VERSION,
"spec": f"{UCP_SPEC}/specification/{path}",
"schema": f"{UCP_SPEC}/schemas/{schema}",
**extra,
}]}
payment_handlers = {
"com.example.card": [
{"id": f"card_{port}", "version": UCP_VERSION,
"available_instruments": [{"type": "card"}], "config": {}}
]
}
# ── UCP Discovery endpoint ──────────────────────────────
@app.get("/.well-known/ucp")
def discovery():
profile = {
"ucp": {
"version": UCP_VERSION,
"services": {
"dev.ucp.shopping": [
{"version": UCP_VERSION,
"spec": f"{UCP_SPEC}/specification/overview",
"transport": "mcp",
"schema": f"{UCP_SPEC}/services/shopping/mcp.openrpc.json",
"endpoint": f"http://localhost:{port}/mcp"}
]
},
"capabilities": {
**_capability("dev.ucp.shopping.catalog.search",
"shopping/catalog/search", "shopping/catalog_search.json"),
**_capability("dev.ucp.shopping.catalog.lookup",
"shopping/catalog/lookup", "shopping/catalog_lookup.json"),
**_capability("dev.ucp.shopping.checkout",
"shopping/checkout", "shopping/checkout.json"),
**_capability("dev.ucp.common.payment.ap2_mandate",
"payment/extensions/ap2-mandates",
"common/payment_ap2_mandate.json",
extends="dev.ucp.shopping.checkout",
config={"vp_formats_supported": {"dc+sd-jwt": {}}}),
},
"payment_handlers": payment_handlers,
},
"keys": [json.loads(key.export_public())],
}
# Check the profile against the UCP SDK models before returning it
BusinessSchema.model_validate(profile)
return profile
# ── MCP JSON-RPC endpoint ───────────────────────────────
@app.post("/mcp")
def mcp(body: dict):
tool = body["params"]["name"]
args = body["params"].get("arguments", {})
rid = body.get("id", "1")
if tool == "search_catalog":
q = args.get("catalog", {}).get("query", "").lower()
hits = [m for m in theater["movies"]
if not q or q in m["title"].lower()
or any(q in c.lower() for c in m["categories"])]
result = {"ucp": _ucp_meta("dev.ucp.shopping.catalog.search"),
"products": [_product(m) for m in hits]}
return _ok(rid, SearchResponse, result)
if tool == "lookup_catalog":
ids = args.get("catalog", {}).get("ids", [])
movies = [m for m in theater["movies"] if m["id"] in ids]
if not movies:
return _err(rid, "Not found")
result = {"ucp": _ucp_meta("dev.ucp.shopping.catalog.lookup"),
"products": [_product(m, lookup=True) for m in movies]}
return _ok(rid, LookupResponse, result)
if tool == "create_checkout":
co = args.get("checkout", {})
sid = f"chk_{uuid.uuid4().hex[:12]}"
items, subtotal = [], 0
for li in co.get("line_items", []):
st = _find_showtime(li["item"]["id"])
if not st:
continue
mv = _find_movie(li["item"]["id"])
qty = li.get("quantity", 1)
amt = st["price"] * qty
subtotal += amt
items.append({
"id": f"li_{uuid.uuid4().hex[:8]}",
"item": {
"id": st["id"],
"title": f"{mv['title']} ({st['format']}, {st['time']})",
"price": st["price"],
},
"quantity": qty,
"totals": [{"type": "subtotal", "amount": amt},
{"type": "total", "amount": amt}],
})
if not items:
return _err(rid, "No valid showtimes in checkout")
tax = int(subtotal * 0.08)
total = subtotal + tax
session = {
"ucp": {
**_ucp_meta("dev.ucp.shopping.checkout",
"dev.ucp.common.payment.ap2_mandate"),
"payment_handlers": payment_handlers,
},
"id": sid,
"status": "ready_for_complete",
"currency": "USD",
"line_items": items,
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": subtotal},
{"type": "tax", "display_text": "Tax", "amount": tax},
{"type": "total", "display_text": "Total", "amount": total},
],
"links": [{"type": "terms_of_service",
"url": f"http://localhost:{port}/terms"}],
"expires_at": (
datetime.now(timezone.utc) + timedelta(minutes=10)
).isoformat(),
}
_sign(session)
sessions[sid] = session
return _ok(rid, Checkout, session)
if tool == "get_checkout":
session = sessions.get(args.get("id"))
if not session:
return _err(rid, "Not found")
return _ok(rid, Checkout, session)
if tool == "complete_checkout":
sid = args.get("id")
session = sessions.get(sid)
if not session:
return _err(rid, "Not found")
co = args.get("checkout", {})
checkout_mandate = co.get("ap2", {}).get("checkout_mandate")
instruments = co.get("payment", {}).get("instruments", [])
if not checkout_mandate or not instruments:
return _err(rid, "mandate_required")
payment_mandate = instruments[0]["credential"]["token"]
# Mock shortcut: a real merchant fetches the platform's keys
# from its profile URL (meta["ucp-agent"]["profile"])
platform_key = JWK(**args["meta"]["ucp-agent"]["keys"][0])
try:
cm = MandateClient().verify(
checkout_mandate, platform_key, payload_type=CheckoutMandate
).mandate_payload
pm = MandateClient().verify(
payment_mandate, platform_key, payload_type=PaymentMandate
).mandate_payload
except Exception as e:
return _err(rid, f"mandate_invalid_signature: {e}")
# The mandates must point at the exact checkout this merchant signed
expected_hash = compute_sha256_b64url(checkout_jwts[sid])
total = next(t["amount"] for t in session["totals"] if t["type"] == "total")
if (cm.checkout_jwt != checkout_jwts[sid]
or cm.checkout_hash != expected_hash
or pm.transaction_id != expected_hash
or pm.payment_amount.amount != total):
return _err(rid, "mandate_scope_mismatch")
order_id = f"ord_{uuid.uuid4().hex[:8]}"
session["status"] = "completed"
session["order"] = {
"id": order_id,
"label": theater["name"],
"permalink_url": f"http://localhost:{port}/orders/{order_id}",
"tickets": [
{
"movie": li["item"]["title"],
"quantity": li["quantity"],
"ticket_code": uuid.uuid4().hex[:8].upper(),
}
for li in session["line_items"]
],
}
_sign(session)
return _ok(rid, Checkout, session)
return _err(rid, f"Unknown tool: {tool}")
def _sign(session):
"""Add the merchant's signature (a detached JWS) to the checkout."""
payload = {k: v for k, v in session.items() if k != "ap2"}
canonical = json.dumps(
payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False
)
jws = JWS(canonical.encode())
jws.add_signature(key, alg="ES256",
protected=json.dumps({"alg": "ES256", "kid": key.kid}))
checkout_jwt = jws.serialize(compact=True)
header, _, sig = checkout_jwt.split(".")
session["ap2"] = {"merchant_authorization": f"{header}..{sig}"}
checkout_jwts[session["id"]] = checkout_jwt
def _ucp_meta(*capabilities):
return {"version": UCP_VERSION,
"capabilities": {c: [{"version": UCP_VERSION}] for c in capabilities}}
def _ok(rid, model, result):
# Check the response against the UCP SDK models before returning it
model.model_validate(result)
return {"jsonrpc": "2.0", "id": rid, "result": {
"structuredContent": result,
"content": [{"type": "text", "text": json.dumps(result)}],
}}
def _err(rid, msg):
return {"jsonrpc": "2.0", "id": rid, "error": {"code": -32000, "message": msg}}
def _product(movie, lookup=False):
prices = [st["price"] for st in movie["showtimes"]]
return {
"id": movie["id"],
"title": movie["title"],
"description": {"plain": f"{movie['title']} at {theater['name']}"},
"categories": [{"value": c, "taxonomy": "merchant"} for c in movie["categories"]],
"price_range": {
"min": {"amount": min(prices), "currency": "USD"},
"max": {"amount": max(prices), "currency": "USD"},
},
"variants": [
{
"id": st["id"],
"title": f"{st['format']} {st['time']}",
"description": {"plain": f"{st['format']} showing at {st['time']}"},
"options": [
{"name": "format", "label": st["format"]},
{"name": "time", "label": st["time"]},
],
"price": {"amount": st["price"], "currency": "USD"},
"availability": {"available": st["seats"] > 0},
"metadata": {"seats_available": st["seats"]},
**({"inputs": [{"id": movie["id"], "match": "featured"}]} if lookup else {}),
}
for st in movie["showtimes"]
],
}
def _find_showtime(sid):
return next(
(st for m in theater["movies"] for st in m["showtimes"] if st["id"] == sid),
None,
)
def _find_movie(sid):
return next(
(m for m in theater["movies"] for st in m["showtimes"] if st["id"] == sid),
None,
)
return app
def _run(port):
uvicorn.run(create_app(port), host="0.0.0.0", port=port, log_level="warning")
if __name__ == "__main__":
for port in THEATERS:
multiprocessing.Process(target=_run, args=(port,), daemon=True).start()
print("Merchants running: Meridian (:8081), StarLight (:8082)")
print("Press Ctrl+C to stop")
try:
while True:
time.sleep(1)
except KeyboardInterrupt:
pass
Thao tác này sẽ tạo ra 2 máy chủ FastAPI, mỗi máy chủ có 2 điểm cuối:
GET /.well-known/ucp: Khám phá UCP. Trả về các chức năng của người bán, URL điểm cuối MCP, các phương thức thanh toán được chấp nhận và khoá ký công khai.POST /mcp: Các thao tác MCP (Giao thức ngữ cảnh mô hình). Xử lý các lệnh gọi JSON-RPC 2.0 cho việc tìm kiếm danh mục, thanh toán và thanh toán.
Mỗi người bán ký tên vào quy trình thanh toán bằng khoá riêng, xác minh các quy định của AP2 trước khi hoàn tất đơn đặt hàng và kiểm tra mọi phản hồi dựa trên các mô hình UCP SDK.
Khởi động người bán trong một thiết bị đầu cuối mới (họ cần tiếp tục chạy):
cd ~/adk-agent-commerce
uv run python agent_payments/merchants.py
Bạn sẽ thấy:
Merchants running: Meridian (:8081), StarLight (:8082)
Trong thiết bị đầu cuối đầu tiên, hãy xác minh tính năng khám phá UCP:
curl -s http://localhost:8081/.well-known/ucp | uv run python -m json.tool
Bạn sẽ thấy các chức năng của người bán, URL điểm cuối MCP, trình xử lý thanh toán và khoá công khai.
8. Chạy tác nhân bằng ADK Web
Hãy sử dụng Giao diện người dùng web tích hợp sẵn của ADK CLI! Điều này cung cấp một giao diện trò chuyện trong trình duyệt và tự động xử lý lời nhắc xác nhận công cụ.
Lúc này, dự án của bạn sẽ có dạng như sau:
adk-agent-commerce/
├── pyproject.toml
└── agent_payments/
├── .env # Project settings
├── merchants.py # Mock UCP merchants
├── ucp_client.py # UCP client helper
├── ap2_handler.py # AP2 mandate handler
├── tools.py # Agent tools
└── agent.py # Agent definition
Dùng thử
Trong thiết bị đầu cuối đầu tiên, hãy chuyển đến thư mục adk-agent-commerce (một thư mục phía trên agent_payments) rồi khởi động Giao diện người dùng web ADK:
cd ~/adk-agent-commerce
uv run adk web --port 8080 --allow_origins '*'
Bạn sẽ thấy đầu ra cho biết máy chủ đang chạy tại http://127.0.0.1:8080.
Trao đổi với nhân viên hỗ trợ
- Mở giao diện người dùng web ADK bằng cách nhấn tổ hợp phím Ctrl hoặc Cmd rồi nhấp vào URL, hoặc bằng cách nhấp vào nút Xem trước trên web rồi chọn Xem trước trên cổng 8080.
- Chọn
agent_paymentstrong trình đơn thả xuống (nếu chưa chọn). Bạn sẽ thấy một giao diện trò chuyện. - Thử hỏi: "Có những phim nào đang chiếu?"
- Đại lý sẽ khám phá các rạp chiếu phim và tìm kiếm danh mục ở chế độ nền, tổng hợp kết quả từ cả hai người bán thông qua UCP.
- Yêu cầu đặt vé: "Đặt 2 vé xem phim Oppenheimer lúc 7 giờ tối".
- Khi tác nhân cố gắng gọi
complete_purchase, hãy lưu ý cách Giao diện người dùng web ADK hiển thị một thẻ xác nhận có thông tin chi tiết về giao dịch mua! - Để uỷ quyền cho giao dịch, hãy chọn hộp đánh dấu Đã xác nhận trên thẻ rồi nhấp vào Gửi.
- Tác nhân sẽ hoàn tất giao dịch mua và gửi cho bạn thông tin xác nhận đơn đặt hàng kèm theo mã vé!
Sau đây là những gì đã xảy ra:
create_checkout→ người bán trả về một quy trình thanh toán được ký bằng khoá của người bán (ap2.merchant_authorization, khoá giá)complete_purchase→ xác minh chữ ký của người bán, tạo CheckoutMandate và PaymentMandate, ký cả hai dưới dạng SD-JWT và gửi cho người bán- Người bán đã xác minh cả hai yêu cầu bắt buộc và kiểm tra để đảm bảo rằng các yêu cầu đó hướng đến quy trình thanh toán mà người bán đã ký → phát hành vé (trong bản mô phỏng)
9. Dọn dẹp
Để tránh để máy chủ cục bộ chạy, hãy dọn dẹp các tài nguyên:
- Trong dòng lệnh đang chạy
adk web, hãy nhấn tổ hợp phím Ctrl+C để dừng máy chủ tác nhân. - Trong thiết bị đầu cuối đang chạy
merchants.py, hãy nhấn tổ hợp phím Ctrl+C để dừng các người bán mô phỏng. - (Không bắt buộc) Nếu bạn đã tạo một dự án trên đám mây mới trên Google Cloud cho lớp học lập trình này và muốn xoá dự án đó, hãy chạy lệnh sau, thay thế
bằng mã dự án của dự án đó:
gcloud projects delete <YOUR_PROJECT_ID>
10. Xin chúc mừng! 🎉
Bạn đã tạo một tác nhân ADK có thể khám phá người bán, duyệt xem danh mục và hoàn tất giao dịch mua bằng UCP và AP2.
Kiến thức bạn học được
Trong lớp học lập trình này, bạn đã tạo một tác nhân ADK xử lý các quy trình thương mại an toàn. Sau đây là phần tóm tắt về những gì bạn đã tạo và các khái niệm chính mà bạn đã áp dụng:
Sản phẩm bạn đã tạo:
- 5 công cụ dành cho tác nhân bao gồm các hoạt động UCP và AP2: khám phá, tìm kiếm danh mục, thanh toán.
- Ký uỷ nhiệm AP2: quy trình thanh toán có chữ ký của người bán (khoá giá) + CheckoutMandate và PaymentMandate (uỷ quyền của người dùng).
- Tìm kiếm nhiều người bán: một tác nhân truy vấn nhiều rạp chiếu phim, hợp nhất kết quả.
Các khái niệm chính:
Giao thức | Ý nghĩa | Cách hoạt động |
Khám phá UCP | Tác nhân tìm thấy người bán và khả năng của họ |
|
UCP MCP | Tác nhân duyệt xem danh mục, tạo quy trình thanh toán | Các lệnh gọi JSON-RPC 2.0 đến điểm cuối MCP của người bán |
Uỷ quyền cho người bán | Người bán cố định giá được báo | Do người bán ký, bao gồm các mục hàng và tổng số tiền |
AP2 CheckoutMandate | Người dùng phê duyệt quy trình thanh toán chính xác | Do người dùng ký, có chứa quy trình thanh toán do người bán ký |
AP2 PaymentMandate | Người dùng uỷ quyền tính phí | Do người dùng ký, tham chiếu đến mã băm của quy trình thanh toán |
Có gì khác biệt trong quá trình sản xuất?
Lớp học lập trình này sử dụng các đối tượng mô phỏng. Đang sản xuất:
- Tính năng khám phá UCP phân giải dựa trên một sổ đăng ký, chứ không phải các URL localhost được mã hoá cứng
- Điểm cuối MCP được lưu trữ bởi người bán thực tế: cùng giao thức JSON-RPC 2.0, khoảng không quảng cáo thực tế
- Các lệnh bắt buộc của AP2 được ký trên thiết bị đáng tin cậy của người dùng hoặc bằng một nền tảng đáng tin cậy, chứ không phải bằng khoá mà tác nhân tạo khi khởi động
- Khoá ký đến từ hồ sơ UCP của mỗi bên (thay vào đó, người bán giả sẽ nhận được khoá công khai của tác nhân trong mỗi yêu cầu)
- Uỷ quyền thanh toán thông qua một trình cung cấp thông tin xác thực để xác minh PaymentMandate và yêu cầu người dùng đồng ý
- Giao diện người dùng hiển thị kết quả của công cụ dưới dạng giao diện người dùng nhiều định dạng (lưới sản phẩm, bản tóm tắt quy trình thanh toán, thẻ xác nhận)
Các bước tiếp theo
- Khám phá quy cách giao thức AP2 và tạo tác nhân hỗ trợ thanh toán của riêng bạn
- Triển khai UCP cho người bán để bật thương mại tác nhân
- Kết nối AP2 với A2A cho quy trình thương mại có nhiều tác nhân
- Tìm hiểu về phần mở rộng AP2 x402 cho các khoản thanh toán bằng tiền mã hoá