30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度在实际项目中AI Agent 已经从实验室概念演变为解决复杂任务的关键技术组件。无论是自动化客服、智能数据分析助手还是集成在应用中的个性化推荐引擎其核心都是让机器能够理解目标、规划步骤、调用工具并执行决策。对于开发者而言从零开始构建一个可用的 Agent 往往面临概念庞杂、工具链不熟悉、代码与理论脱节等挑战。本文旨在提供一个结构清晰、可动手实践的 AI Agent 开发入门指南帮助具备基础编程能力的开发者理解 Agent 的核心工作机制并完成一个具备规划与执行能力的简单任务执行 Agent。我们将从最基础的 Agent 概念和工作流讲起然后搭建一个最小化的开发环境接着通过一个“联网信息查询与总结”的完整案例展示如何利用主流框架如 LangChain的关键组件构建 Agent。文章会详细解释每一步的代码意图、配置参数以及背后的设计逻辑并提供运行验证、常见问题排查路径和向更复杂场景扩展的建议。学完后你将能够掌握 Agent 开发的基本模式并具备将其应用于实际业务场景的初步能力。1. 理解 AI Agent 的核心从感知到行动的循环在深入代码之前必须厘清 AI Agent 与普通调用大语言模型LLMAPI 的程序有何本质区别。很多初学者误以为给 LLM 加个循环就是 Agent这忽略了其核心的自主决策与工具使用能力。1.1 Agent 是什么超越简单问答的智能体通俗地讲一个 AI Agent 是一个能够感知环境、自主决策并执行行动以达成给定目标的软件实体。它不仅仅是根据输入生成文本而是具备“思考-行动-观察”的循环能力。例如一个简单的“天气查询Agent”的思考过程可能是用户目标是“北京明天适合穿什么”Agent 需要先规划步骤1. 获取北京明天的天气预报。2. 根据天气数据温度、降水生成穿衣建议。3. 将建议返回给用户。其中第一步就需要调用一个“获取天气”的工具Tool。技术定义上一个典型的 Agent 系统包含几个核心组件规划器Planner通常由 LLM 担任负责将复杂目标分解为可执行的步骤或子任务序列。工具ToolsAgent 可以调用的外部函数或 API用于获取信息如搜索、查数据库或执行操作如发送邮件、操作文件。记忆Memory用于存储和回顾与当前任务相关的历史信息对话历史、中间结果为后续决策提供上下文。执行器Executor协调整个循环根据规划调用工具处理工具返回的结果并决定下一步是继续规划、重新规划还是结束任务。1.2 Agent 的典型工作流ReAct 模式目前最流行且有效的 Agent 工作流之一是ReAct (Reasoning Acting)模式。它清晰地展示了 Agent 的思考过程。思考ThinkLLM 根据当前目标、历史记录和可用工具列表分析下一步应该做什么。输出格式通常是“我需要先使用 X 工具来获取 Y 信息。”行动Act根据思考结果调用指定的工具并传入相应的参数。观察Observe获取工具执行后的返回结果可能是数据也可能是成功/失败状态。循环将“思考-行动-观察”的结果作为新的上下文再次送入 LLM 进行下一轮思考直到 LLM 认为任务已完成并输出最终答案。这个循环的关键在于LLM 的每次“思考”都基于最新的环境观察工具执行结果从而能够动态调整计划。例如如果调用天气 API 失败LLM 可能会思考“天气 API 调用失败我可以尝试使用网络搜索工具来查找天气信息。”1.3 为什么需要框架LangChain 的角色手动实现上述循环、工具调用封装、提示词Prompt管理和记忆存储非常繁琐且容易出错。因此我们使用LangChain这样的框架。它抽象了这些通用模式提供了构建 Agent 所需的高层组件让我们可以更专注于业务逻辑和工具定义而不是底层通信和状态管理。在接下来的部分我们将基于 LangChain 来构建我们的第一个 Agent。2. 环境准备与依赖配置搭建可复现的开发底座一个稳定、版本对齐的开发环境是后续所有步骤的基础。Agent 开发涉及 LLM 服务、Python 环境、框架和多个工具库版本冲突是新手最常见的“拦路虎”。2.1 基础环境与 Python 版本建议使用 Python 3.9 至 3.11 的稳定版本。Python 3.12 及以上版本可能存在某些依赖库的兼容性问题。使用虚拟环境venv 或 conda隔离项目依赖是必须遵循的最佳实践。# 创建并激活虚拟环境 (以 venv 为例) python -m venv .venv # Windows .venv\Scripts\activate # Linux/macOS source .venv/bin/activate激活虚拟环境后命令行提示符前通常会出现环境名如(.venv)这表示后续的 pip 安装都会作用于该独立环境。2.2 核心依赖安装我们将使用 LangChain 作为主要框架并选择 OpenAI 的 GPT 模型作为 LLM 驱动你也可以替换为其他兼容 API 的模型。此外为了演示工具调用我们需要一个执行网络搜索的工具。这里使用 DuckDuckGo 搜索无需 API Key作为示例。创建requirements.txt文件内容如下langchain0.1.0 langchain-openai0.0.5 langchain-community0.0.10 duckduckgo-search5.4.0 python-dotenv1.0.0逐行解释langchain: LangChain 核心框架。langchain-openai: LangChain 对 OpenAI 模型的官方集成。langchain-community: 社区维护的各种工具、组件和集成。duckduckgo-search: 提供 DuckDuckGo 搜索功能的 Python 库我们将用它构建一个搜索工具。python-dotenv: 用于从.env文件加载环境变量如 API Key避免将敏感信息硬编码在代码中。使用 pip 安装所有依赖pip install -r requirements.txt注意依赖版本号是动态变化的。上述版本在撰写时能保证兼容性。如果未来遇到问题可以尝试移除版本号pip install langchain安装最新版但需注意 API 可能发生变更。2.3 配置 LLM 服务与 API Key你需要一个可用的 LLM API。这里以 OpenAI 为例。访问 OpenAI 平台创建 API Key。切勿将 API Key 直接提交到代码仓库。在项目根目录创建.env文件OPENAI_API_KEY你的实际API密钥 OPENAI_BASE_URLhttps://api.openai.com/v1 # 如果你使用官方服务此项可选。若使用代理或兼容服务需修改。在代码中使用python-dotenv加载这个 Keyfrom dotenv import load_dotenv load_dotenv() # 这会从 .env 文件加载环境变量到 os.environ # 现在可以通过 os.getenv(OPENAI_API_KEY) 获取密钥3. 构建第一个任务执行 Agent联网查询与总结我们将构建一个能够根据用户问题自动决定是否需要联网搜索并整合信息给出答案的 Agent。这个例子涵盖了 Agent 的核心要素LLM 驱动、工具定义、流程控制。3.1 项目结构与初始化创建一个名为simple_agent.py的文件。首先导入必要的模块并初始化 LLM。import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain.prompts import PromptTemplate from langchain_community.utilities import DuckDuckGoSearchAPIWrapper # 1. 加载环境变量 load_dotenv() # 2. 初始化 LLM # 使用 gpt-3.5-turbo 模型温度设为 0 使其输出更确定。根据你的 API 配置可能需要调整 base_url。 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, api_keyos.getenv(OPENAI_API_KEY), # base_urlos.getenv(OPENAI_BASE_URL) # 如果使用非官方端点取消注释并设置 )关键参数解释model: 指定使用的模型。gpt-3.5-turbo性价比高适合学习和简单任务。对于复杂推理可升级到gpt-4。temperature: 控制输出的随机性。范围 0~2值越低输出越确定和一致。在 Agent 场景下通常设为 0 或较低值以保证规划的逻辑稳定性。api_key: 从环境变量中读取保证安全。3.2 定义工具赋予 Agent “手脚”工具是 Agent 与外部世界交互的桥梁。这里我们定义一个网络搜索工具。# 3. 定义工具 # 使用 DuckDuckGo 搜索包装器 search DuckDuckGoSearchAPIWrapper() def search_tool(query: str) - str: 执行网络搜索并返回摘要结果。 参数 query: 搜索查询字符串。 返回: 搜索结果的前几条摘要文本。 # 限制返回结果数量避免上下文过长 return search.run(query, max_results3) # 将函数封装成 LangChain Tool 对象 tools [ Tool( nameSearch, funcsearch_tool, description当你需要回答关于实时信息、最新事件、特定事实或未知领域的问题时使用此工具。 输入应该是一个具体的搜索查询字符串。 ), ]工具定义详解name: 工具的唯一标识符LLM 在思考时会根据这个名字来决定调用哪个工具。func: 工具对应的 Python 可调用对象函数。description:这是最重要的部分。LLM 根据描述来判断在什么情况下使用该工具。描述必须清晰、具体说明工具的用途和输入格式。模糊的描述会导致 LLM 误用或不用工具。在search_tool函数中我们通过max_results限制返回条目防止过多的搜索结果挤占 LLM 的上下文窗口Token 有限。3.3 构建 ReAct Agent 与执行器LangChain 提供了高阶的create_react_agent函数它已经内置了 ReAct 模式的提示词模板和解析逻辑。我们需要提供 LLM、工具列表和一个提示词Prompt。# 4. 创建 ReAct Agent # 首先定义系统提示词用于设定 Agent 的角色和行为准则 system_prompt 你是一个有帮助的AI助手。你可以使用工具来获取信息。 请遵循以下步骤 1. 思考分析用户的问题判断是否需要使用工具以及使用哪个工具。 2. 行动如果需要工具就调用合适的工具。工具调用格式为Action: 工具名\\nAction Input: 输入 3. 观察你会收到工具返回的结果。 4. 重复思考、行动、观察直到你拥有足够的信息来回答问题。 5. 最终答案基于所有观察给出清晰、准确的最终答案。 你有以下工具可用 {tools} 开始记住如果你不需要工具就直接给出答案。 问题{input} 思考 prompt PromptTemplate.from_template(system_prompt) # 使用 create_react_agent 创建 Agent agent create_react_agent(llm, tools, prompt) # 5. 创建 Agent 执行器 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 设为 True 可以看到 Agent 的思考过程调试时非常有用 handle_parsing_errorsTrue, # 处理 LLM 输出格式解析错误 max_iterations5, # 限制最大迭代次数防止无限循环 early_stopping_methodgenerate, # 当 LLM 输出最终答案时停止 )关键配置解释verboseTrue: 强烈建议在开发阶段开启。它会在控制台打印出 Agent 完整的“思考Thought”、“行动Action”、“观察Observation”日志是理解和调试 Agent 行为的关键。handle_parsing_errorsTrue: LLM 的输出可能偶尔不符合框架预期的解析格式如缺少Action:关键字。此参数允许执行器尝试从错误中恢复而不是直接崩溃。max_iterations5:安全护栏。防止因逻辑错误或工具失败导致 Agent 陷入死循环不断消耗 API 调用和 Token。early_stopping_method”generate”: 当 LLM 的输出被识别为“最终答案”时即不再包含工具调用自动停止循环。3.4 运行与验证观察 Agent 的思考过程现在让我们用几个不同的问题来测试我们的 Agent。# 6. 运行 Agent 进行测试 if __name__ __main__: test_questions [ 什么是人工智能, # 知识型问题可能无需搜索 截至今天苹果公司AAPL的股价是多少, # 实时信息需要搜索 请总结一下昨天关于火星探测的主要新闻。, # 复杂任务需要搜索并总结 ] for question in test_questions: print(f\n{*50}) print(f问题: {question}) print(f{*50}) try: result agent_executor.invoke({input: question}) print(f\n最终答案: {result[output]}) except Exception as e: print(f执行出错: {e})运行脚本python simple_agent.py。由于设置了verboseTrue你将在控制台看到类似以下的输出内容为示例 问题: 截至今天苹果公司AAPL的股价是多少 思考用户想知道苹果公司今天的股价这是实时金融信息我无法从内部知识直接获取需要使用搜索工具。 Action: Search Action Input: AAPL stock price today Observation苹果(AAPL)股价今日开盘为...当前价格为 182.63 美元上涨 0.5%...实际搜索返回的文本 思考我已经获得了苹果公司今天的股价信息可以给出答案了。 最终答案根据最新信息苹果公司AAPL的股价今天目前约为 182.63 美元。 最终答案: 根据最新信息苹果公司AAPL的股价今天目前约为 182.63 美元。结果分析对于“什么是人工智能”Agent 可能直接利用 LLM 的内部知识回答不调用工具。对于股价问题Agent 识别出需要实时数据正确调用了Search工具并生成了查询”AAPL stock price today“。对于火星新闻Agent 可能会先搜索然后对返回的多条结果进行总结归纳。通过这个流程你已经完成了一个具备基础规划与工具调用能力的 AI Agent。4. 核心机制详解与参数调优仅仅让 Agent 跑起来还不够理解其内部机制和关键参数才能有效诊断问题和优化性能。4.1 提示词Prompt的设计艺术Prompt 是引导 LLM 扮演好“规划者”角色的关键。一个糟糕的 Prompt 会导致 Agent 行为混乱。我们的系统提示词包含了几个关键部分角色设定你是一个有帮助的AI助手。这设定了基本的交互基调。流程指令明确列出了“思考-行动-观察”的步骤并给出了工具调用的格式范例Action: ...。ReAct 框架依赖这种固定格式来解析 LLM 的输出。工具描述{tools}是一个占位符运行时会被替换为所有工具的name和description。清晰的工具描述是 LLM 正确选择工具的前提。问题上下文{input}是用户问题的占位符。结束指令记住如果你不需要工具就直接给出答案。这防止了 LLM 对所有问题都机械地尝试使用工具。优化建议如果 Agent 频繁错误调用工具可以强化工具描述的区分度。如果 Agent 在应该结束时继续循环可以在 Prompt 中更强调“当你拥有足够信息时给出最终答案”。对于复杂任务可以在 Prompt 中加入“分步解决”、“先理解核心问题”等引导词。4.2 Agent 执行器的关键参数AgentExecutor的参数直接影响 Agent 的稳定性、成本和性能。参数默认值/示例作用与影响调优建议verboseFalse是否打印详细的思考日志。开发调试必设为True生产环境可设为False。handle_parsing_errorsFalse是否处理 LLM 输出格式解析错误。建议设为True提高鲁棒性。可配合自定义错误处理函数。max_iterations15最大迭代思考-行动次数。必须设置。根据任务复杂度调整简单任务 3-5复杂任务 10-15。防止无限循环。max_execution_timeNone最大执行时间秒。对于有实时性要求的任务可以设置超时限制。early_stopping_method”force”提前停止方法。”force”在达到max_iterations时强制停止”generate”在 LLM 输出最终答案时停止。推荐”generate”更符合直觉能节省 Token。return_intermediate_stepsFalse是否在返回结果中包含中间步骤思考、行动、观察。调试或需要分析 Agent 决策过程时设为True。4.3 工具Tools的扩展与封装除了搜索Agent 可以拥有任何你能用代码实现的工具。以下是几种常见工具类型及其实现思路计算器/单位转换封装eval需极度谨慎或sympy库。数据库查询封装 SQLAlchemy 或特定数据库驱动执行查询并返回格式化结果。API 调用封装requests库调用外部 RESTful API如天气、股票、翻译。文件操作封装读写本地文件或云存储的操作。代码执行封装一个安全的沙箱环境来运行代码风险高需严格隔离。定义新工具的示例模拟一个计算器from langchain.tools import Tool import re def safe_calculator(expression: str) - str: 执行安全的数学表达式计算。只支持数字和基础运算符。 # 简单的安全过滤防止代码注入 if not re.match(r^[\d\s\\-\*\/\(\)\.]$, expression): return 错误表达式包含不安全字符。 try: # 警告实际生产环境应使用更安全的评估方式如 ast.literal_eval 或专用库 result eval(expression) return f计算结果: {result} except Exception as e: return f计算错误: {e} calculator_tool Tool( nameCalculator, funcsafe_calculator, description用于执行数学计算。输入是一个纯数学表达式例如 12 5 * 2。不要包含任何文字。 ) # 将新工具加入到 tools 列表中 tools.append(calculator_tool)重要安全警告上例中的eval仅用于演示在生产环境中直接使用eval处理用户输入是极其危险的会导致代码注入漏洞。必须使用更安全的替代方案如ast.literal_eval限制更多或numexpr等库。5. 常见问题排查与调试指南在开发 Agent 时你会遇到一些典型问题。以下是排查路径和解决方案。5.1 Agent 不调用工具直接回答问题现象对于明显需要实时信息的问题如“现在几点了”Agent 却基于 LLM 的旧知识编造了一个答案。可能原因与排查工具描述不清晰检查工具的description是否准确说明了使用场景如“获取实时信息”。LLM 可能不理解何时该用它。解决重写描述使其更具体、更具场景化。例如“当问题涉及当前时间、实时股价、最新新闻等非静态知识时使用此工具。”Prompt 引导不足系统 Prompt 可能没有强调查询实时信息时必须使用工具。解决在 Prompt 中明确加入规则例如“对于涉及今天、现在、最新、当前等时间关键词的问题你必须优先使用搜索工具确认信息。”LLM 温度Temperature过高温度值过高导致输出随机性大可能忽略了工具调用指令。解决将temperature设为 0 或一个较低的值如 0.1。5.2 Agent 陷入无限循环或达到最大迭代次数现象控制台不断打印思考、行动、观察的日志始终不输出最终答案直到被max_iterations强制停止。可能原因与排查工具返回结果质量差工具返回的内容可能无法回答子问题导致 LLM 认为信息不足反复调用同一个或不同的工具。解决检查工具函数。对于搜索工具可以优化查询词或对返回结果进行清洗和摘要。添加日志打印工具的输入和原始输出。任务过于复杂或模糊LLM 无法将模糊的目标分解为清晰的步骤。解决让用户提供更具体的问题。或者在 Prompt 中引导 LLM 进行更精细的步骤分解例如“请将复杂任务分解为不超过3个明确的子问题。”上下文混乱随着迭代进行大量的“思考”和“观察”文本积累在上下文中干扰了 LLM 的最新决策。解决这是复杂 Agent 系统的常见挑战。可以考虑使用ConversationSummaryMemory或ConversationBufferWindowMemory来管理历史长度只保留最近的几次交互。5.3 工具调用格式解析错误现象控制台抛出类似OutputParserException的错误提示无法解析 LLM 的输出。可能原因与排查LLM 没有遵循指令格式LLM 的输出没有严格按照Action: ...的格式。解决首先检查verbose日志看 LLM 输出了什么。强化 Prompt 中的格式指令使用更明确的示例Few-Shot Prompting。例如在 Prompt 中加入示例 问题纽约现在的天气如何 思考这是一个关于实时天气的问题我需要使用搜索工具。 Action: Search Action Input: New York current weather中文或其他语言导致的格式偏差LLM 可能用中文输出了“动作搜索”。解决在 Prompt 中严格要求使用英文关键词Action和Action Input或者将整个 Agent 的交互语言设置为英文。5.4 性能与成本优化问题每次运行都消耗大量 Token响应慢API 调用费用高。优化策略精简 Prompt移除 Prompt 中不必要的叙述性文字。限制工具返回长度像我们之前做的在search_tool中使用max_results。对于其他工具也要限制返回数据的大小只提取关键信息。使用更便宜的模型对于规划步骤可以尝试使用gpt-3.5-turbo对于需要高质量总结或创作的最终答案生成再使用gpt-4。这需要更复杂的 Agent 架构。实现缓存对于相同的问题或工具查询可以使用langchain.cache如SQLiteCache缓存 LLM 响应和工具结果显著提升重复请求的速度并降低成本。6. 从原型到生产最佳实践与扩展方向让一个演示 Agent 稳定运行于生产环境还需要考虑更多因素。6.1 生产环境检查清单在部署前请对照此清单进行检查[ ]安全性API Keys、数据库密码等敏感信息是否已通过环境变量或密钥管理服务管理工具函数如计算器是否进行了输入验证和安全过滤防止注入攻击Agent 的输入是否进行了内容安全过滤[ ]可靠性是否设置了合理的max_iterations和max_execution_time是否对工具调用和 LLM 调用添加了重试机制和超时处理是否有降级方案例如当核心工具失败时Agent 能否给出友好的错误提示或转向备用方案[ ]可观测性是否记录了完整的 Agent 执行日志包括思考过程、工具调用及结果这对于排查问题和优化 Prompt 至关重要。是否监控了 Token 消耗、响应延迟和错误率[ ]性能是否对频繁查询实施了缓存对于耗时长的工具调用是否考虑使用异步Async模式6.2 扩展方向构建更强大的 Agent掌握了基础模式后你可以探索以下方向来增强你的 Agent多工具协同为 Agent 装备更多工具如数据库查询、邮件发送、数据分析等使其能处理跨领域工作流。记忆Memory集成让 Agent 记住对话历史或任务上下文。LangChain 提供了多种 Memory 类型ConversationBufferMemory: 保存所有历史消息。ConversationSummaryMemory: 对长历史进行摘要节省 Token。VectorStoreRetrieverMemory: 将历史存入向量数据库实现基于语义的相关信息检索。智能路由Router根据用户输入的意图自动选择不同的子 Agent 或处理链。例如将“订机票”路由到旅行 Agent将“分析报表”路由到数据分析 Agent。自主智能体Autonomous Agent如 AutoGPT 模式给 Agent 一个长期目标如“研究某个主题并写份报告”它能够自主创建任务列表、优先排序并执行直至目标达成。这需要更复杂的任务规划、优先级管理和自我反思机制。与现有系统集成将 Agent 作为微服务嵌入到你现有的业务系统中通过 API 提供智能决策支持。6.3 框架选型考量虽然本文以 LangChain 为例但生态中还有其他优秀框架如Semantic Kernel(微软)、LlamaIndex(更专注于数据索引与检索)。选择时考虑LangChain生态最丰富组件齐全社区活跃学习资料多是快速上手的首选。Semantic Kernel与 .NET 生态结合紧密规划Planner功能强大适合企业级复杂工作流。LlamaIndex如果你的核心需求是让 Agent 基于私有知识库文档、数据库进行问答LlamaIndex 的数据连接和检索能力是强项。建议从 LangChain 开始建立对 Agent 的完整认知再根据项目特定需求评估其他框架。构建 AI Agent 是一个迭代过程核心在于清晰定义任务边界、精心设计工具、不断调试 Prompt 并建立有效的安全护栏。从本文这个可运行的简单搜索 Agent 出发你已经掌握了最核心的循环机制和调试方法接下来就是结合具体业务场景不断实践和深化的过程。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度
30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度在实际项目中AI Agent 已经从实验室概念演变为解决复杂任务的关键技术组件。无论是自动化客服、智能数据分析助手还是集成在应用中的个性化推荐引擎其核心都是让机器能够理解目标、规划步骤、调用工具并执行决策。对于开发者而言从零开始构建一个可用的 Agent 往往面临概念庞杂、工具链不熟悉、代码与理论脱节等挑战。本文旨在提供一个结构清晰、可动手实践的 AI Agent 开发入门指南帮助具备基础编程能力的开发者理解 Agent 的核心工作机制并完成一个具备规划与执行能力的简单任务执行 Agent。我们将从最基础的 Agent 概念和工作流讲起然后搭建一个最小化的开发环境接着通过一个“联网信息查询与总结”的完整案例展示如何利用主流框架如 LangChain的关键组件构建 Agent。文章会详细解释每一步的代码意图、配置参数以及背后的设计逻辑并提供运行验证、常见问题排查路径和向更复杂场景扩展的建议。学完后你将能够掌握 Agent 开发的基本模式并具备将其应用于实际业务场景的初步能力。1. 理解 AI Agent 的核心从感知到行动的循环在深入代码之前必须厘清 AI Agent 与普通调用大语言模型LLMAPI 的程序有何本质区别。很多初学者误以为给 LLM 加个循环就是 Agent这忽略了其核心的自主决策与工具使用能力。1.1 Agent 是什么超越简单问答的智能体通俗地讲一个 AI Agent 是一个能够感知环境、自主决策并执行行动以达成给定目标的软件实体。它不仅仅是根据输入生成文本而是具备“思考-行动-观察”的循环能力。例如一个简单的“天气查询Agent”的思考过程可能是用户目标是“北京明天适合穿什么”Agent 需要先规划步骤1. 获取北京明天的天气预报。2. 根据天气数据温度、降水生成穿衣建议。3. 将建议返回给用户。其中第一步就需要调用一个“获取天气”的工具Tool。技术定义上一个典型的 Agent 系统包含几个核心组件规划器Planner通常由 LLM 担任负责将复杂目标分解为可执行的步骤或子任务序列。工具ToolsAgent 可以调用的外部函数或 API用于获取信息如搜索、查数据库或执行操作如发送邮件、操作文件。记忆Memory用于存储和回顾与当前任务相关的历史信息对话历史、中间结果为后续决策提供上下文。执行器Executor协调整个循环根据规划调用工具处理工具返回的结果并决定下一步是继续规划、重新规划还是结束任务。1.2 Agent 的典型工作流ReAct 模式目前最流行且有效的 Agent 工作流之一是ReAct (Reasoning Acting)模式。它清晰地展示了 Agent 的思考过程。思考ThinkLLM 根据当前目标、历史记录和可用工具列表分析下一步应该做什么。输出格式通常是“我需要先使用 X 工具来获取 Y 信息。”行动Act根据思考结果调用指定的工具并传入相应的参数。观察Observe获取工具执行后的返回结果可能是数据也可能是成功/失败状态。循环将“思考-行动-观察”的结果作为新的上下文再次送入 LLM 进行下一轮思考直到 LLM 认为任务已完成并输出最终答案。这个循环的关键在于LLM 的每次“思考”都基于最新的环境观察工具执行结果从而能够动态调整计划。例如如果调用天气 API 失败LLM 可能会思考“天气 API 调用失败我可以尝试使用网络搜索工具来查找天气信息。”1.3 为什么需要框架LangChain 的角色手动实现上述循环、工具调用封装、提示词Prompt管理和记忆存储非常繁琐且容易出错。因此我们使用LangChain这样的框架。它抽象了这些通用模式提供了构建 Agent 所需的高层组件让我们可以更专注于业务逻辑和工具定义而不是底层通信和状态管理。在接下来的部分我们将基于 LangChain 来构建我们的第一个 Agent。2. 环境准备与依赖配置搭建可复现的开发底座一个稳定、版本对齐的开发环境是后续所有步骤的基础。Agent 开发涉及 LLM 服务、Python 环境、框架和多个工具库版本冲突是新手最常见的“拦路虎”。2.1 基础环境与 Python 版本建议使用 Python 3.9 至 3.11 的稳定版本。Python 3.12 及以上版本可能存在某些依赖库的兼容性问题。使用虚拟环境venv 或 conda隔离项目依赖是必须遵循的最佳实践。# 创建并激活虚拟环境 (以 venv 为例) python -m venv .venv # Windows .venv\Scripts\activate # Linux/macOS source .venv/bin/activate激活虚拟环境后命令行提示符前通常会出现环境名如(.venv)这表示后续的 pip 安装都会作用于该独立环境。2.2 核心依赖安装我们将使用 LangChain 作为主要框架并选择 OpenAI 的 GPT 模型作为 LLM 驱动你也可以替换为其他兼容 API 的模型。此外为了演示工具调用我们需要一个执行网络搜索的工具。这里使用 DuckDuckGo 搜索无需 API Key作为示例。创建requirements.txt文件内容如下langchain0.1.0 langchain-openai0.0.5 langchain-community0.0.10 duckduckgo-search5.4.0 python-dotenv1.0.0逐行解释langchain: LangChain 核心框架。langchain-openai: LangChain 对 OpenAI 模型的官方集成。langchain-community: 社区维护的各种工具、组件和集成。duckduckgo-search: 提供 DuckDuckGo 搜索功能的 Python 库我们将用它构建一个搜索工具。python-dotenv: 用于从.env文件加载环境变量如 API Key避免将敏感信息硬编码在代码中。使用 pip 安装所有依赖pip install -r requirements.txt注意依赖版本号是动态变化的。上述版本在撰写时能保证兼容性。如果未来遇到问题可以尝试移除版本号pip install langchain安装最新版但需注意 API 可能发生变更。2.3 配置 LLM 服务与 API Key你需要一个可用的 LLM API。这里以 OpenAI 为例。访问 OpenAI 平台创建 API Key。切勿将 API Key 直接提交到代码仓库。在项目根目录创建.env文件OPENAI_API_KEY你的实际API密钥 OPENAI_BASE_URLhttps://api.openai.com/v1 # 如果你使用官方服务此项可选。若使用代理或兼容服务需修改。在代码中使用python-dotenv加载这个 Keyfrom dotenv import load_dotenv load_dotenv() # 这会从 .env 文件加载环境变量到 os.environ # 现在可以通过 os.getenv(OPENAI_API_KEY) 获取密钥3. 构建第一个任务执行 Agent联网查询与总结我们将构建一个能够根据用户问题自动决定是否需要联网搜索并整合信息给出答案的 Agent。这个例子涵盖了 Agent 的核心要素LLM 驱动、工具定义、流程控制。3.1 项目结构与初始化创建一个名为simple_agent.py的文件。首先导入必要的模块并初始化 LLM。import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain.prompts import PromptTemplate from langchain_community.utilities import DuckDuckGoSearchAPIWrapper # 1. 加载环境变量 load_dotenv() # 2. 初始化 LLM # 使用 gpt-3.5-turbo 模型温度设为 0 使其输出更确定。根据你的 API 配置可能需要调整 base_url。 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, api_keyos.getenv(OPENAI_API_KEY), # base_urlos.getenv(OPENAI_BASE_URL) # 如果使用非官方端点取消注释并设置 )关键参数解释model: 指定使用的模型。gpt-3.5-turbo性价比高适合学习和简单任务。对于复杂推理可升级到gpt-4。temperature: 控制输出的随机性。范围 0~2值越低输出越确定和一致。在 Agent 场景下通常设为 0 或较低值以保证规划的逻辑稳定性。api_key: 从环境变量中读取保证安全。3.2 定义工具赋予 Agent “手脚”工具是 Agent 与外部世界交互的桥梁。这里我们定义一个网络搜索工具。# 3. 定义工具 # 使用 DuckDuckGo 搜索包装器 search DuckDuckGoSearchAPIWrapper() def search_tool(query: str) - str: 执行网络搜索并返回摘要结果。 参数 query: 搜索查询字符串。 返回: 搜索结果的前几条摘要文本。 # 限制返回结果数量避免上下文过长 return search.run(query, max_results3) # 将函数封装成 LangChain Tool 对象 tools [ Tool( nameSearch, funcsearch_tool, description当你需要回答关于实时信息、最新事件、特定事实或未知领域的问题时使用此工具。 输入应该是一个具体的搜索查询字符串。 ), ]工具定义详解name: 工具的唯一标识符LLM 在思考时会根据这个名字来决定调用哪个工具。func: 工具对应的 Python 可调用对象函数。description:这是最重要的部分。LLM 根据描述来判断在什么情况下使用该工具。描述必须清晰、具体说明工具的用途和输入格式。模糊的描述会导致 LLM 误用或不用工具。在search_tool函数中我们通过max_results限制返回条目防止过多的搜索结果挤占 LLM 的上下文窗口Token 有限。3.3 构建 ReAct Agent 与执行器LangChain 提供了高阶的create_react_agent函数它已经内置了 ReAct 模式的提示词模板和解析逻辑。我们需要提供 LLM、工具列表和一个提示词Prompt。# 4. 创建 ReAct Agent # 首先定义系统提示词用于设定 Agent 的角色和行为准则 system_prompt 你是一个有帮助的AI助手。你可以使用工具来获取信息。 请遵循以下步骤 1. 思考分析用户的问题判断是否需要使用工具以及使用哪个工具。 2. 行动如果需要工具就调用合适的工具。工具调用格式为Action: 工具名\\nAction Input: 输入 3. 观察你会收到工具返回的结果。 4. 重复思考、行动、观察直到你拥有足够的信息来回答问题。 5. 最终答案基于所有观察给出清晰、准确的最终答案。 你有以下工具可用 {tools} 开始记住如果你不需要工具就直接给出答案。 问题{input} 思考 prompt PromptTemplate.from_template(system_prompt) # 使用 create_react_agent 创建 Agent agent create_react_agent(llm, tools, prompt) # 5. 创建 Agent 执行器 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 设为 True 可以看到 Agent 的思考过程调试时非常有用 handle_parsing_errorsTrue, # 处理 LLM 输出格式解析错误 max_iterations5, # 限制最大迭代次数防止无限循环 early_stopping_methodgenerate, # 当 LLM 输出最终答案时停止 )关键配置解释verboseTrue: 强烈建议在开发阶段开启。它会在控制台打印出 Agent 完整的“思考Thought”、“行动Action”、“观察Observation”日志是理解和调试 Agent 行为的关键。handle_parsing_errorsTrue: LLM 的输出可能偶尔不符合框架预期的解析格式如缺少Action:关键字。此参数允许执行器尝试从错误中恢复而不是直接崩溃。max_iterations5:安全护栏。防止因逻辑错误或工具失败导致 Agent 陷入死循环不断消耗 API 调用和 Token。early_stopping_method”generate”: 当 LLM 的输出被识别为“最终答案”时即不再包含工具调用自动停止循环。3.4 运行与验证观察 Agent 的思考过程现在让我们用几个不同的问题来测试我们的 Agent。# 6. 运行 Agent 进行测试 if __name__ __main__: test_questions [ 什么是人工智能, # 知识型问题可能无需搜索 截至今天苹果公司AAPL的股价是多少, # 实时信息需要搜索 请总结一下昨天关于火星探测的主要新闻。, # 复杂任务需要搜索并总结 ] for question in test_questions: print(f\n{*50}) print(f问题: {question}) print(f{*50}) try: result agent_executor.invoke({input: question}) print(f\n最终答案: {result[output]}) except Exception as e: print(f执行出错: {e})运行脚本python simple_agent.py。由于设置了verboseTrue你将在控制台看到类似以下的输出内容为示例 问题: 截至今天苹果公司AAPL的股价是多少 思考用户想知道苹果公司今天的股价这是实时金融信息我无法从内部知识直接获取需要使用搜索工具。 Action: Search Action Input: AAPL stock price today Observation苹果(AAPL)股价今日开盘为...当前价格为 182.63 美元上涨 0.5%...实际搜索返回的文本 思考我已经获得了苹果公司今天的股价信息可以给出答案了。 最终答案根据最新信息苹果公司AAPL的股价今天目前约为 182.63 美元。 最终答案: 根据最新信息苹果公司AAPL的股价今天目前约为 182.63 美元。结果分析对于“什么是人工智能”Agent 可能直接利用 LLM 的内部知识回答不调用工具。对于股价问题Agent 识别出需要实时数据正确调用了Search工具并生成了查询”AAPL stock price today“。对于火星新闻Agent 可能会先搜索然后对返回的多条结果进行总结归纳。通过这个流程你已经完成了一个具备基础规划与工具调用能力的 AI Agent。4. 核心机制详解与参数调优仅仅让 Agent 跑起来还不够理解其内部机制和关键参数才能有效诊断问题和优化性能。4.1 提示词Prompt的设计艺术Prompt 是引导 LLM 扮演好“规划者”角色的关键。一个糟糕的 Prompt 会导致 Agent 行为混乱。我们的系统提示词包含了几个关键部分角色设定你是一个有帮助的AI助手。这设定了基本的交互基调。流程指令明确列出了“思考-行动-观察”的步骤并给出了工具调用的格式范例Action: ...。ReAct 框架依赖这种固定格式来解析 LLM 的输出。工具描述{tools}是一个占位符运行时会被替换为所有工具的name和description。清晰的工具描述是 LLM 正确选择工具的前提。问题上下文{input}是用户问题的占位符。结束指令记住如果你不需要工具就直接给出答案。这防止了 LLM 对所有问题都机械地尝试使用工具。优化建议如果 Agent 频繁错误调用工具可以强化工具描述的区分度。如果 Agent 在应该结束时继续循环可以在 Prompt 中更强调“当你拥有足够信息时给出最终答案”。对于复杂任务可以在 Prompt 中加入“分步解决”、“先理解核心问题”等引导词。4.2 Agent 执行器的关键参数AgentExecutor的参数直接影响 Agent 的稳定性、成本和性能。参数默认值/示例作用与影响调优建议verboseFalse是否打印详细的思考日志。开发调试必设为True生产环境可设为False。handle_parsing_errorsFalse是否处理 LLM 输出格式解析错误。建议设为True提高鲁棒性。可配合自定义错误处理函数。max_iterations15最大迭代思考-行动次数。必须设置。根据任务复杂度调整简单任务 3-5复杂任务 10-15。防止无限循环。max_execution_timeNone最大执行时间秒。对于有实时性要求的任务可以设置超时限制。early_stopping_method”force”提前停止方法。”force”在达到max_iterations时强制停止”generate”在 LLM 输出最终答案时停止。推荐”generate”更符合直觉能节省 Token。return_intermediate_stepsFalse是否在返回结果中包含中间步骤思考、行动、观察。调试或需要分析 Agent 决策过程时设为True。4.3 工具Tools的扩展与封装除了搜索Agent 可以拥有任何你能用代码实现的工具。以下是几种常见工具类型及其实现思路计算器/单位转换封装eval需极度谨慎或sympy库。数据库查询封装 SQLAlchemy 或特定数据库驱动执行查询并返回格式化结果。API 调用封装requests库调用外部 RESTful API如天气、股票、翻译。文件操作封装读写本地文件或云存储的操作。代码执行封装一个安全的沙箱环境来运行代码风险高需严格隔离。定义新工具的示例模拟一个计算器from langchain.tools import Tool import re def safe_calculator(expression: str) - str: 执行安全的数学表达式计算。只支持数字和基础运算符。 # 简单的安全过滤防止代码注入 if not re.match(r^[\d\s\\-\*\/\(\)\.]$, expression): return 错误表达式包含不安全字符。 try: # 警告实际生产环境应使用更安全的评估方式如 ast.literal_eval 或专用库 result eval(expression) return f计算结果: {result} except Exception as e: return f计算错误: {e} calculator_tool Tool( nameCalculator, funcsafe_calculator, description用于执行数学计算。输入是一个纯数学表达式例如 12 5 * 2。不要包含任何文字。 ) # 将新工具加入到 tools 列表中 tools.append(calculator_tool)重要安全警告上例中的eval仅用于演示在生产环境中直接使用eval处理用户输入是极其危险的会导致代码注入漏洞。必须使用更安全的替代方案如ast.literal_eval限制更多或numexpr等库。5. 常见问题排查与调试指南在开发 Agent 时你会遇到一些典型问题。以下是排查路径和解决方案。5.1 Agent 不调用工具直接回答问题现象对于明显需要实时信息的问题如“现在几点了”Agent 却基于 LLM 的旧知识编造了一个答案。可能原因与排查工具描述不清晰检查工具的description是否准确说明了使用场景如“获取实时信息”。LLM 可能不理解何时该用它。解决重写描述使其更具体、更具场景化。例如“当问题涉及当前时间、实时股价、最新新闻等非静态知识时使用此工具。”Prompt 引导不足系统 Prompt 可能没有强调查询实时信息时必须使用工具。解决在 Prompt 中明确加入规则例如“对于涉及今天、现在、最新、当前等时间关键词的问题你必须优先使用搜索工具确认信息。”LLM 温度Temperature过高温度值过高导致输出随机性大可能忽略了工具调用指令。解决将temperature设为 0 或一个较低的值如 0.1。5.2 Agent 陷入无限循环或达到最大迭代次数现象控制台不断打印思考、行动、观察的日志始终不输出最终答案直到被max_iterations强制停止。可能原因与排查工具返回结果质量差工具返回的内容可能无法回答子问题导致 LLM 认为信息不足反复调用同一个或不同的工具。解决检查工具函数。对于搜索工具可以优化查询词或对返回结果进行清洗和摘要。添加日志打印工具的输入和原始输出。任务过于复杂或模糊LLM 无法将模糊的目标分解为清晰的步骤。解决让用户提供更具体的问题。或者在 Prompt 中引导 LLM 进行更精细的步骤分解例如“请将复杂任务分解为不超过3个明确的子问题。”上下文混乱随着迭代进行大量的“思考”和“观察”文本积累在上下文中干扰了 LLM 的最新决策。解决这是复杂 Agent 系统的常见挑战。可以考虑使用ConversationSummaryMemory或ConversationBufferWindowMemory来管理历史长度只保留最近的几次交互。5.3 工具调用格式解析错误现象控制台抛出类似OutputParserException的错误提示无法解析 LLM 的输出。可能原因与排查LLM 没有遵循指令格式LLM 的输出没有严格按照Action: ...的格式。解决首先检查verbose日志看 LLM 输出了什么。强化 Prompt 中的格式指令使用更明确的示例Few-Shot Prompting。例如在 Prompt 中加入示例 问题纽约现在的天气如何 思考这是一个关于实时天气的问题我需要使用搜索工具。 Action: Search Action Input: New York current weather中文或其他语言导致的格式偏差LLM 可能用中文输出了“动作搜索”。解决在 Prompt 中严格要求使用英文关键词Action和Action Input或者将整个 Agent 的交互语言设置为英文。5.4 性能与成本优化问题每次运行都消耗大量 Token响应慢API 调用费用高。优化策略精简 Prompt移除 Prompt 中不必要的叙述性文字。限制工具返回长度像我们之前做的在search_tool中使用max_results。对于其他工具也要限制返回数据的大小只提取关键信息。使用更便宜的模型对于规划步骤可以尝试使用gpt-3.5-turbo对于需要高质量总结或创作的最终答案生成再使用gpt-4。这需要更复杂的 Agent 架构。实现缓存对于相同的问题或工具查询可以使用langchain.cache如SQLiteCache缓存 LLM 响应和工具结果显著提升重复请求的速度并降低成本。6. 从原型到生产最佳实践与扩展方向让一个演示 Agent 稳定运行于生产环境还需要考虑更多因素。6.1 生产环境检查清单在部署前请对照此清单进行检查[ ]安全性API Keys、数据库密码等敏感信息是否已通过环境变量或密钥管理服务管理工具函数如计算器是否进行了输入验证和安全过滤防止注入攻击Agent 的输入是否进行了内容安全过滤[ ]可靠性是否设置了合理的max_iterations和max_execution_time是否对工具调用和 LLM 调用添加了重试机制和超时处理是否有降级方案例如当核心工具失败时Agent 能否给出友好的错误提示或转向备用方案[ ]可观测性是否记录了完整的 Agent 执行日志包括思考过程、工具调用及结果这对于排查问题和优化 Prompt 至关重要。是否监控了 Token 消耗、响应延迟和错误率[ ]性能是否对频繁查询实施了缓存对于耗时长的工具调用是否考虑使用异步Async模式6.2 扩展方向构建更强大的 Agent掌握了基础模式后你可以探索以下方向来增强你的 Agent多工具协同为 Agent 装备更多工具如数据库查询、邮件发送、数据分析等使其能处理跨领域工作流。记忆Memory集成让 Agent 记住对话历史或任务上下文。LangChain 提供了多种 Memory 类型ConversationBufferMemory: 保存所有历史消息。ConversationSummaryMemory: 对长历史进行摘要节省 Token。VectorStoreRetrieverMemory: 将历史存入向量数据库实现基于语义的相关信息检索。智能路由Router根据用户输入的意图自动选择不同的子 Agent 或处理链。例如将“订机票”路由到旅行 Agent将“分析报表”路由到数据分析 Agent。自主智能体Autonomous Agent如 AutoGPT 模式给 Agent 一个长期目标如“研究某个主题并写份报告”它能够自主创建任务列表、优先排序并执行直至目标达成。这需要更复杂的任务规划、优先级管理和自我反思机制。与现有系统集成将 Agent 作为微服务嵌入到你现有的业务系统中通过 API 提供智能决策支持。6.3 框架选型考量虽然本文以 LangChain 为例但生态中还有其他优秀框架如Semantic Kernel(微软)、LlamaIndex(更专注于数据索引与检索)。选择时考虑LangChain生态最丰富组件齐全社区活跃学习资料多是快速上手的首选。Semantic Kernel与 .NET 生态结合紧密规划Planner功能强大适合企业级复杂工作流。LlamaIndex如果你的核心需求是让 Agent 基于私有知识库文档、数据库进行问答LlamaIndex 的数据连接和检索能力是强项。建议从 LangChain 开始建立对 Agent 的完整认知再根据项目特定需求评估其他框架。构建 AI Agent 是一个迭代过程核心在于清晰定义任务边界、精心设计工具、不断调试 Prompt 并建立有效的安全护栏。从本文这个可运行的简单搜索 Agent 出发你已经掌握了最核心的循环机制和调试方法接下来就是结合具体业务场景不断实践和深化的过程。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度
领衔4家靠谱门店实测 - 生活测评小能手)
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
