1. 项目概述为什么现在要自己动手做AI编程智能体最近几个月AI编程领域的热度几乎被“智能体”这个词给点燃了。无论是社区里讨论的LangChain、LangGraph还是像Claude Code、DeepSeek这类新冒头的代码模型大家都在琢磨一件事怎么让AI不只是回答代码问题而是能像一个真正的程序员助手那样理解上下文、规划任务、执行操作甚至能自我纠错。这就是所谓的“AI编程智能体”。你可能已经用过GitHub Copilot或者Cursor它们能补全代码、解释函数这很好。但智能体更进一步。想象一下你告诉它“帮我在当前项目里添加一个用户登录功能用FastAPI和JWT再写几个测试。”一个合格的编程智能体应该能理解这个复杂指令拆解成“检查现有项目结构”、“创建认证路由文件”、“编写JWT工具函数”、“生成单元测试”等一系列子任务然后逐一执行过程中遇到错误还能自己尝试修复。这不再是简单的问答而是具备一定自主性的“代理”。我之所以想从零开始带大家搭建一个是因为现成的平台或插件虽然方便但往往是个黑盒。你不知道它内部怎么运作的出了问题很难调试想定制功能更是无从下手。更重要的是理解智能体的构建过程能让你真正掌握AI如何与编程工作流结合的核心逻辑这是未来无论作为开发者还是技术决策者都非常有价值的能力。本系列文章就面向有一定Python基础对AI应用开发感兴趣想亲手打造一个“听话又聪明”的编程助手的开发者。我们会从最基础的概念讲起用最实用的代码一步步把它实现出来。2. 智能体核心概念与框架选型在动手写代码之前我们必须把几个关键概念和为什么选它们搞清楚。这就像盖房子先看图纸能避免后面很多返工的坑。2.1 智能体究竟是什么不仅仅是聊天机器人很多人把智能体等同于一个更复杂的聊天机器人这其实低估了它。在AI的语境下智能体通常指一个能够感知环境、进行决策并执行动作以达成目标的系统。对于编程智能体来说环境就是你的代码库、文件系统、终端可能还包括数据库、API文档等。感知通过读取文件、分析代码结构、解析错误信息来获取信息。决策基于目标如“实现登录功能”和当前感知到的信息决定下一步做什么是写文件还是运行测试。动作执行具体的操作比如创建新文件、写入代码、运行shell命令。它与普通聊天机器人的核心区别在于状态管理和工具调用。聊天机器人每次对话相对独立而智能体需要记住之前做了什么、当前任务进展到哪一步。工具调用则让它从“说说而已”变成“真能干活”比如调用文件读写工具、命令行工具。2.2 主流框架对比为什么选择LangChain目前搭建智能体有几个主流选择LangChain、LangGraph、Dify、Coze等。我们选择LangChain作为起点原因如下灵活性与控制度最高LangChain是一个底层框架提供了构建链和智能体所需的各种模块模型调用、记忆、工具。它不像Dify或Coze那样提供开箱即用的可视化界面但正因为如此你能完全控制智能体的每一个逻辑环节适合学习和深度定制。强大的工具生态LangChain社区提供了海量的工具集成从简单的搜索引擎、计算器到复杂的Git操作、数据库查询几乎都能找到现成的封装。这对于编程智能体需要操作文件、运行命令的场景至关重要。清晰的概念模型LangChain将智能体抽象为“AgentExecutor”执行“Tools”并使用“LLM”作为大脑的模式概念清晰易于理解其运作机制。理解了LangChain再去看更复杂的LangGraph用于多智能体协作或复杂工作流也会更容易。成熟的社区和文档虽然LangChain的API有时变化较快但其官方文档和社区资源是目前最丰富的。遇到问题更容易找到解决方案。LangGraph和LangChain是什么关系你可以把LangChain看作是提供了基础建材砖块、水泥而LangGraph是帮你设计复杂建筑蓝图如带循环、分支的工作流的专门工具。对于初期的单一编程智能体LangChain的AgentExecutor已经足够。当我们需要智能体进行多轮复杂规划或者协调多个子智能体时才会用到LangGraph。本系列我们先聚焦前者。2.3 模型选型Claude Code与DeepSeek的抉择智能体的“大脑”是大语言模型。它的代码能力、逻辑推理能力和对指令的遵循程度直接决定了智能体的上限。Claude Code这是Anthropic专门为代码生成的模型在多项基准测试中表现优异尤其擅长生成高质量、安全、符合人类偏好的代码。它的强项是代码生成质量和对复杂指令的理解。如果你想打造一个代码风格优雅、bug较少的智能体Claude Code是顶级选择。但它的API访问可能对部分开发者有门槛且通常不是免费的。DeepSeek深度求索公司推出的模型特别是最近热议的DeepSeek-V4 Flash以其极高的性价比和强大的代码能力迅速走红。它的优势在于极高的上下文长度支持128K甚至更长、完全免费的API对于有限额度以及对中文指令的良好理解。对于个人开发者或实验项目DeepSeek是目前最具吸引力的选择之一。我的选择与建议考虑到本教程的普适性和成本我们将以DeepSeek作为默认模型进行演示。它的免费额度足够我们完成学习和搭建一个可用的原型。如果你有Claude Code的API权限替换起来也非常简单只需修改几行配置代码。两者的核心逻辑完全一致。注意模型领域迭代极快今天的选择可能明天就有更好的出现。掌握智能体的构建框架比绑定某个特定模型更重要。框架搭好了换模型就像换发动机车还能跑。3. 开发环境搭建与核心依赖安装工欲善其事必先利其器。我们来建立一个干净、可复现的开发环境。3.1 Python环境与虚拟环境管理强烈建议使用Python 3.10或3.11版本这是大多数AI库兼容性最好的版本。避免使用最新的3.12或3.13可能会遇到一些底层依赖的编译问题。使用虚拟环境是Python开发的好习惯它能隔离项目依赖避免冲突。# 1. 创建项目目录并进入 mkdir ai_code_agent cd ai_code_agent # 2. 创建虚拟环境这里使用venv你也可以用conda python3.10 -m venv venv # 3. 激活虚拟环境 # 在 macOS/Linux 上 source venv/bin/activate # 在 Windows 上 # venv\Scripts\activate # 激活后命令行提示符前通常会显示 (venv)3.2 安装LangChain及关键依赖我们将通过pip安装必要的包。这里不仅安装LangChain还包括用于工具调用、模型交互的组件。# 升级pip到最新版本 pip install --upgrade pip # 安装LangChain核心包 pip install langchain langchain-core # 安装LangChain社区包里面包含大量社区维护的工具和集成 pip install langchain-community # 安装用于调用OpenAI/DeepSeek等API兼容接口的包 # LangChain官方推荐使用 langchain-openai它兼容OpenAI API格式的接口DeepSeek也兼容此格式。 pip install langchain-openai # 安装用于构建Web后端的FastAPI可选但后续扩展智能体为服务时会用到 pip install fastapi uvicorn # 安装环境变量管理库用于安全存储API密钥 pip install python-dotenv安装后验证在Python交互环境中尝试导入langchain如果没有报错说明安装成功。import langchain print(langchain.__version__)3.3 获取并配置DeepSeek API密钥访问DeepSeek官网注册并登录账号。在控制台或API密钥管理页面创建一个新的API密钥。在项目根目录下创建一个名为.env的文件用于存储密钥切记不要将此文件提交到Git。# .env 文件内容 DEEPSEEK_API_KEY你的实际API密钥然后在代码中通过python-dotenv加载from dotenv import load_dotenv import os load_dotenv() # 加载 .env 文件中的环境变量 deepseek_api_key os.getenv(DEEPSEEK_API_KEY) if not deepseek_api_key: raise ValueError(请在 .env 文件中设置 DEEPSEEK_API_KEY)3.4 初始化一个简单的LangChain智能体进行验证让我们写一个最简单的“Hello World”智能体确保一切就绪。这个智能体只有一个功能调用一个“打招呼”的工具。# test_agent.py from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain import hub # 1. 初始化模型 - 注意我们使用ChatOpenAI但通过base_url指向DeepSeek llm ChatOpenAI( modeldeepseek-chat, # 模型名称根据DeepSeek文档填写 openai_api_keydeepseek_api_key, base_urlhttps://api.deepseek.com/v1, # DeepSeek的API端点 temperature0.1, # 温度调低让代码生成更确定 ) # 2. 定义一个简单的工具 def introduce_yourself(name: str) - str: 向某人做自我介绍。 return f你好{name}我是一个AI编程智能体很高兴为你服务。 introduce_tool Tool( nameIntroduce, funcintroduce_yourself, description当用户要求你自我介绍时使用此工具。 ) # 3. 获取一个预设的智能体提示词模板从LangChain Hub prompt hub.pull(hwchase17/react-chat) # 4. 创建智能体 agent create_react_agent(llm, tools[introduce_tool], promptprompt) # 5. 创建执行器 agent_executor AgentExecutor(agentagent, tools[introduce_tool], verboseTrue) # 6. 运行测试 if __name__ __main__: response agent_executor.invoke({input: 请介绍一下你自己, chat_history: []}) print(智能体回复, response[output])运行这个脚本python test_agent.py。如果配置正确你应该能看到详细的执行日志因为verboseTrue最终智能体会调用Introduce工具并返回问候语。这一步验证了模型连接、工具定义和智能体执行流程都是通的。4. 构建编程智能体的核心工具集一个只会打招呼的智能体显然没用。编程智能体的核心能力来自于它的一套“工具”。这些工具就是它能操作现实世界代码世界的手和脚。我们来打造几个程序员最需要的核心工具。4.1 文件读写工具智能体的眼睛和手这是最基本也是最重要的工具。智能体需要能读取现有代码来理解上下文也需要能写入新代码或修改旧代码。# file_tools.py import os from typing import Optional from langchain.tools import Tool def read_file(file_path: str) - str: 读取指定路径文件的内容。 try: with open(file_path, r, encodingutf-8) as f: content f.read() return f文件 {file_path} 的内容如下\n\n{content}\n except FileNotFoundError: return f错误文件 {file_path} 不存在。 except Exception as e: return f读取文件 {file_path} 时出错{str(e)} def write_file(file_path: str, content: str, mode: str w) - str: 将内容写入指定路径的文件。mode可以是w覆盖或a追加。 try: # 确保目录存在 os.makedirs(os.path.dirname(file_path), exist_okTrue) with open(file_path, mode, encodingutf-8) as f: f.write(content) action 已覆盖写入 if mode w else 已追加到 return f成功内容{action}文件 {file_path}。 except Exception as e: return f写入文件 {file_path} 时出错{str(e)} def list_directory(dir_path: str .) - str: 列出指定目录下的文件和文件夹。 try: items os.listdir(dir_path) # 简单区分文件和文件夹 result [] for item in items: full_path os.path.join(dir_path, item) if os.path.isdir(full_path): result.append(f[目录] {item}/) else: result.append(f[文件] {item}) return f目录 {dir_path} 下的内容\n \n.join(result) except Exception as e: return f列出目录 {dir_path} 时出错{str(e)} # 将函数包装成LangChain Tool read_file_tool Tool( nameread_file, funcread_file, description读取一个文件的内容。输入应该是文件的绝对路径或相对于当前工作目录的路径。 ) write_file_tool Tool( namewrite_file, funcwrite_file, description将内容写入文件。输入应该是一个JSON字符串包含file_path和content两个键。例如{\file_path\: \test.py\, \content\: \print(hello)\}。可选键mode默认为w覆盖可设为a追加。 ) list_dir_tool Tool( namelist_directory, funclist_directory, description列出目录中的文件和子目录。输入是目录路径默认为当前目录。 )实操心得在write_file工具中我特意要求输入是JSON字符串而不是多个参数。这是因为LangChain的智能体在决定使用工具时需要生成一个格式严格的“工具调用”参数。让LLM生成一个结构化的JSON比让它自由组织多个参数更可靠能减少解析错误。这是构建稳定工具的一个小技巧。4.2 命令行执行工具让智能体能运行代码智能体写完代码总得跑起来看看对不对。一个安全的、受控的命令行执行工具必不可少。# shell_tool.py import subprocess import shlex from typing import Optional from langchain.tools import Tool def run_shell_command(command: str, timeout: int 30) - str: 在安全模式下运行shell命令。 参数: command: 要执行的shell命令字符串。 timeout: 命令执行超时时间秒防止长时间运行。 返回: 命令的标准输出和错误输出。 # **安全警告**在实际生产环境中必须对命令进行严格过滤 # 这里仅作演示禁止执行危险命令如rm -rf /, sudo等。 dangerous_keywords [rm -rf, sudo, mkfs, dd, /dev/sd, chmod 777] for keyword in dangerous_keywords: if keyword in command: return f安全限制禁止执行包含危险指令 {keyword} 的命令。 try: # 使用shlex分割命令更安全 args shlex.split(command) result subprocess.run( args, capture_outputTrue, textTrue, timeouttimeout, cwd. # 在当前项目目录下执行 ) output [] if result.stdout: output.append(f标准输出\n{result.stdout}) if result.stderr: output.append(f标准错误\n{result.stderr}) output.append(f返回码{result.returncode}) return \n---\n.join(output) except subprocess.TimeoutExpired: return f错误命令执行超时{timeout}秒。 except FileNotFoundError: return f错误命令未找到或无法执行。请检查命令拼写。 except Exception as e: return f执行命令时发生未知错误{str(e)} shell_tool Tool( namerun_shell_command, funcrun_shell_command, description在终端中执行一个安全的shell命令。输入是纯字符串命令例如 python --version 或 ls -la。注意禁止执行删除、格式化等危险操作。 )为什么安全如此重要这是编程智能体开发中最容易忽视也最危险的部分。你绝对不希望智能体因为误解了你的指令就执行rm -rf /*。上面的简单过滤只是第一道防线。在更严肃的场景下你需要使用沙箱环境如Docker容器来运行命令。实现更精细的基于权限的允许列表Allow List只允许运行python,pip,git,npm等特定命令及其安全参数。对用户输入即给智能体的指令进行预处理识别并阻止危险意图。4.3 代码分析与搜索工具可选但强大为了让智能体更“懂”项目我们可以给它增加一些分析能力。# analysis_tools.py import ast from typing import List from langchain.tools import Tool def get_python_file_structure(file_path: str) - str: 分析Python文件提取其中的类、函数定义。 try: with open(file_path, r, encodingutf-8) as f: tree ast.parse(f.read(), filenamefile_path) except Exception as e: return f无法解析Python文件 {file_path}{str(e)} definitions [] for node in ast.walk(tree): if isinstance(node, ast.FunctionDef): args [arg.arg for arg in node.args.args] def_str f函数: {node.name}({, .join(args)}) if node.returns: def_str f - {ast.unparse(node.returns)} definitions.append(def_str) elif isinstance(node, ast.ClassDef): methods [n.name for n in node.body if isinstance(n, ast.FunctionDef)] definitions.append(f类: {node.name} [方法: {, .join(methods)}]) elif isinstance(node, ast.Import): for alias in node.names: definitions.append(f导入: {alias.name}) elif isinstance(node, ast.ImportFrom): module node.module or names , .join([alias.name for alias in node.names]) definitions.append(f从 {module} 导入: {names}) if not definitions: return f文件 {file_path} 中没有找到明显的类或函数定义。 return f文件 {file_path} 的结构概览\n \n.join(definitions) # 这里可以集成更强大的代码搜索比如用ripgrep (rg) 进行全文搜索 # 需要系统安装 ripgrep: pip install subprocess 并调用 rg 命令 def search_in_code(keyword: str, path: str .) - str: 在代码库中搜索包含关键词的文件和行。 # 这是一个简化版实际可以使用 subprocess 调用 grep -r 或 rg import subprocess try: # 使用grep进行简单搜索确保系统有grep cmd fgrep -r -n --include\*.py\ --include\*.js\ --include\*.ts\ \{keyword}\ {path} result subprocess.run(cmd, shellTrue, capture_outputTrue, textTrue, timeout20) if result.stdout: return f在 {path} 中搜索 {keyword} 的结果\n{result.stdout} else: return f在 {path} 中没有找到包含 {keyword} 的代码。 except Exception as e: return f搜索过程中出错{str(e)} analysis_tool Tool( nameanalyze_python_file, funcget_python_file_structure, description分析一个Python文件列出其中的类、函数和导入语句。输入是文件路径。 ) search_tool Tool( namesearch_code, funcsearch_in_code, description在项目代码中搜索指定的关键词。输入是搜索关键词可选第二个参数是搜索路径默认当前目录。 )有了这些工具智能体就能“看到”项目结构“理解”代码关系并“执行”命令了。这构成了它最基础的感知和行动能力。5. 组装你的第一个可工作的编程智能体现在我们把大脑LLM和手脚工具组装起来创建一个真正能处理编程任务的智能体。5.1 创建智能体执行器并集成工具我们将使用LangChain的create_react_agent它基于ReAct框架能让LLM以“思考-行动-观察”的循环来解决问题非常适合需要多步工具调用的场景。# coding_agent.py from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain import hub from dotenv import load_dotenv import os # 导入我们之前定义的工具 from file_tools import read_file_tool, write_file_tool, list_dir_tool from shell_tool import shell_tool from analysis_tools import analysis_tool, search_tool load_dotenv() deepseek_api_key os.getenv(DEEPSEEK_API_KEY) class CodingAgent: def __init__(self): # 1. 初始化模型 self.llm ChatOpenAI( modeldeepseek-chat, openai_api_keydeepseek_api_key, base_urlhttps://api.deepseek.com/v1, temperature0.1, # 可以增加其他参数如请求超时时间 # timeout30, ) # 2. 组合所有工具 self.tools [ read_file_tool, write_file_tool, list_dir_tool, shell_tool, analysis_tool, search_tool, # 未来可以在这里添加更多工具如Git工具、数据库工具等 ] # 3. 从Hub拉取一个针对聊天和工具使用优化的提示词模板 # 你可以自定义这个提示词让它更擅长编程任务 self.prompt hub.pull(hwchase17/react-chat) # 在提示词中注入一些系统指令让智能体更专注于编程 self.prompt.messages[0].prompt.template ( 你是一个专业的AI编程助手。你的目标是帮助用户完成代码编写、文件操作、项目分析等编程任务。 你可以使用工具来读取、写入文件运行命令分析代码结构。 在行动前请先思考你需要做什么以及按什么顺序使用工具。 对于代码修改请先读取相关文件了解现有内容。 对于运行命令请确保命令是安全的。 如果用户的要求模糊请先询问澄清。 请用中文回复。\n\n self.prompt.messages[0].prompt.template ) # 4. 创建智能体和执行器 self.agent create_react_agent(llmself.llm, toolsself.tools, promptself.prompt) self.agent_executor AgentExecutor( agentself.agent, toolsself.tools, verboseTrue, # 设为True可以看到详细的思考过程调试时非常有用 handle_parsing_errorsTrue, # 当LLM输出无法解析为工具调用时尝试让LLM重试 max_iterations10, # 限制最大迭代次数防止死循环 early_stopping_methodgenerate, # 当认为任务完成时可以提前停止 ) def run(self, task: str, chat_history: list None) - str: 执行一个编程任务。 if chat_history is None: chat_history [] try: result self.agent_executor.invoke({ input: task, chat_history: chat_history }) return result[output] except Exception as e: return f智能体执行过程中出现错误{str(e)} # 使用示例 if __name__ __main__: agent CodingAgent() # 测试1让智能体查看当前目录然后创建一个简单的Python文件 print( 测试列出目录并创建文件 ) result agent.run(首先列出当前目录下有什么文件。然后创建一个名为 hello_agent.py 的文件内容是一个打印Hello from AI Agent!的函数并调用它。) print(result) # 测试2让智能体运行它刚刚创建的文件 print(\n 测试运行创建的文件 ) result agent.run(运行刚才创建的 hello_agent.py 文件看看输出是什么。) print(result)运行这个脚本你会看到智能体详细的思考过程verboseTrue。它会先思考“用户要我做什么”然后决定调用list_directory工具观察结果后再决定调用write_file工具并生成合适的JSON参数。最后当你要求它运行时它会调用run_shell_command工具。5.2 设计有效的系统提示词智能体的行为很大程度上受提示词控制。上面代码中我们修改了系统提示词让它更专注于编程。一个更精细的提示词可以包含角色定义明确告诉它“你是一个Python专家”。约束条件例如“不要执行任何破坏性命令”、“修改文件前必须先备份”。输出格式例如“在提供代码时请使用Markdown代码块包裹”。工作流程引导例如“对于任何代码修改请求请遵循1. 读取相关文件 2. 分析问题 3. 提供修改方案或直接修改”。你可以不断迭代提示词观察智能体行为的变化这是优化智能体性能的关键一步。5.3 运行你的智能体并观察其行为运行python coding_agent.py。仔细观察控制台输出的日志。你会看到类似这样的内容 Entering new AgentExecutor chain... 思考用户要求我列出目录并创建文件。我需要先看看当前有什么然后创建一个新的Python文件。 我应该使用list_directory工具。 Action: list_directory Action Input: {input: .} Observation: 目录 . 下的内容 [文件] README.md [目录] venv/ [文件] coding_agent.py ... Thought: 现在我需要创建hello_agent.py文件。我需要使用write_file工具并生成文件内容。 Action: write_file Action Input: {file_path: hello_agent.py, content: def greet():\n print(Hello from AI Agent!)\n\nif __name__ __main__:\n greet()} Observation: 成功内容已覆盖写入文件 hello_agent.py。 Thought: 我已经完成了用户要求的两个步骤。可以结束了。 Final Answer: 已列出当前目录并成功创建了 hello_agent.py 文件其中包含一个打印问候语的函数。这个过程完美展示了ReAct框架Thought(思考) -Action(选择工具并输入) -Observation(工具返回结果) - 循环直到任务完成。6. 实战演练让智能体完成一个真实小任务让我们给智能体一个稍微复杂点的任务检验它的综合能力。任务“在当前目录下检查是否有一个名为requirements.txt的文件。如果没有就创建一个内容包含langchain-openai和python-dotenv。然后使用pip命令检查这两个包是否已安装。”将以下代码添加到coding_agent.py的__main__部分print(\n 实战任务管理依赖文件 ) complex_task 请执行以下任务 1. 检查当前目录下是否存在一个名为 requirements.txt 的文件。 2. 如果不存在则创建它并在文件中写入以下两行内容 langchain-openai python-dotenv 3. 如果文件已存在请读取它的内容并告诉我里面有什么。 4. 最后运行一个pip命令来检查 langchain-openai 这个包是否已经安装在当前环境中。 result agent.run(complex_task) print(result)运行后观察智能体如何拆解这个多步骤任务。一个表现良好的智能体应该调用list_directory或尝试read_file来检查文件是否存在。根据观察结果决定是调用write_file创建文件还是直接返回文件内容。最后调用run_shell_command执行类似pip show langchain-openai或python -c import pkg_resources; print(pkg_resources.get_distribution(langchain-openai))的命令来检查安装情况。这个任务测试了智能体的条件判断、顺序执行和工具组合能力。7. 常见问题、调试技巧与性能优化在实际操作中你肯定会遇到各种问题。这里记录一些我踩过的坑和解决方法。7.1 智能体陷入循环或行为怪异症状智能体反复调用同一个工具或者生成无意义的Action。原因提示词不清晰LLM没有理解任务边界。需要强化提示词中的约束比如“如果你认为任务已经完成请直接给出最终答案。”工具描述不准确工具的描述(description)太模糊或误导了LLM。确保描述清晰说明工具的用途、输入格式和输出示例。max_iterations设置过小或过大太小会导致任务未完成就停止太大会让智能体在死胡同里浪费API调用。解决打开verboseTrue仔细阅读它的“Thought”过程看它在想什么。优化提示词和工具描述。调整AgentExecutor的max_iterations比如设为15和early_stopping_method。7.2 工具调用参数解析错误症状日志中看到Could not parse LLM output: ...错误。原因LLM生成的工具调用参数不是合法的JSON或者缺少必需的字段。解决设置handle_parsing_errorsTrue让执行器尝试要求LLM重试。在工具描述中用非常明确的例子说明输入格式如“输入必须是一个JSON字符串例如{\file_path\: \test.py\, \content\: \print(1)\}”。考虑使用LangChain的StructuredTool它能提供更严格的参数模式验证。7.3 API调用缓慢或超时症状每次智能体思考都要等很久或者请求超时。原因网络问题或模型服务端负载高。ReAct模式每一步都需要调用一次LLM如果步骤多总耗时很长。上下文chat_history过长导致每次请求的token数很多。解决为ChatOpenAI设置timeout参数。使用流式输出虽然不能加快总体速度但可以让用户先看到部分输出体验更好。agent_executor.invoke()返回的是一个字典如果需要流式可以使用agent_executor.stream()。优化上下文管理定期总结或清除过长的历史对话只保留关键信息。考虑更高效的Agent类型create_react_agent是通用但可能较慢的。对于特定领域可以设计更直接的、工具选择更少的智能体流程。7.4 智能体“幻觉”或做出危险操作症状智能体尝试执行rm命令或者修改了不该修改的系统文件。原因LLM本身具有不可预测性且我们的安全限制不够。解决强化工具层面的安全像我们在run_shell_command里做的那样实现命令过滤。对于文件工具可以限制可访问的路径范围如只能在项目目录内操作。在提示词中强调安全在系统指令里明确写出禁止事项。实现“人工确认”环节对于写文件、运行安装或删除命令等高风险操作可以让智能体先输出它计划执行的命令等待用户确认后再实际调用工具。这可以通过设计一个特殊的“确认工具”来实现。7.5 如何扩展更多工具这是智能体能力扩展的核心。假设你想让智能体能操作Git安装Python Git库pip install gitpython创建Git工具函数from git import Repo, GitCommandError def git_status(repo_path: str .) - str: try: repo Repo(repo_path) return repo.git.status() except Exception as e: return fGit操作失败{str(e)} # ... 类似创建 git_add, git_commit, git_push 等函数包装成Tool并添加到self.tools列表里。遵循这个模式你可以集成数据库客户端、HTTP请求库、云服务SDK等打造一个无比强大的智能体。8. 下一步进阶方向与展望至此你已经拥有了一个具备基础感知和行动能力的AI编程智能体。但这仅仅是起点。要让它在实际开发中真正成为得力助手还需要在以下几个方向深耕1. 记忆与上下文管理目前的智能体是“无状态”的每次对话都是新的。你需要为它添加记忆能力让它能记住之前的对话、已经完成的任务、项目特定的约定。这可以通过LangChain的ConversationBufferMemory、ConversationSummaryMemory等组件实现甚至可以将对话历史存入数据库。2. 复杂工作流与LangGraph当任务需要多个智能体协作或者包含复杂的循环、分支判断时例如“持续运行测试直到所有测试通过如果失败则分析日志并尝试修复”AgentExecutor就显得力不从心了。这时需要引入LangGraph它允许你以图Graph的形式定义智能体的工作流精确控制状态转移和节点执行是构建复杂、可靠智能体系统的利器。3. 代码理解与生成的专项优化我们目前使用的通用聊天模型在代码任务上可能不是最优的。可以 *微调提示词提供更多代码示例、约定代码风格如PEP 8。 *使用代码专用模型如Claude Code或者在本地部署CodeLlama等开源代码模型。 *集成代码索引与检索RAG为智能体建立项目代码的向量数据库当需要理解大型项目时可以先检索相关的代码片段再基于此进行生成或修改大大提高准确率。这就是LangChain RAG在编程领域的应用。4. 可视化与交互界面命令行交互不够友好。可以考虑用Gradio或Streamlit快速搭建一个Web界面或者开发一个VSCode插件让智能体深度集成到你的IDE中实现右键菜单、代码块分析、实时建议等功能。5. 评估与持续改进如何衡量智能体的好坏你需要建立一套评估体系例如给定100个编程任务如“修复这个bug”、“实现这个函数”看智能体完成的比例和质量。通过分析失败案例不断优化提示词、工具设计和模型选择。构建AI编程智能体是一个迭代的过程。从今天这个能读文件、写代码、跑命令的“小助手”开始你可以根据自己的需求一点点为它添砖加瓦。最重要的是你亲手搭建了它的核心架构理解了它的运作原理这让你拥有了随时定制和修复它的能力而不是仅仅作为一个神秘黑盒的使用者。在下一篇文章中我们将深入探讨如何为这个智能体添加“记忆”并尝试用LangGraph来构建一个能自主完成多步骤调试任务的更智能体。
1. 项目概述为什么现在要自己动手做AI编程智能体最近几个月AI编程领域的热度几乎被“智能体”这个词给点燃了。无论是社区里讨论的LangChain、LangGraph还是像Claude Code、DeepSeek这类新冒头的代码模型大家都在琢磨一件事怎么让AI不只是回答代码问题而是能像一个真正的程序员助手那样理解上下文、规划任务、执行操作甚至能自我纠错。这就是所谓的“AI编程智能体”。你可能已经用过GitHub Copilot或者Cursor它们能补全代码、解释函数这很好。但智能体更进一步。想象一下你告诉它“帮我在当前项目里添加一个用户登录功能用FastAPI和JWT再写几个测试。”一个合格的编程智能体应该能理解这个复杂指令拆解成“检查现有项目结构”、“创建认证路由文件”、“编写JWT工具函数”、“生成单元测试”等一系列子任务然后逐一执行过程中遇到错误还能自己尝试修复。这不再是简单的问答而是具备一定自主性的“代理”。我之所以想从零开始带大家搭建一个是因为现成的平台或插件虽然方便但往往是个黑盒。你不知道它内部怎么运作的出了问题很难调试想定制功能更是无从下手。更重要的是理解智能体的构建过程能让你真正掌握AI如何与编程工作流结合的核心逻辑这是未来无论作为开发者还是技术决策者都非常有价值的能力。本系列文章就面向有一定Python基础对AI应用开发感兴趣想亲手打造一个“听话又聪明”的编程助手的开发者。我们会从最基础的概念讲起用最实用的代码一步步把它实现出来。2. 智能体核心概念与框架选型在动手写代码之前我们必须把几个关键概念和为什么选它们搞清楚。这就像盖房子先看图纸能避免后面很多返工的坑。2.1 智能体究竟是什么不仅仅是聊天机器人很多人把智能体等同于一个更复杂的聊天机器人这其实低估了它。在AI的语境下智能体通常指一个能够感知环境、进行决策并执行动作以达成目标的系统。对于编程智能体来说环境就是你的代码库、文件系统、终端可能还包括数据库、API文档等。感知通过读取文件、分析代码结构、解析错误信息来获取信息。决策基于目标如“实现登录功能”和当前感知到的信息决定下一步做什么是写文件还是运行测试。动作执行具体的操作比如创建新文件、写入代码、运行shell命令。它与普通聊天机器人的核心区别在于状态管理和工具调用。聊天机器人每次对话相对独立而智能体需要记住之前做了什么、当前任务进展到哪一步。工具调用则让它从“说说而已”变成“真能干活”比如调用文件读写工具、命令行工具。2.2 主流框架对比为什么选择LangChain目前搭建智能体有几个主流选择LangChain、LangGraph、Dify、Coze等。我们选择LangChain作为起点原因如下灵活性与控制度最高LangChain是一个底层框架提供了构建链和智能体所需的各种模块模型调用、记忆、工具。它不像Dify或Coze那样提供开箱即用的可视化界面但正因为如此你能完全控制智能体的每一个逻辑环节适合学习和深度定制。强大的工具生态LangChain社区提供了海量的工具集成从简单的搜索引擎、计算器到复杂的Git操作、数据库查询几乎都能找到现成的封装。这对于编程智能体需要操作文件、运行命令的场景至关重要。清晰的概念模型LangChain将智能体抽象为“AgentExecutor”执行“Tools”并使用“LLM”作为大脑的模式概念清晰易于理解其运作机制。理解了LangChain再去看更复杂的LangGraph用于多智能体协作或复杂工作流也会更容易。成熟的社区和文档虽然LangChain的API有时变化较快但其官方文档和社区资源是目前最丰富的。遇到问题更容易找到解决方案。LangGraph和LangChain是什么关系你可以把LangChain看作是提供了基础建材砖块、水泥而LangGraph是帮你设计复杂建筑蓝图如带循环、分支的工作流的专门工具。对于初期的单一编程智能体LangChain的AgentExecutor已经足够。当我们需要智能体进行多轮复杂规划或者协调多个子智能体时才会用到LangGraph。本系列我们先聚焦前者。2.3 模型选型Claude Code与DeepSeek的抉择智能体的“大脑”是大语言模型。它的代码能力、逻辑推理能力和对指令的遵循程度直接决定了智能体的上限。Claude Code这是Anthropic专门为代码生成的模型在多项基准测试中表现优异尤其擅长生成高质量、安全、符合人类偏好的代码。它的强项是代码生成质量和对复杂指令的理解。如果你想打造一个代码风格优雅、bug较少的智能体Claude Code是顶级选择。但它的API访问可能对部分开发者有门槛且通常不是免费的。DeepSeek深度求索公司推出的模型特别是最近热议的DeepSeek-V4 Flash以其极高的性价比和强大的代码能力迅速走红。它的优势在于极高的上下文长度支持128K甚至更长、完全免费的API对于有限额度以及对中文指令的良好理解。对于个人开发者或实验项目DeepSeek是目前最具吸引力的选择之一。我的选择与建议考虑到本教程的普适性和成本我们将以DeepSeek作为默认模型进行演示。它的免费额度足够我们完成学习和搭建一个可用的原型。如果你有Claude Code的API权限替换起来也非常简单只需修改几行配置代码。两者的核心逻辑完全一致。注意模型领域迭代极快今天的选择可能明天就有更好的出现。掌握智能体的构建框架比绑定某个特定模型更重要。框架搭好了换模型就像换发动机车还能跑。3. 开发环境搭建与核心依赖安装工欲善其事必先利其器。我们来建立一个干净、可复现的开发环境。3.1 Python环境与虚拟环境管理强烈建议使用Python 3.10或3.11版本这是大多数AI库兼容性最好的版本。避免使用最新的3.12或3.13可能会遇到一些底层依赖的编译问题。使用虚拟环境是Python开发的好习惯它能隔离项目依赖避免冲突。# 1. 创建项目目录并进入 mkdir ai_code_agent cd ai_code_agent # 2. 创建虚拟环境这里使用venv你也可以用conda python3.10 -m venv venv # 3. 激活虚拟环境 # 在 macOS/Linux 上 source venv/bin/activate # 在 Windows 上 # venv\Scripts\activate # 激活后命令行提示符前通常会显示 (venv)3.2 安装LangChain及关键依赖我们将通过pip安装必要的包。这里不仅安装LangChain还包括用于工具调用、模型交互的组件。# 升级pip到最新版本 pip install --upgrade pip # 安装LangChain核心包 pip install langchain langchain-core # 安装LangChain社区包里面包含大量社区维护的工具和集成 pip install langchain-community # 安装用于调用OpenAI/DeepSeek等API兼容接口的包 # LangChain官方推荐使用 langchain-openai它兼容OpenAI API格式的接口DeepSeek也兼容此格式。 pip install langchain-openai # 安装用于构建Web后端的FastAPI可选但后续扩展智能体为服务时会用到 pip install fastapi uvicorn # 安装环境变量管理库用于安全存储API密钥 pip install python-dotenv安装后验证在Python交互环境中尝试导入langchain如果没有报错说明安装成功。import langchain print(langchain.__version__)3.3 获取并配置DeepSeek API密钥访问DeepSeek官网注册并登录账号。在控制台或API密钥管理页面创建一个新的API密钥。在项目根目录下创建一个名为.env的文件用于存储密钥切记不要将此文件提交到Git。# .env 文件内容 DEEPSEEK_API_KEY你的实际API密钥然后在代码中通过python-dotenv加载from dotenv import load_dotenv import os load_dotenv() # 加载 .env 文件中的环境变量 deepseek_api_key os.getenv(DEEPSEEK_API_KEY) if not deepseek_api_key: raise ValueError(请在 .env 文件中设置 DEEPSEEK_API_KEY)3.4 初始化一个简单的LangChain智能体进行验证让我们写一个最简单的“Hello World”智能体确保一切就绪。这个智能体只有一个功能调用一个“打招呼”的工具。# test_agent.py from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain import hub # 1. 初始化模型 - 注意我们使用ChatOpenAI但通过base_url指向DeepSeek llm ChatOpenAI( modeldeepseek-chat, # 模型名称根据DeepSeek文档填写 openai_api_keydeepseek_api_key, base_urlhttps://api.deepseek.com/v1, # DeepSeek的API端点 temperature0.1, # 温度调低让代码生成更确定 ) # 2. 定义一个简单的工具 def introduce_yourself(name: str) - str: 向某人做自我介绍。 return f你好{name}我是一个AI编程智能体很高兴为你服务。 introduce_tool Tool( nameIntroduce, funcintroduce_yourself, description当用户要求你自我介绍时使用此工具。 ) # 3. 获取一个预设的智能体提示词模板从LangChain Hub prompt hub.pull(hwchase17/react-chat) # 4. 创建智能体 agent create_react_agent(llm, tools[introduce_tool], promptprompt) # 5. 创建执行器 agent_executor AgentExecutor(agentagent, tools[introduce_tool], verboseTrue) # 6. 运行测试 if __name__ __main__: response agent_executor.invoke({input: 请介绍一下你自己, chat_history: []}) print(智能体回复, response[output])运行这个脚本python test_agent.py。如果配置正确你应该能看到详细的执行日志因为verboseTrue最终智能体会调用Introduce工具并返回问候语。这一步验证了模型连接、工具定义和智能体执行流程都是通的。4. 构建编程智能体的核心工具集一个只会打招呼的智能体显然没用。编程智能体的核心能力来自于它的一套“工具”。这些工具就是它能操作现实世界代码世界的手和脚。我们来打造几个程序员最需要的核心工具。4.1 文件读写工具智能体的眼睛和手这是最基本也是最重要的工具。智能体需要能读取现有代码来理解上下文也需要能写入新代码或修改旧代码。# file_tools.py import os from typing import Optional from langchain.tools import Tool def read_file(file_path: str) - str: 读取指定路径文件的内容。 try: with open(file_path, r, encodingutf-8) as f: content f.read() return f文件 {file_path} 的内容如下\n\n{content}\n except FileNotFoundError: return f错误文件 {file_path} 不存在。 except Exception as e: return f读取文件 {file_path} 时出错{str(e)} def write_file(file_path: str, content: str, mode: str w) - str: 将内容写入指定路径的文件。mode可以是w覆盖或a追加。 try: # 确保目录存在 os.makedirs(os.path.dirname(file_path), exist_okTrue) with open(file_path, mode, encodingutf-8) as f: f.write(content) action 已覆盖写入 if mode w else 已追加到 return f成功内容{action}文件 {file_path}。 except Exception as e: return f写入文件 {file_path} 时出错{str(e)} def list_directory(dir_path: str .) - str: 列出指定目录下的文件和文件夹。 try: items os.listdir(dir_path) # 简单区分文件和文件夹 result [] for item in items: full_path os.path.join(dir_path, item) if os.path.isdir(full_path): result.append(f[目录] {item}/) else: result.append(f[文件] {item}) return f目录 {dir_path} 下的内容\n \n.join(result) except Exception as e: return f列出目录 {dir_path} 时出错{str(e)} # 将函数包装成LangChain Tool read_file_tool Tool( nameread_file, funcread_file, description读取一个文件的内容。输入应该是文件的绝对路径或相对于当前工作目录的路径。 ) write_file_tool Tool( namewrite_file, funcwrite_file, description将内容写入文件。输入应该是一个JSON字符串包含file_path和content两个键。例如{\file_path\: \test.py\, \content\: \print(hello)\}。可选键mode默认为w覆盖可设为a追加。 ) list_dir_tool Tool( namelist_directory, funclist_directory, description列出目录中的文件和子目录。输入是目录路径默认为当前目录。 )实操心得在write_file工具中我特意要求输入是JSON字符串而不是多个参数。这是因为LangChain的智能体在决定使用工具时需要生成一个格式严格的“工具调用”参数。让LLM生成一个结构化的JSON比让它自由组织多个参数更可靠能减少解析错误。这是构建稳定工具的一个小技巧。4.2 命令行执行工具让智能体能运行代码智能体写完代码总得跑起来看看对不对。一个安全的、受控的命令行执行工具必不可少。# shell_tool.py import subprocess import shlex from typing import Optional from langchain.tools import Tool def run_shell_command(command: str, timeout: int 30) - str: 在安全模式下运行shell命令。 参数: command: 要执行的shell命令字符串。 timeout: 命令执行超时时间秒防止长时间运行。 返回: 命令的标准输出和错误输出。 # **安全警告**在实际生产环境中必须对命令进行严格过滤 # 这里仅作演示禁止执行危险命令如rm -rf /, sudo等。 dangerous_keywords [rm -rf, sudo, mkfs, dd, /dev/sd, chmod 777] for keyword in dangerous_keywords: if keyword in command: return f安全限制禁止执行包含危险指令 {keyword} 的命令。 try: # 使用shlex分割命令更安全 args shlex.split(command) result subprocess.run( args, capture_outputTrue, textTrue, timeouttimeout, cwd. # 在当前项目目录下执行 ) output [] if result.stdout: output.append(f标准输出\n{result.stdout}) if result.stderr: output.append(f标准错误\n{result.stderr}) output.append(f返回码{result.returncode}) return \n---\n.join(output) except subprocess.TimeoutExpired: return f错误命令执行超时{timeout}秒。 except FileNotFoundError: return f错误命令未找到或无法执行。请检查命令拼写。 except Exception as e: return f执行命令时发生未知错误{str(e)} shell_tool Tool( namerun_shell_command, funcrun_shell_command, description在终端中执行一个安全的shell命令。输入是纯字符串命令例如 python --version 或 ls -la。注意禁止执行删除、格式化等危险操作。 )为什么安全如此重要这是编程智能体开发中最容易忽视也最危险的部分。你绝对不希望智能体因为误解了你的指令就执行rm -rf /*。上面的简单过滤只是第一道防线。在更严肃的场景下你需要使用沙箱环境如Docker容器来运行命令。实现更精细的基于权限的允许列表Allow List只允许运行python,pip,git,npm等特定命令及其安全参数。对用户输入即给智能体的指令进行预处理识别并阻止危险意图。4.3 代码分析与搜索工具可选但强大为了让智能体更“懂”项目我们可以给它增加一些分析能力。# analysis_tools.py import ast from typing import List from langchain.tools import Tool def get_python_file_structure(file_path: str) - str: 分析Python文件提取其中的类、函数定义。 try: with open(file_path, r, encodingutf-8) as f: tree ast.parse(f.read(), filenamefile_path) except Exception as e: return f无法解析Python文件 {file_path}{str(e)} definitions [] for node in ast.walk(tree): if isinstance(node, ast.FunctionDef): args [arg.arg for arg in node.args.args] def_str f函数: {node.name}({, .join(args)}) if node.returns: def_str f - {ast.unparse(node.returns)} definitions.append(def_str) elif isinstance(node, ast.ClassDef): methods [n.name for n in node.body if isinstance(n, ast.FunctionDef)] definitions.append(f类: {node.name} [方法: {, .join(methods)}]) elif isinstance(node, ast.Import): for alias in node.names: definitions.append(f导入: {alias.name}) elif isinstance(node, ast.ImportFrom): module node.module or names , .join([alias.name for alias in node.names]) definitions.append(f从 {module} 导入: {names}) if not definitions: return f文件 {file_path} 中没有找到明显的类或函数定义。 return f文件 {file_path} 的结构概览\n \n.join(definitions) # 这里可以集成更强大的代码搜索比如用ripgrep (rg) 进行全文搜索 # 需要系统安装 ripgrep: pip install subprocess 并调用 rg 命令 def search_in_code(keyword: str, path: str .) - str: 在代码库中搜索包含关键词的文件和行。 # 这是一个简化版实际可以使用 subprocess 调用 grep -r 或 rg import subprocess try: # 使用grep进行简单搜索确保系统有grep cmd fgrep -r -n --include\*.py\ --include\*.js\ --include\*.ts\ \{keyword}\ {path} result subprocess.run(cmd, shellTrue, capture_outputTrue, textTrue, timeout20) if result.stdout: return f在 {path} 中搜索 {keyword} 的结果\n{result.stdout} else: return f在 {path} 中没有找到包含 {keyword} 的代码。 except Exception as e: return f搜索过程中出错{str(e)} analysis_tool Tool( nameanalyze_python_file, funcget_python_file_structure, description分析一个Python文件列出其中的类、函数和导入语句。输入是文件路径。 ) search_tool Tool( namesearch_code, funcsearch_in_code, description在项目代码中搜索指定的关键词。输入是搜索关键词可选第二个参数是搜索路径默认当前目录。 )有了这些工具智能体就能“看到”项目结构“理解”代码关系并“执行”命令了。这构成了它最基础的感知和行动能力。5. 组装你的第一个可工作的编程智能体现在我们把大脑LLM和手脚工具组装起来创建一个真正能处理编程任务的智能体。5.1 创建智能体执行器并集成工具我们将使用LangChain的create_react_agent它基于ReAct框架能让LLM以“思考-行动-观察”的循环来解决问题非常适合需要多步工具调用的场景。# coding_agent.py from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain import hub from dotenv import load_dotenv import os # 导入我们之前定义的工具 from file_tools import read_file_tool, write_file_tool, list_dir_tool from shell_tool import shell_tool from analysis_tools import analysis_tool, search_tool load_dotenv() deepseek_api_key os.getenv(DEEPSEEK_API_KEY) class CodingAgent: def __init__(self): # 1. 初始化模型 self.llm ChatOpenAI( modeldeepseek-chat, openai_api_keydeepseek_api_key, base_urlhttps://api.deepseek.com/v1, temperature0.1, # 可以增加其他参数如请求超时时间 # timeout30, ) # 2. 组合所有工具 self.tools [ read_file_tool, write_file_tool, list_dir_tool, shell_tool, analysis_tool, search_tool, # 未来可以在这里添加更多工具如Git工具、数据库工具等 ] # 3. 从Hub拉取一个针对聊天和工具使用优化的提示词模板 # 你可以自定义这个提示词让它更擅长编程任务 self.prompt hub.pull(hwchase17/react-chat) # 在提示词中注入一些系统指令让智能体更专注于编程 self.prompt.messages[0].prompt.template ( 你是一个专业的AI编程助手。你的目标是帮助用户完成代码编写、文件操作、项目分析等编程任务。 你可以使用工具来读取、写入文件运行命令分析代码结构。 在行动前请先思考你需要做什么以及按什么顺序使用工具。 对于代码修改请先读取相关文件了解现有内容。 对于运行命令请确保命令是安全的。 如果用户的要求模糊请先询问澄清。 请用中文回复。\n\n self.prompt.messages[0].prompt.template ) # 4. 创建智能体和执行器 self.agent create_react_agent(llmself.llm, toolsself.tools, promptself.prompt) self.agent_executor AgentExecutor( agentself.agent, toolsself.tools, verboseTrue, # 设为True可以看到详细的思考过程调试时非常有用 handle_parsing_errorsTrue, # 当LLM输出无法解析为工具调用时尝试让LLM重试 max_iterations10, # 限制最大迭代次数防止死循环 early_stopping_methodgenerate, # 当认为任务完成时可以提前停止 ) def run(self, task: str, chat_history: list None) - str: 执行一个编程任务。 if chat_history is None: chat_history [] try: result self.agent_executor.invoke({ input: task, chat_history: chat_history }) return result[output] except Exception as e: return f智能体执行过程中出现错误{str(e)} # 使用示例 if __name__ __main__: agent CodingAgent() # 测试1让智能体查看当前目录然后创建一个简单的Python文件 print( 测试列出目录并创建文件 ) result agent.run(首先列出当前目录下有什么文件。然后创建一个名为 hello_agent.py 的文件内容是一个打印Hello from AI Agent!的函数并调用它。) print(result) # 测试2让智能体运行它刚刚创建的文件 print(\n 测试运行创建的文件 ) result agent.run(运行刚才创建的 hello_agent.py 文件看看输出是什么。) print(result)运行这个脚本你会看到智能体详细的思考过程verboseTrue。它会先思考“用户要我做什么”然后决定调用list_directory工具观察结果后再决定调用write_file工具并生成合适的JSON参数。最后当你要求它运行时它会调用run_shell_command工具。5.2 设计有效的系统提示词智能体的行为很大程度上受提示词控制。上面代码中我们修改了系统提示词让它更专注于编程。一个更精细的提示词可以包含角色定义明确告诉它“你是一个Python专家”。约束条件例如“不要执行任何破坏性命令”、“修改文件前必须先备份”。输出格式例如“在提供代码时请使用Markdown代码块包裹”。工作流程引导例如“对于任何代码修改请求请遵循1. 读取相关文件 2. 分析问题 3. 提供修改方案或直接修改”。你可以不断迭代提示词观察智能体行为的变化这是优化智能体性能的关键一步。5.3 运行你的智能体并观察其行为运行python coding_agent.py。仔细观察控制台输出的日志。你会看到类似这样的内容 Entering new AgentExecutor chain... 思考用户要求我列出目录并创建文件。我需要先看看当前有什么然后创建一个新的Python文件。 我应该使用list_directory工具。 Action: list_directory Action Input: {input: .} Observation: 目录 . 下的内容 [文件] README.md [目录] venv/ [文件] coding_agent.py ... Thought: 现在我需要创建hello_agent.py文件。我需要使用write_file工具并生成文件内容。 Action: write_file Action Input: {file_path: hello_agent.py, content: def greet():\n print(Hello from AI Agent!)\n\nif __name__ __main__:\n greet()} Observation: 成功内容已覆盖写入文件 hello_agent.py。 Thought: 我已经完成了用户要求的两个步骤。可以结束了。 Final Answer: 已列出当前目录并成功创建了 hello_agent.py 文件其中包含一个打印问候语的函数。这个过程完美展示了ReAct框架Thought(思考) -Action(选择工具并输入) -Observation(工具返回结果) - 循环直到任务完成。6. 实战演练让智能体完成一个真实小任务让我们给智能体一个稍微复杂点的任务检验它的综合能力。任务“在当前目录下检查是否有一个名为requirements.txt的文件。如果没有就创建一个内容包含langchain-openai和python-dotenv。然后使用pip命令检查这两个包是否已安装。”将以下代码添加到coding_agent.py的__main__部分print(\n 实战任务管理依赖文件 ) complex_task 请执行以下任务 1. 检查当前目录下是否存在一个名为 requirements.txt 的文件。 2. 如果不存在则创建它并在文件中写入以下两行内容 langchain-openai python-dotenv 3. 如果文件已存在请读取它的内容并告诉我里面有什么。 4. 最后运行一个pip命令来检查 langchain-openai 这个包是否已经安装在当前环境中。 result agent.run(complex_task) print(result)运行后观察智能体如何拆解这个多步骤任务。一个表现良好的智能体应该调用list_directory或尝试read_file来检查文件是否存在。根据观察结果决定是调用write_file创建文件还是直接返回文件内容。最后调用run_shell_command执行类似pip show langchain-openai或python -c import pkg_resources; print(pkg_resources.get_distribution(langchain-openai))的命令来检查安装情况。这个任务测试了智能体的条件判断、顺序执行和工具组合能力。7. 常见问题、调试技巧与性能优化在实际操作中你肯定会遇到各种问题。这里记录一些我踩过的坑和解决方法。7.1 智能体陷入循环或行为怪异症状智能体反复调用同一个工具或者生成无意义的Action。原因提示词不清晰LLM没有理解任务边界。需要强化提示词中的约束比如“如果你认为任务已经完成请直接给出最终答案。”工具描述不准确工具的描述(description)太模糊或误导了LLM。确保描述清晰说明工具的用途、输入格式和输出示例。max_iterations设置过小或过大太小会导致任务未完成就停止太大会让智能体在死胡同里浪费API调用。解决打开verboseTrue仔细阅读它的“Thought”过程看它在想什么。优化提示词和工具描述。调整AgentExecutor的max_iterations比如设为15和early_stopping_method。7.2 工具调用参数解析错误症状日志中看到Could not parse LLM output: ...错误。原因LLM生成的工具调用参数不是合法的JSON或者缺少必需的字段。解决设置handle_parsing_errorsTrue让执行器尝试要求LLM重试。在工具描述中用非常明确的例子说明输入格式如“输入必须是一个JSON字符串例如{\file_path\: \test.py\, \content\: \print(1)\}”。考虑使用LangChain的StructuredTool它能提供更严格的参数模式验证。7.3 API调用缓慢或超时症状每次智能体思考都要等很久或者请求超时。原因网络问题或模型服务端负载高。ReAct模式每一步都需要调用一次LLM如果步骤多总耗时很长。上下文chat_history过长导致每次请求的token数很多。解决为ChatOpenAI设置timeout参数。使用流式输出虽然不能加快总体速度但可以让用户先看到部分输出体验更好。agent_executor.invoke()返回的是一个字典如果需要流式可以使用agent_executor.stream()。优化上下文管理定期总结或清除过长的历史对话只保留关键信息。考虑更高效的Agent类型create_react_agent是通用但可能较慢的。对于特定领域可以设计更直接的、工具选择更少的智能体流程。7.4 智能体“幻觉”或做出危险操作症状智能体尝试执行rm命令或者修改了不该修改的系统文件。原因LLM本身具有不可预测性且我们的安全限制不够。解决强化工具层面的安全像我们在run_shell_command里做的那样实现命令过滤。对于文件工具可以限制可访问的路径范围如只能在项目目录内操作。在提示词中强调安全在系统指令里明确写出禁止事项。实现“人工确认”环节对于写文件、运行安装或删除命令等高风险操作可以让智能体先输出它计划执行的命令等待用户确认后再实际调用工具。这可以通过设计一个特殊的“确认工具”来实现。7.5 如何扩展更多工具这是智能体能力扩展的核心。假设你想让智能体能操作Git安装Python Git库pip install gitpython创建Git工具函数from git import Repo, GitCommandError def git_status(repo_path: str .) - str: try: repo Repo(repo_path) return repo.git.status() except Exception as e: return fGit操作失败{str(e)} # ... 类似创建 git_add, git_commit, git_push 等函数包装成Tool并添加到self.tools列表里。遵循这个模式你可以集成数据库客户端、HTTP请求库、云服务SDK等打造一个无比强大的智能体。8. 下一步进阶方向与展望至此你已经拥有了一个具备基础感知和行动能力的AI编程智能体。但这仅仅是起点。要让它在实际开发中真正成为得力助手还需要在以下几个方向深耕1. 记忆与上下文管理目前的智能体是“无状态”的每次对话都是新的。你需要为它添加记忆能力让它能记住之前的对话、已经完成的任务、项目特定的约定。这可以通过LangChain的ConversationBufferMemory、ConversationSummaryMemory等组件实现甚至可以将对话历史存入数据库。2. 复杂工作流与LangGraph当任务需要多个智能体协作或者包含复杂的循环、分支判断时例如“持续运行测试直到所有测试通过如果失败则分析日志并尝试修复”AgentExecutor就显得力不从心了。这时需要引入LangGraph它允许你以图Graph的形式定义智能体的工作流精确控制状态转移和节点执行是构建复杂、可靠智能体系统的利器。3. 代码理解与生成的专项优化我们目前使用的通用聊天模型在代码任务上可能不是最优的。可以 *微调提示词提供更多代码示例、约定代码风格如PEP 8。 *使用代码专用模型如Claude Code或者在本地部署CodeLlama等开源代码模型。 *集成代码索引与检索RAG为智能体建立项目代码的向量数据库当需要理解大型项目时可以先检索相关的代码片段再基于此进行生成或修改大大提高准确率。这就是LangChain RAG在编程领域的应用。4. 可视化与交互界面命令行交互不够友好。可以考虑用Gradio或Streamlit快速搭建一个Web界面或者开发一个VSCode插件让智能体深度集成到你的IDE中实现右键菜单、代码块分析、实时建议等功能。5. 评估与持续改进如何衡量智能体的好坏你需要建立一套评估体系例如给定100个编程任务如“修复这个bug”、“实现这个函数”看智能体完成的比例和质量。通过分析失败案例不断优化提示词、工具设计和模型选择。构建AI编程智能体是一个迭代的过程。从今天这个能读文件、写代码、跑命令的“小助手”开始你可以根据自己的需求一点点为它添砖加瓦。最重要的是你亲手搭建了它的核心架构理解了它的运作原理这让你拥有了随时定制和修复它的能力而不是仅仅作为一个神秘黑盒的使用者。在下一篇文章中我们将深入探讨如何为这个智能体添加“记忆”并尝试用LangGraph来构建一个能自主完成多步骤调试任务的更智能体。
)
