从零构建一个 AI 代码 Agent：自然语言生成 Python 代码、安全执行与自动纠错
从零开始实现和了解一个极简但功能完整的 AI 代码 Agent 框架——code-agent-demo。不到 500 行核心代码，却涵盖了 LLM 调用、安全沙盒、自动改进循环、历史管理、CLI 交互等所有关键环节。
一、它能做什么？
直接上图不够直观，我们用命令行来感受一下：
> /run 用 matplotlib 画一个 sin(x) 和 cos(x) 的对比图，加上图例和标题
[Agent] Generating code for: 用 matplotlib 画一个 sin(x) 和 cos(x) 的对比图...
[Agent] Code generated (847 chars)
[Agent] Executing code...
[Agent] Execution succeeded.
[Agent] === Task completed successfully ===
这就是一次典型的交互：输入自然语言 → LLM 生成代码 → 沙盒安全执行 → 输出结果。
如果代码运行失败了怎么办？框架会自动进入改进循环：
[Agent] Generating code for: 实现一个快速排序算法...
[Agent] Execution failed: NameError: name 'quicksort' is not defined
[Agent] --- Improvement attempt 1/3 ---
[Agent] Improving code based on error...
[Agent] Code improved (v2, 523 chars)
[Agent] Execution succeeded.
[Agent] === Task completed successfully ===
LLM 生成了有 bug 的代码，Agent 自动把错误信息喂回给 LLM，让它修复后再执行——全程无需人工干预。
二、架构设计：四个抽象接口 + 一个编排核心
整个项目遵循「面向接口编程」的思想，核心架构非常清晰：
┌────────────────────────────────────────────┐
│ main.py (CLI 入口) │
└───────────────────┬────────────────────────┘
│
┌───────────────────▼────────────────────────┐
│ Agent (core.py) │
│ generate() → execute() → improve() │
│ ↑ ↑ ↑ │
│ ┌────┴────┐ ┌───┴────┐ ┌────┴─────┐ │
│ │ BaseLLM │ │BaseExec│ │ BaseTool │ │
│ └────┬────┘ └───┬────┘ └────┬─────┘ │
└─────────┼──────────┼───────────┼───────────┘
│ │ │
┌─────▼─────┐ ┌──▼───────┐ ┌▼───────────┐
│ OpenAI │ │ Sandbox │ │ 可扩展... │
│ Provider │ │ Executor │ │ │
└───────────┘ └──────────┘ └─────────────┘
2.1 四个抽象接口
BaseLLM — LLM 抽象层，定义三个核心方法：
class BaseLLM(ABC):
def chat(self, messages: list[dict]) -> LLMResponse: ...
def generate_code(self, requirement: str, context: str = None) -> LLMResponse: ...
def improve_code(self, original_code: str, error_message: str, requirement: str) -> LLMResponse: ...
目前提供了 OpenAI 的实现，但因为是抽象接口，你可以无缝切换成 Claude、本地 Llama、通义千问等任何模型。
BaseExecutor — 代码执行器抽象：
class BaseExecutor(ABC):
def execute(self, code: str) -> ExecutionResult: ...
返回统一的 ExecutionResult，包含 success、stdout、stderr、exit_code 等字段。
BaseTool — 工具接口（预留扩展点），支持 Agent 调用外部工具。
HistoryManager — 历史管理器，记录每次生成和改进，支持 JSON 持久化。
2.2 核心编排引擎
Agent 类是大脑，串联起整个工作流。最核心的方法是 run()：
def run(self, requirement: str) -> ExecutionResult:
# 1. 生成代码
code = self.generate(requirement)
# 2. 执行代码
result = self.execute(code)
# 3. 失败则自动改进
for attempt in range(self.config.max_retries):
if result.success:
break
improved = self.improve(result.error_message)
result = self.execute(improved)
return result
就这么简洁——「生成 → 执行 → 改进」的循环构成了 Agent 的完整心智模型。
三、安全沙盒：不只是 subprocess
执行 AI 生成的代码最大的风险是什么？是安全问题。LLM 可能会生成 import os; os.system("rm -rf /") 这样的危险代码。
code-agent 采用了双重防护机制：
第一层：导入拦截 Hook
在用户代码执行前，注入一段 Hook 代码，劫持 __import__ 函数：
RESTRICTED_IMPORTS = {"os.system", "subprocess", "shutil", "socket", "requests", "urllib"}
def _safe_import(name, *args, **kwargs):
for restricted in RESTRICTED:
if name == restricted or name.startswith(restricted + '.'):
raise ImportError("Import is not allowed in sandbox")
return _original_import(name, *args, **kwargs)
_builtins.__import__ = _safe_import
任何被列入黑名单的模块，直接抛出 ImportError。
第二层：禁用危险内置函数
for func in ("exec", "eval", "compile", "open", "breakpoint", "__import__"):
_builtins.__dict__[func] = _blocked
exec()、eval()、open() 等函数全部被封堵。
第三层：子进程隔离
在子进程中运行用户代码，限制超时时间，捕获 stdout 和 stderr。即使沙盒 Hook 被绕过，最多也只能影响子进程，不会波及主进程。
四、代码风格：追求可读性的 Python
整个项目刻意保持极简风格，尽量使用 Python 原生特性：
- dataclass 替代普通类，减少样板代码
- 类型注解 全覆盖，配合 IDE 有完整的智能提示
- 抽象基类（ABC） 定义接口契约
- YAML + 环境变量 管理配置，
${OPENAI_API_KEY}自动展开 - 零框架依赖，只依赖
openai和pyyaml
项目文件结构一目了然：
code-agent/
├── agent/
│ ├── core.py # Agent 核心编排引擎
│ ├── llm/ # LLM 抽象层 + OpenAI 实现
│ ├── executor/ # 执行器抽象层 + 沙盒实现
│ ├── tools/ # 工具接口（扩展预留）
│ └── history/ # 历史记录管理
├── main.py # CLI 交互入口
├── config.yaml # 配置文件
├── requirements.txt # 依赖
└── test_agent.py # 单元测试 + 集成测试
五、实战：5 分钟跑起来
第 1 步：安装依赖
pip install -r requirements.txt
第 2 步：配置 LLM
编辑 config.yaml：
llm:
model: gpt-4o-mini
api_key: ${OPENAI_API_KEY} # 自动从环境变量读取
base_url: null # 或填 http://localhost:1234/v1 用本地模型
支持 OpenAI 官方 API 和 LM Studio 等本地推理服务。
第 3 步：启动 CLI
python main.py
你会看到一个交互式命令行：
Commands:
/generate <requirement> - 生成代码
/run <requirement> - 生成并执行（含自动改进）
/execute - 执行上次生成的代码
/improve - 基于上次错误改进代码
/show - 查看当前代码
/history - 查看会话历史
/save <filename> - 保存代码到文件
/exit - 退出
第 4 步：试试这些提示词
/run 生成 100 个随机数，计算均值和标准差
/run 写一个装饰器，测量任意函数的执行时间
/run 实现一个简单的 LRU 缓存类
六、为什么这个项目值得关注？
-
学习的绝佳起点：如果你对 AI Agent 感兴趣但不知从何入手，这个项目的 500 行核心代码是最好的教材。它剥离了所有不必要的复杂度，只保留 Agent 的骨架。
-
高度的可扩展性：想接入 Claude？实现一个
ClaudeProvider(BaseLLM)即可。想用 Docker 执行代码？实现一个DockerExecutor(BaseExecutor)。想接入搜索引擎？实现一个SearchTool(BaseTool)。每个模块都是可插拔的。 -
扎实的安全防护：三层沙盒机制，多一层保障就少一分风险。这在 AI 生成代码自动执行的场景中至关重要。
-
完整的工程实践：从抽象接口到具体实现，从单元测试到集成测试，从配置管理到 CLI 设计，这是一个麻雀虽小五脏俱全的 Python 项目。
七、未来展望(一些规划中的方向,大概率实现不了,只是作为学习的起点)
- 工具链扩展：文件读写、HTTP 请求、数据库查询等标准工具
- 多轮对话记忆：让 Agent 记住之前的上下文，支持更复杂的任务拆解
八、总结
code-agent 用不到 500 行代码，展示了 AI Agent 的核心工作流：理解需求 → 生成代码 → 安全执行 → 错误自愈。它不是一个庞然大物，但胜在清晰、可扩展、能跑通——这正好是学习和上手 AI Agent 开发的最佳状态。
如果你也在做 AI Agent 相关的项目，或者对这篇文章有任何想法，欢迎在评论区交流！
