通用商务协议教程：构建您的首个 UCP 服务器

在本指南中，您将了解通用商务协议（UCP）是什么、为谁而建、为何需要新的商务标准，以及其架构如何运作。

您还将通过动手演练来搭建自己的 UCP 示例服务器，探索其发现（discovery）配置文件，创建结账会话，并在本地运行完整示例流程。

这将既帮助您清晰理解该协议，也为在真实实现中测试 UCP 的工作方式提供一个实用的起点。

通用商务协议简介

通用商务协议是一项开放标准，帮助 AI 代理、应用、企业与支付提供方在一个共享的购物流程中协同工作。UCP 提供了一种通用的通信方式，避免为每个新伙伴都构建一次性定制集成。

UCP 专为现代代理主导的购物而设计，人们通过 AI 助手和对话式界面来发现与购买商品。它支持完整旅程，从发现企业提供的内容，到发起结账并以结构化方式管理购买。

来源：Google Developers Blog

通俗地说，UCP 就像一门通用商务语言。企业可以发布其支持的内容，代理读取该信息后即可与之交互，而无需单独开发 API 集成。Shopify 将其描述为支撑大规模代理型商务的基础设施。

UCP 还是开源且与供应商无关。它可与现有商务系统协同工作，并与代理支付协议（AP2）兼容，以实现安全的代理发起支付。它还能跨多种传输方式工作，包括 REST API、代理到代理通信，以及 MCP。

通用商务协议面向哪些人？

通用UCP 面向现代数字商务中的主要群体。其目标是为所有参与者提供一种共享的沟通方式，从而免去为每个连接都开发定制集成的需求。

它主要面向：

1. AI 代理与消费平台

这些包括帮助用户发现商品并完成购买的应用、助手与发现界面。UCP 帮助它们理解企业支持的内容，并以结构化方式进行交互。Google 将此描述为将消费端界面与企业后端相连，以实现无缝购物。

2. 企业与商家

UCP 帮助企业以标准格式公开其商品、结账流程与支持的功能。这样它们就能更轻松地与不同的 AI 平台和代理协作，而无需为每一个单独构建集成。

3. 支付提供方

支付提供方同样是 UCP 生态的一部分。该协议设计为以灵活方式支持不同的支付处理器与支付凭据，从而在不同系统间安全处理支付。

4. 开发者与协议构建者

UCP 是开源的，同样面向希望实现、扩展或对标准做出贡献的开发者。UCP 项目明确邀请企业、开发者和支付提供方共同塑造协议的未来。

简而言之，UCP 面向所有参与 AI 驱动商务的人：帮助用户购物的平台、销售商品的企业、处理交易的支付系统，以及构建它们之间连接的开发者。

为何需要一项新的商务标准

之所以需要新的商务标准，是因为当前大多数商务系统是为传统网站和移动应用而建，而非为AI 助手与对话式购物。

旧有模式往往依赖自定义 API 和一次性集成，难以在多平台间快速扩展。UCP 通过为企业、代理与平台提供统一的沟通方式来解决这一问题。

随着越来越多人通过 AI 工具购物，商务需要在同一段对话中支持产品发现、结账、优惠与订单更新等实时操作。

UCP 正是为这种全新购物方式而设计，体验更具互动性，并发生在不同的数字界面上。

此外，当今商务生态十分碎片化。不同企业、支付提供方与平台往往使用不同系统。UCP 通过通用标准将它们连接起来，让彼此无需反复重建相同的集成即可协作。

简而言之，旧的商务工具并非为 AI 主导购物而生，UCP 则为行业提供了一个更现代、更灵活的基础，支撑未来用户发现与购买商品的方式。

理解通用商务协议的架构

通用通用商务协议（UCP）是一个面向代理型商务的模块化系统。它为企业、AI 代理与支付提供方提供了从发现到结账及后续环节的共享处理方式。

