1. 项目概述用50行Python解锁Anthropic的Advisor工具最近在折腾AI应用开发特别是想给一些内部系统加上智能问答和决策支持的能力。市面上大模型API很多但很多方案要么太“重”需要一整套复杂的工程架构要么太“泛”回答虽然流畅但缺乏针对具体业务场景的深度。直到我试用了Anthropic的Claude API尤其是他们提供的Advisor工具发现这玩意儿简直是给垂直领域应用“开外挂”的神器。它不像普通的聊天补全你扔一个问题它给一个答案就完了。Advisor更像一个内置了“思考链”和“工具箱”的智能体能根据你的问题自动规划步骤、调用你预先定义好的函数工具去获取信息然后给出经过推理和验证的结论。最让我惊喜的是它的接入成本低得离谱。官方文档可能看起来有点复杂但经过一番摸索我发现核心的调用逻辑用大约50行清晰、可维护的Python代码就能完整实现。这意味着一线业务人员、数据分析师甚至是对后端不太熟悉的前端同学都能快速上手把强大的推理能力嵌入到自己的脚本、自动化流程或者轻量级Web应用里。今天我就来拆解一下这50行代码背后的门道从环境准备、核心对象解析到完整的请求-响应循环最后再分享几个我踩过坑才总结出来的实战技巧。2. 核心思路与架构拆解2.1 什么是Advisor工具它解决了什么痛点在深入代码之前我们得先搞清楚Advisor工具到底是什么以及为什么它值得我们用代码去集成。你可以把它理解为Claude模型的一个“增强模式”。当我们使用标准的messagesAPI时交互模式是线性的用户提问模型回答。但如果问题复杂需要查数据、做计算或者分步骤推理用户就得手动拆解问题多次提问或者提前把所有上下文喂给模型。Advisor工具改变了这个范式。它允许开发者预先定义一系列“工具”本质上就是函数描述了名称、作用、输入参数。当你向Advisor提出一个复杂问题时模型不会直接生成最终答案而是先“思考”要解决这个问题我需要按什么步骤来每一步需要调用哪个工具需要传入什么参数然后它会以结构化的格式一个tool_use块告诉你它想调用哪个工具以及参数是什么。你的代码接收到这个请求后就去本地执行对应的真实函数获取结果比如查询了数据库、计算了指标、调用了某个外部API再将结果以tool_result块的形式返回给模型。模型基于这个结果继续它的推理可能再次调用工具如此循环直到它认为已经收集到足够的信息可以生成最终答案。这个过程解决了几个关键痛点信息实时性模型的知识有截止日期但通过工具它可以获取到实时、动态的数据如当前股价、天气、库存。准确性涉及具体计算或业务逻辑时让模型调用你写的、经过验证的函数远比让它自己“心算”或“编造”要可靠得多。可控性与安全性模型只能在你允许的“工具箱”范围内操作。它无法直接访问你的数据库或内部系统必须通过你定义的、带有权限控制和输入校验的函数来间接访问。复杂任务自动化将多步骤的推理和操作自动化用户只需提出最终目标剩下的规划、执行、整合由Advisor协同你的代码来完成。2.2 50行代码的架构设计要实现Advisor调用核心是构建一个能与Claude API进行多轮“对话”的循环。这个循环的每一次迭代都可能包含模型的“思考”想调用工具和我们的“执行”运行工具并返回结果。我们的50行代码就是精心设计了这个循环的骨架。整个架构围绕以下几个核心对象展开client(Anthropic客户端)负责所有与Anthropic API服务器的网络通信。tools(工具列表)一个列表里面每个元素都是一个字典严格遵循Anthropic的tool格式描述了工具的名字、描述和输入参数模式。这是Advisor的“工具箱说明书”。messages(消息列表)记录整个对话的历史。它不仅仅包含用户和AI的文本还穿插着tool_useAI想用工具和tool_result我们返回工具结果这两种特殊的消息块。这个列表维护了完整的对话上下文。real_tools(真实工具映射)一个Python字典键是工具名name值是对应的、真正可以被执行的Python函数。这是“工具箱”本身。代码的主循环逻辑如下初始化准备好client定义好tools和real_tools初始化一个空的messages列表并把用户的问题作为第一条用户消息加进去。发起请求调用client.messages.create()传入model如claude-3-5-sonnet-20241022、messages、tools并最关键的是设置tool_choice{type: any}这告诉API“请让模型以Advisor模式运行可以自主选择使用任何工具”。处理响应API返回一个响应对象。我们遍历响应中的所有content块。如果块类型是text说明模型输出了文本我们把它追加到messages中并可能直接展示给用户如果是最终答案。如果块类型是tool_use说明模型想调用工具了我们会从中提取tool_name和input参数。执行工具根据tool_name去real_tools字典里找到对应的真实函数把input作为参数传进去执行。返回结果将工具执行的结果或错误信息包装成一个tool_result块追加到messages列表中。这个块必须通过tool_use_id关联到之前那个tool_use块。循环由于messages列表末尾现在有了新的tool_result循环回到第2步再次调用client.messages.create()。模型会基于这个新结果继续推理可能输出更多文本或再次调用工具。终止当模型的响应中不再包含tool_use块且输出了完整的text内容时循环结束我们得到了最终答案。这个设计巧妙地将AI的“规划”能力与我们本地代码的“执行”能力结合了起来而代码本身主要扮演一个“调度员”和“记录员”的角色。3. 环境准备与核心依赖解析3.1 安装与配置Anthropic Python SDK一切开始之前你得有一个能访问Claude API的环境。首先确保你有一个Anthropic的账户并在其控制台创建了API密钥。这个密钥是你的通行证务必妥善保管不要硬编码在脚本里。接下来是Python环境。我强烈建议使用虚拟环境venv或conda来管理依赖避免污染全局环境。# 创建并激活虚拟环境以venv为例 python -m venv claude-advisor-env source claude-advisor-env/bin/activate # Linux/macOS # claude-advisor-env\Scripts\activate # Windows # 安装官方Anthropic SDK pip install anthropicanthropic这个库就是我们的核心武器。它封装了所有与API交互的细节让我们能用非常Pythonic的方式调用Claude。目前确保你安装的是较新的版本如0.25.0以支持完整的工具调用功能。3.2 API密钥的安全管理把API密钥直接写在代码里是绝对的大忌。一旦代码上传到GitHub或其他地方密钥就泄露了会带来严重的财务和安全风险。正确的做法是使用环境变量。# 在终端中设置环境变量临时重启后失效 export ANTHROPIC_API_KEYyour-api-key-here # 或者更持久的方法写入shell配置文件如 ~/.bashrc 或 ~/.zshrc echo export ANTHROPIC_API_KEYyour-api-key-here ~/.zshrc source ~/.zshrc在Python代码中通过os模块来读取import os from anthropic import Anthropic api_key os.environ.get(ANTHROPIC_API_KEY) if not api_key: raise ValueError(请设置 ANTHROPIC_API_KEY 环境变量。) client Anthropic(api_keyapi_key)对于更复杂的项目可以考虑使用.env文件配合python-dotenv库或者在云服务平台使用其秘密管理服务。3.3 工具定义连接AI与真实世界的桥梁tools参数是我们代码中第一个需要精心构造的部分。它不是一个可以随意写的Python字典而必须遵循严格的JSON Schema格式。这就像是给AI的一份“工具使用说明书”必须清晰、无歧义。一个完整的工具定义通常包含以下字段name: 工具的唯一标识符字符串。最好使用蛇形命名法snake_case清晰易懂如get_current_weather。description: 对工具功能的自然语言描述。这个描述至关重要AI主要靠它来理解何时以及如何使用这个工具。描述应简洁说明输入是什么输出是什么。例如“获取指定城市的当前天气情况。”input_schema: 一个符合JSON Schema的字典严格定义工具所需的参数。必须包含type: object和properties字段。每个属性都要定义其type如string,number、description参数描述等信息。下面是一个定义“查询天气”和“执行计算”工具的示例tools [ { name: get_weather, description: 根据城市名称查询当前的天气状况包括温度、天气现象和湿度。, input_schema: { type: object, properties: { city_name: { type: string, description: 要查询天气的城市名称例如北京、上海、New York。 } }, required: [city_name] # 指定哪些参数是必须的 } }, { name: calculator, description: 执行一个简单的数学计算。支持加()、减(-)、乘(*)、除(/)。, input_schema: { type: object, properties: { expression: { type: string, description: 数学表达式例如3 5 * (2 - 1)。 } }, required: [expression] } } ]注意input_schema中的description字段对于AI理解参数意图非常有帮助。尽量写清楚比如“城市名称”就比“location”更明确。同时required列表可以防止AI漏掉关键参数。4. 核心代码逐行详解与实现现在我们把架构中的各个部分用代码组装起来。我会将完整的50行左右代码分块解释你可以把它们拼接成一个完整的脚本。4.1 初始化与工具定义import os from anthropic import Anthropic import json # 1. 初始化客户端 api_key os.environ.get(ANTHROPIC_API_KEY) client Anthropic(api_keyapi_key) # 2. 定义给AI看的工具列表 (Tools for AI) tools_for_ai [ { name: get_weather, description: 获取指定城市的当前天气信息。, input_schema: { type: object, properties: { city: {type: string, description: 城市名称例如北京、东京、San Francisco} }, required: [city] } }, { name: calculate, description: 计算一个数学表达式的结果。, input_schema: { type: object, properties: { expression: {type: string, description: 数学表达式如2 3 * 4 或 (10 - 5) / 2} }, required: [expression] } } ] # 3. 定义真实的工具函数映射 (Real Tools Implementation) def real_get_weather(city: str) - str: 模拟天气查询函数。在实际应用中这里会调用天气API。 # 这里只是一个模拟。真实情况可能调用如OpenWeatherMap的API。 weather_data { 北京: 晴朗25°C湿度40%, 上海: 多云28°C湿度65%, San Francisco: 雾18°C湿度80% } return weather_data.get(city, f未找到城市 {city} 的天气信息。) def real_calculate(expression: str) - str: 安全地计算数学表达式。 try: # 警告在生产环境中直接使用eval是危险的可能造成代码注入。 # 这里仅作演示。安全做法是使用ast.literal_eval或专门的数学表达式解析库。 result eval(expression) return f表达式 {expression} 的计算结果是{result} except Exception as e: return f计算表达式 {expression} 时出错{e} # 将工具名映射到真实的函数 real_tools { get_weather: real_get_weather, calculate: real_calculate }这部分代码做了三件事创建了API客户端。定义了tools_for_ai这是给Claude看的“工具菜单”。定义了real_tools字典和对应的函数real_get_weather、real_calculate。这是我们的真实“工具库”。注意两个calculate函数中的安全警告演示中用了eval但实际产品中必须替换为更安全的方案。4.2 主循环与Advisor的对话引擎这是最核心的部分实现了之前描述的请求-响应循环。def run_advisor_cycle(user_query: str, max_turns: int 10): 运行Advisor对话循环。 :param user_query: 用户的初始问题 :param max_turns: 最大对话轮次防止无限循环 # 初始化消息历史加入用户问题 messages [{role: user, content: user_query}] for turn in range(max_turns): print(f\n--- 第 {turn 1} 轮对话 ---) # 1. 调用Claude API关键是指定 tool_choiceany response client.messages.create( modelclaude-3-5-sonnet-20241022, # 使用支持工具调用的模型 max_tokens1024, messagesmessages, toolstools_for_ai, tool_choice{type: any} # 允许模型自主选择使用工具 ) # 2. 处理响应内容 new_messages_content [] # 用于收集本轮要追加的消息块 should_continue False # 标记是否需要继续循环即是否有工具调用 for content_block in response.content: if content_block.type text: # 模型输出了文本 print(fClaude: {content_block.text}) new_messages_content.append({type: text, text: content_block.text}) elif content_block.type tool_use: # 模型想要使用工具 tool_name content_block.name tool_input content_block.input tool_use_id content_block.id print(fClaude 想调用工具 {tool_name}参数{tool_input}) # 3. 执行对应的真实工具 tool_func real_tools.get(tool_name) if tool_func: try: # 调用函数传入参数 tool_output tool_func(**tool_input) print(f工具 {tool_name} 执行结果{tool_output}) except Exception as e: tool_output f工具执行出错{e} print(f工具 {tool_name} 执行失败{e}) else: tool_output f错误未找到名为 {tool_name} 的工具实现。 print(tool_output) # 4. 将工具执行结果构建成 tool_result 块 # 注意必须使用正确的 tool_use_id 来关联 new_messages_content.append({ type: tool_result, tool_use_id: tool_use_id, content: tool_output }) should_continue True # 因为有工具调用需要继续循环 # 将本轮产生的所有新内容块text 和 tool_result作为一个整体追加到历史中 if new_messages_content: messages.append({role: assistant, content: new_messages_content}) # 5. 判断循环是否结束 if not should_continue: print(\n--- 对话结束已获得最终答案 ---) break else: # 如果for循环正常结束未break说明达到了最大轮次 print(f\n警告已达到最大对话轮次{max_turns}强制结束。)让我们拆解这个循环max_turns一个安全阀防止AI陷入无限的工具调用循环。response client.messages.create(...)这是核心调用。tool_choice{type: any}是激活Advisor模式的关键。你也可以用{type: tool, name: specific_tool}来强制使用某个工具但“any”模式才能体现其自主规划能力。遍历response.content响应内容是一个列表可能包含多个块TextBlock或ToolUseBlock。我们必须按顺序处理。tool_use块的处理这是枢纽。我们提取name和input然后用real_tools[tool_name](**tool_input)来调用真实函数。**tool_input是将字典参数解包传递给函数的关键技巧。构建tool_result这是将现实世界的数据反馈给AI的桥梁。tool_use_id必须与触发它的那个tool_use块的id一致否则API无法正确关联。循环条件should_continue如果本轮响应中有tool_use我们就设置should_continueTrue让循环继续。如果只有text说明AI给出了最终答案循环结束。4.3 完整示例与调用将以上两部分代码组合并添加一个入口点就是一个完整的可运行脚本if __name__ __main__: # 示例问题一个需要多步推理和工具调用的问题 query 请问北京现在的天气怎么样如果天气晴朗帮我计算一下25 17乘以2等于多少 print(f用户问题{query}) run_advisor_cycle(query)运行这个脚本你将会在控制台看到类似以下的对话流用户问题请问北京现在的天气怎么样如果天气晴朗帮我计算一下25 17乘以2等于多少 --- 第 1 轮对话 --- Claude 想调用工具 get_weather参数{city: 北京} 工具 get_weather 执行结果晴朗25°C湿度40% --- 第 2 轮对话 --- Claude: 北京现在的天气是晴朗25°C湿度40%。 Claude 想调用工具 calculate参数{expression: (25 17) * 2} 工具 calculate 执行结果表达式 (25 17) * 2 的计算结果是84 --- 第 3 轮对话 --- Claude: 根据计算(25 17) 乘以 2 等于 84。 --- 对话结束已获得最终答案 ---可以看到Advisor自动将复杂问题拆解成了“先查天气再根据结果决定是否计算”的步骤并依次调用了我们定义的工具最终整合信息给出了连贯的回答。5. 高级技巧与实战避坑指南掌握了基础实现后下面这些从实战中总结的经验能让你用得更顺手、更稳健。5.1 工具设计的艺术如何写出AI爱用的工具工具定义的好坏直接决定了Advisor使用的流畅度和准确性。描述要具体职责要单一description字段避免模糊。对比“处理数据”和“计算给定列表的平均值”后者清晰得多。一个工具最好只做一件事单一职责原则这样AI更容易理解和调用。参数设计要友好input_schema中的参数名应直观。使用city_name而非loc。为每个参数提供清晰的description。合理使用required字段确保AI不会遗漏关键信息。处理枚举和约束如果参数只能是几个特定值可以在schema中使用enum进行约束。例如一个currency_converter工具from_currency和to_currency可以限定为[USD, CNY, EUR, JPY]。这能极大提高AI调用时的准确性。input_schema: { type: object, properties: { from_currency: {type: string, enum: [USD, CNY, EUR, JPY]}, to_currency: {type: string, enum: [USD, CNY, EUR, JPY]}, amount: {type: number} }, required: [from_currency, to_currency, amount] }提供示例在工具描述的末尾可以加一句“例如get_stock_price(AAPL)”。这能给AI很强的提示。5.2 错误处理与鲁棒性增强我们的基础代码已经有了简单的try...except但在生产环境中需要更周全。工具函数内部的健壮性真实工具函数如real_get_weather必须包含完善的错误处理。网络请求超时、API返回异常格式、数据库查询失败等情况都要考虑并返回清晰的错误信息给AI例如“天气服务暂时不可用请稍后再试。”而不是抛出一个Python异常堆栈。处理未知工具虽然我们定义了映射但要预防AI因为上下文混淆或“幻觉”而请求一个未定义的工具。在tool_func real_tools.get(tool_name)后如果tool_func是None应该返回一个友好的错误信息如“抱歉我目前无法执行‘XXX’这个操作。”参数校验前置可以在调用真实函数前先根据input_schema对AI传入的tool_input做一次校验。比如检查必填字段是否存在类型是否匹配枚举值是否有效。这可以提前拦截很多问题。设置超时与重试对于网络调用类工具务必设置超时如使用requests库的timeout参数并考虑加入简单的重试逻辑如重试2次避免一次网络波动导致整个对话卡住。5.3 性能优化与成本控制频繁调用API会产生费用也需要时间。缓存工具结果对于一些耗时或调用成本高、且结果在短时间内不变的工具如天气查询、股票价格可以引入简单的缓存机制。例如用city作为键将结果在内存中缓存5分钟。from functools import lru_cache import time lru_cache(maxsize128) def real_get_weather_with_cache(city: str) - str: # ... 真实的API调用 ... pass注意需要根据业务场景决定缓存策略对于实时性要求高的数据不能缓存。精简上下文Messagesmessages列表会随着对话轮次增长每次都会发送给API。Token消耗与成本直接相关。对于非常长的多轮对话可以考虑在适当的时候比如一个问题完全解决后清空或截断历史或者使用API可能提供的“上下文摘要”功能如果未来支持。选择合适的模型claude-3-haiku模型更快、更便宜对于工具调用这类结构化任务其能力可能已经足够。claude-3-5-sonnet能力更强但更贵。根据任务复杂度进行选择。限制最大轮次max_turns我们代码里已经做了这是防止意外情况导致循环失控、产生高额费用的必要措施。一般设置为5-10轮已经能处理绝大多数复杂任务。5.4 扩展应用场景这50行代码是一个强大的框架可以轻松扩展到各种场景企业内部知识库问答定义search_internal_wiki工具函数内部连接你的Elasticsearch或向量数据库Advisor就能根据员工提问自动搜索并总结内部文档。数据分析与报表定义query_database、generate_chart工具。用户可以说“帮我分析一下上季度华东区的销售数据找出Top 3的产品并总结趋势。”Advisor会自动规划查询、分析、可视化的步骤。自动化工作流定义send_email、create_jira_ticket、query_crm等工具。Advisor可以理解“通知客户A项目延期并在CRM中更新状态”这样的指令并自动执行一系列操作。智能客服升级当标准客服机器人无法解决时可以无缝切换到Advisor模式Advisor通过调用“查询订单”、“检查物流”、“发起退款”等工具提供更深度的、可执行的服务。关键在于你将复杂的业务逻辑封装成一个个简单的工具函数而Advisor则扮演了理解用户意图、并智能编排这些工具的大脑。这种“AI规划 本地执行”的模式在安全可控的前提下极大地扩展了AI的应用边界。
50行Python实现Anthropic Claude Advisor工具调用：AI规划与本地执行的工程实践
发布时间：2026/5/26 6:14:05
1. 项目概述用50行Python解锁Anthropic的Advisor工具最近在折腾AI应用开发特别是想给一些内部系统加上智能问答和决策支持的能力。市面上大模型API很多但很多方案要么太“重”需要一整套复杂的工程架构要么太“泛”回答虽然流畅但缺乏针对具体业务场景的深度。直到我试用了Anthropic的Claude API尤其是他们提供的Advisor工具发现这玩意儿简直是给垂直领域应用“开外挂”的神器。它不像普通的聊天补全你扔一个问题它给一个答案就完了。Advisor更像一个内置了“思考链”和“工具箱”的智能体能根据你的问题自动规划步骤、调用你预先定义好的函数工具去获取信息然后给出经过推理和验证的结论。最让我惊喜的是它的接入成本低得离谱。官方文档可能看起来有点复杂但经过一番摸索我发现核心的调用逻辑用大约50行清晰、可维护的Python代码就能完整实现。这意味着一线业务人员、数据分析师甚至是对后端不太熟悉的前端同学都能快速上手把强大的推理能力嵌入到自己的脚本、自动化流程或者轻量级Web应用里。今天我就来拆解一下这50行代码背后的门道从环境准备、核心对象解析到完整的请求-响应循环最后再分享几个我踩过坑才总结出来的实战技巧。2. 核心思路与架构拆解2.1 什么是Advisor工具它解决了什么痛点在深入代码之前我们得先搞清楚Advisor工具到底是什么以及为什么它值得我们用代码去集成。你可以把它理解为Claude模型的一个“增强模式”。当我们使用标准的messagesAPI时交互模式是线性的用户提问模型回答。但如果问题复杂需要查数据、做计算或者分步骤推理用户就得手动拆解问题多次提问或者提前把所有上下文喂给模型。Advisor工具改变了这个范式。它允许开发者预先定义一系列“工具”本质上就是函数描述了名称、作用、输入参数。当你向Advisor提出一个复杂问题时模型不会直接生成最终答案而是先“思考”要解决这个问题我需要按什么步骤来每一步需要调用哪个工具需要传入什么参数然后它会以结构化的格式一个tool_use块告诉你它想调用哪个工具以及参数是什么。你的代码接收到这个请求后就去本地执行对应的真实函数获取结果比如查询了数据库、计算了指标、调用了某个外部API再将结果以tool_result块的形式返回给模型。模型基于这个结果继续它的推理可能再次调用工具如此循环直到它认为已经收集到足够的信息可以生成最终答案。这个过程解决了几个关键痛点信息实时性模型的知识有截止日期但通过工具它可以获取到实时、动态的数据如当前股价、天气、库存。准确性涉及具体计算或业务逻辑时让模型调用你写的、经过验证的函数远比让它自己“心算”或“编造”要可靠得多。可控性与安全性模型只能在你允许的“工具箱”范围内操作。它无法直接访问你的数据库或内部系统必须通过你定义的、带有权限控制和输入校验的函数来间接访问。复杂任务自动化将多步骤的推理和操作自动化用户只需提出最终目标剩下的规划、执行、整合由Advisor协同你的代码来完成。2.2 50行代码的架构设计要实现Advisor调用核心是构建一个能与Claude API进行多轮“对话”的循环。这个循环的每一次迭代都可能包含模型的“思考”想调用工具和我们的“执行”运行工具并返回结果。我们的50行代码就是精心设计了这个循环的骨架。整个架构围绕以下几个核心对象展开client(Anthropic客户端)负责所有与Anthropic API服务器的网络通信。tools(工具列表)一个列表里面每个元素都是一个字典严格遵循Anthropic的tool格式描述了工具的名字、描述和输入参数模式。这是Advisor的“工具箱说明书”。messages(消息列表)记录整个对话的历史。它不仅仅包含用户和AI的文本还穿插着tool_useAI想用工具和tool_result我们返回工具结果这两种特殊的消息块。这个列表维护了完整的对话上下文。real_tools(真实工具映射)一个Python字典键是工具名name值是对应的、真正可以被执行的Python函数。这是“工具箱”本身。代码的主循环逻辑如下初始化准备好client定义好tools和real_tools初始化一个空的messages列表并把用户的问题作为第一条用户消息加进去。发起请求调用client.messages.create()传入model如claude-3-5-sonnet-20241022、messages、tools并最关键的是设置tool_choice{type: any}这告诉API“请让模型以Advisor模式运行可以自主选择使用任何工具”。处理响应API返回一个响应对象。我们遍历响应中的所有content块。如果块类型是text说明模型输出了文本我们把它追加到messages中并可能直接展示给用户如果是最终答案。如果块类型是tool_use说明模型想调用工具了我们会从中提取tool_name和input参数。执行工具根据tool_name去real_tools字典里找到对应的真实函数把input作为参数传进去执行。返回结果将工具执行的结果或错误信息包装成一个tool_result块追加到messages列表中。这个块必须通过tool_use_id关联到之前那个tool_use块。循环由于messages列表末尾现在有了新的tool_result循环回到第2步再次调用client.messages.create()。模型会基于这个新结果继续推理可能输出更多文本或再次调用工具。终止当模型的响应中不再包含tool_use块且输出了完整的text内容时循环结束我们得到了最终答案。这个设计巧妙地将AI的“规划”能力与我们本地代码的“执行”能力结合了起来而代码本身主要扮演一个“调度员”和“记录员”的角色。3. 环境准备与核心依赖解析3.1 安装与配置Anthropic Python SDK一切开始之前你得有一个能访问Claude API的环境。首先确保你有一个Anthropic的账户并在其控制台创建了API密钥。这个密钥是你的通行证务必妥善保管不要硬编码在脚本里。接下来是Python环境。我强烈建议使用虚拟环境venv或conda来管理依赖避免污染全局环境。# 创建并激活虚拟环境以venv为例 python -m venv claude-advisor-env source claude-advisor-env/bin/activate # Linux/macOS # claude-advisor-env\Scripts\activate # Windows # 安装官方Anthropic SDK pip install anthropicanthropic这个库就是我们的核心武器。它封装了所有与API交互的细节让我们能用非常Pythonic的方式调用Claude。目前确保你安装的是较新的版本如0.25.0以支持完整的工具调用功能。3.2 API密钥的安全管理把API密钥直接写在代码里是绝对的大忌。一旦代码上传到GitHub或其他地方密钥就泄露了会带来严重的财务和安全风险。正确的做法是使用环境变量。# 在终端中设置环境变量临时重启后失效 export ANTHROPIC_API_KEYyour-api-key-here # 或者更持久的方法写入shell配置文件如 ~/.bashrc 或 ~/.zshrc echo export ANTHROPIC_API_KEYyour-api-key-here ~/.zshrc source ~/.zshrc在Python代码中通过os模块来读取import os from anthropic import Anthropic api_key os.environ.get(ANTHROPIC_API_KEY) if not api_key: raise ValueError(请设置 ANTHROPIC_API_KEY 环境变量。) client Anthropic(api_keyapi_key)对于更复杂的项目可以考虑使用.env文件配合python-dotenv库或者在云服务平台使用其秘密管理服务。3.3 工具定义连接AI与真实世界的桥梁tools参数是我们代码中第一个需要精心构造的部分。它不是一个可以随意写的Python字典而必须遵循严格的JSON Schema格式。这就像是给AI的一份“工具使用说明书”必须清晰、无歧义。一个完整的工具定义通常包含以下字段name: 工具的唯一标识符字符串。最好使用蛇形命名法snake_case清晰易懂如get_current_weather。description: 对工具功能的自然语言描述。这个描述至关重要AI主要靠它来理解何时以及如何使用这个工具。描述应简洁说明输入是什么输出是什么。例如“获取指定城市的当前天气情况。”input_schema: 一个符合JSON Schema的字典严格定义工具所需的参数。必须包含type: object和properties字段。每个属性都要定义其type如string,number、description参数描述等信息。下面是一个定义“查询天气”和“执行计算”工具的示例tools [ { name: get_weather, description: 根据城市名称查询当前的天气状况包括温度、天气现象和湿度。, input_schema: { type: object, properties: { city_name: { type: string, description: 要查询天气的城市名称例如北京、上海、New York。 } }, required: [city_name] # 指定哪些参数是必须的 } }, { name: calculator, description: 执行一个简单的数学计算。支持加()、减(-)、乘(*)、除(/)。, input_schema: { type: object, properties: { expression: { type: string, description: 数学表达式例如3 5 * (2 - 1)。 } }, required: [expression] } } ]注意input_schema中的description字段对于AI理解参数意图非常有帮助。尽量写清楚比如“城市名称”就比“location”更明确。同时required列表可以防止AI漏掉关键参数。4. 核心代码逐行详解与实现现在我们把架构中的各个部分用代码组装起来。我会将完整的50行左右代码分块解释你可以把它们拼接成一个完整的脚本。4.1 初始化与工具定义import os from anthropic import Anthropic import json # 1. 初始化客户端 api_key os.environ.get(ANTHROPIC_API_KEY) client Anthropic(api_keyapi_key) # 2. 定义给AI看的工具列表 (Tools for AI) tools_for_ai [ { name: get_weather, description: 获取指定城市的当前天气信息。, input_schema: { type: object, properties: { city: {type: string, description: 城市名称例如北京、东京、San Francisco} }, required: [city] } }, { name: calculate, description: 计算一个数学表达式的结果。, input_schema: { type: object, properties: { expression: {type: string, description: 数学表达式如2 3 * 4 或 (10 - 5) / 2} }, required: [expression] } } ] # 3. 定义真实的工具函数映射 (Real Tools Implementation) def real_get_weather(city: str) - str: 模拟天气查询函数。在实际应用中这里会调用天气API。 # 这里只是一个模拟。真实情况可能调用如OpenWeatherMap的API。 weather_data { 北京: 晴朗25°C湿度40%, 上海: 多云28°C湿度65%, San Francisco: 雾18°C湿度80% } return weather_data.get(city, f未找到城市 {city} 的天气信息。) def real_calculate(expression: str) - str: 安全地计算数学表达式。 try: # 警告在生产环境中直接使用eval是危险的可能造成代码注入。 # 这里仅作演示。安全做法是使用ast.literal_eval或专门的数学表达式解析库。 result eval(expression) return f表达式 {expression} 的计算结果是{result} except Exception as e: return f计算表达式 {expression} 时出错{e} # 将工具名映射到真实的函数 real_tools { get_weather: real_get_weather, calculate: real_calculate }这部分代码做了三件事创建了API客户端。定义了tools_for_ai这是给Claude看的“工具菜单”。定义了real_tools字典和对应的函数real_get_weather、real_calculate。这是我们的真实“工具库”。注意两个calculate函数中的安全警告演示中用了eval但实际产品中必须替换为更安全的方案。4.2 主循环与Advisor的对话引擎这是最核心的部分实现了之前描述的请求-响应循环。def run_advisor_cycle(user_query: str, max_turns: int 10): 运行Advisor对话循环。 :param user_query: 用户的初始问题 :param max_turns: 最大对话轮次防止无限循环 # 初始化消息历史加入用户问题 messages [{role: user, content: user_query}] for turn in range(max_turns): print(f\n--- 第 {turn 1} 轮对话 ---) # 1. 调用Claude API关键是指定 tool_choiceany response client.messages.create( modelclaude-3-5-sonnet-20241022, # 使用支持工具调用的模型 max_tokens1024, messagesmessages, toolstools_for_ai, tool_choice{type: any} # 允许模型自主选择使用工具 ) # 2. 处理响应内容 new_messages_content [] # 用于收集本轮要追加的消息块 should_continue False # 标记是否需要继续循环即是否有工具调用 for content_block in response.content: if content_block.type text: # 模型输出了文本 print(fClaude: {content_block.text}) new_messages_content.append({type: text, text: content_block.text}) elif content_block.type tool_use: # 模型想要使用工具 tool_name content_block.name tool_input content_block.input tool_use_id content_block.id print(fClaude 想调用工具 {tool_name}参数{tool_input}) # 3. 执行对应的真实工具 tool_func real_tools.get(tool_name) if tool_func: try: # 调用函数传入参数 tool_output tool_func(**tool_input) print(f工具 {tool_name} 执行结果{tool_output}) except Exception as e: tool_output f工具执行出错{e} print(f工具 {tool_name} 执行失败{e}) else: tool_output f错误未找到名为 {tool_name} 的工具实现。 print(tool_output) # 4. 将工具执行结果构建成 tool_result 块 # 注意必须使用正确的 tool_use_id 来关联 new_messages_content.append({ type: tool_result, tool_use_id: tool_use_id, content: tool_output }) should_continue True # 因为有工具调用需要继续循环 # 将本轮产生的所有新内容块text 和 tool_result作为一个整体追加到历史中 if new_messages_content: messages.append({role: assistant, content: new_messages_content}) # 5. 判断循环是否结束 if not should_continue: print(\n--- 对话结束已获得最终答案 ---) break else: # 如果for循环正常结束未break说明达到了最大轮次 print(f\n警告已达到最大对话轮次{max_turns}强制结束。)让我们拆解这个循环max_turns一个安全阀防止AI陷入无限的工具调用循环。response client.messages.create(...)这是核心调用。tool_choice{type: any}是激活Advisor模式的关键。你也可以用{type: tool, name: specific_tool}来强制使用某个工具但“any”模式才能体现其自主规划能力。遍历response.content响应内容是一个列表可能包含多个块TextBlock或ToolUseBlock。我们必须按顺序处理。tool_use块的处理这是枢纽。我们提取name和input然后用real_tools[tool_name](**tool_input)来调用真实函数。**tool_input是将字典参数解包传递给函数的关键技巧。构建tool_result这是将现实世界的数据反馈给AI的桥梁。tool_use_id必须与触发它的那个tool_use块的id一致否则API无法正确关联。循环条件should_continue如果本轮响应中有tool_use我们就设置should_continueTrue让循环继续。如果只有text说明AI给出了最终答案循环结束。4.3 完整示例与调用将以上两部分代码组合并添加一个入口点就是一个完整的可运行脚本if __name__ __main__: # 示例问题一个需要多步推理和工具调用的问题 query 请问北京现在的天气怎么样如果天气晴朗帮我计算一下25 17乘以2等于多少 print(f用户问题{query}) run_advisor_cycle(query)运行这个脚本你将会在控制台看到类似以下的对话流用户问题请问北京现在的天气怎么样如果天气晴朗帮我计算一下25 17乘以2等于多少 --- 第 1 轮对话 --- Claude 想调用工具 get_weather参数{city: 北京} 工具 get_weather 执行结果晴朗25°C湿度40% --- 第 2 轮对话 --- Claude: 北京现在的天气是晴朗25°C湿度40%。 Claude 想调用工具 calculate参数{expression: (25 17) * 2} 工具 calculate 执行结果表达式 (25 17) * 2 的计算结果是84 --- 第 3 轮对话 --- Claude: 根据计算(25 17) 乘以 2 等于 84。 --- 对话结束已获得最终答案 ---可以看到Advisor自动将复杂问题拆解成了“先查天气再根据结果决定是否计算”的步骤并依次调用了我们定义的工具最终整合信息给出了连贯的回答。5. 高级技巧与实战避坑指南掌握了基础实现后下面这些从实战中总结的经验能让你用得更顺手、更稳健。5.1 工具设计的艺术如何写出AI爱用的工具工具定义的好坏直接决定了Advisor使用的流畅度和准确性。描述要具体职责要单一description字段避免模糊。对比“处理数据”和“计算给定列表的平均值”后者清晰得多。一个工具最好只做一件事单一职责原则这样AI更容易理解和调用。参数设计要友好input_schema中的参数名应直观。使用city_name而非loc。为每个参数提供清晰的description。合理使用required字段确保AI不会遗漏关键信息。处理枚举和约束如果参数只能是几个特定值可以在schema中使用enum进行约束。例如一个currency_converter工具from_currency和to_currency可以限定为[USD, CNY, EUR, JPY]。这能极大提高AI调用时的准确性。input_schema: { type: object, properties: { from_currency: {type: string, enum: [USD, CNY, EUR, JPY]}, to_currency: {type: string, enum: [USD, CNY, EUR, JPY]}, amount: {type: number} }, required: [from_currency, to_currency, amount] }提供示例在工具描述的末尾可以加一句“例如get_stock_price(AAPL)”。这能给AI很强的提示。5.2 错误处理与鲁棒性增强我们的基础代码已经有了简单的try...except但在生产环境中需要更周全。工具函数内部的健壮性真实工具函数如real_get_weather必须包含完善的错误处理。网络请求超时、API返回异常格式、数据库查询失败等情况都要考虑并返回清晰的错误信息给AI例如“天气服务暂时不可用请稍后再试。”而不是抛出一个Python异常堆栈。处理未知工具虽然我们定义了映射但要预防AI因为上下文混淆或“幻觉”而请求一个未定义的工具。在tool_func real_tools.get(tool_name)后如果tool_func是None应该返回一个友好的错误信息如“抱歉我目前无法执行‘XXX’这个操作。”参数校验前置可以在调用真实函数前先根据input_schema对AI传入的tool_input做一次校验。比如检查必填字段是否存在类型是否匹配枚举值是否有效。这可以提前拦截很多问题。设置超时与重试对于网络调用类工具务必设置超时如使用requests库的timeout参数并考虑加入简单的重试逻辑如重试2次避免一次网络波动导致整个对话卡住。5.3 性能优化与成本控制频繁调用API会产生费用也需要时间。缓存工具结果对于一些耗时或调用成本高、且结果在短时间内不变的工具如天气查询、股票价格可以引入简单的缓存机制。例如用city作为键将结果在内存中缓存5分钟。from functools import lru_cache import time lru_cache(maxsize128) def real_get_weather_with_cache(city: str) - str: # ... 真实的API调用 ... pass注意需要根据业务场景决定缓存策略对于实时性要求高的数据不能缓存。精简上下文Messagesmessages列表会随着对话轮次增长每次都会发送给API。Token消耗与成本直接相关。对于非常长的多轮对话可以考虑在适当的时候比如一个问题完全解决后清空或截断历史或者使用API可能提供的“上下文摘要”功能如果未来支持。选择合适的模型claude-3-haiku模型更快、更便宜对于工具调用这类结构化任务其能力可能已经足够。claude-3-5-sonnet能力更强但更贵。根据任务复杂度进行选择。限制最大轮次max_turns我们代码里已经做了这是防止意外情况导致循环失控、产生高额费用的必要措施。一般设置为5-10轮已经能处理绝大多数复杂任务。5.4 扩展应用场景这50行代码是一个强大的框架可以轻松扩展到各种场景企业内部知识库问答定义search_internal_wiki工具函数内部连接你的Elasticsearch或向量数据库Advisor就能根据员工提问自动搜索并总结内部文档。数据分析与报表定义query_database、generate_chart工具。用户可以说“帮我分析一下上季度华东区的销售数据找出Top 3的产品并总结趋势。”Advisor会自动规划查询、分析、可视化的步骤。自动化工作流定义send_email、create_jira_ticket、query_crm等工具。Advisor可以理解“通知客户A项目延期并在CRM中更新状态”这样的指令并自动执行一系列操作。智能客服升级当标准客服机器人无法解决时可以无缝切换到Advisor模式Advisor通过调用“查询订单”、“检查物流”、“发起退款”等工具提供更深度的、可执行的服务。关键在于你将复杂的业务逻辑封装成一个个简单的工具函数而Advisor则扮演了理解用户意图、并智能编排这些工具的大脑。这种“AI规划 本地执行”的模式在安全可控的前提下极大地扩展了AI的应用边界。
![别再乱装 Skill 了！这 4 组神级 Skill 让你的 Claude Code 直接封神[特殊字符]【2026 最新实测】](http://pic.xiahunao.cn/yaotu/别再乱装 Skill 了！这 4 组神级 Skill 让你的 Claude Code 直接封神[特殊字符]【2026 最新实测】)
