1. 背景与核心概念1.1 从“电商助手”到“Commerce Agents”今年人工智能领域最明显的变化不只是大模型回答得更准确了而是模型开始真正“动手干活”。在电商场景里过去我们熟悉的聊天机器人Chatbot只能帮助用户查一下订单、解释一下售后政策本质上是一个基于知识库的问答系统。用户如果想要完成退款、申请价保、比价下单仍然要跳出对话窗口手动进入页面一次次点击。Commerce Agents 要解决的正是这个“能说不能做”的问题。它是一类具备工具调用能力的智能体Agent可以理解用户意图调用电商平台和商户系统的各类工具代替用户执行完整的购物或经营操作。Anthropic 将 Claude 在 Agent 方向上的能力开放出来推出了面向开发者的开源智能体蓝图。这套蓝图覆盖了两条核心主线购物智能体Shopping Agent面向消费者理解用户购物意图完成商品搜索、比价、加购、下单、订单跟踪和售后申请的闭环。商户智能体Merchant Agent面向商家帮助商户处理经营分析、库存管理、客服响应、营销配置、风险预警等事务。简单理解购物智能体是“帮用户买”商户智能体是“帮商家卖”。两者共用一套 Claude 的 Agent 技术底座但工具集、权限边界、业务流程完全不同。1.2 为什么开源这件事很重要Anthropic 把 Commerce Agents 的蓝图开源意味着开发者不再需要从零摸索智能体与电商系统的对接方式。你可以直接拿到一套参考架构、示例代码、提示词模板和工具调用规范再结合自己的业务系统进行二次开发。对技术团队来说开源带来的实际价值有三点一是降低了调研成本。你不需要把整个电商系统全部接入大模型只需要在关键节点上定义工具让 Agent 按流程调用。二是形成了可复用的工程范式。订单查询怎么做、支付授权怎么控制、价格保护逻辑怎么触发这些电商 Agent 里的“硬骨头”开源蓝图提供了相对标准的解法。三是便于做合规审查。代码在你自己手里你可以清楚知道 Agent 每一步做了什么、调用了哪些接口、数据流向哪里这在金融和电商场景尤其重要。1.3 智能体Agent与普通 API 调用的区别要理解 Commerce Agents先要搞清楚 Agent 与普通 API 调用的本质区别。普通 API 调用是“写死的流程”用户输入 - 后端固定逻辑 - 调用固定接口 - 返回固定结果Agent 调用是“模型自主决策的流程”用户输入 - 模型理解意图 - 选择工具 - 组织参数 - 调用工具 - 拿到结果 - 再理解 - 再调用……这里的关键在于“循环”。Agent 并不是一次问答就结束而是会反复执行“推理-行动-观察”的循环直到完成用户的目标。例如用户说“我想买一台 3000 元左右的办公笔记本最好今天能送到”Agent 需要理解需求预算 3000 元、办公本、今日达。调用商品搜索工具传入预算范围和品类标签。分析返回的商品列表筛选符合条件的商品。调用库存查询工具确认哪些支持当日达。整理推荐结果询问用户是否直接下单。如果用户确认调用下单工具。这一系列动作依赖的是一个稳定可靠的 Agent 运行时环境也就是 Anthropic 开源蓝图中最核心的部分。2. 环境准备与版本说明2.1 技术栈选型开始编写 Commerce Agents 之前我们需要准备好基础环境。由于 Anthropic 官方提供的 Agent SDK 支持多种语言本文以 Python 为例这也是目前社区示例最丰富、上手最快的语言组合。组件建议方案说明操作系统macOS / Linux / Windows本文示例在 macOS 上验证Windows 用户注意路径分隔符差异Python3.10 及以上依赖新版类型注解和异步特性Claude APIanthropic 官方 SDK需要 Anthropic API Key框架FastAPI用于构建 Agent 的 HTTP 服务层工具调用Claude Agent SDK官方提供的 Agent 运行时数据库SQLite开发/ PostgreSQL生产存储订单、商品、用户授权等数据版本需要根据你的项目实际情况灵活调整。Anthropic 的 SDK 更新比较频繁建议使用pip install -U anthropic拉取最新版本并在requirements.txt中锁定你验证过的版本号。2.2 获取 API Key 与基础配置在 Anthropic 控制台完成账号注册后创建 API Key。这里要特别强调不要把 API Key 硬编码在代码里推荐使用环境变量管理。# Linux / macOS export ANTHROPIC_API_KEYsk-ant-xxxx # Windows PowerShell $env:ANTHROPIC_API_KEYsk-ant-xxxx同时准备一个配置文件用来管理模型名称和 Agent 行为参数# config.py import os ANTHROPIC_API_KEY os.getenv(ANTHROPIC_API_KEY) MODEL_NAME os.getenv(CLAUDE_MODEL_NAME, claude-sonnet-4-5) MAX_TOKENS 4096 TEMPERATURE 0.2细心的读者会发现我把TEMPERATURE设置得比较低。原因在于电商场景对准确性的要求很高温度过高会导致模型“发挥想象力”出现编造订单号、虚构价格之类的问题。在工具调用场景下较低的温度有助于模型严格按照工具返回的数据回答用户。2.3 安装依赖pip install anthropic fastapi uvicorn pydantic安装完成后创建项目目录commerce-agent-demo/ ├── main.py # Agent 服务入口 ├── config.py # 全局配置 ├── tools/ # 工具定义 │ ├── __init__.py │ ├── product.py # 商品相关工具 │ ├── cart.py # 购物车工具 │ └── order.py # 订单工具 ├── agent.py # Agent 核心逻辑 └── requirements.txt3. 核心架构与原理拆解3.1 Commerce Agents 的整体架构一套完整的 Commerce Agents 系统按职责可以拆成五层。我把这五层整理成下表方便你对照自己的业务系统做映射层级职责关键组件接入层接收用户消息返回 Agent 响应Web 聊天框、IM 接口、移动端 SDK智能体层理解意图、规划步骤、选择工具Claude 模型、Agent 运行时、提示词管理工具层封装电商系统能力供 Agent 调用商品搜索、订单查询、购物车、支付、售后数据层持久化 Agent 执行状态与业务数据用户信息、订单表、商品表、授权记录治理层权限控制、安全审计、配额管理用户授权体系、操作日志、限额控制这五层架构的核心思想是“模型做决策工具做执行”。模型本身不直接操作数据库而是通过标准化的工具接口完成动作。这样设计的好处是安全边界清晰——模型永远拿不到数据库密码也无法绕过权限系统直接执行 SQL。3.2 购物智能体Shopping Agent的完整闭环购物智能体是消费者直接接触的部分。一个完整的购物流程闭环包含以下阶段阶段一意图识别用户发来一句自然语言Agent 需要判断用户的真实意图。比如“帮我在 500 元以内找一套适合油皮夏天用的护肤品”和“我上周买的洗面奶什么时候发货”前者是商品推荐意图后者是订单查询意图。Claude 会先输出一个结构化的意图判断结果再决定后续调用哪些工具。阶段二工具调用循环确定意图之后Agent 会进入工具调用循环Claude 分析用户需求 - 调用 search_products 工具查询商品 - 拿到商品列表 - 对比价格、库存、物流时效 - 调用 get_product_detail 查看详情 - 整理推荐话术 - 询问用户是否下单这个循环是 Agent 的核心运转方式在技术上由 Agent SDK 中的“工具调用循环”机制支持。每一轮工具调用后模型都会重新评估当前状态决定是继续调用工具还是直接回复用户。阶段三交易执行用户确认下单后Agent 需要执行交易动作。这里有一个安全关键点Agent 本身不应该直接操作支付而是应该调用支付工具的“预下单”能力生成一笔待支付订单然后由用户完成最终确认。整个过程需要记录操作日志方便后续审计。阶段四售后处理支付完成不是终点。用户之后可能会申请退款、询问物流、申请价保。购物智能体需要具备调用售后工具的能力并且在涉及退款、赔付等敏感操作时及时将控制权交还给人或系统审批。3.3 商户智能体Merchant Agent的核心能力商户智能体服务于商家核心场景可以分成四类经营分析自动汇总销售数据、转化率、客单价生成每日经营日报。库存管理监控 SKU 库存水位当库存低于阈值时生成补货建议。客服自动化高效处理常见售后问题例如退款路径查询、物流异常上报、发票补开。营销配置根据活动规则创建优惠券、设置满减活动。商户智能体和购物智能体在技术上没有本质区别差异主要体现在工具权限上。商户智能体调用的是商户后台接口操作对象是商户自己的店铺数据因此在权限设计上更偏向“商家授权 角色隔离”。4. 完整实战搭建一个最小可用的购物智能体这一节我们来实现一个最小可用的购物智能体功能包括商品搜索、购物车添加、订单状态查询。为了让你能直接运行我会使用内存数据模拟电商系统接口但代码结构完全兼容真实环境替换。4.1 创建项目结构commerce-agent-demo/ ├── main.py ├── config.py ├── agent.py ├── tools/ │ ├── __init__.py │ ├── product.py │ └── order.py └── requirements.txt4.2 定义工具函数先看商品工具。这个模块负责模拟电商平台商品库的检索能力# tools/product.py from typing import Optional # 模拟商品数据库 PRODUCTS [ { id: p001, name: 无线降噪耳机, category: 数码, price: 499.00, stock: 120, rating: 4.8, }, { id: p002, name: 便携蓝牙音箱, category: 数码, price: 299.00, stock: 80, rating: 4.5, }, { id: p003, name: 智能手环, category: 数码, price: 249.00, stock: 200, rating: 4.6, }, ] def search_products( keyword: Optional[str] None, max_price: Optional[float] None, category: Optional[str] None, ) - list: 根据关键词、价格上限和品类搜索商品 results PRODUCTS if keyword: results [ p for p in results if keyword.lower() in p[name].lower() ] if max_price is not None: results [p for p in results if p[price] max_price] if category: results [p for p in results if p[category] category] return results def get_product_detail(product_id: str) - Optional[dict]: 根据商品 ID 获取详细信息 for p in PRODUCTS: if p[id] product_id: return p return None每个函数上面都有一段 docstring。这不是注释风格的问题而是 Agent 工具调用的关键——Claude 会通过工具的函数签名和 docstring 来理解这个工具是做什么的、参数应该怎么填。所以工具的描述要尽量精准。然后是订单工具# tools/order.py from typing import Optional from datetime import datetime # 模拟订单数据库 ORDERS [ { order_id: 202501010001, user_id: u001, product_id: p001, status: 已发货, created_at: 2025-01-01 10:30:00, tracking_number: SF1234567890, }, { order_id: 202501020002, user_id: u001, product_id: p002, status: 待付款, created_at: 2025-01-02 14:20:00, tracking_number: None, }, ] def get_order_status(order_id: str, user_id: str) - Optional[dict]: 根据订单号和用户 ID 查询订单状态 for order in ORDERS: if order[order_id] order_id and order[user_id] user_id: return { order_id: order[order_id], status: order[status], created_at: order[created_at], tracking_number: order[tracking_number], } return None def create_order(user_id: str, product_id: str, quantity: int) - dict: 创建新订单返回订单号 order_id datetime.now().strftime(%Y%m%d%H%M%S) order { order_id: order_id, user_id: user_id, product_id: product_id, status: 待付款, created_at: datetime.now().strftime(%Y-%m-%d %H:%M:%S), tracking_number: None, quantity: quantity, } ORDERS.append(order) return order注意create_order只是一个模拟实现真实项目中还应该包含库存锁定、价格计算、地址校验等逻辑。4.3 实现 Agent 核心逻辑Agent 的核心是把工具注册给 Claude让它能够在对话过程中调用。这里使用 Anthropic 官方 SDK 的方式来实现工具调用循环# agent.py import anthropic from config import ANTHROPIC_API_KEY, MODEL_NAME, MAX_TOKENS, TEMPERATURE from tools.product import search_products, get_product_detail from tools.order import get_order_status, create_order client anthropic.Anthropic(api_keyANTHROPIC_API_KEY) # 工具注册清单 TOOLS [ { name: search_products, description: 根据关键词、价格上限等条件搜索商品返回商品列表, input_schema: { type: object, properties: { keyword: {type: string, description: 搜索关键词}, max_price: {type: number, description: 价格上限}, category: {type: string, description: 商品类目}, }, }, }, { name: get_product_detail, description: 根据商品 ID 获取商品详细信息, input_schema: { type: object, properties: { product_id: {type: string, description: 商品 ID}, }, required: [product_id], }, }, { name: get_order_status, description: 根据订单号和用户 ID 查询订单状态, input_schema: { type: object, properties: { order_id: {type: string, description: 订单号}, user_id: {type: string, description: 用户 ID}, }, required: [order_id, user_id], }, }, ] # 工具名到函数实现的映射 TOOL_MAP { search_products: search_products, get_product_detail: get_product_detail, get_order_status: get_order_status, } def run_agent(user_input: str, user_id: str u001): messages [ { role: user, content: f当前用户 ID 是 {user_id}。请根据用户需求调用工具帮助用户。 f如果用户查询订单一定要使用正确的用户 ID。\n\n用户{user_input}, } ] while True: response client.messages.create( modelMODEL_NAME, max_tokensMAX_TOKENS, temperatureTEMPERATURE, toolsTOOLS, messagesmessages, ) # 检查模型是否请求调用工具 tool_calls [ block for block in response.content if block.type tool_use ] if not tool_calls: # 没有工具调用请求说明模型要直接回复用户 text_blocks [ block.text for block in response.content if block.type text ] return .join(text_blocks) # 将模型回复追加到对话历史 messages.append({ role: assistant, content: response.content, }) # 执行每个工具调用 for tool_call in tool_calls: tool_name tool_call.name tool_input tool_call.input if tool_name not in TOOL_MAP: tool_result {error: f未知工具: {tool_name}} else: tool_result TOOL_MAP[tool_name](**tool_input) # 追加工具调用结果 messages.append({ role: user, content: [ { type: tool_result, tool_use_id: tool_call.id, content: str(tool_result), } ], })这段代码里有几个细节值得注意第一轮 user 消息中我额外注入了user_id上下文。因为在真实场景中用户身份应该来自登录态而不是让模型猜测。while True循环是 Agent 运行的核心。每次模型可能返回文本也可能请求工具调用循环会持续到模型认为任务完成、不再请求工具为止。工具执行结果必须以tool_result的形式回传给模型并关联到对应的tool_use_id这样模型才能把结果和之前的工具调用对应起来。4.4 搭建 FastAPI 服务有了 Agent 核心逻辑最后一步是用 FastAPI 把能力暴露成 HTTP 接口# main.py from fastapi import FastAPI from pydantic import BaseModel from agent import run_agent app FastAPI(titleClaude Commerce Agent Demo) class ChatRequest(BaseModel): message: str user_id: str u001 class ChatResponse(BaseModel): reply: str app.post(/chat, response_modelChatResponse) async def chat(req: ChatRequest): reply run_agent(req.message, req.user_id) return ChatResponse(replyreply) app.get(/health) async def health(): return {status: ok}启动服务uvicorn main:app --host 0.0.0.0 --port 8000 --reload4.5 运行与验证使用 curl 测试商品推荐能力curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d {message: 帮我推荐一款 300 元以内的数码产品, user_id: u001}预期输出会包含模型根据search_products返回的数据整理出的推荐话术例如推荐蓝牙音箱和智能手环并附上价格、库存、评分信息。再测试订单查询能力curl -X POST http://localhost:8000/chat \ -H Content-Type: application/json \ -d {message: 帮我查一下订单 202501010001 的物流状态, user_id: u001}模型会识别出用户要查询订单自动调用get_order_status并将“已发货、顺丰单号 SF1234567890”这类信息组织成自然语言返回。5. 常见问题与排查思路5.1 API 连接异常在实际开发过程中很多同学会碰到连接 Anthropic API 失败的问题。这类报错的现象大概是unable to connect to anthropic services failed to connect to api.anthropic.com: status 403出现这类报错时建议按下面的顺序排查排查步骤操作说明1. 检查 Key 是否有效在控制台检查 API Key 状态Key 可能被删除、过期或额度透支2. 检查网络环境确认你的服务器能否正常访问外部网络域名解析是否正常、网络策略是否放行 HTTPS 443 端口3. 确认组织权限查看账号所属组织是否有 API 访问权限企业账号可能需要管理员单独开启4. 检查请求头确认代码中正确设置了x-api-key或AuthorizationHTTP 403 通常是鉴权问题5. 查看官方状态页确认 Anthropic API 服务本身是否发生故障排除服务端问题5.2 模型返回“工具不存在”类错误如果你在使用网关代理或中转服务时可能会看到类似这样的报错doesnt look like an anthropic model: expected a gateway model route reference这个报错一般是因为请求被路由到了不支持 Anthropic 原生产品的网关节点。解决思路是确认你的 API 接入地址是否直接指向 Anthropic 官方端点以及账号是否被配置为通过第三方网关转发。使用官方 SDK 默认配置时通常不会出现此问题。5.3 Agent 长时间不调用工具有时模型会“顾左右而言他”不调用工具就直接回复用户。常见原因有两个工具的description写得不清晰模型没理解到该用哪个工具。用户的提问比较模糊模型不确定该传什么参数。解决方案是在工具描述中补充触发条件。例如{ name: get_order_status, description: 当用户询问订单状态、物流信息、发货进度时调用此工具 必须提供订单号和用户 ID。不要尝试自己编造订单状态。, }5.4 使用本地或非官方接入时的兼容问题搜索热词中多次出现类似“Claude Code 如何接入非 Anthropic 服务”的问题。这里统一说明Anthropic 官方 SDK 默认指向官方 API 端点。如果你使用的是兼容 Anthropic API 协议的第三方平台需要修改base_url配置并且确认对方平台完整支持工具调用tool use协议否则 Commerce Agents 的核心循环将无法工作。client anthropic.Anthropic( api_keyANTHROPIC_API_KEY, base_urlhttps://your-compatible-gateway.example.com, )这里需要提醒的是使用第三方兼容网关时请务必确认其服务条款、数据安全政策和合规性不要将生产环境的用户数据发送到未经验证的第三方服务。6. 最佳实践与工程建议6.1 工具设计要遵循“最小权限”原则每个工具都应该只做一件事并且只暴露必要的参数。比如订单查询工具只需要order_id和user_id不要设计成“全量订单查询 用户信息返回”。这样即使模型调用出问题造成的风险也是可控的。真实项目中建议给每个工具增加权限级别权限级别工具示例说明L1 只读商品搜索、订单查询不修改数据风险较低L2 写入加购、创建订单修改数据需要操作留痕L3 高敏退款、改价、发货涉及资金或物权需要二次确认或人工审批6.2 对话上下文要控制长度Agent 的工具调用循环会不断累积消息长对话会快速消耗 token。建议对早期工具调用结果做截断只保留关键字段。设置最大轮数限制防止 Agent 陷入死循环。用户长时间未操作时主动清理会话上下文。6.3 为 Agent 提供“退路”再好的 Agent 也有无法处理的情况。一定要设计兜底逻辑当工具调用失败时模型应该如实告知用户而不是编造结果。当用户情绪激烈或涉及投诉时Agent 应该主动转接人工客服。所有涉及资金的操作必须在执行前让用户明确确认。6.4 日志体系要覆盖“全链路审计”在电商场景尤其是涉及支付、改价、退款的工具调用日志必须做到可追溯。建议记录以下信息用户 ID、会话 ID、消息时间戳。模型调用轮次、工具名称、传入参数。工具返回状态、耗时、异常堆栈。最终回复内容和用户补充反馈。每次工具调用的日志都应该关联到同一个会话 ID方便问题分析时完整还原现场。6.5 灰度发布与 A/B 测试Agent 的行为有不确定性直接全量上线风险较大。建议采用灰度发布策略先在测试环境用模拟数据验证工具链路。再对 5% 的真实用户开放观察工具调用成功率、用户满意度、订单转化率。根据数据调整提示词和工具参数逐步扩大流量。6.6 用“评测集”持续检验 Agent 质量不同于传统接口的单元测试Agent 的评估需要更全面的维度。建议构建一个评测集包含三类用例标准流程用例正常下单、正常查询。边界用例超预算、缺货商品、空搜索结果。恶意用例试图套取他人订单信息、试图让 Agent 绕过价格限制。每次修改提示词或工具逻辑后都跑一遍评测集对比回答准确率和工具调用正确率。7. 总结与下一步建议回过头来看Commerce Agents 真正难的并不是“接入 Claude API”这一步而是围绕模型把电商业务拆解成标准工具再为工具调用建立起安全、可控、可审计的运行环境。本文从概念出发带你拆解了购物智能体和商户智能体的核心链路并用一个最小示例走通了商品搜索、订单查询的完整工具调用闭环。无论你是打算做电商导购、客服自动化还是商户经营助手都可以基于这套开源蓝图做二次扩展。下一步建议优先从你自己的业务中挑一个高频、低风险的场景切入例如“订单状态自动查询”或“商品推荐”先跑通闭环再逐步加入支付、退款等高风险能力。动手实践永远比看文档学得快。打开你的编辑器把本文的示例跑起来替换成你自己的业务工具你会对 Agent 的运转逻辑有完全不同的理解。如果这篇文章对你有帮助欢迎收藏备用也欢迎在评论区交流你在电商智能体落地中遇到的问题。