企业无需为每个平台单独构建自定义集成。通过 UCP，企业可发布其支持内容，代理读取后即可按标准流程交互。

UCP 具有模块化与可扩展性，支持 REST、MCP 与A2A 等传输方式，并与支付处理器协同工作，便于企业沿用既有支付方案。

1. 企业发布发现配置文件

启用 UCP 的企业会在 /.well-known/ucp 暴露一个配置文件。该文件在任何交易开始前告知平台与代理企业支持的内容，包括可用能力与端点。

2. 代理读取支持的能力

完成发现后，代理会检查企业提供的服务与能力。UCP 初始发布聚焦于核心能力，如结账（Checkout）、身份关联（Identity Linking）与订单管理（Order Management），它们是协议的主要构件。

3. 扩展提供额外功能

UCP 保持核心流程简洁，但企业可在需要时添加可选扩展。这些扩展基于核心能力构建，让企业在不更改整个协议的情况下支持更丰富的功能。

4. 通过受支持的传输方式运行流程

一旦代理了解已支持的内容，即可通过受支持的传输方式（如REST、MCP 或A2A）与企业交互。这样，同样的商务逻辑可更容易在 API、AI 工具和代理到代理系统中复用。

5. 通过支付处理器完成支付

UCP 将商务流程与支付层解耦。企业可以声明所支持的支付处理器，协议设计允许商家沿用现有支付集成，而无需从头重建一切。

6. 使用 AP2 实现安全的代理主导支付

UCP 与代理支付协议（AP2）兼容，为代理发起的支付增加安全层，帮助在 AI 代理代表用户行动时实现更安全的授权。

通用商务协议端到端演练

本指南使用 Python 参考实现演示完整的通用商务协议流程。您将搭建示例商家服务器，加载演示花店目录，发现企业能力，创建结账会话，应用折扣，然后停止服务器。

步骤 1：设置商家服务器

在此步骤中，您将安装用于 Python 依赖管理的 uv，然后克隆UCP Python SDK与示例服务器仓库。示例服务器的 README 采用相同的设置方式，并指出示例中 SDK 的相对路径很重要。

由于我们的操作系统是Linux，我们将使用以下命令安装 uv。uv 是一个快速可靠的 Python 包与环境管理器，作用类似 Anaconda，但更轻量更迅速。

curl -LsSf https://astral.sh/uv/install.sh | sh技术支持

安装完成后，重新加载终端会话，使uv 命令在当前 Shell 中可用。

source ~/.bashrc技术支持

接下来，新建一个名为sdk 的文件夹，用于存放我们从 GitHub 克隆的通用商务协议 Python SDK。

mkdir sdk
git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git 
sdk/python技术支持

现在切换到 sdk/python 目录，即 SDK 仓库被克隆到的位置。

pushd sdk/python技术支持

进入 SDK 目录后，使用 uv sync 安装 SDK 所需的全部 Python 依赖。

uv sync技术支持

依赖安装完成后，返回先前的工作目录。

popd技术支持

现在克隆示例仓库，其中包含本演练所用的 Python 参考商家服务器。

git clone https://github.com/Universal-Commerce-Protocol/samples.git技术支持

接着，进入示例仓库中的 Python 服务器示例目录。

cd samples/rest/python/server技术支持

最后，安装运行示例服务器所需的全部 Python 依赖。

uv sync技术支持

至此，示例商家服务器已在您的工作区就绪。该服务器已实现 UCP 定义的核心购物能力。

步骤 2：创建示例产品数据库

此步骤将为示例商家创建一个基于 SQLite 的本地演示商店。本教程中的示例商家为花店，此命令将加载服务器所用的示例产品目录与交易数据库。

首先，创建一个用于存放数据库文件的临时文件夹。

mkdir /tmp/ucp_test技术支持

然后运行导入脚本来创建并填充产品与交易数据库。

