从零构建AI Agent：基于LangChain实现代码执行与工具调用的智能体开发实践

30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度在实际 AI 开发项目中我们常常面临一个困境如何让一个 AI 模型不仅能理解我们的指令还能像一位经验丰富的工程师一样主动调用工具、执行代码、分析结果并最终完成一个复杂的、多步骤的任务这正是 AI Agent智能体技术试图解决的问题。它不再是简单的“一问一答”而是赋予了 AI 自主规划、决策和执行的能力。xbtlin/ai-berkshire这个项目以及围绕它的关键词如 Claude Code、Codex为我们提供了一个观察和学习 AI Agent 开发实践的绝佳窗口。本文将带你深入理解 AI Agent 的核心概念并以一个典型的开发框架为例从零开始构建一个具备基础能力的 AI Agent。我们将重点关注其工作机制、环境搭建、核心代码实现、技能Skill扩展以及在实际运行中可能遇到的各类问题。无论你是希望将 AI 能力集成到现有业务系统还是探索自动化编程、数据分析等前沿应用掌握 AI Agent 的开发流程都是关键一步。1. 理解 AI Agent 的核心从被动响应到主动执行在深入代码之前我们必须先厘清几个核心概念这决定了我们后续开发的方向和边界。1.1 什么是 AI Agent通俗地讲一个 AI Agent 是一个能够感知环境、自主决策并执行动作以达成目标的软件实体。它不同于传统的聊天机器人后者通常只进行对话轮次管理。一个功能完整的 AI Agent 通常包含以下几个关键组件规划PlanningAgent 能够将复杂目标分解为一系列可执行的子任务或步骤。例如目标“分析上个月的销售数据并生成报告”可以被分解为连接数据库、查询数据、清洗数据、生成图表、撰写总结。记忆MemoryAgent 需要记住之前的交互历史、工具调用结果和上下文信息以保持对话和任务执行的连贯性。工具使用Tool Use这是 Agent 能力的延伸。Agent 可以调用外部工具如执行 Shell 命令、运行 Python 代码、调用 API、查询数据库等从而突破纯语言模型的限制。行动Action基于规划和工具调用的结果Agent 执行具体的操作并将结果反馈给用户或用于下一步决策。在xbtlin/ai-berkshire及相关生态如 Claude Code的语境下AI Agent 通常指一个能够理解用户自然语言需求并自动调用代码解释器Code Interpreter、文件系统、网络搜索等工具来完成任务的系统。1.2 Claude Code、Codex 与 AI Agent 的关系从搜索热词可以看出这些术语经常被一起讨论容易混淆。Claude Code这通常指的是 Anthropic 公司 Claude 模型系列中针对代码生成、理解和执行进行优化的版本或相关工具。在一些上下文中它可能特指一个集成了 Claude 模型、具备代码执行环境的桌面应用或插件类似 GitHub Copilot 但更侧重于执行。它本身可以作为一个强大的“大脑”被集成到 AI Agent 系统中。Codex这是 OpenAI 推出的一个强大的代码生成模型也是 GitHub Copilot 背后的核心技术。它同样擅长将自然语言转换为代码。在 AI Agent 开发中Codex 或类似的代码生成模型常被用于“工具使用”环节即根据任务描述动态生成并执行代码。AI Agent这是一个更上层的架构概念。你可以把 Claude Code 或 Codex 这样的模型作为 Agent 的“推理核心”或“代码生成器”。然后围绕这个核心你需要构建规划器、记忆模块、工具调用框架等才能形成一个完整的 Agent。因此一个典型的开发模式是使用一个强大的语言模型如 Claude 3, GPT-4, DeepSeek-V3作为规划与决策中心并为其配备一个代码执行环境作为核心工具再集成其他工具如网络搜索、文件操作从而构建出一个功能强大的 AI Agent。2. 环境准备与核心依赖选择构建一个 AI Agent 需要选择合适的开发框架和模型服务。由于xbtlin/ai-berkshire的具体实现细节未提供我们将基于当前开源社区的最佳实践选择一个流行且功能完整的框架作为示例——LangChain或LlamaIndex。这两个框架都提供了构建 Agent 所需的核心抽象。为了更贴近“代码执行”这一热点我们选择以LangChain为例因为它对工具调用和代码执行的支持非常直观。同时我们将使用OpenAI 兼容的 API例如来自 DeepSeek、智谱AI、Ollama 本地模型等作为语言模型以规避某些服务的访问限制。2.1 基础环境与 Python 包管理首先确保你的开发环境已就绪。操作系统Windows (WSL2 推荐)、macOS 或 Linux。Python 版本 3.9。建议使用虚拟环境隔离项目依赖# 创建并激活虚拟环境 (以 venv 为例) python -m venv ai_agent_env # Windows ai_agent_env\Scripts\activate # macOS/Linux source ai_agent_env/bin/activate2.2 安装核心依赖我们将安装langchain核心包、用于连接 OpenAI 兼容 API 的openai库、以及一个用于代码执行和工具调用的关键组件langchain-experimental。pip install langchain openai langchain-experimentallangchain-experimental包含了一些尚在实验阶段但非常强大的功能例如PythonREPLTool它允许 Agent 在安全的沙箱中执行 Python 代码——这正是实现“Claude Code”类似功能的核心。2.3 配置模型 API 密钥为了调用大模型你需要一个 API 密钥。这里以 DeepSeek 为例因其在热搜词中被提及它提供了 OpenAI 兼容的接口。访问 DeepSeek 平台注册并获取 API Key。在代码中或环境变量中配置。强烈建议使用环境变量避免将密钥硬编码在代码中。# 在终端中设置环境变量 (临时) export DEEPSEEK_API_KEYyour-api-key-here # Windows PowerShell $env:DEEPSEEK_API_KEYyour-api-key-here如果你的网络环境无法稳定访问公有云 API可以考虑使用Ollama在本地部署开源模型。安装 Ollama 后拉取一个模型如llama3.2、qwen2.5-coderLangChain 也可以通过Ollama库进行调用。# 安装 Ollama (详见官网) # 拉取一个代码能力较强的模型 ollama pull qwen2.5-coder:7b3. 构建你的第一个代码执行 AI Agent现在我们将一步步构建一个能够理解自然语言任务、并自动编写和执行 Python 代码的简易 AI Agent。3.1 项目结构与初始化创建一个新的项目目录结构如下ai-berkshire-demo/ ├── main.py # 主程序入口 ├── tools/ # 自定义工具目录 │ └── __init__.py ├── .env # 存储环境变量 (需加入.gitignore) └── requirements.txt # 依赖列表在requirements.txt中写入langchain openai langchain-experimental python-dotenv运行pip install -r requirements.txt安装依赖。创建.env文件并填入你的 API 密钥DEEPSEEK_API_KEYyour_actual_deepseek_api_key_here # 如果使用其他服务如 OpenAI # OPENAI_API_KEYsk-...3.2 编写核心 Agent 逻辑在main.py中我们开始编写代码。首先加载环境变量并初始化语言模型LLM。import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI # 注意这里用 ChatOpenAI 兼容 DeepSeek # 加载 .env 文件中的环境变量 load_dotenv() # 初始化 LLM # 以 DeepSeek 为例base_url 需要指向其兼容端点 llm ChatOpenAI( modeldeepseek-chat, # 模型名称根据服务商调整 openai_api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com/v1, # DeepSeek 的 API 地址 temperature0.1, # 较低的温度使输出更确定适合代码生成 ) # 如果你使用 Ollama 本地模型 # from langchain_community.llms import Ollama # llm Ollama(modelqwen2.5-coder:7b)接下来为 Agent 配备最关键的工具——Python REPL读取-求值-打印-循环工具。这个工具允许 Agent 在隔离环境中执行 Python 代码并获取结果。from langchain_experimental.tools import PythonREPLTool python_repl PythonREPLTool()现在我们将工具封装成一个列表并创建 Agent。LangChain 提供了多种 Agent 类型这里使用功能强大的create_react_agent它基于 ReAct 框架能让 Agent 进行“思考-行动-观察”的循环。from langchain import hub from langchain.agents import create_react_agent, AgentExecutor # 从 LangChain Hub 拉取一个适合的 ReAct 提示词模板 # 这个模板会指导 LLM 如何规划和使用工具 prompt hub.pull(hwchase17/react-chat) # 定义 Agent 可以使用的工具列表 tools [python_repl] # 创建 ReAct Agent agent create_react_agent(llm, tools, prompt) # 创建 Agent 执行器它负责运行 Agent 的循环 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 开启详细日志方便观察 Agent 的思考过程 handle_parsing_errorsTrue, # 处理解析错误 max_iterations10, # 限制最大迭代次数防止死循环 )3.3 运行并测试你的 Agent让我们用一个简单的数学计算和文件操作任务来测试它。# 测试 1: 简单的计算 print( 测试 1: 计算 2 的 10 次方 ) result1 agent_executor.invoke({ input: 请计算 2 的 10 次方是多少, chat_history: [] # 初始对话历史为空 }) print(f最终答案: {result1[output]}\n) # 测试 2: 使用 Python 进行文件操作在沙箱中 print( 测试 2: 创建一个包含列表的 JSON 文件 ) result2 agent_executor.invoke({ input: “在当前目录下如果不行就在临时目录创建一个名为 ‘data.json’ 的文件内容是一个包含三个水果名称的 JSON 列表。”, chat_history: [] }) print(f最终答案: {result2[output]}\n) # 测试 3: 更复杂的任务 - 数据分析 print( 测试 3: 简单的数据分析 ) # 先让 Agent 生成一些模拟数据并分析 result3 agent_executor.invoke({ input: “生成一个包含 10 个随机整数范围1-100的列表然后计算这个列表的平均值和最大值。”, chat_history: [] }) print(f最终答案: {result3[output]})运行python main.py你将看到类似以下的详细输出verboseTrue的效果 测试 1: 计算 2 的 10 次方 Entering new AgentExecutor chain... 思考用户让我计算 2 的 10 次方。这是一个数学计算我可以使用 Python REPL 工具来执行 Python 代码。 行动使用 Python REPL 工具。 行动输入print(2 ** 10) 观察1024 思考我得到了结果 1024这就是答案。 最终答案2 的 10 次方是 1024。 Finished chain. 最终答案: 2 的 10 次方是 1024。通过日志你可以清晰地看到 Agent 的“思考-行动-观察”过程。对于测试 2 和 3它会展示更复杂的步骤比如导入json库、使用random库等。4. 扩展 Agent 能力自定义工具与技能Skills仅仅能执行 Python 代码还不够。一个强大的 AI Agent 应该能调用各种外部工具这就是热搜词中提到的Skill。在 LangChain 中工具Tool就是技能的载体。4.1 创建一个自定义工具获取当前时间假设我们希望 Agent 能知道当前时间。我们可以创建一个返回当前时间的工具。在tools/目录下创建custom_tools.pyfrom datetime import datetime from langchain.tools import tool tool def get_current_time(query: str) - str: 当用户询问当前时间、日期或现在几点时使用此工具。参数 query 是用户的原始问题。 now datetime.now() # 返回格式化的时间字符串 return now.strftime(%Y-%m-%d %H:%M:%S)4.2 集成自定义工具到 Agent修改main.py导入并添加这个新工具。# ... 之前的导入 ... from tools.custom_tools import get_current_time # ... 初始化 llm, python_repl ... # 定义工具列表现在包含两个工具 tools [python_repl, get_current_time] # ... 后续创建 agent 和 executor 的代码不变 ...4.3 测试多工具协作现在Agent 可以同时处理涉及代码执行和时间查询的任务。print( 测试多工具 Agent ) result agent_executor.invoke({ input: “现在几点了然后基于当前的小时数如果是白天6-18点就打印‘你好白天’否则打印‘你好夜晚’。请用 Python 代码判断。”, chat_history: [] }) print(f最终答案: {result[output]})运行后Agent 会先调用get_current_time工具获取时间然后基于返回的时间字符串在“思考”后决定调用PythonREPLTool来编写并执行条件判断的代码。4.4 理解工具的描述Description与参数创建工具时函数文档字符串docstring至关重要。LLM 依靠它来理解工具的用途和调用方式。tool装饰器会自动使用 docstring 作为工具的描述。对于更复杂的工具你可能需要定义args_schema来明确参数结构。例如一个搜索工具from pydantic import BaseModel, Field from langchain.tools import tool class SearchInput(BaseModel): query: str Field(description搜索查询词) tool(args_schemaSearchInput) def web_search(query: str) - str: 一个用于搜索互联网信息的工具。 # 这里可以集成 SerperAPI、Google Search API 等 # 返回模拟结果 return f关于 ‘{query}’ 的搜索结果...5. 生产环境考量与常见问题排查将演示项目转化为一个稳定、可用的生产级 AI Agent 需要解决更多问题。5.1 安全性与沙箱隔离代码执行是最高风险的操作。PythonREPLTool虽然提供了一定隔离但在生产环境中远远不够。风险恶意或错误的代码可能删除文件、访问敏感信息、消耗大量资源或进行网络攻击。建议使用 Docker 沙箱将代码执行环境放在一个无网络、资源受限的 Docker 容器中。可以使用langchain社区工具或自行封装。限制功能禁用危险模块如os,sys,subprocess的部分功能。可以通过自定义一个安全的PythonREPL来实现。超时与资源限制对每次代码执行设置 CPU/内存限制和超时时间。审计日志记录所有被执行的代码用于审计和问题回溯。5.2 记忆与上下文管理我们的示例只处理单轮对话。真实的 Agent 需要记住对话历史。实现LangChain 提供了多种记忆后端如ConversationBufferMemory、ConversationSummaryMemory。集成在创建AgentExecutor时传入memory参数。from langchain.memory import ConversationBufferMemory memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, # 加入记忆 verboseTrue, handle_parsing_errorsTrue, max_iterations10, )在调用invoke时不再需要手动传递chat_history执行器会自动从memory中管理。5.3 错误处理与稳定性Agent 执行可能失败原因包括LLM 输出格式错误、工具调用异常、代码执行错误等。handle_parsing_errors如上文设置可以捕获 Agent 输出无法解析为工具调用的错误并尝试让 LLM 修正。工具异常捕获在每个自定义工具内部进行try-except返回清晰的错误信息供 LLM 理解。迭代限制务必设置max_iterations防止因逻辑错误导致无限循环。回退策略当 Agent 多次尝试失败后应有一个回退机制例如转为向用户请求澄清或执行一个更安全的默认操作。5.4 性能与成本优化提示词工程精心设计系统提示词prompt明确 Agent 的角色、约束和目标可以减少无效的迭代提高任务成功率。工具选择优化当工具很多时LLM 可能选错工具。可以通过在工具描述中提供更清晰的示例或使用Tool calling格式更规范的模型如 GPT-4来改善。缓存对 LLM 的响应和某些工具的结果如不变的天气数据进行缓存可以降低延迟和 API 成本。异步执行对于 I/O 密集型的工具调用如网络请求使用异步模式可以大幅提升吞吐量。5.5 常见问题排查表在开发和运行 AI Agent 时你会遇到各种问题。下表列出了典型问题及其排查思路。问题现象可能原因检查与解决步骤Agent 不调用工具直接回答1. 提示词Prompt未明确要求使用工具。2. 工具描述不够清晰LLM 不理解何时使用。3. LLM 能力不足如模型太小。1. 检查hub.pull(“hwchase17/react-chat”)的提示词内容确保包含使用工具的指令。2. 优化工具函数的 docstring使其用途和输入参数极其明确。3. 尝试更换更强的基础模型如从gpt-3.5-turbo切换到gpt-4或claude-3。工具调用参数错误LLM 生成的工具调用参数格式不符合args_schema要求。1. 开启verboseTrue查看 LLM 输出的原始“行动”内容。2. 确保args_schema中的字段描述清晰。3. 使用handle_parsing_errorsTrue让执行器尝试修复。Python 代码执行失败1. 生成的代码存在语法错误。2. 沙箱环境中缺少必要包。3. 代码试图执行不安全操作被拦截。1. 查看verbose日志中代码执行后的“观察”输出通常会有错误信息。2. 确保沙箱环境预装了常用库如numpy,pandas。可以在工具初始化时安装。3. 审查并强化沙箱的安全策略。达到最大迭代次数max_iterations1. 任务过于复杂10 步内无法完成。2. Agent 陷入“思考-调用-失败”的死循环。1. 适当增加max_iterations如到 15 或 20。2. 分析verbose日志看是哪一步反复失败。可能是工具能力不足或 LLM 规划有误需要优化提示词或增加新工具。API 调用失败或超时1. API 密钥错误或余额不足。2. 网络连接问题。3. 服务端限流或故障。1. 检查环境变量DEEPSEEK_API_KEY是否正确加载。2. 尝试用curl或直接调用openai库测试 API 连通性。3. 查看返回的错误码和消息如果是429错误需要降低请求频率。记忆Memory不工作1.memory_key与提示词中使用的键不匹配。2. 未将memory对象正确传递给AgentExecutor。1. 确保ConversationBufferMemory(memory_key”chat_history”)中的memory_key值与提示词模板中引用历史记录的变量名一致。2. 确认agent_executor AgentExecutor(…, memorymemory)已设置。6. 进阶方向与学习路径掌握了基础 AI Agent 的构建后你可以向以下几个方向深入探索这正是热搜词中提及的“AI Agent 工作流”、“商用 AI Agent”等概念所涵盖的领域。6.1 集成更复杂的工具链MCPModel Context Protocol (MCP) 是一种新兴标准用于让 AI 模型更安全、更标准化地使用工具和访问数据。你可以探索如何将你的 Agent 与 MCP 服务器连接从而获得访问数据库、内部系统、第三方 SaaS 等强大能力而不是自己编写每一个工具。6.2 实现分层规划与子任务分解对于复杂任务简单的 ReAct 循环可能不够。可以引入更高级的规划器如 LLM 本身作为规划器将顶级目标分解为子任务树然后为每个子任务实例化专门的 Agent 或调用特定的工具链。LangChain 的PlanAndExecute执行器是这方面的起点。6.3 加入验证与确认机制在生产环境中让 AI 自动执行代码或操作存在风险。可以为关键操作如文件删除、数据库写入、发送邮件加入“人工确认”环节。Agent 在调用此类工具前必须先向用户展示计划执行的操作并等待确认。6.4 模型微调与领域适配如果你的 Agent 专注于特定领域如金融分析、法律文书、医疗问答可以考虑使用领域数据对基础 LLM 进行微调Fine-tuning或为其编写领域特定的提示词和工具使其在该领域的表现更加专业和可靠。6.5 学习路线建议基础巩固熟练掌握 LangChain/LlamaIndex 的核心概念Model, Prompt, Chain, Agent, Tool, Memory。工具开发练习为你的 Agent 编写各种自定义工具包括调用 REST API、操作数据库、处理文件等。安全实践深入学习安全沙箱技术Docker, gVisor、权限控制和审计日志。架构设计学习如何设计一个可扩展、高可用的 Agent 服务考虑并发、队列、状态管理等问题。领域深入结合你的业务背景将 AI Agent 应用到具体场景中解决实际问题。构建一个真正智能、可靠且安全的 AI Agent 是一个系统工程它结合了提示词工程、软件架构、安全运维和领域知识。从xbtlin/ai-berkshire这类项目出发理解其设计理念然后亲手搭建、调试、迭代你自己的 Agent是掌握这项技术最有效的途径。记住从第一个能安全执行print(“Hello, Agent!”)的简单 Agent 开始每一步扩展都要把稳定性和安全性放在首位。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度