在AI技术快速迭代的今天智能体Agent的开发与应用已成为开发者必须掌握的核心技能之一。你是否曾对如何构建一个能理解复杂指令、自主规划并执行任务的智能体感到困惑面对网上零散的教程和抽象的概念是否觉得无从下手本文将为你带来一份系统、完整的Agent开发实战指南深度结合当前热门的Anthropic Claude模型从零开始手把手带你构建功能强大的智能体。无论你是AI领域的初学者还是希望将Agent能力集成到现有项目的开发者都能从本文获得从环境搭建、核心原理到项目实战的闭环解决方案。1. 智能体Agent核心概念与架构解析在深入代码之前我们首先需要厘清几个关键概念什么是Agent它与传统的AI模型调用有何不同以及当前生态中“Agent Skills”与“Tools”等术语的具体含义。1.1 什么是智能体Agent简单来说一个智能体Agent是一个能够感知环境、进行决策并执行行动以实现特定目标的系统。在AI编程的语境下它通常指一个大型语言模型LLM驱动的程序该程序不仅能够生成文本还能根据目标自主调用外部工具如搜索、计算、API接口、访问数据并基于执行结果进行循环思考与决策。与传统的“单次问答”模式相比Agent的核心特征是自主性和工具使用能力。例如当你问一个普通聊天机器人“北京今天的天气如何”时它可能直接回答“我不知道实时信息”。而一个集成了天气API工具的Agent则会自主执行“调用天气查询工具 - 获取数据 - 组织语言回复”这一系列动作。1.2 Agent Skills vs. Agent Tools关键区别在网络搜索中我们常看到“Agent Skills”和“Agent Tools”这两个词它们容易混淆但侧重点不同Agent Tools工具这是指Agent可以调用的具体、离散的功能单元。一个工具通常对应一个函数或一个API接口有明确的输入和输出。例如search_web(query): 执行网络搜索。calculator(expression): 计算数学表达式。get_stock_price(symbol): 获取股票价格。工具是Agent执行动作的“手”和“脚”。Agent Skills技能这是一个更高层次、更抽象的概念。一项技能Skill通常由一系列的工具调用、逻辑判断和记忆组合而成用于完成一个更复杂的任务。你可以将技能视为一个“微工作流”或“能力包”。示例研究技能Research Skill这项技能可能包含以下步骤1) 调用search_web工具获取初步信息2) 分析搜索结果提炼关键问题3) 针对关键问题再次进行深度搜索4) 综合所有信息撰写一份结构化的报告。在这个过程中Agent可能需要多次调用同一个或不同的工具并进行链式思考。技能是目标导向的它封装了“如何完成某类任务”的知识和流程。简单总结Tools是原子操作Skills是由原子操作组成的复合能力。在开发中我们通常先定义好一系列Tools然后通过设计Prompt提示词和Workflow工作流来让Agent学会组合使用这些Tools从而形成Skills。1.3 主流框架与Anthropic Claude的角色目前构建Agent的常见框架有LangChain、LlamaIndex等它们提供了编排LLM、工具和记忆的底层架构。而Anthropic的Claude系列模型如Claude 3 Opus, Sonnet, Haiku因其强大的推理能力、长上下文支持和遵循指令的特性成为驱动Agent的“大脑”的绝佳选择。Claude模型通过其API提供了良好的function calling函数调用或tool use工具使用能力这意味着我们可以清晰地定义工具模型能够理解何时以及如何调用这些工具。本文的实战部分将基于Claude API进行。2. 环境准备与项目初始化工欲善其事必先利其器。在开始编码前我们需要准备好开发环境。2.1 基础环境要求操作系统Windows 10/11, macOS, 或 Linux (Ubuntu 20.04 推荐)。本文示例将在 macOS/Linux 环境下演示Windows 用户请注意命令行的差异建议使用 WSL2。Python版本 3.8 或更高。这是大多数AI库的基础。包管理工具pip(Python自带) 或conda(Anaconda发行版)。代码编辑器VS Code (推荐拥有丰富的Python和AI插件) 或 PyCharm。Anthropic API Key这是调用Claude模型的凭证。你需要访问Anthropic官网注册账户并创建API Key。请妥善保管你的API Key不要将其直接提交到代码仓库中。2.2 创建项目与安装依赖首先我们创建一个干净的项目目录并初始化虚拟环境以隔离项目依赖。# 1. 创建项目目录并进入 mkdir ai-agent-tutorial cd ai-agent-tutorial # 2. 创建虚拟环境 (以 venv 为例) python -m venv venv # 3. 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate # 4. 升级pip pip install --upgrade pip接下来安装核心依赖库。我们将使用anthropic官方库来调用Claude模型并使用langchain社区版本来构建Agent框架因为它对工具调用和流程编排有很好的支持。# 安装核心库 pip install anthropic langchain langchain-community # 安装其他实用库如用于网页搜索工具示例的库 pip install duckduckgo-search安装完成后你的项目根目录下应该有一个venv文件夹。我们建议创建以下项目结构ai-agent-tutorial/ ├── venv/ # Python虚拟环境 ├── .env # 环境变量文件用于存储API KEY ├── tools/ # 自定义工具模块 │ └── __init__.py │ └── web_tools.py ├── agents/ # Agent定义模块 │ └── __init__.py │ └── research_agent.py ├── main.py # 主程序入口 └── requirements.txt # 依赖列表创建.env文件来安全地存储你的API Key# .env 文件内容 ANTHROPIC_API_KEYyour_anthropic_api_key_here重要安全提示务必在.gitignore文件中添加.env防止将密钥意外提交到公开仓库。3. 核心组件一定义与封装工具Tools工具是Agent能力的基石。我们首先学习如何为Claude定义它能够使用的工具。3.1 工具的定义规范在LangChain和Claude的API中一个工具通常用一个JSON Schema来描述。这个Schema定义了工具的名称、描述、参数列表包括类型和说明。清晰的描述对于LLM理解工具用途至关重要。3.2 实战创建第一个工具——网络搜索我们使用duckduckgo-search库创建一个简单的网络搜索工具。首先在tools/web_tools.py中编写代码# tools/web_tools.py import json from duckduckgo_search import DDGS from typing import Dict, Any def search_web(query: str, max_results: int 5) - str: 使用DuckDuckGo在互联网上搜索信息。 Args: query (str): 搜索查询关键词。 max_results (int): 返回的最大结果数量默认为5。 Returns: str: 格式化后的搜索结果字符串。如果出错返回错误信息。 try: with DDGS() as ddgs: # 执行搜索 results list(ddgs.text(query, max_resultsmax_results)) if not results: return 未找到相关结果。 # 格式化结果 formatted_results [] for i, r in enumerate(results, 1): formatted_results.append( f[{i}] 标题: {r.get(title, N/A)}\n f 链接: {r.get(href, N/A)}\n f 摘要: {r.get(body, N/A)[:200]}... # 截取前200字符 ) return \n\n.join(formatted_results) except Exception as e: return f搜索过程中发生错误: {str(e)} # 为了能被LangChain和Claude识别我们需要将函数包装成标准工具格式。 # 这里我们先定义工具的Schema后续在Agent部分进行绑定。 WEB_SEARCH_TOOL_SCHEMA { name: search_web, description: 在互联网上搜索实时信息。当用户的问题涉及最新事件、事实核查或未知领域时使用此工具。, input_schema: { type: object, properties: { query: { type: string, description: 搜索查询词应具体、明确。 }, max_results: { type: integer, description: 期望返回的结果数量默认为5。, default: 5 } }, required: [query] } }代码解释search_web函数是工具的具体实现。它接收查询词和结果数量返回格式化的字符串。WEB_SEARCH_TOOL_SCHEMA字典定义了工具的元数据。description字段非常重要LLM会根据它来决定是否以及如何调用该工具。我们使用了类型提示typing和详细的文档字符串这有助于代码维护和AI理解。3.3 实战创建第二个工具——计算器再创建一个本地计算工具展示如何处理结构化输入。# tools/calculator_tools.py (新建文件) import math import ast import operator as op # 安全评估表达式的操作符映射 allowed_operators { ast.Add: op.add, ast.Sub: op.sub, ast.Mult: op.mul, ast.Div: op.truediv, ast.Pow: op.pow, ast.USub: op.neg, } def eval_expr(expr: str) - float: 安全地评估一个数学表达式字符串。 支持 , -, *, /, **, () 和常见函数如 sqrt, sin, cos。 # 替换常见的数学函数和常量 expr expr.replace(^, **) expr expr.replace(sqrt, math.sqrt) expr expr.replace(sin, math.sin) expr expr.replace(cos, math.cos) expr expr.replace(pi, str(math.pi)) expr expr.replace(e, str(math.e)) def _eval(node): if isinstance(node, ast.Num): # Python 3.8 return node.n elif isinstance(node, ast.Constant): # Python 3.8 return node.value elif isinstance(node, ast.BinOp): left_val _eval(node.left) right_val _eval(node.right) return allowed_operators[type(node.op)](left_val, right_val) elif isinstance(node, ast.UnaryOp): operand_val _eval(node.operand) return allowed_operators[type(node.op)](operand_val) elif isinstance(node, ast.Call): # 处理 math.sqrt 等函数调用 func_name node.func.attr if isinstance(node.func, ast.Attribute) else node.func.id args [_eval(arg) for arg in node.args] return getattr(math, func_name)(*args) else: raise TypeError(f不支持的表达式节点: {node}) try: tree ast.parse(expr, modeeval) result _eval(tree.body) return float(result) except (SyntaxError, TypeError, KeyError, AttributeError, ZeroDivisionError) as e: raise ValueError(f无法计算表达式 {expr}: {e}) def calculator(expression: str) - str: 计算一个数学表达式的结果。 Args: expression (str): 数学表达式例如 \(3 4) * 2 / sqrt(9)\。 Returns: str: 计算结果或错误信息。 try: result eval_expr(expression) return f表达式 {expression} 的计算结果是: {result} except ValueError as e: return str(e) CALCULATOR_TOOL_SCHEMA { name: calculator, description: 计算一个数学表达式的结果。支持加减乘除(, -, *, /)、乘方(**)、括号、以及sqrt、sin、cos等函数。当用户需要进行数值计算时使用此工具。, input_schema: { type: object, properties: { expression: { type: string, description: 需要计算的数学表达式例如 (12.5 4.3) * 2 或 sqrt(16) sin(pi/2)。 } }, required: [expression] } }这个计算器工具实现了安全的表达式求值避免了直接使用eval()的安全风险并提供了更清晰的错误处理。4. 核心组件二构建智能体Agent工作流有了工具我们需要一个“大脑”LLM和一个“调度系统”Agent Executor来协调工作。我们将使用LangChain的create_react_agent模式这是一种经典的“思考-行动-观察”ReAct模式。4.1 初始化Claude模型与工具列表首先在agents/research_agent.py中设置Agent。# agents/research_agent.py import os from dotenv import load_dotenv from langchain.agents import AgentExecutor, create_react_agent from langchain_anthropic import ChatAnthropic from langchain_core.prompts import PromptTemplate from langchain_core.tools import Tool # 导入我们自定义的工具函数和Schema from tools.web_tools import search_web, WEB_SEARCH_TOOL_SCHEMA from tools.calculator_tools import calculator, CALCULATOR_TOOL_SCHEMA # 加载环境变量 load_dotenv() class ResearchAgent: def __init__(self, model_nameclaude-3-haiku-20240307, temperature0.1, verboseTrue): 初始化研究型智能体。 Args: model_name (str): 使用的Claude模型名称。 temperature (float): 模型创造性越低越确定。 verbose (bool): 是否打印Agent的思考过程。 self.verbose verbose # 1. 初始化Claude模型 self.llm ChatAnthropic( modelmodel_name, temperaturetemperature, anthropic_api_keyos.getenv(ANTHROPIC_API_KEY), # 从.env读取 max_tokens4096, # 根据任务调整 ) # 2. 将自定义函数包装成LangChain Tool对象 self.tools [ Tool( nameWEB_SEARCH_TOOL_SCHEMA[name], funcsearch_web, descriptionWEB_SEARCH_TOOL_SCHEMA[description], args_schemaNone, # 使用函数签名自动推断或可自定义Schema ), Tool( nameCALCULATOR_TOOL_SCHEMA[name], funccalculator, descriptionCALCULATOR_TOOL_SCHEMA[description], args_schemaNone, ), ] # 3. 定义ReAct模式的提示词模板 # 这个模板指导LLM如何思考、何时使用工具。 self.prompt_template PromptTemplate.from_template( 你是一个强大的研究助手可以访问以下工具 {tools} 请严格按照以下格式回答 思考你需要首先思考当前问题判断是否需要使用工具以及使用哪个工具。 行动你选择的工具名称必须是以下之一[{tool_names}] 行动输入你选择的工具的输入参数必须是一个格式正确的JSON字符串。 观察工具返回的结果。 ... (这个“思考/行动/行动输入/观察”循环可以重复多次) 当你最终得出答案时必须以以下格式结束 最终答案[你的最终答案应清晰、完整地回应用户的问题。] 开始 问题{input} 思考{agent_scratchpad} ) # 4. 创建Agent和Executor self.agent create_react_agent( llmself.llm, toolsself.tools, promptself.prompt_template, ) self.agent_executor AgentExecutor( agentself.agent, toolsself.tools, verboseself.verbose, handle_parsing_errorsTrue, # 优雅处理解析错误 max_iterations10, # 防止无限循环 early_stopping_methodgenerate, # 达到最终答案后停止 ) def run(self, query: str) - str: 运行Agent处理用户查询。 Args: query (str): 用户的问题。 Returns: str: Agent的最终回答。 try: result self.agent_executor.invoke({input: query}) return result.get(output, Agent未返回明确输出。) except Exception as e: return fAgent执行过程中出现错误: {str(e)}关键点解析模型初始化我们使用ChatAnthropic类连接Claude API。claude-3-haiku-20240307是性价比高、速度快的模型适合开发调试。生产环境可考虑claude-3-sonnet或claude-3-opus。工具包装Tool类将我们的Python函数、描述绑定在一起供Agent框架使用。提示词工程PromptTemplate定义了Agent的“工作说明书”。ReAct格式强制模型进行链式推理输出结构化的中间步骤这对于调试和理解Agent行为至关重要。执行器AgentExecutor负责运行循环将用户输入和上一步的“观察”填入提示词 - 调用LLM获取下一步动作 - 执行工具 - 将结果作为“观察”反馈给LLM - 循环直到LLM输出“最终答案”。4.2 编写主程序进行测试创建main.py来集成并运行我们的Agent。# main.py from agents.research_agent import ResearchAgent def main(): print( AI研究助手Agent启动 ) print(输入 quit 或 exit 结束对话。\n) # 初始化Agent设置verboseTrue以查看思考过程 agent ResearchAgent(verboseTrue) while True: try: user_input input(\n您的问题: ).strip() if user_input.lower() in [quit, exit, q]: print(再见) break if not user_input: continue print(\n *50) print(Agent正在思考...) answer agent.run(user_input) print(\n *50) print(f助手: {answer}) except KeyboardInterrupt: print(\n\n程序被中断。) break except Exception as e: print(f\n发生未知错误: {e}) if __name__ __main__: main()5. 运行与实战演示现在让我们启动Agent并观察它如何工作。确保你的.env文件已正确配置ANTHROPIC_API_KEY。在终端激活虚拟环境后运行主程序python main.py5.1 场景一混合查询需要计算和搜索您的问题: 请帮我计算一下如果一台手机原价3999元现在打85折再加上150元的优惠券最终需要支付多少钱另外最近这款手机有什么用户评价吗 Agent正在思考... ... 思考用户的问题包含两个部分。第一部分是一个数学计算问题需要计算折扣和优惠券后的价格。第二部分是询问用户评价这需要最新的网络信息。我应该先计算价格然后搜索评价。 行动calculator 行动输入{expression: 3999 * 0.85 - 150} 观察表达式 3999 * 0.85 - 150 的计算结果是: 3249.15 思考计算结果显示最终价格为3249.15元。现在需要搜索这款手机的用户评价。我需要一个具体的手机型号来搜索。用户没有提及型号但提到了“这款手机”结合原价3999元可能是某个品牌的中高端机型。我需要先假设一个常见型号进行搜索或者让用户澄清。但根据指令我应该尽力回答问题。我可以搜索“3999元 手机 用户评价 2024”。 行动search_web 行动输入{query: 3999元 手机 用户评价 2024 最新, max_results: 5} 观察 [1] 标题: 2024年4000元价位手机推荐性价比与口碑俱佳的机型盘点 - 科技媒体 链接: https://example.com/article1 摘要: 本文盘点了2024年上半年在4000元价位段备受好评的几款手机包括小米14、一加12、荣耀Magic6等并从性能、拍照、续航和用户反馈进行了分析... [2] 标题: 小米14 用户真实评价性能强悍徕卡影像出色但续航有待提升 - 数码论坛 链接: https://example.com/article2 摘要: 在各大电商平台和论坛上小米14起售价3999元获得了大量用户评价。多数用户称赞其骁龙8 Gen 3处理器带来的流畅体验和徕卡影像质感... ... 思考我获得了关于3999元价位手机用户评价的通用信息。我可以总结这些信息来回答用户。同时我需要将计算的价格整合进去。 最终答案根据计算手机原价3999元打85折后为3399.15元再减去150元优惠券最终需要支付 **3249.15元**。 关于用户评价根据近期2024年的网络信息在3999元价位段像小米14、一加12、荣耀Magic6等机型关注度较高。普遍用户反馈包括 * **优点**旗舰级处理器如骁龙8 Gen 3性能强劲游戏和日常使用流畅旗舰影像系统如徕卡、哈苏联名拍照效果好屏幕素质高。 * **需要注意的方面**部分机型在高负载下发热控制一般续航表现因使用习惯差异较大系统更新和售后服务是用户考量的重点。 建议您确定具体手机型号后在电商平台如京东、天猫的商品评价区或专业数码论坛如酷安查看更具体的真实用户反馈。5.2 场景二纯计算您的问题: 一个半径为5的圆的面积是多少 Agent正在思考... 思考这是一个直接的数学计算问题。圆的面积公式是 π * r²。半径r5。 行动calculator 行动输入{expression: pi * 5 ** 2} 观察表达式 pi * 5 ** 2 的计算结果是: 78.53981633974483 思考计算完成可以直接给出答案。 最终答案半径为5的圆的面积大约是 **78.54**平方单位精确值约为78.53981633974483。5.3 场景三纯事实查询您的问题: 2024年巴黎奥运会中国代表团获得了多少枚金牌 Agent正在思考... 思考这是一个关于最新体育赛事结果的事实性问题需要实时信息。我应该使用网络搜索工具。 行动search_web 行动输入{query: 2024年巴黎奥运会 中国 金牌 数, max_results: 3} 观察 [1] 标题: 2024年巴黎奥运会中国体育代表团金牌榜 - 新华社快讯 链接: https://example.com/news/paris2024-china-gold 摘要: 截至巴黎奥运会闭幕2024年8月11日中国体育代表团共获得**42枚金牌**位列金牌榜第二位... ... 最终答案根据最新报道在2024年巴黎奥运会上中国体育代表团共获得了 **42枚金牌**。通过以上演示你可以看到Agent如何自主拆解问题、选择工具、执行并整合信息最终给出连贯的回答。verboseTrue模式下打印的“思考/行动/观察”链是调试和优化Agent行为的宝贵窗口。6. 常见问题与排查思路在开发和使用Agent过程中你可能会遇到以下典型问题。问题现象可能原因排查与解决思路Unable to connect to Anthropic services或Failed to connect to api.anthropic.com1.网络连接问题本地网络不稳定或受限。2.API Key错误或失效Key未设置、拼写错误或已过期。3.区域限制Anthropic服务在特定地区不可用。4.代理配置冲突本地系统或代码设置了错误的代理。1.检查网络使用curl或ping测试到api.anthropic.com的连接。2.验证API Key确认.env文件中的ANTHROPIC_API_KEY正确无误且在Anthropic控制台处于激活状态。3.检查环境变量确保代码通过load_dotenv()或os.getenv()正确读取了Key。4.排查代理如果使用代理确保代码中未错误配置或与系统代理冲突。可尝试在代码中临时设置anthropic_api_key参数直接传入Key进行测试。Agent陷入无限循环或多次调用无效工具1.工具描述不清晰LLM无法理解工具的用途。2.提示词Prompt设计不佳未能有效引导LLM的思考流程。3.max_iterations设置过高。1.优化工具描述确保description字段清晰、具体说明工具的精确用途和适用场景。2.优化提示词在Prompt中更明确地规定思考步骤和停止条件。可以加入示例Few-shot。3.设置迭代限制合理设置AgentExecutor的max_iterations如5-10次。4.启用verbose模式观察Agent的思考链找出循环点。LLM无法正确解析工具参数或格式错误1.工具参数Schema不匹配函数参数类型与Schema定义不符。2.LLM生成格式错误生成的“行动输入”不是合法的JSON。1.使用强类型和默认值在Python函数中使用类型提示并在Schema中定义default值。2.启用错误处理设置AgentExecutor(handle_parsing_errorsTrue)让Executor尝试修复格式错误。3.在Prompt中强调格式明确要求LLM输出“必须是一个格式正确的JSON字符串”。工具执行出错如搜索超时、计算异常1.工具函数内部有Bug未处理异常情况。2.外部服务不稳定。1.加强工具函数的健壮性使用try...except捕获所有可能异常并返回清晰的错误信息给LLM。2.添加重试机制对于网络请求类工具可以增加重试逻辑。3.提供备用方案在Agent的Prompt中指示当某个工具失败时可以尝试其他方法或告知用户。响应速度慢1.模型选择使用了大型号模型如Opus。2.网络延迟。3.工具调用耗时如搜索工具响应慢。4.迭代次数过多。1.开发期使用轻量模型如claude-3-haiku。2.为工具设置超时。3.优化工具性能如缓存频繁请求的结果。4.限制迭代次数。7. 进阶优化与最佳实践构建一个可用的Agent只是第一步要使其可靠、高效地应用于生产环境还需要遵循以下工程实践。7.1 技能Skill的抽象与封装如前所述Skill是更高阶的能力。我们可以通过创建链Chain或智能体Agent的集合来实现。示例封装一个“数据分析报告Skill”这个Skill的输入是一个数据集名称它需要1) 搜索该数据集的描述2) 获取最新数据假设通过另一个工具3) 进行简单的统计计算4) 生成一段文字报告。# skills/data_analysis_skill.py from langchain.chains import LLMChain, SequentialChain from langchain_core.prompts import PromptTemplate from .research_agent import ResearchAgent # 假设复用之前的Agent class DataAnalysisSkill: def __init__(self, llm): self.llm llm # 定义子链或子Agent self.research_agent ResearchAgent(verboseFalse) # 内嵌一个研究Agent # 定义报告生成链 report_prompt PromptTemplate.from_template( 你是一个数据分析师。以下是你收集到的关于数据集“{dataset_name}”的信息 {collected_info} 请基于以上信息撰写一份简短的数据分析报告包含1) 数据集概述2) 关键统计指标如存在3) 潜在的分析价值或应用方向。 报告 ) self.report_chain LLMChain(llmllm, promptreport_prompt) def run(self, dataset_name: str) - str: # 步骤1研究数据集描述 desc_query f{dataset_name} 数据集是什么主要包含哪些字段 description self.research_agent.run(desc_query) # 步骤2获取数据并计算这里简化假设有个get_dataset_stats工具 # stats get_dataset_stats(dataset_name) stats 此处为模拟的统计结果共10万条记录字段A均值5.6字段B标准差2.1 collected_info f描述信息{description}\n\n统计信息{stats} # 步骤3生成报告 report self.report_chain.run(dataset_namedataset_name, collected_infocollected_info) return report7.2 记忆Memory与多轮对话基础的ReAct Agent是无状态的。为了实现多轮对话需要引入记忆机制。LangChain提供了多种记忆组件。from langchain.memory import ConversationBufferMemory from langchain.agents import AgentExecutor, create_react_agent # 在初始化Agent时加入Memory memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 需要修改Prompt Template以包含历史对话 prompt_with_history PromptTemplate.from_template( 你是一个助手。以下是之前的对话历史 {chat_history} 现在请回答新问题。你可以使用工具。 工具{tools} 问题{input} 思考{agent_scratchpad} ) # 创建Agent时将memory传入prompt和executor的输入变量中 agent create_react_agent(llmllm, toolstools, promptprompt_with_history) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, # 关键传入memory verboseTrue, ) # 调用时Agent会自动管理chat_history的输入输出7.3 生产环境部署建议API密钥管理使用专业的密钥管理服务如AWS Secrets Manager, HashiCorp Vault或至少使用环境变量绝不在代码中硬编码。错误处理与降级对LLM API调用和工具调用添加完善的重试、超时和降级逻辑例如搜索失败时返回缓存结果或友好提示。日志与监控记录详细的运行日志包括用户查询、Agent的思考链、工具调用详情和最终响应。监控API调用成本、延迟和错误率。速率限制遵守Anthropic API的速率限制在客户端实现限流或使用队列。安全性工具权限隔离为不同的工具设置不同的执行权限特别是涉及写操作或敏感API的工具。用户输入净化对用户输入进行校验防止Prompt注入攻击。输出内容过滤对Agent生成的内容进行安全检查避免输出有害或不适当信息。测试为你的Agent和工具编写单元测试和集成测试模拟各种用户输入和工具响应。7.4 提示词Prompt优化技巧角色设定在Prompt开头明确Agent的角色如“你是一个专业的研究助手”。格式约束严格规定输出格式如ReAct格式这能极大提高输出的可解析性。提供示例Few-shot在Prompt中给出1-2个完整的“问题-思考-行动-答案”示例能显著提升模型表现。分步思考Chain-of-Thought鼓励模型“一步一步思考”即使在不使用工具的情况下也能提高复杂问题推理的准确性。明确边界告诉模型什么能做什么不能做例如“不要编造信息如果不知道就使用搜索工具”。从定义清晰的工具开始构建一个结构良好的ReAct Agent再通过记忆、技能封装和严格的工程实践进行增强你就能打造出真正强大、实用的AI智能体应用。记住迭代和测试是关键不断观察Agent的“思考过程”优化提示词和工具设计你的Agent会变得越来越聪明可靠。 基于Claude的AI智能体开发实战：从工具定义到ReAct工作流构建
在AI技术快速迭代的今天智能体Agent的开发与应用已成为开发者必须掌握的核心技能之一。你是否曾对如何构建一个能理解复杂指令、自主规划并执行任务的智能体感到困惑面对网上零散的教程和抽象的概念是否觉得无从下手本文将为你带来一份系统、完整的Agent开发实战指南深度结合当前热门的Anthropic Claude模型从零开始手把手带你构建功能强大的智能体。无论你是AI领域的初学者还是希望将Agent能力集成到现有项目的开发者都能从本文获得从环境搭建、核心原理到项目实战的闭环解决方案。1. 智能体Agent核心概念与架构解析在深入代码之前我们首先需要厘清几个关键概念什么是Agent它与传统的AI模型调用有何不同以及当前生态中“Agent Skills”与“Tools”等术语的具体含义。1.1 什么是智能体Agent简单来说一个智能体Agent是一个能够感知环境、进行决策并执行行动以实现特定目标的系统。在AI编程的语境下它通常指一个大型语言模型LLM驱动的程序该程序不仅能够生成文本还能根据目标自主调用外部工具如搜索、计算、API接口、访问数据并基于执行结果进行循环思考与决策。与传统的“单次问答”模式相比Agent的核心特征是自主性和工具使用能力。例如当你问一个普通聊天机器人“北京今天的天气如何”时它可能直接回答“我不知道实时信息”。而一个集成了天气API工具的Agent则会自主执行“调用天气查询工具 - 获取数据 - 组织语言回复”这一系列动作。1.2 Agent Skills vs. Agent Tools关键区别在网络搜索中我们常看到“Agent Skills”和“Agent Tools”这两个词它们容易混淆但侧重点不同Agent Tools工具这是指Agent可以调用的具体、离散的功能单元。一个工具通常对应一个函数或一个API接口有明确的输入和输出。例如search_web(query): 执行网络搜索。calculator(expression): 计算数学表达式。get_stock_price(symbol): 获取股票价格。工具是Agent执行动作的“手”和“脚”。Agent Skills技能这是一个更高层次、更抽象的概念。一项技能Skill通常由一系列的工具调用、逻辑判断和记忆组合而成用于完成一个更复杂的任务。你可以将技能视为一个“微工作流”或“能力包”。示例研究技能Research Skill这项技能可能包含以下步骤1) 调用search_web工具获取初步信息2) 分析搜索结果提炼关键问题3) 针对关键问题再次进行深度搜索4) 综合所有信息撰写一份结构化的报告。在这个过程中Agent可能需要多次调用同一个或不同的工具并进行链式思考。技能是目标导向的它封装了“如何完成某类任务”的知识和流程。简单总结Tools是原子操作Skills是由原子操作组成的复合能力。在开发中我们通常先定义好一系列Tools然后通过设计Prompt提示词和Workflow工作流来让Agent学会组合使用这些Tools从而形成Skills。1.3 主流框架与Anthropic Claude的角色目前构建Agent的常见框架有LangChain、LlamaIndex等它们提供了编排LLM、工具和记忆的底层架构。而Anthropic的Claude系列模型如Claude 3 Opus, Sonnet, Haiku因其强大的推理能力、长上下文支持和遵循指令的特性成为驱动Agent的“大脑”的绝佳选择。Claude模型通过其API提供了良好的function calling函数调用或tool use工具使用能力这意味着我们可以清晰地定义工具模型能够理解何时以及如何调用这些工具。本文的实战部分将基于Claude API进行。2. 环境准备与项目初始化工欲善其事必先利其器。在开始编码前我们需要准备好开发环境。2.1 基础环境要求操作系统Windows 10/11, macOS, 或 Linux (Ubuntu 20.04 推荐)。本文示例将在 macOS/Linux 环境下演示Windows 用户请注意命令行的差异建议使用 WSL2。Python版本 3.8 或更高。这是大多数AI库的基础。包管理工具pip(Python自带) 或conda(Anaconda发行版)。代码编辑器VS Code (推荐拥有丰富的Python和AI插件) 或 PyCharm。Anthropic API Key这是调用Claude模型的凭证。你需要访问Anthropic官网注册账户并创建API Key。请妥善保管你的API Key不要将其直接提交到代码仓库中。2.2 创建项目与安装依赖首先我们创建一个干净的项目目录并初始化虚拟环境以隔离项目依赖。# 1. 创建项目目录并进入 mkdir ai-agent-tutorial cd ai-agent-tutorial # 2. 创建虚拟环境 (以 venv 为例) python -m venv venv # 3. 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate # 4. 升级pip pip install --upgrade pip接下来安装核心依赖库。我们将使用anthropic官方库来调用Claude模型并使用langchain社区版本来构建Agent框架因为它对工具调用和流程编排有很好的支持。# 安装核心库 pip install anthropic langchain langchain-community # 安装其他实用库如用于网页搜索工具示例的库 pip install duckduckgo-search安装完成后你的项目根目录下应该有一个venv文件夹。我们建议创建以下项目结构ai-agent-tutorial/ ├── venv/ # Python虚拟环境 ├── .env # 环境变量文件用于存储API KEY ├── tools/ # 自定义工具模块 │ └── __init__.py │ └── web_tools.py ├── agents/ # Agent定义模块 │ └── __init__.py │ └── research_agent.py ├── main.py # 主程序入口 └── requirements.txt # 依赖列表创建.env文件来安全地存储你的API Key# .env 文件内容 ANTHROPIC_API_KEYyour_anthropic_api_key_here重要安全提示务必在.gitignore文件中添加.env防止将密钥意外提交到公开仓库。3. 核心组件一定义与封装工具Tools工具是Agent能力的基石。我们首先学习如何为Claude定义它能够使用的工具。3.1 工具的定义规范在LangChain和Claude的API中一个工具通常用一个JSON Schema来描述。这个Schema定义了工具的名称、描述、参数列表包括类型和说明。清晰的描述对于LLM理解工具用途至关重要。3.2 实战创建第一个工具——网络搜索我们使用duckduckgo-search库创建一个简单的网络搜索工具。首先在tools/web_tools.py中编写代码# tools/web_tools.py import json from duckduckgo_search import DDGS from typing import Dict, Any def search_web(query: str, max_results: int 5) - str: 使用DuckDuckGo在互联网上搜索信息。 Args: query (str): 搜索查询关键词。 max_results (int): 返回的最大结果数量默认为5。 Returns: str: 格式化后的搜索结果字符串。如果出错返回错误信息。 try: with DDGS() as ddgs: # 执行搜索 results list(ddgs.text(query, max_resultsmax_results)) if not results: return 未找到相关结果。 # 格式化结果 formatted_results [] for i, r in enumerate(results, 1): formatted_results.append( f[{i}] 标题: {r.get(title, N/A)}\n f 链接: {r.get(href, N/A)}\n f 摘要: {r.get(body, N/A)[:200]}... # 截取前200字符 ) return \n\n.join(formatted_results) except Exception as e: return f搜索过程中发生错误: {str(e)} # 为了能被LangChain和Claude识别我们需要将函数包装成标准工具格式。 # 这里我们先定义工具的Schema后续在Agent部分进行绑定。 WEB_SEARCH_TOOL_SCHEMA { name: search_web, description: 在互联网上搜索实时信息。当用户的问题涉及最新事件、事实核查或未知领域时使用此工具。, input_schema: { type: object, properties: { query: { type: string, description: 搜索查询词应具体、明确。 }, max_results: { type: integer, description: 期望返回的结果数量默认为5。, default: 5 } }, required: [query] } }代码解释search_web函数是工具的具体实现。它接收查询词和结果数量返回格式化的字符串。WEB_SEARCH_TOOL_SCHEMA字典定义了工具的元数据。description字段非常重要LLM会根据它来决定是否以及如何调用该工具。我们使用了类型提示typing和详细的文档字符串这有助于代码维护和AI理解。3.3 实战创建第二个工具——计算器再创建一个本地计算工具展示如何处理结构化输入。# tools/calculator_tools.py (新建文件) import math import ast import operator as op # 安全评估表达式的操作符映射 allowed_operators { ast.Add: op.add, ast.Sub: op.sub, ast.Mult: op.mul, ast.Div: op.truediv, ast.Pow: op.pow, ast.USub: op.neg, } def eval_expr(expr: str) - float: 安全地评估一个数学表达式字符串。 支持 , -, *, /, **, () 和常见函数如 sqrt, sin, cos。 # 替换常见的数学函数和常量 expr expr.replace(^, **) expr expr.replace(sqrt, math.sqrt) expr expr.replace(sin, math.sin) expr expr.replace(cos, math.cos) expr expr.replace(pi, str(math.pi)) expr expr.replace(e, str(math.e)) def _eval(node): if isinstance(node, ast.Num): # Python 3.8 return node.n elif isinstance(node, ast.Constant): # Python 3.8 return node.value elif isinstance(node, ast.BinOp): left_val _eval(node.left) right_val _eval(node.right) return allowed_operators[type(node.op)](left_val, right_val) elif isinstance(node, ast.UnaryOp): operand_val _eval(node.operand) return allowed_operators[type(node.op)](operand_val) elif isinstance(node, ast.Call): # 处理 math.sqrt 等函数调用 func_name node.func.attr if isinstance(node.func, ast.Attribute) else node.func.id args [_eval(arg) for arg in node.args] return getattr(math, func_name)(*args) else: raise TypeError(f不支持的表达式节点: {node}) try: tree ast.parse(expr, modeeval) result _eval(tree.body) return float(result) except (SyntaxError, TypeError, KeyError, AttributeError, ZeroDivisionError) as e: raise ValueError(f无法计算表达式 {expr}: {e}) def calculator(expression: str) - str: 计算一个数学表达式的结果。 Args: expression (str): 数学表达式例如 \(3 4) * 2 / sqrt(9)\。 Returns: str: 计算结果或错误信息。 try: result eval_expr(expression) return f表达式 {expression} 的计算结果是: {result} except ValueError as e: return str(e) CALCULATOR_TOOL_SCHEMA { name: calculator, description: 计算一个数学表达式的结果。支持加减乘除(, -, *, /)、乘方(**)、括号、以及sqrt、sin、cos等函数。当用户需要进行数值计算时使用此工具。, input_schema: { type: object, properties: { expression: { type: string, description: 需要计算的数学表达式例如 (12.5 4.3) * 2 或 sqrt(16) sin(pi/2)。 } }, required: [expression] } }这个计算器工具实现了安全的表达式求值避免了直接使用eval()的安全风险并提供了更清晰的错误处理。4. 核心组件二构建智能体Agent工作流有了工具我们需要一个“大脑”LLM和一个“调度系统”Agent Executor来协调工作。我们将使用LangChain的create_react_agent模式这是一种经典的“思考-行动-观察”ReAct模式。4.1 初始化Claude模型与工具列表首先在agents/research_agent.py中设置Agent。# agents/research_agent.py import os from dotenv import load_dotenv from langchain.agents import AgentExecutor, create_react_agent from langchain_anthropic import ChatAnthropic from langchain_core.prompts import PromptTemplate from langchain_core.tools import Tool # 导入我们自定义的工具函数和Schema from tools.web_tools import search_web, WEB_SEARCH_TOOL_SCHEMA from tools.calculator_tools import calculator, CALCULATOR_TOOL_SCHEMA # 加载环境变量 load_dotenv() class ResearchAgent: def __init__(self, model_nameclaude-3-haiku-20240307, temperature0.1, verboseTrue): 初始化研究型智能体。 Args: model_name (str): 使用的Claude模型名称。 temperature (float): 模型创造性越低越确定。 verbose (bool): 是否打印Agent的思考过程。 self.verbose verbose # 1. 初始化Claude模型 self.llm ChatAnthropic( modelmodel_name, temperaturetemperature, anthropic_api_keyos.getenv(ANTHROPIC_API_KEY), # 从.env读取 max_tokens4096, # 根据任务调整 ) # 2. 将自定义函数包装成LangChain Tool对象 self.tools [ Tool( nameWEB_SEARCH_TOOL_SCHEMA[name], funcsearch_web, descriptionWEB_SEARCH_TOOL_SCHEMA[description], args_schemaNone, # 使用函数签名自动推断或可自定义Schema ), Tool( nameCALCULATOR_TOOL_SCHEMA[name], funccalculator, descriptionCALCULATOR_TOOL_SCHEMA[description], args_schemaNone, ), ] # 3. 定义ReAct模式的提示词模板 # 这个模板指导LLM如何思考、何时使用工具。 self.prompt_template PromptTemplate.from_template( 你是一个强大的研究助手可以访问以下工具 {tools} 请严格按照以下格式回答 思考你需要首先思考当前问题判断是否需要使用工具以及使用哪个工具。 行动你选择的工具名称必须是以下之一[{tool_names}] 行动输入你选择的工具的输入参数必须是一个格式正确的JSON字符串。 观察工具返回的结果。 ... (这个“思考/行动/行动输入/观察”循环可以重复多次) 当你最终得出答案时必须以以下格式结束 最终答案[你的最终答案应清晰、完整地回应用户的问题。] 开始 问题{input} 思考{agent_scratchpad} ) # 4. 创建Agent和Executor self.agent create_react_agent( llmself.llm, toolsself.tools, promptself.prompt_template, ) self.agent_executor AgentExecutor( agentself.agent, toolsself.tools, verboseself.verbose, handle_parsing_errorsTrue, # 优雅处理解析错误 max_iterations10, # 防止无限循环 early_stopping_methodgenerate, # 达到最终答案后停止 ) def run(self, query: str) - str: 运行Agent处理用户查询。 Args: query (str): 用户的问题。 Returns: str: Agent的最终回答。 try: result self.agent_executor.invoke({input: query}) return result.get(output, Agent未返回明确输出。) except Exception as e: return fAgent执行过程中出现错误: {str(e)}关键点解析模型初始化我们使用ChatAnthropic类连接Claude API。claude-3-haiku-20240307是性价比高、速度快的模型适合开发调试。生产环境可考虑claude-3-sonnet或claude-3-opus。工具包装Tool类将我们的Python函数、描述绑定在一起供Agent框架使用。提示词工程PromptTemplate定义了Agent的“工作说明书”。ReAct格式强制模型进行链式推理输出结构化的中间步骤这对于调试和理解Agent行为至关重要。执行器AgentExecutor负责运行循环将用户输入和上一步的“观察”填入提示词 - 调用LLM获取下一步动作 - 执行工具 - 将结果作为“观察”反馈给LLM - 循环直到LLM输出“最终答案”。4.2 编写主程序进行测试创建main.py来集成并运行我们的Agent。# main.py from agents.research_agent import ResearchAgent def main(): print( AI研究助手Agent启动 ) print(输入 quit 或 exit 结束对话。\n) # 初始化Agent设置verboseTrue以查看思考过程 agent ResearchAgent(verboseTrue) while True: try: user_input input(\n您的问题: ).strip() if user_input.lower() in [quit, exit, q]: print(再见) break if not user_input: continue print(\n *50) print(Agent正在思考...) answer agent.run(user_input) print(\n *50) print(f助手: {answer}) except KeyboardInterrupt: print(\n\n程序被中断。) break except Exception as e: print(f\n发生未知错误: {e}) if __name__ __main__: main()5. 运行与实战演示现在让我们启动Agent并观察它如何工作。确保你的.env文件已正确配置ANTHROPIC_API_KEY。在终端激活虚拟环境后运行主程序python main.py5.1 场景一混合查询需要计算和搜索您的问题: 请帮我计算一下如果一台手机原价3999元现在打85折再加上150元的优惠券最终需要支付多少钱另外最近这款手机有什么用户评价吗 Agent正在思考... ... 思考用户的问题包含两个部分。第一部分是一个数学计算问题需要计算折扣和优惠券后的价格。第二部分是询问用户评价这需要最新的网络信息。我应该先计算价格然后搜索评价。 行动calculator 行动输入{expression: 3999 * 0.85 - 150} 观察表达式 3999 * 0.85 - 150 的计算结果是: 3249.15 思考计算结果显示最终价格为3249.15元。现在需要搜索这款手机的用户评价。我需要一个具体的手机型号来搜索。用户没有提及型号但提到了“这款手机”结合原价3999元可能是某个品牌的中高端机型。我需要先假设一个常见型号进行搜索或者让用户澄清。但根据指令我应该尽力回答问题。我可以搜索“3999元 手机 用户评价 2024”。 行动search_web 行动输入{query: 3999元 手机 用户评价 2024 最新, max_results: 5} 观察 [1] 标题: 2024年4000元价位手机推荐性价比与口碑俱佳的机型盘点 - 科技媒体 链接: https://example.com/article1 摘要: 本文盘点了2024年上半年在4000元价位段备受好评的几款手机包括小米14、一加12、荣耀Magic6等并从性能、拍照、续航和用户反馈进行了分析... [2] 标题: 小米14 用户真实评价性能强悍徕卡影像出色但续航有待提升 - 数码论坛 链接: https://example.com/article2 摘要: 在各大电商平台和论坛上小米14起售价3999元获得了大量用户评价。多数用户称赞其骁龙8 Gen 3处理器带来的流畅体验和徕卡影像质感... ... 思考我获得了关于3999元价位手机用户评价的通用信息。我可以总结这些信息来回答用户。同时我需要将计算的价格整合进去。 最终答案根据计算手机原价3999元打85折后为3399.15元再减去150元优惠券最终需要支付 **3249.15元**。 关于用户评价根据近期2024年的网络信息在3999元价位段像小米14、一加12、荣耀Magic6等机型关注度较高。普遍用户反馈包括 * **优点**旗舰级处理器如骁龙8 Gen 3性能强劲游戏和日常使用流畅旗舰影像系统如徕卡、哈苏联名拍照效果好屏幕素质高。 * **需要注意的方面**部分机型在高负载下发热控制一般续航表现因使用习惯差异较大系统更新和售后服务是用户考量的重点。 建议您确定具体手机型号后在电商平台如京东、天猫的商品评价区或专业数码论坛如酷安查看更具体的真实用户反馈。5.2 场景二纯计算您的问题: 一个半径为5的圆的面积是多少 Agent正在思考... 思考这是一个直接的数学计算问题。圆的面积公式是 π * r²。半径r5。 行动calculator 行动输入{expression: pi * 5 ** 2} 观察表达式 pi * 5 ** 2 的计算结果是: 78.53981633974483 思考计算完成可以直接给出答案。 最终答案半径为5的圆的面积大约是 **78.54**平方单位精确值约为78.53981633974483。5.3 场景三纯事实查询您的问题: 2024年巴黎奥运会中国代表团获得了多少枚金牌 Agent正在思考... 思考这是一个关于最新体育赛事结果的事实性问题需要实时信息。我应该使用网络搜索工具。 行动search_web 行动输入{query: 2024年巴黎奥运会 中国 金牌 数, max_results: 3} 观察 [1] 标题: 2024年巴黎奥运会中国体育代表团金牌榜 - 新华社快讯 链接: https://example.com/news/paris2024-china-gold 摘要: 截至巴黎奥运会闭幕2024年8月11日中国体育代表团共获得**42枚金牌**位列金牌榜第二位... ... 最终答案根据最新报道在2024年巴黎奥运会上中国体育代表团共获得了 **42枚金牌**。通过以上演示你可以看到Agent如何自主拆解问题、选择工具、执行并整合信息最终给出连贯的回答。verboseTrue模式下打印的“思考/行动/观察”链是调试和优化Agent行为的宝贵窗口。6. 常见问题与排查思路在开发和使用Agent过程中你可能会遇到以下典型问题。问题现象可能原因排查与解决思路Unable to connect to Anthropic services或Failed to connect to api.anthropic.com1.网络连接问题本地网络不稳定或受限。2.API Key错误或失效Key未设置、拼写错误或已过期。3.区域限制Anthropic服务在特定地区不可用。4.代理配置冲突本地系统或代码设置了错误的代理。1.检查网络使用curl或ping测试到api.anthropic.com的连接。2.验证API Key确认.env文件中的ANTHROPIC_API_KEY正确无误且在Anthropic控制台处于激活状态。3.检查环境变量确保代码通过load_dotenv()或os.getenv()正确读取了Key。4.排查代理如果使用代理确保代码中未错误配置或与系统代理冲突。可尝试在代码中临时设置anthropic_api_key参数直接传入Key进行测试。Agent陷入无限循环或多次调用无效工具1.工具描述不清晰LLM无法理解工具的用途。2.提示词Prompt设计不佳未能有效引导LLM的思考流程。3.max_iterations设置过高。1.优化工具描述确保description字段清晰、具体说明工具的精确用途和适用场景。2.优化提示词在Prompt中更明确地规定思考步骤和停止条件。可以加入示例Few-shot。3.设置迭代限制合理设置AgentExecutor的max_iterations如5-10次。4.启用verbose模式观察Agent的思考链找出循环点。LLM无法正确解析工具参数或格式错误1.工具参数Schema不匹配函数参数类型与Schema定义不符。2.LLM生成格式错误生成的“行动输入”不是合法的JSON。1.使用强类型和默认值在Python函数中使用类型提示并在Schema中定义default值。2.启用错误处理设置AgentExecutor(handle_parsing_errorsTrue)让Executor尝试修复格式错误。3.在Prompt中强调格式明确要求LLM输出“必须是一个格式正确的JSON字符串”。工具执行出错如搜索超时、计算异常1.工具函数内部有Bug未处理异常情况。2.外部服务不稳定。1.加强工具函数的健壮性使用try...except捕获所有可能异常并返回清晰的错误信息给LLM。2.添加重试机制对于网络请求类工具可以增加重试逻辑。3.提供备用方案在Agent的Prompt中指示当某个工具失败时可以尝试其他方法或告知用户。响应速度慢1.模型选择使用了大型号模型如Opus。2.网络延迟。3.工具调用耗时如搜索工具响应慢。4.迭代次数过多。1.开发期使用轻量模型如claude-3-haiku。2.为工具设置超时。3.优化工具性能如缓存频繁请求的结果。4.限制迭代次数。7. 进阶优化与最佳实践构建一个可用的Agent只是第一步要使其可靠、高效地应用于生产环境还需要遵循以下工程实践。7.1 技能Skill的抽象与封装如前所述Skill是更高阶的能力。我们可以通过创建链Chain或智能体Agent的集合来实现。示例封装一个“数据分析报告Skill”这个Skill的输入是一个数据集名称它需要1) 搜索该数据集的描述2) 获取最新数据假设通过另一个工具3) 进行简单的统计计算4) 生成一段文字报告。# skills/data_analysis_skill.py from langchain.chains import LLMChain, SequentialChain from langchain_core.prompts import PromptTemplate from .research_agent import ResearchAgent # 假设复用之前的Agent class DataAnalysisSkill: def __init__(self, llm): self.llm llm # 定义子链或子Agent self.research_agent ResearchAgent(verboseFalse) # 内嵌一个研究Agent # 定义报告生成链 report_prompt PromptTemplate.from_template( 你是一个数据分析师。以下是你收集到的关于数据集“{dataset_name}”的信息 {collected_info} 请基于以上信息撰写一份简短的数据分析报告包含1) 数据集概述2) 关键统计指标如存在3) 潜在的分析价值或应用方向。 报告 ) self.report_chain LLMChain(llmllm, promptreport_prompt) def run(self, dataset_name: str) - str: # 步骤1研究数据集描述 desc_query f{dataset_name} 数据集是什么主要包含哪些字段 description self.research_agent.run(desc_query) # 步骤2获取数据并计算这里简化假设有个get_dataset_stats工具 # stats get_dataset_stats(dataset_name) stats 此处为模拟的统计结果共10万条记录字段A均值5.6字段B标准差2.1 collected_info f描述信息{description}\n\n统计信息{stats} # 步骤3生成报告 report self.report_chain.run(dataset_namedataset_name, collected_infocollected_info) return report7.2 记忆Memory与多轮对话基础的ReAct Agent是无状态的。为了实现多轮对话需要引入记忆机制。LangChain提供了多种记忆组件。from langchain.memory import ConversationBufferMemory from langchain.agents import AgentExecutor, create_react_agent # 在初始化Agent时加入Memory memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 需要修改Prompt Template以包含历史对话 prompt_with_history PromptTemplate.from_template( 你是一个助手。以下是之前的对话历史 {chat_history} 现在请回答新问题。你可以使用工具。 工具{tools} 问题{input} 思考{agent_scratchpad} ) # 创建Agent时将memory传入prompt和executor的输入变量中 agent create_react_agent(llmllm, toolstools, promptprompt_with_history) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, # 关键传入memory verboseTrue, ) # 调用时Agent会自动管理chat_history的输入输出7.3 生产环境部署建议API密钥管理使用专业的密钥管理服务如AWS Secrets Manager, HashiCorp Vault或至少使用环境变量绝不在代码中硬编码。错误处理与降级对LLM API调用和工具调用添加完善的重试、超时和降级逻辑例如搜索失败时返回缓存结果或友好提示。日志与监控记录详细的运行日志包括用户查询、Agent的思考链、工具调用详情和最终响应。监控API调用成本、延迟和错误率。速率限制遵守Anthropic API的速率限制在客户端实现限流或使用队列。安全性工具权限隔离为不同的工具设置不同的执行权限特别是涉及写操作或敏感API的工具。用户输入净化对用户输入进行校验防止Prompt注入攻击。输出内容过滤对Agent生成的内容进行安全检查避免输出有害或不适当信息。测试为你的Agent和工具编写单元测试和集成测试模拟各种用户输入和工具响应。7.4 提示词Prompt优化技巧角色设定在Prompt开头明确Agent的角色如“你是一个专业的研究助手”。格式约束严格规定输出格式如ReAct格式这能极大提高输出的可解析性。提供示例Few-shot在Prompt中给出1-2个完整的“问题-思考-行动-答案”示例能显著提升模型表现。分步思考Chain-of-Thought鼓励模型“一步一步思考”即使在不使用工具的情况下也能提高复杂问题推理的准确性。明确边界告诉模型什么能做什么不能做例如“不要编造信息如果不知道就使用搜索工具”。从定义清晰的工具开始构建一个结构良好的ReAct Agent再通过记忆、技能封装和严格的工程实践进行增强你就能打造出真正强大、实用的AI智能体应用。记住迭代和测试是关键不断观察Agent的“思考过程”优化提示词和工具设计你的Agent会变得越来越聪明可靠。