在实际的大模型应用开发中单纯调用 API 生成文本已经无法满足复杂业务需求。我们需要一种能够理解目标、规划步骤、使用工具并持续执行的智能体Agent。无论是自动化客服、数据分析助手还是代码生成工具Agent 都是连接大模型能力与具体任务的关键桥梁。然而从零开始构建一个稳定、可用的 Agent 系统涉及概念理解、框架选型、环境搭建、工具集成、流程调试等多个环节新手往往感到无从下手。本文旨在为希望进入 Agent 开发领域的开发者提供一套系统、可落地的实践指南。我们将从 Agent 的核心概念和工作机制讲起逐步完成一个具备联网搜索和代码执行能力的智能体项目。文章将涵盖主流框架如 LangChain的集成、本地与云端模型的调用、工具链的构建以及生产环境下的注意事项。无论你是希望将大模型能力集成到现有业务中还是想探索 AI 原生应用的可能性这篇教程都将为你提供清晰的路径和可复现的代码。1. 理解智能体Agent从概念到工作机制在深入代码之前必须厘清智能体Agent究竟是什么以及它如何工作。这有助于我们在后续开发中做出正确的架构决策。1.1 Agent 的核心定义与价值通俗地讲一个 AI Agent 是一个能够感知环境、自主决策并执行行动以实现特定目标的软件实体。它不同于简单的聊天机器人其核心在于“自主性”和“工具使用能力”。自主决策Agent 能够根据当前状态和目标自行决定下一步做什么而不是机械地执行预设流程。工具使用Agent 可以调用外部工具如搜索引擎、数据库、代码解释器、API来获取信息或改变环境状态从而完成仅靠大模型本身无法完成的任务。其技术价值在于它将大语言模型LLM强大的理解和生成能力与外部系统的精确执行能力结合起来解决了大模型“幻觉”、知识滞后、无法操作外部系统等核心短板。例如让大模型直接告诉你“今天北京的天气如何”可能得到过时或编造的信息但一个配备了天气查询工具的 Agent可以自主调用天气 API 获取实时数据再组织成自然语言回复给你。1.2 Agent 的核心组件与运行循环一个典型的 Agent 系统包含以下几个关键组件它们共同构成了 Agent 的“思考-行动”循环ReAct 模式是其典型代表规划器Planner/ 大脑LLM Core通常由大语言模型担任负责理解用户目标、分解任务、制定计划并在每一步决定使用哪个工具。工具ToolsAgent 可以调用的外部函数或 API。每个工具都有明确的名称、描述和参数定义供 LLM 理解和选择。记忆Memory用于存储对话历史、工具执行结果、中间状态等使 Agent 具备上下文感知能力实现多轮对话和长期任务。执行器Executor负责协调整个循环。它接收用户输入调用 LLM 进行规划解析 LLM 的输出决定使用哪个工具及参数执行工具将结果返回给 LLM 进行下一步决策直到任务完成或达到终止条件。其工作流程可以简化为以下循环用户输入 - LLM思考决定行动- 解析并执行工具 - 观察工具结果 - LLM根据结果再次思考 - ... - 生成最终回复1.3 主流 Agent 开发框架简介手动实现上述循环需要处理大量细节如提示词工程、输出解析、错误处理等。因此使用成熟的开发框架是更高效的选择。LangChain / LangGraph目前生态最丰富、社区最活跃的框架之一。它提供了AgentExecutor、丰富的内置工具如搜索引擎、计算器以及清晰的抽象AgentToolMemory。LangGraph 进一步支持构建复杂的、有状态的多 Agent 工作流。AutoGen由微软推出专注于多智能体对话协作。它简化了定义多个具有不同角色和能力的 Agent并让它们通过对话来解决问题的过程非常适合需要分工协作的场景。Semantic Kernel微软推出的另一个框架深度集成在 .NET 生态中但也支持 Python。它强调将传统编程技能与 LLM 能力结合“原生函数”与“语义函数”。对于初学者和大多数应用场景LangChain因其 Python 友好性、丰富的文档和教程成为入门和快速原型开发的首选。本文后续实践也将基于 LangChain 展开。2. 环境准备与核心依赖配置开始构建 Agent 之前需要建立一个稳定且可复现的开发环境。我们将同时覆盖使用云端 API 和本地部署模型两种方式。2.1 Python 环境与包管理推荐使用conda或venv创建独立的 Python 环境避免包冲突。# 使用 conda 创建环境假设已安装 Anaconda/Miniconda conda create -n ai-agent python3.10 conda activate ai-agent # 或使用 venv python -m venv ai-agent-env # Windows ai-agent-env\Scripts\activate # Linux/Mac source ai-agent-env/bin/activate2.2 安装核心开发框架与工具我们将安装 LangChain 及其相关组件。注意LangChain 生态庞大我们按需安装。# 安装 LangChain 核心包 pip install langchain langchain-community # 安装用于构建 Agent 的核心组件 pip install langchain-agents # 安装用于调用 OpenAI API 的包如果使用 GPT 系列模型 pip install openai # 安装用于网页搜索的工具需要申请 Serper 或 Tavily 的 API Key本文以 DuckDuckGo 免费版为例 pip install duckduckgo-search # 安装用于代码解释执行的工具谨慎使用注意安全 pip install langchain-experimental # langchain-experimental 包含一些实验性功能如 Python REPL 工具 # 安装环境变量管理包方便管理 API Key pip install python-dotenv2.3 大模型接入云端 API 与本地部署Agent 的“大脑”需要一个大语言模型。你可以根据需求、预算和数据安全要求选择。方案一使用云端 API快速入门以 OpenAI 为例你需要一个 API Key。访问 OpenAI 平台注册并获取 API Key。在项目根目录创建.env文件存储密钥# .env OPENAI_API_KEYsk-your-actual-api-key-here在代码中加载并使用from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # temperature 控制创造性Agent 任务通常设为较低值如0以保证稳定性方案二本地部署模型数据安全、可控使用Ollama或vLLM等工具在本地运行开源模型。安装 Ollama从官网下载并安装。拉取并运行模型# 在终端中拉取一个模型例如 Llama 3.1 8B ollama pull llama3.1:8b # 运行模型服务默认在 11434 端口 ollama run llama3.1:8b在代码中通过 LangChain 连接本地 Ollama 服务from langchain_community.llms import Ollama llm Ollama(modelllama3.1:8b, base_urlhttp://localhost:11434)注意本地模型的推理能力、速度和准确性通常低于顶级商用 API且需要足够的硬件资源GPU 内存。对于复杂任务云端 API 是更可靠的选择。2.4 关键依赖版本与兼容性检查不同版本的 LangChain 接口可能有变化。以下是撰写本文时的一个稳定版本组合参考# 可以使用以下命令查看版本 pip show langchain openai建议记录下你的主要依赖版本以便在团队协作或未来复现时保持一致。常见的兼容性问题多源于langchain、langchain-community与其他工具包版本不匹配。3. 构建你的第一个智能体联网搜索助手现在我们动手构建一个具备联网搜索能力的 Agent。这个 Agent 将能回答需要最新信息的问题例如“今天科技圈有什么重磅新闻”。3.1 项目结构与初始化创建一个新的项目目录结构如下my_first_agent/ ├── .env # 存储敏感信息如API Key ├── .gitignore # 忽略 .env 等文件 ├── requirements.txt # 项目依赖 ├── config.py # 配置文件可选 └── main.py # 主程序入口在main.py中我们开始编写代码。3.2 定义工具让 Agent 拥有“手脚”工具是 Agent 能力的延伸。我们先定义一个基于 DuckDuckGo 的搜索工具。# main.py import os from dotenv import load_dotenv from langchain.agents import Tool, AgentExecutor, create_react_agent from langchain.memory import ConversationBufferMemory from langchain import hub # 用于拉取预设的提示词 from langchain_community.utilities import DuckDuckGoSearchAPIWrapper from langchain_openai import ChatOpenAI # 1. 加载环境变量 load_dotenv() # 2. 初始化 LLM这里使用 OpenAI GPT-3.5-Turbo你也可以替换为本地模型 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, openai_api_keyos.getenv(OPENAI_API_KEY)) # 3. 创建搜索工具 search DuckDuckGoSearchAPIWrapper() tools [ Tool( nameSearch, funcsearch.run, descriptionUseful for when you need to answer questions about current events or latest information. Input should be a search query string. ) ]代码解释DuckDuckGoSearchAPIWrapper是 LangChain 社区提供的一个搜索工具包装器。我们创建了一个Tool对象其中name是工具的唯一标识func是工具函数description至关重要——LLM 根据这个描述来决定是否以及如何使用该工具。描述必须清晰准确。3.3 构建智能体与执行器接下来我们将工具和 LLM 组装成 Agent。# 4. 拉取一个适合 ReAct 框架的提示词模板 # 这个模板定义了 Agent 的思考格式Thought, Action, Observation... prompt hub.pull(hwchase17/react-chat) # 5. 创建记忆使 Agent 能记住对话历史 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 6. 创建 Agent agent create_react_agent(llm, tools, prompt) # 7. 创建 Agent 执行器它负责运行整个思考-行动循环 agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, # 开启详细日志方便调试 handle_parsing_errorsTrue, # 处理 LLM 输出解析错误 max_iterations5, # 限制最大循环次数防止死循环 early_stopping_methodgenerate # 当 LLM 输出最终答案时停止 )关键参数说明verboseTrue强烈建议在开发阶段开启它会打印出 Agent 内部的“思考”Thought、“行动”Action和“观察”Observation过程是调试的核心依据。handle_parsing_errorsTrue当 LLM 的输出不符合工具调用格式时尝试让 LLM 重新生成。max_iterations防止 Agent 陷入无限循环的安全阀。根据任务复杂度调整。early_stopping_method当 LLM 的输出中包含最终答案而非工具调用时结束循环。3.4 运行与验证现在让我们运行这个 Agent 并提问。# 8. 运行 Agent if __name__ __main__: # 第一个问题 response agent_executor.invoke({input: What is the latest version of Python released? Summarize the key features in Chinese.}) print(*50) print(Answer:, response[output]) print(*50) # 第二个问题测试记忆功能 response2 agent_executor.invoke({input: Who is the creator of that programming language?}) print(*50) print(Answer:, response2[output])运行python main.py你将看到类似以下的详细输出verboseTrue的效果 Entering new AgentExecutor chain... Thought: The user is asking about the latest version of Python and wants a summary of key features in Chinese. I need to get the latest information. I should use the Search tool. Action: Search Action Input: latest Python version release key features 2024 Observation: [Search results about Python 3.12 or 3.13...] Thought: Based on the search results, the latest stable version is Python 3.12.x. I need to summarize the key features in Chinese. Action: I now have the information needed to answer. Final Answer: Python 的最新稳定版本是 3.12.x。其主要新特性包括更快的解释器性能得益于“自适应解释器”、改进的错误信息提示、新的类型语法如 **kwargs 的类型标注、f-string 解析的增强等。 Finished chain. Answer: Python 的最新稳定版本是 3.12.x。其主要新特性包括... Entering new AgentExecutor chain... Thought: The user is asking about the creator of the programming language mentioned in the previous conversation, which was Python. I know this from general knowledge, no need to search. Action: I have the answer. Final Answer: Python 语言的创始人是吉多·范罗苏姆 (Guido van Rossum)。从输出中你可以清晰地看到 Agent 的思考过程它识别出需要最新信息决定使用搜索工具解析搜索结果并最终生成中文摘要。在第二个问题中它利用记忆之前的对话提到了 Python直接给出了答案无需再次搜索。4. 增强智能体集成代码执行与安全实践一个更强大的 Agent 应该能处理计算和代码相关问题。我们将为其添加一个安全的代码执行工具并讨论相关的安全风险。4.1 添加 Python REPL 工具LangChain 提供了一个实验性的 Python REPL读取-求值-打印-循环工具允许 Agent 执行 Python 代码。# 在 main.py 中更新 tools 列表 from langchain_experimental.tools import PythonREPLTool tools [ Tool( nameSearch, funcsearch.run, descriptionUseful for when you need to answer questions about current events or latest information. Input should be a search query string. ), Tool( namePython_REPL, funcPythonREPLTool().run, # 注意这里创建了工具实例并调用其 run 方法 descriptionA Python shell. Use this to execute Python commands. Input should be a valid Python command. Use this for calculations, data manipulation, or when asked to write or run code. ) ]警告PythonREPLTool允许执行任意 Python 代码这存在极高的安全风险如删除文件、访问网络、安装恶意包。绝对不要在公开或生产环境中未经严格沙箱隔离就使用此工具。它仅适用于受控的本地开发和学习环境。4.2 运行增强版 Agent现在 Agent 拥有了搜索和代码执行两种能力。让我们测试一个需要计算的问题。# 更新运行部分 if __name__ __main__: # 测试计算能力 response agent_executor.invoke({input: Calculate the factorial of 10 using Python, and then tell me the result.}) print(Answer:, response[output])观察verbose日志你会看到 Agent 的思考过程类似“用户要求计算阶乘我需要使用 Python_REPL 工具”然后它生成import math; print(math.factorial(10))这样的代码并执行最后将结果3628800返回给用户。4.3 安全实践与工具限制在生产环境中开放代码执行是极其危险的。必须实施严格的安全措施使用沙箱Sandbox在 Docker 容器或安全沙箱如pysandbox、gVisor中运行代码限制其网络、文件系统和系统调用权限。限制工具集只为 Agent 提供完成特定任务所必需的最小工具集。例如一个数据分析 Agent 可能只需要pandas操作数据的特定函数而不是完整的PythonREPLTool。输入验证与过滤在将用户输入传递给 LLM 和工具之前进行严格的验证和过滤防止提示词注入攻击。人工审核回路对于高风险操作如写入数据库、发送邮件设计流程让 Agent 先提出方案经人工确认后再执行。使用专用工具替代通用 REPL为常见任务创建专用的、安全的工具函数。例如创建一个Calculate工具内部只调用eval处理数学表达式并提前过滤掉危险字符和模块。# 示例一个相对安全的计算工具仍有一定风险需谨慎评估 import ast import operator class SafeCalculatorTool(BaseTool): name Safe_Calculator description Useful for performing basic arithmetic calculations. Input should be a mathematical expression like 2 3 * 4. def _run(self, expression: str) - str: try: # 使用 ast.literal_eval 替代 eval它更安全但功能有限 # 这里我们实现一个简单的安全评估器作为示例 # 生产环境应使用更严格的库或自定义解析器 allowed_operators {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul, ast.Div: operator.truediv, ast.Pow: operator.pow, ast.USub: operator.neg} node ast.parse(expression, modeeval).body def _eval(node): if isinstance(node, ast.Num): return node.n elif isinstance(node, ast.BinOp): return allowed_operators[type(node.op)](_eval(node.left), _eval(node.right)) elif isinstance(node, ast.UnaryOp): return allowed_operators[type(node.op)](_eval(node.operand)) else: raise TypeError(fUnsupported operation: {node}) result _eval(node) return str(result) except Exception as e: return fCalculation error: {e}5. 生产环境部署与高级考量将实验性的 Agent 转化为生产可用的服务需要关注稳定性、性能和可观测性。5.1 配置管理与密钥安全永远不要将 API Key 等敏感信息硬编码在代码中。使用环境变量或专业的密钥管理服务如 AWS Secrets Manager, HashiCorp Vault。开发环境使用.env文件配合python-dotenv。生产环境通过容器环境变量、云服务商密钥管理或配置文件与代码仓库分离注入。5.2 性能优化与成本控制缓存对 LLM 的相同请求和工具调用结果进行缓存减少重复计算和 API 调用。LangChain 提供了LLMCache和SQLiteCache等组件。限制与超时为 Agent 执行设置超时max_execution_time和最大迭代次数max_iterations防止单个请求消耗过多资源或费用。模型选型根据任务复杂度选择合适的模型。简单的分类或提取任务可能使用小模型如gpt-3.5-turbo即可复杂的推理任务再使用大模型如gpt-4。异步处理对于耗时较长的 Agent 任务采用异步处理模式避免阻塞 Web 服务主线程。5.3 可观测性与监控没有监控的 Agent 上线如同盲人骑马。日志记录除了verbose日志应将 Agent 的关键步骤决策、工具调用及结果、最终输出结构化地记录到日志系统如 ELK Stack中。链路追踪为每个用户会话或请求分配唯一 ID追踪完整的“思考-行动”链条便于问题排查和效果分析。关键指标监控延迟Agent 完成一个请求的平均时间、P95/P99 时间。成本每个请求消耗的 Token 数、API 调用费用。成功率任务成功完成的比例。工具使用分布各工具被调用的频率帮助优化工具设计。迭代次数分布大多数请求在几次迭代内完成识别异常长循环。5.4 错误处理与韧性Agent 执行过程中可能发生多种错误LLM API 调用失败、工具执行异常、输出解析错误、陷入循环等。重试机制对瞬时的网络错误或 API 限流进行指数退避重试。优雅降级当核心工具如搜索失败时Agent 应能尝试使用其他方式如从记忆或知识库中回答问题或明确告知用户能力受限。用户友好提示将内部错误转化为用户能理解的提示如“当前服务繁忙请稍后再试”或“我暂时无法处理这个问题”。死循环检测与中断除了设置max_iterations还可以检测重复的工具调用或长时间无进展的状态主动中断任务。6. 常见问题排查清单在开发和使用 Agent 过程中你会遇到各种问题。以下是一个快速排查清单。问题现象可能原因检查步骤解决方案Agent 不调用任何工具直接回答1. 工具描述不清晰或与问题不匹配。2. LLM 的temperature设置过高导致输出随机。3. 提示词Prompt未明确要求使用工具。1. 检查verbose日志看 LLM 的“Thought”部分是否考虑了工具。2. 审查工具description是否准确描述了功能和输入格式。3. 检查使用的prompt模板是否是为 Agent 设计的如react-chat。1. 优化工具描述使其更精确。2. 将 LLM 的temperature设为 0 或接近 0 的值。3. 使用 LangChain Hub 上标准的 Agent 提示词。Agent 陷入无限循环或重复调用同一工具1. 工具返回的结果未能帮助 LLM 推进任务。2.max_iterations设置过高或未设置。3. 任务本身定义不明确LLM 无法找到终止点。1. 查看每次循环中“Observation”的内容是否有效。2. 检查AgentExecutor的max_iterations和early_stopping_method参数。1. 改进工具功能确保其返回有意义的信息。2. 合理设置max_iterations如 10。3. 在用户问题或系统提示中更清晰地定义任务边界。解析 LLM 输出时出错 (ParsingError)1. LLM 的输出格式不符合ReAct等框架预期的Action: ... Action Input: ...格式。2. LLM 输出了最终答案但解析器仍在期待工具调用。1. 查看verbose日志中出错前 LLM 的完整输出。2. 确认handle_parsing_errorsTrue是否已设置。1. 使用更强大的模型如 GPT-4往往有更好的格式遵循能力。2. 启用handle_parsing_errors让执行器尝试让 LLM 重试。3. 微调或提供更详细的提示词指导 LLM 输出正确格式。工具执行失败如网络超时、权限错误1. 工具依赖的外部服务不可用。2. 工具函数内部有 bug。3. 传入工具的输入参数格式错误。1. 单独测试工具函数确认其能正常工作。2. 检查网络连接和 API 密钥有效性。3. 查看工具执行时的错误堆栈信息。1. 在工具函数内部添加更完善的错误处理和日志。2. 为工具调用设置超时和重试机制。3. 在 Agent 层面捕获工具异常并让 LLM 尝试其他方案或向用户报错。本地模型响应慢或无响应1. 本地硬件特别是 GPU 内存不足。2. Ollama 等服务未正确启动。3. 模型文件损坏。1. 使用nvidia-smiNVIDIA或任务管理器检查资源占用。2. 检查 Ollama 服务状态ollama list。3. 尝试用ollama run model-name直接与模型对话测试。1. 换用更小的模型如 7B 参数。2. 确保为 Ollama 分配了足够的资源。3. 重新拉取模型ollama pull model-name。7. 下一步学习与扩展方向完成基础 Agent 构建后你可以从以下几个方向深化学习和实践探索更复杂的 Agent 架构学习使用LangGraph来构建有状态、可分支、多角色协作的智能体工作流。这对于实现审批流程、多专家会诊等场景至关重要。集成向量数据库与检索增强生成RAG为 Agent 配备“长期记忆”和“私有知识库”。将企业内部文档、产品手册等数据存入向量数据库如 Chroma, Pinecone让 Agent 在回答问题时能优先检索并引用这些信息大幅提升答案的准确性和专业性。工具链的深度定制根据你的业务场景开发定制化工具。例如连接数据库执行查询的工具、调用内部 CRM/ERP 系统 API 的工具、生成并发送邮件的工具等。这是 Agent 价值落地的关键。评估与优化建立 Agent 的评估体系。如何量化一个 Agent 回答的质量除了人工评估可以设计自动化评估流程检查其答案的事实准确性、步骤合理性、工具使用效率等并基于评估结果迭代优化提示词和工具设计。前端交互与部署为你的 Agent 构建一个友好的用户界面可以是 Web 聊天界面使用 Gradio, Streamlit也可以是集成到 Slack、钉钉等办公软件中的机器人。最后使用 Docker 容器化你的应用并部署到云服务器或 Kubernetes 集群。构建 AI Agent 是一个持续迭代的过程从简单的原型到稳定可靠的生产系统需要你在工程、算法和安全等多个层面不断打磨。建议从一个明确的、小范围的业务痛点开始快速构建原型并获取反馈再逐步扩展其能力和 robustness。