在电商业务里用户侧和商户侧的体验优化往往是两套完全不同的工程问题。用户要的是“帮我找到最合适的商品、比价、下单、查物流”商户要的是“订单处理、退款审核、库存预警、经营报表”。这些流程看起来不复杂但一旦要让 AI 智能体接手就需要一套完整的“工具调用 权限控制 任务编排”方案。Anthropic 近期开源了 Claude Commerce Agents 智能体蓝图目的就是给开发者提供一个可直接参考的电商购物与商户智能体实现模板。它不是为了替代你的业务系统而是把“如何用 Claude 的 Tool Use 能力构建可靠电商 Agent”这件事拆成一个可运行、可扩展的参考项目。本文会从概念讲起逐步拆解 Claude Commerce Agents 的整体架构、核心设计思路并给出一个完整的 Python 实战示例帮助你理解购物智能体Shopping Agent是如何完成商品检索、比价、下单、物流查询的商户智能体Merchant Agent是如何处理订单、退款、库存的真实生产环境中Agent 工具设计有哪些安全红线与工程坑点。不管你是刚接触智能体开发的新手还是已经在做 AI 应用落地的工程师这篇文章都能帮你少走弯路。1. 背景与核心概念1.1 什么是 Claude Commerce AgentsClaude Commerce Agents 是 Anthropic 开源的一套智能体参考实现聚焦电商购物与商户运营两大场景。可以把它理解为“给 AI 智能体配套的电商工具集与流程蓝图”。传统电商系统提供的是 API 接口开发者需要自己写代码把“用户意图”翻译成“API 调用”。而 Commerce Agents 的思路是把 API 封装成 AI 可调用的工具Tools然后由大模型根据用户请求自动决定调用哪些工具、以什么顺序调用。例如一个用户说我想买一台 5000 元左右的轻薄本最好 16G 内存下午能送到。购物智能体需要自动完成调用商品搜索工具找出符合条件的商品。调用商品详情工具获取内存、重量、价格、配送时效。对比多个商品后向用户推荐。用户确认后调用下单工具。返回订单号并调用物流查询工具跟踪配送状态。整个过程在大模型内部表现为“规划-调用-观察-调整”的循环也就是 Agent 的核心工作模式。1.2 为什么需要 Commerce Agents先看传统电商系统的痛点场景传统实现方式存在的问题用户比价用户自己打开多个 App 搜索效率低体验差下单流程用户手动填写收货地址、优惠券步骤繁琐容易出错商户订单处理运营人员人工审核订单人力成本高处理慢退款审核人工核对退款条件审核标准不统一Commerce Agents 的核心价值是把这些重复性、规则性较强的流程交给 AI 智能体去编排和执行。它并不是要取代电商平台而是作为“智能中间层”连接用户/商户与大模型能力。1.3 智能体与普通 API 调用的区别这里要区分两个容易混淆的概念普通 API 调用模式用户输入 - 代码写死逻辑 - 调用固定 API - 返回结果比如一个天气查询机器人用户说“北京天气”代码里写死了解析逻辑把“北京”作为参数传给天气接口。这个模式没有“规划”能力。Agent 模式用户输入 - 大模型理解意图 - 选择并调用工具 A - 观察结果 - 选择并调用工具 B - 观察结果 - 得出最终答案Agent 模式的核心是工具选择与调用顺序由模型动态决定而不是开发者预先写死。Claude Commerce Agents 正是围绕这个模式设计的。开发者需要提供两样东西一组功能明确的工具Tool。一个系统级 Prompt告诉模型它的角色、边界和工作流程。模型负责“思考”工具负责“执行”两者通过 Tool Use 机制通信。2. 蓝图整体架构与核心设计2.1 双角色划分Claude Commerce Agents 开源蓝图主要有两个角色Shopping Agent购物智能体面向 C 端用户处理商品搜索与推荐商品对比与比价购物车管理下单与支付引导订单物流跟踪售后服务入口Merchant Agent商户智能体面向 B 端商户运营人员处理订单查询与统计订单状态修改退款审核库存管理与预警商品信息维护经营报表生成两个 Agent 共用一套工具调用基础设施但工具集合和权限边界完全不同。这一点很重要后面实战部分会详细说明。2.2 核心机制Tool Use 循环Claude 这类大模型本身不能直接执行外部操作必须通过“工具调用”间接完成。Commerce Agents 的运行时逻辑可以简化为下面的循环用户请求 | v [模型] 生成回复可能包含工具调用请求 | v [应用层] 解析模型返回的工具调用 | v [应用层] 执行对应函数拿到结构化结果 | v [应用层] 把工具结果回传给模型 | v [模型] 根据工具结果生成最终回复或继续调用下一批工具这个循环会一直持续直到模型认为任务完成并给出最终答案。2.3 权限边界与安全沙箱开源蓝图中特别值得关注的是权限边界设计。购物智能体和商户智能体的工具集合是完全隔离的购物智能体不能调用退款审核工具。商户智能体不能直接操作用户的支付账户。在设计上所有涉及资金、退款、库存修改等高风险操作都需要额外的确认步骤或人工审批。这是 Commerce Agents 能够安全落地的关键。2.4 数据流设计下面用 ASCII 图描述一个典型的购物查询数据流用户: 帮我找一款 5000 元以内的轻薄本 | v ---------------- tool call ------------------ | Claude 模型 | ------------------- | search_products | ---------------- ------------------ | | | ------- 商品列表JSON--------------- v ---------------- | 模型筛选、对比 | ---------------- | | tool call v ------------------ | get_product_info | ------------------ | | ------- 商品详情JSON------- v ---------------- | 生成推荐结果 | ----------------整个过程中模型不直接连数据库也不直接调第三方服务所有实际操作都由开发者实现的工具函数完成。3. 环境准备与项目结构3.1 运行环境说明在动手之前先明确本文示例的运行环境Python 3.9 及以上版本。需要安装anthropicSDK版本建议使用官方最新稳定版。如果需要真实调用 Claude API需要准备ANTHROPIC_API_KEY环境变量。为了让没有 API Key 的读者也能跑通流程本文会先提供一个“模拟工具调用模式”再给出真实接入方式。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路不绑定某个具体版本号。3.2 安装依赖创建项目文件夹并安装依赖mkdir claude-commerce-agents-demo cd claude-commerce-agents-demo python -m venv venv source venv/bin/activate # Windows 下执行 venv\Scripts\activate pip install anthropic python-dotenvanthropic用于调用 Claude APIpython-dotenv用于读取.env配置文件。3.3 项目目录结构推荐按下面的方式组织代码claude-commerce-agents-demo/ ├── .env ├── main.py # 入口文件演示购物 Agent ├── merchant.py # 商户 Agent 演示 ├── tools/ │ ├── __init__.py │ ├── shopping_tools.py # 购物侧工具 │ └── merchant_tools.py # 商户侧工具 ├── data/ │ ├── products.json # 模拟商品数据 │ └── orders.json # 模拟订单数据 └── agent/ ├── __init__.py └── core.py # Agent 工具调用循环核心这样拆分的好处是工具层、数据层、Agent 逻辑层相互独立方便后续替换成真实数据库。4. 购物智能体完整实战4.1 模拟商品数据为了让示例不依赖外部服务就能运行先准备一份模拟商品数据。文件路径data/products.json[ { id: p1001, name: 轻羽轻薄本 Pro, category: 笔记本电脑, price: 4699, memory: 16GB, weight: 1.2kg, stock: 25, shipping_time: 次日达 }, { id: p1002, name: 星航办公本 Air, category: 笔记本电脑, price: 5299, memory: 16GB, weight: 1.4kg, stock: 12, shipping_time: 次日达 }, { id: p1003, name: 极速游戏本, category: 笔记本电脑, price: 8999, memory: 32GB, weight: 2.1kg, stock: 8, shipping_time: 3日达 }, { id: p1004, name: 轻薄办公本青春版, category: 笔记本电脑, price: 3999, memory: 8GB, weight: 1.3kg, stock: 40, shipping_time: 5日达 } ]这里使用 JSON 文件模拟数据库便于理解。真实项目中工具函数内部应该换成 SQL 查询或微服务调用。4.2 实现购物工具集文件路径tools/shopping_tools.py 购物智能体工具集。 每个工具都是一段独立的函数接收参数并返回 JSON 可序列化的结果。 真实项目中这些函数内改为调用商品中心、交易中心等后端服务。 import json import os from typing import Any, Dict, List def _load_products() - List[Dict[str, Any]]: 从 JSON 文件加载商品数据。 base_dir os.path.dirname(os.path.dirname(os.path.abspath(__file__))) path os.path.join(base_dir, data, products.json) with open(path, r, encodingutf-8) as f: return json.load(f) def search_products(keyword: str , max_price: float 0) - List[Dict[str, Any]]: 搜索商品。 参数 keyword: 商品名称关键词 max_price: 最高价格0 表示不限制 返回 符合条件且仍有库存的商品列表 products _load_products() result [] for p in products: if keyword and keyword not in p[name]: continue if max_price and p[price] max_price: continue if p[stock] 0: continue result.append(p) return result def get_product_detail(product_id: str) - Dict[str, Any]: 获取商品详情。 products _load_products() for p in products: if p[id] product_id: return p return {error: f商品 {product_id} 不存在} def create_order(user_id: str, product_id: str, quantity: int 1) - Dict[str, Any]: 创建订单。 注意真实系统中这里必须校验用户身份、地址、支付方式 并通过幂等键防止重复下单。 product get_product_detail(product_id) if error in product: return product if product[stock] quantity: return {error: 库存不足} # 模拟扣减库存。真实项目应使用数据库事务 行锁。 if quantity 0: return {error: 购买数量必须大于 0} total_price product[price] * quantity order { order_id: fORD{user_id}{product_id}, product_id: product_id, product_name: product[name], quantity: quantity, total_price: total_price, status: CREATED, shipping_time: product[shipping_time], } return order def track_order(order_id: str) - Dict[str, Any]: 查询订单物流状态。 # 这里应接入真实的订单查询服务 return { order_id: order_id, status: SHIPPED, current_location: 华东转运中心, estimated_delivery: 明日 18:00 前, } # 工具注册表给模型使用的工具元信息 SHOPPING_TOOLS [ { name: search_products, description: 搜索商品支持关键词和最高价格过滤, input_schema: { type: object, properties: { keyword: {type: string, description: 商品名称关键词}, max_price: {type: number, description: 最高价格0 表示不限} } } }, { name: get_product_detail, description: 根据商品 ID 获取商品详细信息, input_schema: { type: object, properties: { product_id: {type: string, description: 商品 ID} }, required: [product_id] } }, { name: create_order, description: 创建订单购买指定商品, input_schema: { type: object, properties: { user_id: {type: string, description: 用户 ID}, product_id: {type: string, description: 商品 ID}, quantity: {type: integer, description: 购买数量} }, required: [user_id, product_id] } }, { name: track_order, description: 查询订单物流信息, input_schema: { type: object, properties: { order_id: {type: string, description: 订单 ID} }, required: [order_id] } } ]工具函数的实现并不复杂关键是SHOPPING_TOOLS这个注册表它描述了每个工具的名称、用途和参数结构。Claude API 会根据这些信息在需要的时候主动发起工具调用。4.3 实现 Agent 工具调用核心循环文件路径agent/core.py Agent 工具调用循环核心。 这个模块负责 1. 将用户消息发送给 Claude 2. 判断模型是否请求调用工具 3. 如果有工具调用请求执行对应函数 4. 把结果传回模型继续对话 5. 直到模型返回最终文字回复 from typing import Any, Callable, Dict, List, Optional import anthropic # 工具名称到实际函数的映射 TOOL_MAP: Dict[str, Callable[..., Any]] {} def register_tool_map(tool_map: Dict[str, Callable[..., Any]]): 注册工具函数映射。 TOOL_MAP.update(tool_map) def run_agent( client: anthropic.Anthropic, model_name: str, system_prompt: str, tools: List[Dict[str, Any]], user_message: str, max_iterations: int 5, ) - str: 运行一个单轮 Agent 任务。 参数 client: Anthropic 客户端 model_name: Claude 模型名称 system_prompt: 系统提示词 tools: 工具注册表 user_message: 用户输入 max_iterations: 最大工具调用轮数防止死循环 返回 最终文本回复 messages [{role: user, content: user_message}] iteration 0 while iteration max_iterations: response client.messages.create( modelmodel_name, max_tokens2048, systemsystem_prompt, toolstools, messagesmessages, ) # 检查返回内容中是否有工具调用请求 tool_calls [] content_blocks response.content for block in content_blocks: if block.type tool_use: tool_calls.append({ id: block.id, name: block.name, input: block.input, }) # 如果没有工具调用说明模型给出了最终回复 if not tool_calls: final_text for block in content_blocks: if block.type text: final_text block.text return final_text or 模型未返回文本内容 # 把带工具调用的 assistant 消息加入历史 messages.append(response.model_dump()) # 执行工具调用并收集结果 tool_result_blocks [] for call in tool_calls: func TOOL_MAP.get(call[name]) if not func: tool_result_blocks.append({ type: tool_result, tool_use_id: call[id], content: f未知工具: {call[name]}, }) continue try: result func(**call[input]) import json content json.dumps(result, ensure_asciiFalse, defaultstr) except Exception as e: content f工具执行异常: {str(e)} tool_result_blocks.append({ type: tool_result, tool_use_id: call[id], content: content, }) # 将工具执行结果作为 user 消息继续对话 messages.append({ role: user, content: tool_result_blocks, }) iteration 1 return 已达最大工具调用轮数任务未完成。这个循环是 Agent 的核心骨架。我在里面做了三层防护max_iterations限制最大轮数避免模型反复调用工具导致成本失控。每种工具都做了异常捕获避免单个工具出错中断整个 Agent。每次工具调用的结果都转为 JSON 字符串确保模型能稳定解析。4.4 购物 Agent 主流程文件路径main.py 购物智能体主入口。 运行前需要设置环境变量 ANTHROPIC_API_KEY。 如果没有 API Key可以先阅读代码逻辑了解 Agent 工作流程。 import os import anthropic from dotenv import load_dotenv from agent.core import run_agent, register_tool_map from tools.shopping_tools import ( SHOPPING_TOOLS, get_product_detail, search_products, create_order, track_order, ) load_dotenv() def build_shopping_system_prompt() - str: 构造购物智能体的系统提示词。 return 你是一个专业的购物助手。你的职责是帮助用户找到合适的商品、完成下单和查询物流。 工作流程 1. 用户提出购物需求后先调用 search_products 搜索商品。 2. 如果搜索结果较多调用 get_product_detail 获取详细参数进行对比。 3. 向用户清晰展示推荐结果包括价格、配置、配送时效。 4. 只有在用户明确确认购买时才能调用 create_order 创建订单。 5. 创建订单后可以调用 track_order 查询物流。 安全规则 - 未获得用户确认前不得创建订单。 - 如果用户的需求不够明确先询问清楚价格预算、配置要求等再搜索。 - 不要虚构不存在的商品参数。 - 如果搜索没有结果如实告知用户不要强行推荐。 def main(): api_key os.getenv(ANTHROPIC_API_KEY) if not api_key: print(请先设置 ANTHROPIC_API_KEY 环境变量) return client anthropic.Anthropic(api_keyapi_key) # 注册购物工具 register_tool_map({ search_products: search_products, get_product_detail: get_product_detail, create_order: create_order, track_order: track_order, }) system_prompt build_shopping_system_prompt() user_input 我想买一台 5000 元以内的轻薄本16G 内存帮我推荐一下 print(用户, user_input) print( * 50) result run_agent( clientclient, model_nameclaude-sonnet-4-5, system_promptsystem_prompt, toolsSHOPPING_TOOLS, user_messageuser_input, max_iterations5, ) print(Agent, result) if __name__ __main__: main()有一点要特别说明model_name我写的是claude-sonnet-4-5不同时间段 Anthropic 的模型名称会变化。你应该以官方文档或 API 返回的实际模型名为准。如果你的账号可用模型不叫这个名字配置会失败。4.5 运行效果说明如果你配置了可用的 API Key运行python main.py后大致的交互过程是模型收到用户需求。模型觉得需要搜索于是调用search_products(keyword轻薄本, max_price5000)。工具返回p1001、p1004两个结果。模型发现两个商品内存不同再次调用get_product_detail获取详情。模型综合信息后给出推荐结论。最终输出类似用户 我想买一台 5000 元以内的轻薄本16G 内存帮我推荐一下 Agent 根据您的需求我为您筛选出以下商品 1. 轻羽轻薄本 Prop1001 - 价格4699 元 - 内存16GB - 重量1.2kg - 配送次日达 这款是目前最符合您预算和配置要求的机型性价比高、重量轻、配送快。这只是模型可能的一种回复实际内容会根据模型输出变化。4.6 没有 API Key 时如何理解流程如果你暂时没有 API Key可以直接阅读agent/core.py里的循环逻辑或者自己写一个假的工具调用响应来模拟模型行为。例如# mock_run.py —— 模拟工具调用循环无需 API Key def mock_model_response(messages): 模拟模型输出。第一次调用工具第二次返回文本。 if len(messages) 1: return { role: assistant, content: [ { type: tool_use, id: call_001, name: search_products, input: {keyword: 轻薄本, max_price: 5000}, } ], } else: return { role: assistant, content: [ {type: text, text: 我找到了以下商品推荐轻羽轻薄本 Pro。} ], }这段代码演示了 Agent 循环里最关键的一点模型先输出工具调用请求应用层执行工具把结果放回消息历史再让模型继续。理解了这一点后面接入真实大模型就很简单了。5. 商户智能体实现5.1 商户侧需求分析商户智能体和购物智能体最大的区别在于商户工具会直接影响业务数据例如修改订单状态、审批退款、调整库存。这些操作如果失控后果比购物推荐严重得多。因此商户智能体的设计要额外关注权限最小化每个工具只做一件事。人工确认高风险操作需要二次确认。审计日志记录每一次工具调用。操作可回滚涉及数据变更时提供补偿操作。5.2 商户工具集实现文件路径tools/merchant_tools.py 商户智能体工具集。 注意商户工具涉及订单、退款、库存等敏感操作 真实生产环境必须增加权限校验、操作审计和幂等控制。 from typing import Any, Dict, List # 模拟订单数据生产环境应替换为数据库查询 MOCK_ORDERS [ { order_id: ORD20250001, product_id: p1001, quantity: 2, total_price: 9398, status: PAID, customer: 张三, }, { order_id: ORD20250002, product_id: p1002, quantity: 1, total_price: 5299, status: REFUNDING, customer: 李四, }, ] def list_orders(status: str ) - List[Dict[str, Any]]: 查询订单列表。 if not status: return MOCK_ORDERS return [o for o in MOCK_ORDERS if o[status] status] def approve_refund(order_id: str) - Dict[str, Any]: 审批退款。 安全提示实际系统中这一步通常还需要 1. 校验当前操作者是否有退款审批权限 2. 检查订单当前状态是否允许退款 3. 记录操作者、时间、原因到审计日志 4. 通过幂等键防止重复退款 for o in MOCK_ORDERS: if o[order_id] order_id: if o[status] ! REFUNDING: return {error: f订单 {order_id} 当前状态不允许退款} o[status] REFUNDED return { order_id: order_id, status: REFUNDED, message: 退款审批通过, } return {error: f订单 {order_id} 不存在} def update_inventory(product_id: str, delta: int) - Dict[str, Any]: 调整库存。 delta 为正表示增加库存为负表示扣减库存。 真实系统应使用数据库事务防止并发超卖。 from tools.shopping_tools import get_product_detail product get_product_detail(product_id) if error in product: return product new_stock product[stock] delta if new_stock 0: return {error: f库存不足当前库存 {product[stock]}} # 真实系统应执行 UPDATE product SET stock stock delta WHERE id ... product[stock] new_stock return { product_id: product_id, current_stock: new_stock, message: 库存更新成功, } MERCHANT_TOOLS [ { name: list_orders, description: 查询订单列表可按状态过滤, input_schema: { type: object, properties: { status: {type: string, description: 订单状态如 PAID、REFUNDING} } } }, { name: approve_refund, description: 审批通过退款申请。高风险操作必须确认用户明确要求退款后才可调用。, input_schema: { type: object, properties: { order_id: {type: string, description: 订单 ID} }, required: [order_id] } }, { name: update_inventory, description: 调整商品库存数量, input_schema: { type: object, properties: { product_id: {type: string, description: 商品 ID}, delta: {type: integer, description: 库存变化量正数增加负数扣减} }, required: [product_id, delta] } } ]5.3 商户 Agent 系统提示词商户 Agent 的系统提示词要比购物 Agent 更严格重点强调“不主动执行敏感操作”。def build_merchant_system_prompt() - str: return 你是一个商户运营助手帮助商户处理订单、退款和库存管理。 工作流程 1. 商户咨询订单情况时调用 list_orders 查询。 2. 商户要求退款审批时先确认订单状态再调用 approve_refund。 3. 商户需要调整库存时调用 update_inventory。 安全规则 - 退款、库存修改属于敏感操作。没有商户明确指令时绝不主动调用这些工具。 - 如果参数不明确先向商户确认清楚再执行。 - 退款操作执行前必须展示订单信息给商户获得再次确认。 - 不要批量修改订单状态一次只能处理一个订单。 5.4 商户 Agent 入口文件路径merchant.pyimport os import anthropic from dotenv import load_dotenv from agent.core import run_agent, register_tool_map from tools.merchant_tools import ( MERCHANT_TOOLS, list_orders, approve_refund, update_inventory, ) from tools.merchant_tools import build_merchant_system_prompt load_dotenv() def main(): api_key os.getenv(ANTHROPIC_API_KEY) if not api_key: print(请先设置 ANTHROPIC_API_KEY 环境变量) return client anthropic.Anthropic(api_keyapi_key) register_tool_map({ list_orders: list_orders, approve_refund: approve_refund, update_inventory: update_inventory, }) result run_agent( clientclient, model_nameclaude-sonnet-4-5, system_promptbuild_merchant_system_prompt(), toolsMERCHANT_TOOLS, user_message有哪些退款中的订单, max_iterations5, ) print(Agent, result) if __name__ __main__: main()商户智能体的代码结构几乎和购物智能体一样区别在于工具集合与权限边界。这也说明 Commerce Agents 蓝图的核心理念工具决定了 Agent 的能力边界Prompt 决定了 Agent 的行为边界。6. 从 Demo 到生产的关键改造开源蓝图给你的是一个可运行的最小骨架。要真正应用到生产环境下面几项改造是必须的。6.1 数据层替换Demo 中商品和订单数据都是 JSON 文件或内存列表。生产环境必须替换为真实的数据库或后端服务。真实项目的工具函数应该是这样的# 以搜索商品为例 def search_products(keyword: str , max_price: float 0) - List[Dict[str, Any]]: 真实实现通过商品中心服务或数据库查询商品。 # 1. 过滤条件校验 if max_price 0: return {error: 价格不能为负数} # 2. 调用商品服务示例伪代码 # products product_service.search( # keywordkeyword, # max_pricemax_price, # page_size10, # ) # return products # 3. 统一异常处理 # try: # ... # except ExternalServiceException: # return {error: 商品服务暂时不可用} ...替换过程中要特别注意工具函数不要直接在内部写 SQL 拼接字符串防止注入。数据库查询要设置超时时间避免 Agent 长时间挂起。返回给模型的数据要控制大小不要一次返回几十万条记录。6.2 幂等控制Agent 最大的风险之一是重复执行。模型可能在网络重试后把同一个下单请求发送两次。解决办法是引入幂等键# 工具函数中增加幂等键校验 def create_order_with_idempotency(user_id: str, product_id: str, idempotency_key: str) - Dict[str, Any]: # 先检查 Redis / DB 中是否已存在该幂等键 # 如果存在直接返回之前的处理结果不重复下单 ...在上面的 Agent 循环中如果模型连续两次调用create_order应用层应该通过幂等键识别出这是重复请求而不是真的下两个订单。6.3 人工确认机制对资金、退款、库存这类高风险操作生产环境建议引入“人工确认队列”模型调用 approve_refund | v 写入待确认任务表状态PENDING_APPROVAL | v 运营人员在小程序中点击“确认” | v 确认后系统执行退款Agent 的工具函数此时只负责“创建审批任务”不直接执行退款。这个改造能极大降低 AI 失控带来的业务风险。6.4 审计日志每次工具调用都要记录调用时间用户/商户 ID工具名称参数内容执行结果模型生成的中间思考如果允许记录日志不仅能用于排错也是后续合规审计的重要依据。6.5 成本控制与限流大模型 Agent 的调用成本包括 token 成本和工具执行消耗。建议设置单次任务的最大工具调用轮数。对工具返回结果做长度限制避免大 JSON 撑爆上下文。使用模型缓存功能如 prompt caching降低系统提示词重复计费。对模型执行结果做超时控制。7. 常见问题与排查思路在实际开发 Claude Commerce Agents 的过程中容易遇到以下几类问题。7.1 工具参数格式不符合 JSON Schema现象模型生成的工具参数在你的函数中取不到预期字段。原因工具的input_schema描述不够严格模型自由发挥了。解决思路在input_schema中把必填字段加入required。为每个字段写清类型例如type: number。函数的参数必须和 schema 完全一致。函数内部增加参数校验不合法就返回{error: ...}。7.2 模型陷入工具调用死循环现象Agent 不停调用工具始终不生成最终回复。原因工具返回的数据与模型预期不符模型想通过反复调用修复。解决思路给run_agent设置合理的max_iterations建议 5 到 8。检查工具返回的 JSON 是否简洁清晰。在系统提示词中增加“如果已经拿到足够信息请直接给出答案”的约束。7.3 工具执行报错导致 Agent 中断现象某个工具抛异常后Agent 直接结束。原因agent/core.py中的异常处理不完善或工具函数内部没有捕获业务异常。解决思路工具函数内部用 try-except 包裹业务逻辑统一返回 JSON 错误信息。不要抛 Python 异常给模型模型无法理解KeyError这类信息。在 Agent 循环中为每个工具调用增加独立的异常捕获。7.4 连接 API 失败或返回 403现象使用 Claude API 时出现无法连接或 403 状态码。原因常见原因包括 API Key 无效、账号权限不足、网络环境受限、模型名称错误。解决思路检查ANTHROPIC_API_KEY是否正确设置。验证所使用的模型名称在当前账号下是否可用。查看官方 API 文档确认请求地址是否需要特殊处理。增加重试机制和超时配置避免临时故障导致 Agent 中断。client anthropic.Anthropic( api_keyapi_key, timeout60.0, max_retries2, )7.5 工具返回的数据太大现象某个工具返回几千条商品模型无法有效处理且 token 消耗极高。解决思路工具函数内部做好分页只返回前 N 条。不要把全量数据塞给模型先做聚合统计。推荐场景中先返回 top 5 商品再让模型决定是否查看详情。问题现象常见原因解决思路授权失败 / 403API Key 无效或权限不足检查 Key 与账号权限模型不调用工具工具描述不清 / 系统提示词不够明确优化工具 description 和 system prompt工具参数取不到值JSON Schema 定义不严谨补充 required 和字段类型重复下单网络重试导致重复调用引入幂等键Agent 死循环工具返回值不满足模型预期限制轮数、优化返回结构8. 最佳实践与工程建议8.1 工具设计原则工具是 Agent 能力的边界。设计时记住一句话一个工具只做一件事并把事情描述清楚。反面示例工具名process_order 描述处理订单这个工具过于模糊。模型不知道它到底能做什么也不知道能否用于退款。正面示例工具名approve_refund 描述审批通过指定订单的退款申请。仅当商户明确要求退款时调用。清晰、单一、有边界。8.2 Prompt 工程要点系统提示词中要写明角色的工作目标。工具调用顺序。何时不能调用工具。参数不明确时怎么办。如何向用户确认关键操作。不建议把大段业务规则都写进 Prompt。复杂的规则应下沉到工具函数里做防呆校验Prompt 只负责约束模型行为。8.3 安全红线以下是必须遵守的几条红线涉及支付、退款、库存修改的高危工具不能在单轮对话中直接执行。Agent 不能拥有比真实操作者更高的权限。所有敏感操作必须有审计日志。生产环境工具调用必须做限流。不要让模型自由拼接 SQL 或 shell 命令。8.4 可观测性生产环境的 Agent 一定要有 trace 链路建议打印如下信息[tool_use] call_idcall_001 namesearch_products input{keyword:轻薄本} [tool_result] call_idcall_001 statussuccess result_size2 [model_message] tokens234 stop_reasonturn_limit这些日志能帮你快速定位“模型到底做了哪些决策”。8.5 渐进式上线不要一开始就把所有电商功能交给 Agent。推荐顺序先用只读工具上线商品搜索、订单查询。再加入低风险写操作购物车管理。最后在人工审核机制到位后再上线退款、库存修改等高危操作。每一步都要在小流量下验证模型行为和工具稳定性。9. 动手实践建议如果你想真正掌握 Claude Commerce Agents不建议只看不练。这里给出一条实际可行的学习路径第一步先阅读agent/core.py里的工具调用循环弄清楚模型、应用层、工具函数三者的关系。第二步自己写一个只包含一个工具的 Agent比如“查天气”。用户说“北京今天适合出门吗”Agent 调用天气工具后给出建议。这个例子虽然简单但能帮你跑通整个链路。第三步将本文的购物 Demo 跑起来。如果有 API Key直接运行如果没有参考mock_run.py自己模拟模型输出。第四步为购物 Agent 增加一个“收藏商品”工具。注意定义好参数 schema并在工具函数中维护一个收藏列表。第五步尝试把商户 Agent 的approve_refund改造成“创建审批任务 人工确认”的模式。这一步做完你就真正理解了生产级 Agent 的安全设计。每次改动后记录模型的行为变化。一个好用的 Agent不是一次写出来的而是在不断调整工具描述、Prompt 和边界条件中打磨出来的。如果你在搭建过程中遇到 Agent 不调用工具、参数格式错误或安全设计拿不准的地方欢迎在评论区带上报错信息或代码片段我们继续排查。
Claude Commerce Agents开源蓝图：电商AI智能体与Tool Use实战解析
在电商业务里用户侧和商户侧的体验优化往往是两套完全不同的工程问题。用户要的是“帮我找到最合适的商品、比价、下单、查物流”商户要的是“订单处理、退款审核、库存预警、经营报表”。这些流程看起来不复杂但一旦要让 AI 智能体接手就需要一套完整的“工具调用 权限控制 任务编排”方案。Anthropic 近期开源了 Claude Commerce Agents 智能体蓝图目的就是给开发者提供一个可直接参考的电商购物与商户智能体实现模板。它不是为了替代你的业务系统而是把“如何用 Claude 的 Tool Use 能力构建可靠电商 Agent”这件事拆成一个可运行、可扩展的参考项目。本文会从概念讲起逐步拆解 Claude Commerce Agents 的整体架构、核心设计思路并给出一个完整的 Python 实战示例帮助你理解购物智能体Shopping Agent是如何完成商品检索、比价、下单、物流查询的商户智能体Merchant Agent是如何处理订单、退款、库存的真实生产环境中Agent 工具设计有哪些安全红线与工程坑点。不管你是刚接触智能体开发的新手还是已经在做 AI 应用落地的工程师这篇文章都能帮你少走弯路。1. 背景与核心概念1.1 什么是 Claude Commerce AgentsClaude Commerce Agents 是 Anthropic 开源的一套智能体参考实现聚焦电商购物与商户运营两大场景。可以把它理解为“给 AI 智能体配套的电商工具集与流程蓝图”。传统电商系统提供的是 API 接口开发者需要自己写代码把“用户意图”翻译成“API 调用”。而 Commerce Agents 的思路是把 API 封装成 AI 可调用的工具Tools然后由大模型根据用户请求自动决定调用哪些工具、以什么顺序调用。例如一个用户说我想买一台 5000 元左右的轻薄本最好 16G 内存下午能送到。购物智能体需要自动完成调用商品搜索工具找出符合条件的商品。调用商品详情工具获取内存、重量、价格、配送时效。对比多个商品后向用户推荐。用户确认后调用下单工具。返回订单号并调用物流查询工具跟踪配送状态。整个过程在大模型内部表现为“规划-调用-观察-调整”的循环也就是 Agent 的核心工作模式。1.2 为什么需要 Commerce Agents先看传统电商系统的痛点场景传统实现方式存在的问题用户比价用户自己打开多个 App 搜索效率低体验差下单流程用户手动填写收货地址、优惠券步骤繁琐容易出错商户订单处理运营人员人工审核订单人力成本高处理慢退款审核人工核对退款条件审核标准不统一Commerce Agents 的核心价值是把这些重复性、规则性较强的流程交给 AI 智能体去编排和执行。它并不是要取代电商平台而是作为“智能中间层”连接用户/商户与大模型能力。1.3 智能体与普通 API 调用的区别这里要区分两个容易混淆的概念普通 API 调用模式用户输入 - 代码写死逻辑 - 调用固定 API - 返回结果比如一个天气查询机器人用户说“北京天气”代码里写死了解析逻辑把“北京”作为参数传给天气接口。这个模式没有“规划”能力。Agent 模式用户输入 - 大模型理解意图 - 选择并调用工具 A - 观察结果 - 选择并调用工具 B - 观察结果 - 得出最终答案Agent 模式的核心是工具选择与调用顺序由模型动态决定而不是开发者预先写死。Claude Commerce Agents 正是围绕这个模式设计的。开发者需要提供两样东西一组功能明确的工具Tool。一个系统级 Prompt告诉模型它的角色、边界和工作流程。模型负责“思考”工具负责“执行”两者通过 Tool Use 机制通信。2. 蓝图整体架构与核心设计2.1 双角色划分Claude Commerce Agents 开源蓝图主要有两个角色Shopping Agent购物智能体面向 C 端用户处理商品搜索与推荐商品对比与比价购物车管理下单与支付引导订单物流跟踪售后服务入口Merchant Agent商户智能体面向 B 端商户运营人员处理订单查询与统计订单状态修改退款审核库存管理与预警商品信息维护经营报表生成两个 Agent 共用一套工具调用基础设施但工具集合和权限边界完全不同。这一点很重要后面实战部分会详细说明。2.2 核心机制Tool Use 循环Claude 这类大模型本身不能直接执行外部操作必须通过“工具调用”间接完成。Commerce Agents 的运行时逻辑可以简化为下面的循环用户请求 | v [模型] 生成回复可能包含工具调用请求 | v [应用层] 解析模型返回的工具调用 | v [应用层] 执行对应函数拿到结构化结果 | v [应用层] 把工具结果回传给模型 | v [模型] 根据工具结果生成最终回复或继续调用下一批工具这个循环会一直持续直到模型认为任务完成并给出最终答案。2.3 权限边界与安全沙箱开源蓝图中特别值得关注的是权限边界设计。购物智能体和商户智能体的工具集合是完全隔离的购物智能体不能调用退款审核工具。商户智能体不能直接操作用户的支付账户。在设计上所有涉及资金、退款、库存修改等高风险操作都需要额外的确认步骤或人工审批。这是 Commerce Agents 能够安全落地的关键。2.4 数据流设计下面用 ASCII 图描述一个典型的购物查询数据流用户: 帮我找一款 5000 元以内的轻薄本 | v ---------------- tool call ------------------ | Claude 模型 | ------------------- | search_products | ---------------- ------------------ | | | ------- 商品列表JSON--------------- v ---------------- | 模型筛选、对比 | ---------------- | | tool call v ------------------ | get_product_info | ------------------ | | ------- 商品详情JSON------- v ---------------- | 生成推荐结果 | ----------------整个过程中模型不直接连数据库也不直接调第三方服务所有实际操作都由开发者实现的工具函数完成。3. 环境准备与项目结构3.1 运行环境说明在动手之前先明确本文示例的运行环境Python 3.9 及以上版本。需要安装anthropicSDK版本建议使用官方最新稳定版。如果需要真实调用 Claude API需要准备ANTHROPIC_API_KEY环境变量。为了让没有 API Key 的读者也能跑通流程本文会先提供一个“模拟工具调用模式”再给出真实接入方式。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路不绑定某个具体版本号。3.2 安装依赖创建项目文件夹并安装依赖mkdir claude-commerce-agents-demo cd claude-commerce-agents-demo python -m venv venv source venv/bin/activate # Windows 下执行 venv\Scripts\activate pip install anthropic python-dotenvanthropic用于调用 Claude APIpython-dotenv用于读取.env配置文件。3.3 项目目录结构推荐按下面的方式组织代码claude-commerce-agents-demo/ ├── .env ├── main.py # 入口文件演示购物 Agent ├── merchant.py # 商户 Agent 演示 ├── tools/ │ ├── __init__.py │ ├── shopping_tools.py # 购物侧工具 │ └── merchant_tools.py # 商户侧工具 ├── data/ │ ├── products.json # 模拟商品数据 │ └── orders.json # 模拟订单数据 └── agent/ ├── __init__.py └── core.py # Agent 工具调用循环核心这样拆分的好处是工具层、数据层、Agent 逻辑层相互独立方便后续替换成真实数据库。4. 购物智能体完整实战4.1 模拟商品数据为了让示例不依赖外部服务就能运行先准备一份模拟商品数据。文件路径data/products.json[ { id: p1001, name: 轻羽轻薄本 Pro, category: 笔记本电脑, price: 4699, memory: 16GB, weight: 1.2kg, stock: 25, shipping_time: 次日达 }, { id: p1002, name: 星航办公本 Air, category: 笔记本电脑, price: 5299, memory: 16GB, weight: 1.4kg, stock: 12, shipping_time: 次日达 }, { id: p1003, name: 极速游戏本, category: 笔记本电脑, price: 8999, memory: 32GB, weight: 2.1kg, stock: 8, shipping_time: 3日达 }, { id: p1004, name: 轻薄办公本青春版, category: 笔记本电脑, price: 3999, memory: 8GB, weight: 1.3kg, stock: 40, shipping_time: 5日达 } ]这里使用 JSON 文件模拟数据库便于理解。真实项目中工具函数内部应该换成 SQL 查询或微服务调用。4.2 实现购物工具集文件路径tools/shopping_tools.py 购物智能体工具集。 每个工具都是一段独立的函数接收参数并返回 JSON 可序列化的结果。 真实项目中这些函数内改为调用商品中心、交易中心等后端服务。 import json import os from typing import Any, Dict, List def _load_products() - List[Dict[str, Any]]: 从 JSON 文件加载商品数据。 base_dir os.path.dirname(os.path.dirname(os.path.abspath(__file__))) path os.path.join(base_dir, data, products.json) with open(path, r, encodingutf-8) as f: return json.load(f) def search_products(keyword: str , max_price: float 0) - List[Dict[str, Any]]: 搜索商品。 参数 keyword: 商品名称关键词 max_price: 最高价格0 表示不限制 返回 符合条件且仍有库存的商品列表 products _load_products() result [] for p in products: if keyword and keyword not in p[name]: continue if max_price and p[price] max_price: continue if p[stock] 0: continue result.append(p) return result def get_product_detail(product_id: str) - Dict[str, Any]: 获取商品详情。 products _load_products() for p in products: if p[id] product_id: return p return {error: f商品 {product_id} 不存在} def create_order(user_id: str, product_id: str, quantity: int 1) - Dict[str, Any]: 创建订单。 注意真实系统中这里必须校验用户身份、地址、支付方式 并通过幂等键防止重复下单。 product get_product_detail(product_id) if error in product: return product if product[stock] quantity: return {error: 库存不足} # 模拟扣减库存。真实项目应使用数据库事务 行锁。 if quantity 0: return {error: 购买数量必须大于 0} total_price product[price] * quantity order { order_id: fORD{user_id}{product_id}, product_id: product_id, product_name: product[name], quantity: quantity, total_price: total_price, status: CREATED, shipping_time: product[shipping_time], } return order def track_order(order_id: str) - Dict[str, Any]: 查询订单物流状态。 # 这里应接入真实的订单查询服务 return { order_id: order_id, status: SHIPPED, current_location: 华东转运中心, estimated_delivery: 明日 18:00 前, } # 工具注册表给模型使用的工具元信息 SHOPPING_TOOLS [ { name: search_products, description: 搜索商品支持关键词和最高价格过滤, input_schema: { type: object, properties: { keyword: {type: string, description: 商品名称关键词}, max_price: {type: number, description: 最高价格0 表示不限} } } }, { name: get_product_detail, description: 根据商品 ID 获取商品详细信息, input_schema: { type: object, properties: { product_id: {type: string, description: 商品 ID} }, required: [product_id] } }, { name: create_order, description: 创建订单购买指定商品, input_schema: { type: object, properties: { user_id: {type: string, description: 用户 ID}, product_id: {type: string, description: 商品 ID}, quantity: {type: integer, description: 购买数量} }, required: [user_id, product_id] } }, { name: track_order, description: 查询订单物流信息, input_schema: { type: object, properties: { order_id: {type: string, description: 订单 ID} }, required: [order_id] } } ]工具函数的实现并不复杂关键是SHOPPING_TOOLS这个注册表它描述了每个工具的名称、用途和参数结构。Claude API 会根据这些信息在需要的时候主动发起工具调用。4.3 实现 Agent 工具调用核心循环文件路径agent/core.py Agent 工具调用循环核心。 这个模块负责 1. 将用户消息发送给 Claude 2. 判断模型是否请求调用工具 3. 如果有工具调用请求执行对应函数 4. 把结果传回模型继续对话 5. 直到模型返回最终文字回复 from typing import Any, Callable, Dict, List, Optional import anthropic # 工具名称到实际函数的映射 TOOL_MAP: Dict[str, Callable[..., Any]] {} def register_tool_map(tool_map: Dict[str, Callable[..., Any]]): 注册工具函数映射。 TOOL_MAP.update(tool_map) def run_agent( client: anthropic.Anthropic, model_name: str, system_prompt: str, tools: List[Dict[str, Any]], user_message: str, max_iterations: int 5, ) - str: 运行一个单轮 Agent 任务。 参数 client: Anthropic 客户端 model_name: Claude 模型名称 system_prompt: 系统提示词 tools: 工具注册表 user_message: 用户输入 max_iterations: 最大工具调用轮数防止死循环 返回 最终文本回复 messages [{role: user, content: user_message}] iteration 0 while iteration max_iterations: response client.messages.create( modelmodel_name, max_tokens2048, systemsystem_prompt, toolstools, messagesmessages, ) # 检查返回内容中是否有工具调用请求 tool_calls [] content_blocks response.content for block in content_blocks: if block.type tool_use: tool_calls.append({ id: block.id, name: block.name, input: block.input, }) # 如果没有工具调用说明模型给出了最终回复 if not tool_calls: final_text for block in content_blocks: if block.type text: final_text block.text return final_text or 模型未返回文本内容 # 把带工具调用的 assistant 消息加入历史 messages.append(response.model_dump()) # 执行工具调用并收集结果 tool_result_blocks [] for call in tool_calls: func TOOL_MAP.get(call[name]) if not func: tool_result_blocks.append({ type: tool_result, tool_use_id: call[id], content: f未知工具: {call[name]}, }) continue try: result func(**call[input]) import json content json.dumps(result, ensure_asciiFalse, defaultstr) except Exception as e: content f工具执行异常: {str(e)} tool_result_blocks.append({ type: tool_result, tool_use_id: call[id], content: content, }) # 将工具执行结果作为 user 消息继续对话 messages.append({ role: user, content: tool_result_blocks, }) iteration 1 return 已达最大工具调用轮数任务未完成。这个循环是 Agent 的核心骨架。我在里面做了三层防护max_iterations限制最大轮数避免模型反复调用工具导致成本失控。每种工具都做了异常捕获避免单个工具出错中断整个 Agent。每次工具调用的结果都转为 JSON 字符串确保模型能稳定解析。4.4 购物 Agent 主流程文件路径main.py 购物智能体主入口。 运行前需要设置环境变量 ANTHROPIC_API_KEY。 如果没有 API Key可以先阅读代码逻辑了解 Agent 工作流程。 import os import anthropic from dotenv import load_dotenv from agent.core import run_agent, register_tool_map from tools.shopping_tools import ( SHOPPING_TOOLS, get_product_detail, search_products, create_order, track_order, ) load_dotenv() def build_shopping_system_prompt() - str: 构造购物智能体的系统提示词。 return 你是一个专业的购物助手。你的职责是帮助用户找到合适的商品、完成下单和查询物流。 工作流程 1. 用户提出购物需求后先调用 search_products 搜索商品。 2. 如果搜索结果较多调用 get_product_detail 获取详细参数进行对比。 3. 向用户清晰展示推荐结果包括价格、配置、配送时效。 4. 只有在用户明确确认购买时才能调用 create_order 创建订单。 5. 创建订单后可以调用 track_order 查询物流。 安全规则 - 未获得用户确认前不得创建订单。 - 如果用户的需求不够明确先询问清楚价格预算、配置要求等再搜索。 - 不要虚构不存在的商品参数。 - 如果搜索没有结果如实告知用户不要强行推荐。 def main(): api_key os.getenv(ANTHROPIC_API_KEY) if not api_key: print(请先设置 ANTHROPIC_API_KEY 环境变量) return client anthropic.Anthropic(api_keyapi_key) # 注册购物工具 register_tool_map({ search_products: search_products, get_product_detail: get_product_detail, create_order: create_order, track_order: track_order, }) system_prompt build_shopping_system_prompt() user_input 我想买一台 5000 元以内的轻薄本16G 内存帮我推荐一下 print(用户, user_input) print( * 50) result run_agent( clientclient, model_nameclaude-sonnet-4-5, system_promptsystem_prompt, toolsSHOPPING_TOOLS, user_messageuser_input, max_iterations5, ) print(Agent, result) if __name__ __main__: main()有一点要特别说明model_name我写的是claude-sonnet-4-5不同时间段 Anthropic 的模型名称会变化。你应该以官方文档或 API 返回的实际模型名为准。如果你的账号可用模型不叫这个名字配置会失败。4.5 运行效果说明如果你配置了可用的 API Key运行python main.py后大致的交互过程是模型收到用户需求。模型觉得需要搜索于是调用search_products(keyword轻薄本, max_price5000)。工具返回p1001、p1004两个结果。模型发现两个商品内存不同再次调用get_product_detail获取详情。模型综合信息后给出推荐结论。最终输出类似用户 我想买一台 5000 元以内的轻薄本16G 内存帮我推荐一下 Agent 根据您的需求我为您筛选出以下商品 1. 轻羽轻薄本 Prop1001 - 价格4699 元 - 内存16GB - 重量1.2kg - 配送次日达 这款是目前最符合您预算和配置要求的机型性价比高、重量轻、配送快。这只是模型可能的一种回复实际内容会根据模型输出变化。4.6 没有 API Key 时如何理解流程如果你暂时没有 API Key可以直接阅读agent/core.py里的循环逻辑或者自己写一个假的工具调用响应来模拟模型行为。例如# mock_run.py —— 模拟工具调用循环无需 API Key def mock_model_response(messages): 模拟模型输出。第一次调用工具第二次返回文本。 if len(messages) 1: return { role: assistant, content: [ { type: tool_use, id: call_001, name: search_products, input: {keyword: 轻薄本, max_price: 5000}, } ], } else: return { role: assistant, content: [ {type: text, text: 我找到了以下商品推荐轻羽轻薄本 Pro。} ], }这段代码演示了 Agent 循环里最关键的一点模型先输出工具调用请求应用层执行工具把结果放回消息历史再让模型继续。理解了这一点后面接入真实大模型就很简单了。5. 商户智能体实现5.1 商户侧需求分析商户智能体和购物智能体最大的区别在于商户工具会直接影响业务数据例如修改订单状态、审批退款、调整库存。这些操作如果失控后果比购物推荐严重得多。因此商户智能体的设计要额外关注权限最小化每个工具只做一件事。人工确认高风险操作需要二次确认。审计日志记录每一次工具调用。操作可回滚涉及数据变更时提供补偿操作。5.2 商户工具集实现文件路径tools/merchant_tools.py 商户智能体工具集。 注意商户工具涉及订单、退款、库存等敏感操作 真实生产环境必须增加权限校验、操作审计和幂等控制。 from typing import Any, Dict, List # 模拟订单数据生产环境应替换为数据库查询 MOCK_ORDERS [ { order_id: ORD20250001, product_id: p1001, quantity: 2, total_price: 9398, status: PAID, customer: 张三, }, { order_id: ORD20250002, product_id: p1002, quantity: 1, total_price: 5299, status: REFUNDING, customer: 李四, }, ] def list_orders(status: str ) - List[Dict[str, Any]]: 查询订单列表。 if not status: return MOCK_ORDERS return [o for o in MOCK_ORDERS if o[status] status] def approve_refund(order_id: str) - Dict[str, Any]: 审批退款。 安全提示实际系统中这一步通常还需要 1. 校验当前操作者是否有退款审批权限 2. 检查订单当前状态是否允许退款 3. 记录操作者、时间、原因到审计日志 4. 通过幂等键防止重复退款 for o in MOCK_ORDERS: if o[order_id] order_id: if o[status] ! REFUNDING: return {error: f订单 {order_id} 当前状态不允许退款} o[status] REFUNDED return { order_id: order_id, status: REFUNDED, message: 退款审批通过, } return {error: f订单 {order_id} 不存在} def update_inventory(product_id: str, delta: int) - Dict[str, Any]: 调整库存。 delta 为正表示增加库存为负表示扣减库存。 真实系统应使用数据库事务防止并发超卖。 from tools.shopping_tools import get_product_detail product get_product_detail(product_id) if error in product: return product new_stock product[stock] delta if new_stock 0: return {error: f库存不足当前库存 {product[stock]}} # 真实系统应执行 UPDATE product SET stock stock delta WHERE id ... product[stock] new_stock return { product_id: product_id, current_stock: new_stock, message: 库存更新成功, } MERCHANT_TOOLS [ { name: list_orders, description: 查询订单列表可按状态过滤, input_schema: { type: object, properties: { status: {type: string, description: 订单状态如 PAID、REFUNDING} } } }, { name: approve_refund, description: 审批通过退款申请。高风险操作必须确认用户明确要求退款后才可调用。, input_schema: { type: object, properties: { order_id: {type: string, description: 订单 ID} }, required: [order_id] } }, { name: update_inventory, description: 调整商品库存数量, input_schema: { type: object, properties: { product_id: {type: string, description: 商品 ID}, delta: {type: integer, description: 库存变化量正数增加负数扣减} }, required: [product_id, delta] } } ]5.3 商户 Agent 系统提示词商户 Agent 的系统提示词要比购物 Agent 更严格重点强调“不主动执行敏感操作”。def build_merchant_system_prompt() - str: return 你是一个商户运营助手帮助商户处理订单、退款和库存管理。 工作流程 1. 商户咨询订单情况时调用 list_orders 查询。 2. 商户要求退款审批时先确认订单状态再调用 approve_refund。 3. 商户需要调整库存时调用 update_inventory。 安全规则 - 退款、库存修改属于敏感操作。没有商户明确指令时绝不主动调用这些工具。 - 如果参数不明确先向商户确认清楚再执行。 - 退款操作执行前必须展示订单信息给商户获得再次确认。 - 不要批量修改订单状态一次只能处理一个订单。 5.4 商户 Agent 入口文件路径merchant.pyimport os import anthropic from dotenv import load_dotenv from agent.core import run_agent, register_tool_map from tools.merchant_tools import ( MERCHANT_TOOLS, list_orders, approve_refund, update_inventory, ) from tools.merchant_tools import build_merchant_system_prompt load_dotenv() def main(): api_key os.getenv(ANTHROPIC_API_KEY) if not api_key: print(请先设置 ANTHROPIC_API_KEY 环境变量) return client anthropic.Anthropic(api_keyapi_key) register_tool_map({ list_orders: list_orders, approve_refund: approve_refund, update_inventory: update_inventory, }) result run_agent( clientclient, model_nameclaude-sonnet-4-5, system_promptbuild_merchant_system_prompt(), toolsMERCHANT_TOOLS, user_message有哪些退款中的订单, max_iterations5, ) print(Agent, result) if __name__ __main__: main()商户智能体的代码结构几乎和购物智能体一样区别在于工具集合与权限边界。这也说明 Commerce Agents 蓝图的核心理念工具决定了 Agent 的能力边界Prompt 决定了 Agent 的行为边界。6. 从 Demo 到生产的关键改造开源蓝图给你的是一个可运行的最小骨架。要真正应用到生产环境下面几项改造是必须的。6.1 数据层替换Demo 中商品和订单数据都是 JSON 文件或内存列表。生产环境必须替换为真实的数据库或后端服务。真实项目的工具函数应该是这样的# 以搜索商品为例 def search_products(keyword: str , max_price: float 0) - List[Dict[str, Any]]: 真实实现通过商品中心服务或数据库查询商品。 # 1. 过滤条件校验 if max_price 0: return {error: 价格不能为负数} # 2. 调用商品服务示例伪代码 # products product_service.search( # keywordkeyword, # max_pricemax_price, # page_size10, # ) # return products # 3. 统一异常处理 # try: # ... # except ExternalServiceException: # return {error: 商品服务暂时不可用} ...替换过程中要特别注意工具函数不要直接在内部写 SQL 拼接字符串防止注入。数据库查询要设置超时时间避免 Agent 长时间挂起。返回给模型的数据要控制大小不要一次返回几十万条记录。6.2 幂等控制Agent 最大的风险之一是重复执行。模型可能在网络重试后把同一个下单请求发送两次。解决办法是引入幂等键# 工具函数中增加幂等键校验 def create_order_with_idempotency(user_id: str, product_id: str, idempotency_key: str) - Dict[str, Any]: # 先检查 Redis / DB 中是否已存在该幂等键 # 如果存在直接返回之前的处理结果不重复下单 ...在上面的 Agent 循环中如果模型连续两次调用create_order应用层应该通过幂等键识别出这是重复请求而不是真的下两个订单。6.3 人工确认机制对资金、退款、库存这类高风险操作生产环境建议引入“人工确认队列”模型调用 approve_refund | v 写入待确认任务表状态PENDING_APPROVAL | v 运营人员在小程序中点击“确认” | v 确认后系统执行退款Agent 的工具函数此时只负责“创建审批任务”不直接执行退款。这个改造能极大降低 AI 失控带来的业务风险。6.4 审计日志每次工具调用都要记录调用时间用户/商户 ID工具名称参数内容执行结果模型生成的中间思考如果允许记录日志不仅能用于排错也是后续合规审计的重要依据。6.5 成本控制与限流大模型 Agent 的调用成本包括 token 成本和工具执行消耗。建议设置单次任务的最大工具调用轮数。对工具返回结果做长度限制避免大 JSON 撑爆上下文。使用模型缓存功能如 prompt caching降低系统提示词重复计费。对模型执行结果做超时控制。7. 常见问题与排查思路在实际开发 Claude Commerce Agents 的过程中容易遇到以下几类问题。7.1 工具参数格式不符合 JSON Schema现象模型生成的工具参数在你的函数中取不到预期字段。原因工具的input_schema描述不够严格模型自由发挥了。解决思路在input_schema中把必填字段加入required。为每个字段写清类型例如type: number。函数的参数必须和 schema 完全一致。函数内部增加参数校验不合法就返回{error: ...}。7.2 模型陷入工具调用死循环现象Agent 不停调用工具始终不生成最终回复。原因工具返回的数据与模型预期不符模型想通过反复调用修复。解决思路给run_agent设置合理的max_iterations建议 5 到 8。检查工具返回的 JSON 是否简洁清晰。在系统提示词中增加“如果已经拿到足够信息请直接给出答案”的约束。7.3 工具执行报错导致 Agent 中断现象某个工具抛异常后Agent 直接结束。原因agent/core.py中的异常处理不完善或工具函数内部没有捕获业务异常。解决思路工具函数内部用 try-except 包裹业务逻辑统一返回 JSON 错误信息。不要抛 Python 异常给模型模型无法理解KeyError这类信息。在 Agent 循环中为每个工具调用增加独立的异常捕获。7.4 连接 API 失败或返回 403现象使用 Claude API 时出现无法连接或 403 状态码。原因常见原因包括 API Key 无效、账号权限不足、网络环境受限、模型名称错误。解决思路检查ANTHROPIC_API_KEY是否正确设置。验证所使用的模型名称在当前账号下是否可用。查看官方 API 文档确认请求地址是否需要特殊处理。增加重试机制和超时配置避免临时故障导致 Agent 中断。client anthropic.Anthropic( api_keyapi_key, timeout60.0, max_retries2, )7.5 工具返回的数据太大现象某个工具返回几千条商品模型无法有效处理且 token 消耗极高。解决思路工具函数内部做好分页只返回前 N 条。不要把全量数据塞给模型先做聚合统计。推荐场景中先返回 top 5 商品再让模型决定是否查看详情。问题现象常见原因解决思路授权失败 / 403API Key 无效或权限不足检查 Key 与账号权限模型不调用工具工具描述不清 / 系统提示词不够明确优化工具 description 和 system prompt工具参数取不到值JSON Schema 定义不严谨补充 required 和字段类型重复下单网络重试导致重复调用引入幂等键Agent 死循环工具返回值不满足模型预期限制轮数、优化返回结构8. 最佳实践与工程建议8.1 工具设计原则工具是 Agent 能力的边界。设计时记住一句话一个工具只做一件事并把事情描述清楚。反面示例工具名process_order 描述处理订单这个工具过于模糊。模型不知道它到底能做什么也不知道能否用于退款。正面示例工具名approve_refund 描述审批通过指定订单的退款申请。仅当商户明确要求退款时调用。清晰、单一、有边界。8.2 Prompt 工程要点系统提示词中要写明角色的工作目标。工具调用顺序。何时不能调用工具。参数不明确时怎么办。如何向用户确认关键操作。不建议把大段业务规则都写进 Prompt。复杂的规则应下沉到工具函数里做防呆校验Prompt 只负责约束模型行为。8.3 安全红线以下是必须遵守的几条红线涉及支付、退款、库存修改的高危工具不能在单轮对话中直接执行。Agent 不能拥有比真实操作者更高的权限。所有敏感操作必须有审计日志。生产环境工具调用必须做限流。不要让模型自由拼接 SQL 或 shell 命令。8.4 可观测性生产环境的 Agent 一定要有 trace 链路建议打印如下信息[tool_use] call_idcall_001 namesearch_products input{keyword:轻薄本} [tool_result] call_idcall_001 statussuccess result_size2 [model_message] tokens234 stop_reasonturn_limit这些日志能帮你快速定位“模型到底做了哪些决策”。8.5 渐进式上线不要一开始就把所有电商功能交给 Agent。推荐顺序先用只读工具上线商品搜索、订单查询。再加入低风险写操作购物车管理。最后在人工审核机制到位后再上线退款、库存修改等高危操作。每一步都要在小流量下验证模型行为和工具稳定性。9. 动手实践建议如果你想真正掌握 Claude Commerce Agents不建议只看不练。这里给出一条实际可行的学习路径第一步先阅读agent/core.py里的工具调用循环弄清楚模型、应用层、工具函数三者的关系。第二步自己写一个只包含一个工具的 Agent比如“查天气”。用户说“北京今天适合出门吗”Agent 调用天气工具后给出建议。这个例子虽然简单但能帮你跑通整个链路。第三步将本文的购物 Demo 跑起来。如果有 API Key直接运行如果没有参考mock_run.py自己模拟模型输出。第四步为购物 Agent 增加一个“收藏商品”工具。注意定义好参数 schema并在工具函数中维护一个收藏列表。第五步尝试把商户 Agent 的approve_refund改造成“创建审批任务 人工确认”的模式。这一步做完你就真正理解了生产级 Agent 的安全设计。每次改动后记录模型的行为变化。一个好用的 Agent不是一次写出来的而是在不断调整工具描述、Prompt 和边界条件中打磨出来的。如果你在搭建过程中遇到 Agent 不调用工具、参数格式错误或安全设计拿不准的地方欢迎在评论区带上报错信息或代码片段我们继续排查。