uv run import_csv.py \
  --products_db_path=/tmp/ucp_test/products.db \
  --transactions_db_path=/tmp/ucp_test/transactions.db \
  --data_dir=../test_data/flower_shop技术支持

该命令将完成以下操作：

• --products_db_path 创建产品目录数据库。
• --transactions_db_path 创建用于结账状态的交易数据库。
• --data_dir=../test_data/flower_shop 指向仓库中附带的花店示例数据。

完成此步骤后，您的本地示例商店数据已就绪，服务器即可使用。

步骤 3：启动商家服务器

在本步骤中，您将启动示例 UCP 商家服务器。该服务器将使用前一步创建的产品与交易数据库，并在端口 8182 上暴露 UCP 购物 API。

运行以下命令在后台启动服务器。

uv run server.py \
  --products_db_path=/tmp/ucp_test/products.db \
  --transactions_db_path=/tmp/ucp_test/transactions.db \
  --port=8182 &
SERVER_PID=$!技术支持

该命令将完成以下操作：

• uv run server.py 启动示例 Python 服务器。
• --products_db_path 连接产品数据库。
• --transactions_db_path 连接交易数据库。
• --port=8182 指定服务器运行在 8182 端口。
• & 将进程放到后台运行，便于继续使用终端。
• SERVER_PID=$! 保存进程 ID，方便稍后停止服务器。

此时，商家服务器已运行，随时可接收来自代理的请求。

步骤 4：发现企业能力

在此步骤中，您将查询 UCP 发现端点。每个启用 UCP 的企业都会在 /.well-known/ucp 发布发现文档，使代理在发起任何请求前先了解企业支持的内容。

首先，将服务器 URL 保存到变量中，便于后续命令阅读。

export SERVER_URL=http://localhost:8182技术支持

现在从商家服务器获取 UCP 发现文档。

curl -s $SERVER_URL/.well-known/ucp技术支持

该响应会告知代理：

• 服务器支持的 UCP 版本，
• 可用的服务，
• 已实现的能力，如结账与折扣，
• 以及支持的支付处理器或方案。

发现步骤很重要，因为它消除了硬编码的定制集成需求。代理可以先检查服务器，再决定如何与之交互。

步骤 5：创建结账会话

在此步骤中，您将使用 UCP 的结账能力创建一个新的结账会话。此时，代理会将所选商品、买家信息与支付结构发送至商家服务器。

在发送请求前，先生成所需的请求头。这些请求头有助于请求追踪、幂等控制与签名校验。

export REQUEST_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export IDEMPOTENCY_KEY=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export REQUEST_SIGNATURE="dev"技术支持

其作用如下：

• REQUEST_ID 生成请求的唯一标识符。
• IDEMPOTENCY_KEY 确保重试时不会重复处理相同请求。
• REQUEST_SIGNATURE 提供所需的签名请求头。在本地演示中，如未严格启用签名校验，可使用 "dev"。

现在将结账请求发送至服务器。

curl -X POST "$SERVER_URL/checkout-sessions" \
  -H "Content-Type: application/json" \
  -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
  -H "request-id: $REQUEST_ID" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -H "request-signature: $REQUEST_SIGNATURE" \
  -d '{
    "line_items": [
      { "item": { "id": "bouquet_roses", "title": "Red Rose" }, "quantity": 1 }
    ],
    "buyer": { "full_name": "John Doe", "email": "[email protected]" },
    "currency": "USD",
    "payment": { "handlers": [], "instruments": [] }
  }'技术支持

该请求包含：

• line_items 定义买家想要购买的内容，
• item.id 标识产品，
• item.title 提供可读名称，
• quantity 指定购买数量，
• buyer 包含顾客信息，
• currency 指定结账货币，
• 以及 payment 提供所需的支付结构。

响应将返回一个结账会话对象，其中包含新的结账 ID、行项目 ID、合计、买家信息以及当前结账状态。

步骤 6：使用 UCP 应用折扣

