Commerce Agents

为什么需要

出海做跨境电商或海外零售，AI 客服和商家后台是两个最常见的 Agent 落地点——但市面上没有官方参考实现，从零搭要踩一堆坑：提示词怎么设计、工具调用边界怎么画、记忆怎么管理、人工复核怎么嵌。Anthropic 把 Commerce Agents 整套实现开源出来，直接给购物 Agent（嵌入商家 App 给客户用）和商家 Agent（商家员工跑后台）两个角色，零售、旅游、电信、文娱 4 个垂直行业的可运行 demo，配 Apache-2.0 协议可商用。

对独立开发者最直接的价值：你想给客户做一个海外电商 AI 客服，clone 下来改 StorefrontBackend 接到自己的 catalog/cart/order 系统，一个能用的 demo 半天就能跑起来；商家 Agent 那侧的 inventory/listing/campaign 自动化也可以借鉴同套架构。这比从 LangChain/AutoGPT 一点点凑快得多。

怎么用

环境要求 Python 3.11+ 和 Node 22。Clone 仓库、装依赖、配 Anthropic API Key：

git clone https://github.com/anthropics/commerce-agents.git && cd commerce-agents
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # 填 ANTHROPIC_API_KEY
(cd examples && npm ci)
python scripts/run_demo.py retail  # API :8000 + storefront :3000

四个垂直 demo：retail(:3000, portal :3100)、travel(:3001, :3101)、telecom(:3002, :3102)、entertainment(:3003, :3103)。加 --merchant 启后台，加 --all 同时启两端。

Claude Code 用户可以用插件脚手架命令，从需求直接生成项目：

claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude
/scaffold-commerce-agent a shopping assistant for our store

之后 /add-commerce-flow / /author-commerce-evals 继续扩展，/review-commerce-agent 审查已有 Agent。

核心特性

• 双角色设计 — 购物 Agent（客户侧）+ 商家 Agent（员工侧）共享 commerce-common 基础库（config、fencing、memory、skills、grounding、executor、events）
• 三种部署方式 — Messages API（参考循环）/ Agent SDK（生产循环）/ Managed Agents（托管 Agent 走 MCP）
• 四垂直 demo — 零售 ACME、旅游 ACME Travel、电信 ACME Mobile、文娱 ACME Tickets，每个都有完整 storefront + portal
• Claude Code 插件 — /scaffold-commerce-agent 脚手架、/review-commerce-agent 审查、/author-commerce-evals 评测三件套
• 安全门禁 — fencing、provenance gates、caps、memory validation、商家审批 gate 在所有路径生效；详情见 docs/safety.md
• 三种后端 — StorefrontBackend / MerchantBackend 实现接口对接你自己的 catalog / cart / order / inventory 系统
• 实时事件流 — text_delta / tool_call / ui / cart_update / turn_complete 等 streaming 事件，前端可以增量渲染
• 审批工作流 — 商家 Agent 所有写入都是 staged change，必须人工 y/N 批准才生效（防误操作）

使用案例

独立开发者做海外 SaaS 工具（比如给跨境电商店铺用的 AI 选品助手），需要快速搭一个购物 Agent demo 跟客户演示。直接 clone commerce-agents，改 StorefrontBackend 接到自建 catalog API，3 小时出可演示的原型；想加商家后台时复用 merchant-agent 那套 inventory/pricing/listing 实现，省一周开发。

另一个场景：海外零售客户（一家旅游公司）想做 AI 客服，从 examples/travel/ 起步——日期绑定库存、present_itinerary 扩展、occupancy 日历、date-window 价格调整都已经实现，对接客户系统改 backend 接口就行。

注意事项

• Apache-2.0 开源协议，可商用
• 需要 Anthropic API Key（Messages API / Agent SDK 路径），或 Managed Agents 托管
• Python 3.11+ 和 Node 22 是基础要求
• 示例无认证、MCP 服务器仅 loopback 绑定，生产部署必须加认证和公网安全措施
• 商家 Agent 的 staged change 设计是安全优先：所有写操作等人工审批，避免 AI 自动改 listing/价格
• 和 LangChain/AutoGPT 区别：commerce-agents 是官方 reference implementation，结构清晰、有完整 demo、覆盖客服+商家双角色；LangChain/AutoGPT 是通用框架，需要自己拼装 commerce 业务逻辑
• 由 Anthropic 官方维护，长期演进有保障