1. 什么是 Code AgentCode Agent 是一种以代码理解和生成为核心能力的智能体Agent它能够接收自然语言任务自主规划执行步骤调用代码解释器、命令行、文件系统等工具最终完成代码编写、调试、重构、测试等开发任务。与传统的代码补全工具不同Code Agent 具备任务拆解、工具调用和结果反馈的闭环能力。一个典型的 Code Agent 通常由以下核心模块组成任务理解模块解析用户意图将自然语言转化为可执行的子任务列表。规划模块根据子任务生成执行计划决定调用哪些工具、按什么顺序执行。工具调用模块执行代码、读写文件、运行测试、搜索文档等。反馈与迭代模块根据执行结果调整计划直到任务完成。2. 核心原理与工作流程Code Agent 的工作流程可以概括为「理解—规划—执行—反馈」的循环。下面用一张流程图说明整体架构flowchart TD A[用户输入自然语言任务] -- B[任务理解与拆解] B -- C[生成执行计划] C -- D[调用工具执行] D -- E{执行结果检查} E --|成功| F[输出最终代码与说明] E --|失败| G[分析错误原因] G -- C在实际工程中Code Agent 通常基于大语言模型LLM构建通过函数调用Function Calling机制与外部工具交互。下面是一个简化的工作流程描述用户提交任务例如「写一个 Python 脚本读取 CSV 文件并统计每列均值」。Agent 将任务拆解为读取文件、解析数据、计算均值、输出结果。Agent 依次调用文件读取工具、数据处理工具并检查每一步的返回结果。如果某一步报错Agent 读取错误信息修改代码后重新执行。最终返回可运行的代码和运行结果。3. 环境准备与工具链在开始代码实战之前需要准备以下环境Python 3.9 及以上版本用于编写 Agent 核心逻辑。OpenAI API Key 或其他兼容 LLM 的 API Key用于调用大模型。必要的 Python 库openai、requests、pandas等。首先安装依赖pip install openai pandas requests然后设置环境变量将 API Key 写入本地环境export OPENAI_API_KEYyour-api-key-here4. 实战一构建一个最小可用的 Code Agent下面我们从一个最简单的 Code Agent 开始它能够接收用户指令调用 Python 解释器执行代码并返回执行结果。这个示例不依赖外部框架只使用 OpenAI 的函数调用能力。首先定义工具函数这里我们实现两个工具执行 Python 代码和读取文件内容。import json import subprocess import os def run_python_code(code: str) - str: 在子进程中执行 Python 代码返回标准输出或错误信息。 try: result subprocess.run( [python, -c, code], capture_outputTrue, textTrue, timeout30 ) if result.returncode 0: return result.stdout else: return fError: {result.stderr} except Exception as e: return fException: {str(e)} def read_file(path: str) - str: 读取指定路径的文件内容。 try: with open(path, r, encodingutf-8) as f: return f.read() except Exception as e: return fError: {str(e)}接下来定义工具描述供大模型识别可用的函数tools [ { type: function, function: { name: run_python_code, description: 执行一段 Python 代码并返回输出结果, parameters: { type: object, properties: { code: { type: string, description: 要执行的 Python 代码 } }, required: [code] } } }, { type: function, function: { name: read_file, description: 读取指定路径的文件内容, parameters: { type: object, properties: { path: { type: string, description: 文件路径 } }, required: [path] } } } ]然后实现 Agent 主循环。核心思路是将用户消息和工具定义发送给模型如果模型返回工具调用请求就执行对应函数并把结果回传给模型直到模型给出最终回答。from openai import OpenAI client OpenAI() def call_agent(user_input: str, max_rounds: int 5) - str: 运行 Code Agent 主循环。 messages [{role: user, content: user_input}] for _ in range(max_rounds): response client.chat.completions.create( modelgpt-4o, messagesmessages, toolstools, tool_choiceauto ) msg response.choices[0].message 如果没有工具调用说明 Agent 已给出最终答案 if not msg.tool_calls: return msg.content 将助手消息加入对话 messages.append(msg) 逐个执行工具调用 for tool_call in msg.tool_calls: fn_name tool_call.function.name fn_args json.loads(tool_call.function.arguments) if fn_name run_python_code: result run_python_code(fn_args[code]) elif fn_name read_file: result read_file(fn_args[path]) else: result fUnknown tool: {fn_name} 将工具执行结果回传给模型 messages.append({ role: tool, tool_call_id: tool_call.id, content: result }) return 达到最大轮数任务未完成。最后测试一下这个最小 Agentif __name__ __main__: task 请写一段 Python 代码计算 1 到 100 之间所有偶数的和并输出结果。 answer call_agent(task) print(answer)运行后Agent 会生成代码、调用run_python_code执行并把计算结果返回给用户。这个示例虽然简单但已经具备了 Code Agent 的核心闭环理解任务、调用工具、反馈迭代。5. 实战二带记忆与多轮对话的 Code Agent实际开发中用户往往需要多轮交互例如先让 Agent 读取项目结构再根据结构生成代码。这就要求 Agent 具备「记忆」能力能够记住之前的对话和工具执行结果。实现方式很简单在messages列表中持续追加历史消息即可。下面我们扩展上面的 Agent让它支持连续对话并增加一个「列出目录文件」的工具。import os def list_directory(path: str .) - str: 列出指定目录下的所有文件和文件夹。 try: items os.listdir(path) return \n.join(items) except Exception as e: return fError: {str(e)}将新工具加入tools列表tools.append({ type: function, function: { name: list_directory, description: 列出指定目录下的所有文件和文件夹, parameters: { type: object, properties: { path: { type: string, description: 目录路径默认为当前目录 } } } } })然后改造主循环使其支持多轮对话。这里我们把messages提升为会话级变量每次用户输入后追加到历史中class CodeAgentSession: 支持多轮对话的 Code Agent。 def __init__(self): self.messages [] self.tools tools def send(self, user_input: str, max_rounds: int 5) -gt; str: 发送用户消息并返回 Agent 回复。 self.messages.append({role: user, content: user_input}) for _ in range(max_rounds): response client.chat.completions.create( modelgpt-4o, messagesself.messages, toolsself.tools, tool_choiceauto ) msg response.choices[0].message if not msg.tool_calls: self.messages.append(msg) return msg.content self.messages.append(msg) for tool_call in msg.tool_calls: fn_name tool_call.function.name fn_args json.loads(tool_call.function.arguments) if fn_name run_python_code: result run_python_code(fn_args[code]) elif fn_name read_file: result read_file(fn_args[path]) elif fn_name list_directory: result list_directory(fn_args.get(path, .)) else: result fUnknown tool: {fn_name} self.messages.append({ role: tool, tool_call_id: tool_call.id, content: result }) return 达到最大轮数任务未完成。/code/pre 测试多轮对话 session CodeAgentSession() 第一轮查看当前目录 print(session.send(请列出当前目录下的所有文件。)) 第二轮基于第一轮结果继续提问 print(session.send(请读取其中第一个 Python 文件的内容并解释它的功能。)) 由于 messages 保留了全部历史Agent 能够记住第一轮列出的文件名并在第二轮直接读取对应文件。这就是多轮记忆的基本实现。 6. 实战三接入本地代码库的 Agent 真实场景中Code Agent 需要理解整个项目的代码结构。下面我们实现一个简单的「项目感知」Agent它先扫描项目目录建立文件索引然后根据用户问题检索相关文件并生成回答。 首先实现项目扫描与索引构建 import os from pathlib import Path def build_project_index(root_dir: str) - dict: 递归扫描项目目录返回文件路径到内容的映射。 index {} for dirpath, dirnames, filenames in os.walk(root_dir): 跳过隐藏目录和常见依赖目录 dirnames[:] [d for d in dirnames if not d.startswith(.) and d not in (node_modules, pycache, venv)] for filename in filenames: if filename.endswith((.py, .js, .ts, .java, .md, .txt)): file_path os.path.join(dirpath, filename) try: with open(file_path, r, encodingutf-8) as f: index[file_path] f.read() except Exception: pass return index 然后实现简单的关键词检索从索引中找出与问题最相关的文件 def search_index(index: dict, query: str, top_k: int 3) - list: 根据关键词返回最相关的文件路径列表。 keywords query.lower().split() scored [] for path, content in index.items(): score 0 content_lower content.lower() for kw in keywords: if kw in path.lower(): score 3 if kw in content_lower: score 1 if score gt; 0: scored.append((score, path)) scored.sort(reverseTrue) return [path for _, path in scored[:top_k]] 最后把检索结果注入提示词让 Agent 基于真实代码回答问题 def ask_project_question(project_dir: str, question: str) - str: 基于项目代码回答用户问题。 index build_project_index(project_dir) related_files search_index(index, question) context_parts [] for path in related_files: context_parts.append(f### 文件: {path}\n\n{index[path][:2000]}\n) context \n\n.join(context_parts) prompt f请根据以下项目代码回答用户问题。 项目相关文件 {context} 用户问题{question} 请结合代码给出准确、详细的回答。 response client.chat.completions.create( modelgpt-4o, messages[{role: user, content: prompt}] ) return response.choices[0].message.content 测试一下 if name main: answer ask_project_question( project_dir./my_project, question这个项目里是如何处理用户登录的 ) print(answer) 这个示例展示了 Code Agent 接入本地代码库的基本思路先建立索引再检索相关代码最后让模型基于真实代码生成回答。更复杂的实现可以引入向量数据库和语义检索这里不再展开。 7. 实战四自动修复代码错误的 Agent Code Agent 的一个重要应用场景是自动修复代码错误。下面我们实现一个「调试 Agent」它接收一段有问题的代码运行后读取报错信息再让模型分析错误并生成修复后的代码。 首先实现一个函数用于执行代码并捕获错误 def run_and_capture(code: str) - dict: 执行代码返回输出和错误信息。 try: result subprocess.run( [python, -c, code], capture_outputTrue, textTrue, timeout30 ) return { stdout: result.stdout, stderr: result.stderr, returncode: result.returncode } except Exception as e: return {stdout: , stderr: str(e), returncode: -1} 然后实现调试主流程 def debug_code(buggy_code: str, max_iterations: int 3) - str: 自动修复代码错误返回修复后的代码。 current_code buggy_code for i in range(max_iterations): result run_and_capture(current_code) 如果运行成功直接返回 if result[returncode] 0: return current_code error_info result[stderr] prompt f以下代码运行出错请分析错误原因并给出修复后的完整代码。 代码 {current_code} 错误信息 {error_info} 请只输出修复后的完整 Python 代码不要输出解释。 response client.chat.completions.create( modelgpt-4o, messages[{role: user, content: prompt}] ) fixed_code response.choices[0].message.content 清理模型输出中的代码块标记 fixed_code fixed_code.replace(python, ).replace(, ).strip() current_code fixed_code return current_code 测试自动修复功能 buggy def divide_list(nums): result [] for i in range(len(nums)): result.append(nums[i] / (i - 1)) return result print(divide_list([10, 20, 30, 40])) fixed debug_code(buggy) print(修复后的代码) print(fixed) print(\n执行结果) print(run_and_capture(fixed)[stdout]) 原始代码在 i 1 时会触发除零错误调试 Agent 会读取错误信息分析原因并生成修复后的代码。这个流程可以扩展到更复杂的场景例如修复语法错误、逻辑错误甚至重构代码。 8. 进阶方向与最佳实践 以上四个实战示例覆盖了 Code Agent 的核心能力工具调用、多轮记忆、项目感知和自动调试。在实际工程中还可以从以下方向继续深入 引入向量检索用 Embedding 模型对代码建立向量索引实现语义级代码检索提升大项目中的定位准确率。 支持更多工具接入 Git 操作、数据库查询、Docker 容器、API 调用等让 Agent 具备更广泛的执行能力。 增加安全沙箱在隔离环境中执行 Agent 生成的代码防止恶意操作或误删文件。 任务规划与子 Agent将复杂任务拆分为多个子任务由多个专用 Agent 并行处理最后汇总结果。 人工审核机制在关键操作如删除文件、修改生产代码前加入人工确认环节提升安全性。 在工程落地时建议遵循以下最佳实践 始终为工具调用设置超时时间避免 Agent 卡死在某个操作上。 对工具执行结果做长度截断防止上下文窗口被大量输出占满。 记录完整的对话和工具调用日志便于问题排查和效果评估。 为不同任务设计不同的系统提示词提升 Agent 在特定场景下的表现。 先用小规模测试集验证 Agent 效果再逐步扩大应用范围。 9. 总结 本文从原理到代码实战系统介绍了 Code Agent 的构建方法。我们从最小可用的 Agent 出发逐步实现了多轮对话记忆、项目代码感知和自动错误修复覆盖了 Code Agent 开发中最核心的几类能力。 Code Agent 的本质是「大模型 工具 反馈循环」。只要掌握了任务拆解、工具调用和结果迭代这三个关键环节就能构建出满足实际需求的代码智能体。希望本文的示例代码能够帮助你快速上手并在自己的项目中落地应用。
