Claude Commerce Agents 详细部署教程

Claude Commerce Agents 是 Anthropic 官方发布的一个参考实现（Reference Blueprint），用于构建基于 Claude 的购物代理 (Shopping Agent) 和商家代理 (Merchant Agent)。它不是一个可以直接商用的产品，而是一套完整的代码库、设计模式和最佳实践，展示了如何将 Claude 集成到零售、电商、电信、娱乐等商业场景中。

本教程将引导你运行内置的演示，并了解如何基于此蓝图构建自己的商业 AI 代理。

1. 准备工作

在开始前，请确保你的开发环境满足以下要求：

要求	版本/说明
操作系统	macOS、Linux 或 Windows (推荐使用 WSL2)
Python	3.11 或更高版本
Node.js	22 或更高版本
Git	用于克隆代码仓库
Anthropic API Key	需要有效的 API 密钥

2. 快速开始：运行内置演示

这是体验项目功能最快的方式，它会启动一个模拟的零售商店前端和对应的 API 服务。

2.1 克隆仓库并设置环境

打开终端，执行以下命令：

git clone https://github.com/anthropics/commerce-agents.git
cd commerce-agents
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# 或 .venv\Scripts\activate  # Windows
pip install -r requirements.txt
cp .env.example .env

编辑 .env 文件，填入你的 ANTHROPIC_API_KEY。

2.2 安装示例前端依赖

1	(cd examples && npm ci)

2.3 运行零售业演示

1	python scripts/run_demo.py retail

此命令会同时启动：

API 服务：在 http://localhost:8000
商店前端 (Storefront)：在 http://localhost:3000

其他垂直领域：
你可以将 retail 替换为 travel (旅游)、telecom (电信) 或 entertainment (娱乐)，它们会使用不同的端口。

启动商家后台：添加 --merchant 参数，例如 python scripts/run_demo.py retail --merchant，后台管理界面会在 http://localhost:3100 启动。
同时启动商店和后台：使用 --all 参数。

3. 使用 Claude Code 插件快速构建

如果你使用 Claude Code，可以通过官方插件快速在你的项目里脚手架出一个新的商业代理。

添加插件市场：

1	claude plugin marketplace add anthropics/commerce-agents

安装构建器插件：

1	claude plugin install commerce-builder@claude-commerce-agents

启动 Claude Code 并运行构建命令：
1
claude
在 Claude Code 会话中，输入：
1
/scaffold-commerce-agent a shopping assistant for our store
插件会询问你的技术栈，然后自动生成项目结构。你还可以使用 /add-commerce-flow 和 /author-commerce-evals 命令继续添加功能或评估。

4. 核心架构与自定义

理解项目结构是构建自有代理的关键。

4.1 两大代理与后端接口

项目定义了两种代理，它们通过你实现的后端接口 (Backend Interface) 与你的业务系统交互：

代理	角色	核心后端接口	技能示例
购物代理	面向顾客，提供商品搜索、比价、购物车、订单查询等服务。	`StorefrontBackend`	搜索、比价、规划、填写购物车、记忆用户偏好
商家代理	面向员工，用于分析业绩、管理商品、库存、定价和促销活动。	`MerchantBackend`	业绩分析、商品管理、库存预警、定价与促销、活动策划

所有写操作（如下单、修改商品）都是“分阶段”的，需要人工批准后才能生效 ，确保了安全性。

4.2 关键目录说明

目录	内容
`shopping-agent/`	购物代理的核心代码、技能定义、提示词和三种运行方式（Messages API, Agent SDK, Managed Agents）的实现。
`merchant-agent/`	商家代理的核心代码、技能、提示词和运行方式实现。
`commerce-common/`	两个代理共享的代码：配置、护栏 (Fencing)、内存管理、技能加载、展示层等。
`examples/`	四个垂直领域（零售、旅游、电信、娱乐）的具体实现，包含前端和后端模拟代码。
`docs/`	核心文档，包含 `safety.md` (安全规则)、`backends.md` (后端对接指南)、`deployment.md` (部署指南)。
`plugins/commerce-builder/`	Claude Code 插件源码。

4.3 自定义代理的核心步骤

实现后端接口：这是最关键的一步。你需要为 StorefrontBackend 或 MerchantBackend 接口编写代码，让它们调用你真实的商品目录 (Catalog)、购物车 (Cart)、订单 (Order) 和分析 (Analytics) 系统。参考 docs/backends.md 获取详细指引。
调整配置：通过 ShoppingAgentConfig 或 MerchantAgentConfig 设置品牌名称、助手名称、语气等。
修改或新增技能：技能位于 shopping-agent/skills/ 或 merchant-agent/skills/ 目录下。每个技能是一个包含 SKILL.md 文件的文件夹，你可以修改现有技能或创建新技能。
关闭不需要的功能：如果你没有购物车或订单追踪系统，可以通过配置开关 (enable_*) 关闭对应功能，系统会自动移除相关的提示词和工具。

5. 高级部署方式

除了运行演示，该蓝图支持三种将代理部署到生产环境的方式：

方式	适用场景	关键文件/命令
Messages API	标准部署，需要自行构建应用循环。	在代码中实例化 `ShoppingAgent` 或 `MerchantAgent` 并调用 `stream_turn` 方法。
Agent SDK	使用 Anthropic Agent SDK 的场景。	运行 `python shopping-agent/runtime-agent-sdk/main.py --once "用户请求"`
Managed Agents	希望以托管服务方式运行，通过 MCP 连接后端。	使用 `scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent` 部署。

6. 验证与测试

项目提供了测试工具来验证你的部署：

# 运行完整测试套件
ruff check . && ruff format --check . && pytest && python scripts/check.py

# 运行更全面的验证（包含构建检查）
python scripts/verify_all.py

# 对特定垂直领域进行一个完整的对话烟雾测试
python scripts/smoke_chat.py --vertical travel

7. 重要注意事项

安全第一：项目内置了多种安全机制，包括护栏 (Fencing)、来源检查 (Provenance Gates)、预算限制 (Caps) 和内存验证。请务必阅读 docs/safety.md 了解详情。
这是参考实现：Anthropic 明确表示此项目不接受外部贡献，它是一个展示设计思路的蓝图。
合规性：你部署的代理必须遵守你所在地区的法律和平台政策。示例中的所有公司、品牌和产品均为虚构。
证书与授权：商业代理涉及财务和客户数据，你的部署必须实现完整的用户认证 (Authentication) 和授权 (Authorization) 机制。

8. 总结

Anthropic 的 Commerce Agents 蓝图提供了一个专业、模块化且安全优先的框架，用于开发商业 AI 代理。通过克隆并运行示例，你可以快速上手；通过实现后端接口和调整配置，你可以将此蓝图转化为适合自身业务的定制化 AI 助手。该项目的最大价值在于其设计模式和最佳实践，而非开箱即用的产品。

相关资源：