在此步骤中，您将更新现有结账会话并应用折扣码。UCP 中的折扣作为结账能力的扩展实现，因此在结账更新请求中添加折扣即可。

首先，保存上一步结账响应返回的真实结账 ID 与行项目 ID。

export CHECKOUT_ID=5dd08e18-c9c1-4fa1-a0d1-885ca81cda29
export LINE_ITEM_ID=ed72ebe6-2484-4e7b-afc8-a8ff5c8f430e技术支持

接着，为此次更新请求生成新的请求 ID 与幂等键。

export REQUEST_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export IDEMPOTENCY_KEY=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export REQUEST_SIGNATURE="dev"
技术支持

现在发送包含折扣码的结账更新请求。

curl -X PUT "$SERVER_URL/checkout-sessions/$CHECKOUT_ID" \
  -H "Content-Type: application/json" \
  -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
  -H "request-id: $REQUEST_ID" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -H "request-signature: $REQUEST_SIGNATURE" \
  -d "{
    \"id\": \"$CHECKOUT_ID\",
    \"line_items\": [
      {
        \"id\": \"$LINE_ITEM_ID\",
        \"item\": { \"id\": \"bouquet_roses\", \"title\": \"Red Rose\" },
        \"quantity\": 1
      }
    ],
    \"buyer\": {
      \"full_name\": \"John Doe\",
      \"email\": \"[email protected]\"
    },
    \"currency\": \"USD\",
    \"discounts\": {
      \"codes\": [\"10OFF\"]
    },
    \"payment\": {
      \"handlers\": [],
      \"instruments\": []
    }
  }"技术支持

该请求将：

• 使用 PUT 更新现有结账，
• 包含原结账 ID，
• 再次包含该行项目，
• 添加 discounts 段，
• 并应用折扣码 10OFF。

响应应返回更新后的结账对象，其中包括：

• 重新计算的合计，
• 折扣金额，
• 最终更新后的总计，
• 以及任何已应用折扣的详细信息。

该折扣码有效；您应能在响应中看到价格变化。

步骤 7：关闭服务器

在最后一步，您将停止先前启动的示例商家服务器。由于启动时保存了进程 ID，可用一条命令轻松关闭它。

运行以下命令停止服务器。

kill $SERVER_PID技术支持

从头到尾，您已在本地机器上成功构建并测试了一个端到端 UCP 流程。

您已经：

• 使用 uv 安装所需的 Python 工具，
• 克隆 UCP Python SDK 与示例服务器仓库，
• 创建示例花店产品数据库，
• 启动商家服务器，
• 通过发现端点获取服务器的 UCP 能力，
• 以代理身份创建结账会话，
• 通过应用折扣码更新该结账，
• 并最终关闭服务器。

简言之，您搭建了一个可用的 UCP 启用企业，以代理方式连接，创建购物结账，并测试了 UCP 如何处理折扣等更新。这为企业与代理如何使用通用商务协议交互提供了一个完整的基础示例。

结语

通用商务协议为行业提供了 AI 主导商务的共享基础。它为企业、AI 代理与支付系统建立标准化的沟通方式，使其更易支持发现、结账、更新与支付，而无需为每个新平台重建定制集成。

在本指南中，您已了解 UCP 是什么、其重要性、架构工作方式，以及如何从头到尾运行完整的本地示例。通过搭建示例服务器、发现其能力、创建结账会话并应用折扣，您看到了 UCP 如何将商务转化为结构化、对代理友好的工作流。

UCP 的最大机遇显而易见：在购物日益通过 AI 助手与对话式界面进行的世界里，它能降低碎片化、提升互操作性。

然而，真正的挑战在于采纳。企业可能依然选择自定义 API、现有的基于 REST 的集成、基于 MCP 的工具，或它们当下已使用的其他代理工作流。要让 UCP 取得成功，需获得商家、平台、开发者与支付提供方的强力生态支持。