Code-Act框架：让AI通过代码生成与执行实现智能体“动手”能力

1. 项目概述：Code-Act，一个让AI“动手”的智能体框架

最近在AI智能体这个圈子里，一个叫“Code-Act”的项目热度挺高。它不是一个具体的应用，而是一个框架，一个旨在解决当前AI智能体“眼高手低”问题的底层工具。简单来说，Code-Act的核心目标，是让大语言模型（LLM）驱动的智能体，不仅能“想”，更能“做”——通过生成和执行代码，来操作计算机环境，完成真实世界的任务。

想象一下，你给AI一个指令：“帮我把桌面上的所有截图整理到一个叫‘截图归档’的文件夹里，并按日期创建子文件夹。” 一个传统的聊天机器人可能会回复你一个操作步骤列表。但一个基于Code-Act构建的智能体，会直接生成一段Python脚本，调用操作系统的文件系统接口，自动完成所有文件的扫描、分类、移动和重命名。这就是“代码即行动”的直观体现。这个项目之所以吸引我，是因为它直击了智能体落地的痛点：如何将LLM强大的理解和规划能力，无缝、安全、可靠地转化为对数字世界的具体操作。它不是为了替代程序员，而是为AI赋予了一种更通用、更精确的“动手能力”。

这个框架适合谁呢？首先，是AI智能体的研究者和开发者。如果你正在构建需要与环境交互的智能体，比如自动化办公助手、软件测试机器人、数据分析流水线调度器，Code-Act提供了一个标准化的“行动”接口和评估基准。其次，是希望将AI能力深度集成到现有工作流中的工程师。通过Code-Act，你可以将复杂的、需要多步骤操作的任务，封装成一个简单的自然语言指令。最后，对于AI爱好者而言，这也是一个绝佳的观察窗口，可以直观地看到当前最前沿的模型（如GPT-4、Claude-3）在代码生成与执行任务上的实际能力边界。

2. 核心设计理念与架构拆解

Code-Act这个名字本身就揭示了它的设计哲学：Code as Action，即“代码即行动”。这背后是对智能体行动范式的一次重要抽象和统一。

2.1 为什么是“代码”？

在智能体与环境的交互中，行动（Action）可以有多种形式：调用一个预设的API函数、发送一个键盘鼠标指令、在图形界面上点击一个按钮。但这些方式都存在局限性。API需要预先定义，扩展性差；模拟键鼠操作脆弱且依赖特定UI。而代码，作为一种通用、精确、可组合的指令集，具有独特的优势：

1. 表达能力强：几乎任何复杂的逻辑和操作都可以通过代码（尤其是Python）来描述。
2. 环境通用：只要目标环境支持某种语言的解释器（如Python、JavaScript），代码就能运行，无需为每个环境定制专用的行动接口。
3. 可验证与可调试：生成的代码可以被静态分析（检查语法、安全）、动态执行并观察结果，这为评估智能体的“行动”质量提供了客观标准。
4. 易于学习：LLM在代码数据上进行了海量训练，它们非常擅长生成和解释代码。让LLM写代码来完成任务，比让它直接输出一串晦涩的底层操作指令要自然得多。

因此，Code-Act选择将“生成一段代码”作为智能体的核心行动。智能体观察环境（例如，当前的屏幕信息、文件列表、应用程序状态），思考任务，然后输出一段旨在改变环境的代码。一个独立的“执行器”模块会安全地运行这段代码，并将结果（成功、失败、输出内容）返回给智能体，作为下一轮观察和决策的依据。

2.2 核心架构组件

一个典型的基于Code-Act的智能体系统包含以下几个关键部分，我们可以将其类比为一个“数字机器人”的感官、大脑和手脚：

1. 环境（Environment）：这是智能体操作的对象，可以是一个虚拟的桌面环境、一个浏览器会话、一个命令行终端，或者一个特定的软件（如IDE、Excel）。环境需要提供状态观察接口（如截图、当前目录列表、活动窗口标题）和代码执行沙箱。
2. 智能体（Agent）：其核心是一个LLM（如GPT-4）。它的输入是任务描述、环境观察历史、以及之前行动（代码）的执行结果。它的输出是一段代码（行动），有时还会附带一段解释（推理过程）。
3. 代码执行器（Code Executor）：这是安全性的关键。它运行智能体生成的代码，但必须在一个受控的“沙箱”中。这个沙箱会限制危险操作（如删除系统文件、访问网络），并捕获代码的标准输出、错误信息以及执行后的环境状态变化。
4. 评估与基准测试套件（Benchmark）：这是Code-Act项目的一大贡献。它定义了一系列真实世界任务（如“在文本编辑器中新建文件并写入特定内容”、“从网页表格中提取数据到CSV”），并为每个任务提供了清晰的完成标准。这允许研究者客观地比较不同LLM或不同提示策略下智能体的性能。

这种架构的优势在于解耦。智能体模型可以独立升级（从GPT-3.5到GPT-4），环境可以更换（从模拟桌面到真实远程桌面），而核心的“代码-行动”循环保持不变。这极大地提高了框架的灵活性和可扩展性。

注意：安全性是Code-Act设计的重中之重。在真实部署中，代码执行器必须运行在高度隔离的容器或虚拟机中，并且要有严格的权限控制和操作审计。绝不能允许未经审查的AI代码在具有重要数据或权限的生产环境中直接运行。

3. 实操演练：构建一个简易的文件管理智能体

理论讲得再多，不如亲手实现一个。下面，我将带你一步步构建一个运行在本地的、简易版的Code-Act智能体，用于完成基本的文件管理任务。我们将使用Python作为主要语言，并假设你具备基础的Python编程知识。

3.1 环境准备与依赖安装

首先，我们需要创建一个干净的Python虚拟环境，并安装核心依赖。这里我们使用openai库来调用GPT模型（你也可以替换为其他兼容OpenAI API的模型服务），以及一些用于系统交互的库。

# 创建并激活虚拟环境 python -m venv code_act_env source code_act_env/bin/activate # Linux/macOS # 或 code_act_env\Scripts\activate # Windows # 安装核心库 pip install openai python-dotenv

接下来，你需要准备一个OpenAI API密钥。如果你没有，需要去OpenAI官网注册获取。为了安全，我们将密钥存储在环境变量中。

创建一个名为.env的文件，内容如下：

OPENAI_API_KEY=你的_api_key_here

然后，创建一个simple_code_act.py文件，开始编写我们的智能体。

3.2 核心智能体循环实现

智能体的核心是一个循环：观察 -> 思考（生成代码）-> 行动（执行代码）-> 观察结果 -> 判断是否完成。我们先来实现这个循环的骨架。

import os import subprocess import sys from typing import Dict, Any import openai from dotenv import load_dotenv # 加载环境变量 load_dotenv() openai.api_key = os.getenv('OPENAI_API_KEY') class SimpleCodeActAgent: def __init__(self, model="gpt-4"): self.model = model self.conversation_history = [] # 保存对话和观察历史 def observe_environment(self, task_description: str) -> str: """ 模拟环境观察。在实际项目中，这里可能会返回屏幕截图描述、文件列表等。 我们这里简化，返回当前工作目录的文件列表作为初始观察。 """ try: # 获取当前目录列表 result = subprocess.run(['ls', '-la'], capture_output=True, text=True, shell=False) current_dir_listing = result.stdout except Exception as e: current_dir_listing = f"Error observing directory: {e}" observation = f""" 任务描述：{task_description} 当前环境观察（工作目录）： {current_dir_listing} """ return observation def think_and_generate_code(self, observation: str) -> str: """ 调用LLM，基于观察生成下一步要执行的代码。 我们设计一个特定的提示词（Prompt）来引导模型。 """ system_prompt = """你是一个帮助用户操作计算机文件的智能助手。你的行动方式是生成一段Python代码来完成任务。 生成的代码必须： 1. 只使用Python标准库（如os, shutil, pathlib, datetime等）。 2. 绝对不要执行任何危险操作（如`os.system('rm -rf /')`）。 3. 代码应该是一个完整的、可独立运行的代码块。 4. 代码的目标是改变文件系统状态以逐步接近任务目标。 5. 在代码最后，打印出关键的操作结果。 请根据用户提供的任务描述和当前环境观察，生成合适的Python代码。只输出代码，不要输出任何其他解释。""" user_prompt = f"{observation}\n\n请生成完成上述任务的Python代码：" try: response = openai.ChatCompletion.create( model=self.model, messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt} ], temperature=0.2, # 低温度，让输出更确定、更偏向代码 max_tokens=1500 ) generated_code = response.choices[0].message.content.strip() # 清理可能出现的markdown代码块标记 if generated_code.startswith('```python'): generated_code = generated_code[9:] if generated_code.startswith('```'): generated_code = generated_code[3:] if generated_code.endswith('```'): generated_code = generated_code[:-3] return generated_code.strip() except Exception as e: print(f"调用LLM生成代码失败: {e}") return "" def execute_code(self, code: str) -> Dict[str, Any]: """ 在一个相对安全的环境中执行生成的代码。 注意：这只是一个简易演示，不具备真正的沙箱安全性！ 生产环境必须使用Docker容器或更严格的隔离机制。 """ result = {"success": False, "output": "", "error": ""} # 创建一个临时文件来存放代码 import tempfile with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f: f.write(code) temp_file_path = f.name try: # 在新进程中执行代码，并捕获输出 process = subprocess.run( [sys.executable, temp_file_path], capture_output=True, text=True, timeout=30, # 设置超时，防止无限循环 cwd=os.getcwd() # 在当前工作目录执行 ) result['output'] = process.stdout if process.stderr: result['error'] = process.stderr result['success'] = (process.returncode == 0) except subprocess.TimeoutExpired: result['error'] = "代码执行超时（超过30秒）。" except Exception as e: result['error'] = f"执行过程异常: {e}" finally: # 清理临时文件 os.unlink(temp_file_path) return result def run(self, task: str, max_steps=5): """运行智能体主循环""" print(f"开始执行任务: {task}") current_observation = self.observe_environment(task) print(f"初始观察:\n{current_observation[:500]}...") # 打印部分观察 for step in range(max_steps): print(f"\n--- 第 {step+1} 步 ---") # 生成代码 code = self.think_and_generate_code(current_observation) if not code: print("未能生成有效代码，终止。") break print(f"生成的代码:\n```python\n{code}\n```") # 执行代码 execution_result = self.execute_code(code) print(f"执行结果 - 成功: {execution_result['success']}") if execution_result['output']: print(f"输出:\n{execution_result['output']}") if execution_result['error']: print(f"错误:\n{execution_result['error']}") # 构建新的观察（简化版：将执行结果作为新观察的一部分） new_observation = f""" 上一步执行结果： 成功：{execution_result['success']} 输出：{execution_result['output']} 错误：{execution_result['error']} 当前环境观察（工作目录）： {subprocess.run(['ls', '-la'], capture_output=True, text=True).stdout} 原始任务描述：{task} """ current_observation = new_observation # 简单判断任务是否可能完成（例如，检查输出中是否有成功完成的信号） # 这里只是一个示例，真实判断需要更复杂的逻辑或由LLM判断。 if "任务完成" in execution_result['output'] or step == max_steps - 1: print(f"\n任务循环结束（达到最大步数或检测到完成信号）。") break if __name__ == "__main__": agent = SimpleCodeActAgent(model="gpt-4") # 可根据情况使用gpt-3.5-turbo # 尝试一个简单任务 task = "在当前目录下创建一个名为‘test_archive’的文件夹，然后列出目录内容确认。" agent.run(task)

这个简易实现包含了Code-Act的核心循环。observe_environment模拟了环境观察（这里只是目录列表），think_and_generate_code调用GPT-4生成代码，execute_code则尝试运行生成的代码并捕获结果。

3.3 提示词工程与代码生成优化

智能体的表现极大程度上依赖于给LLM的提示词（Prompt）。上面的system_prompt是一个基础版本。在实际应用中，我们需要不断优化它以提高代码的准确性、安全性和任务完成率。

优化方向1：增加上下文和示例（Few-Shot Learning）在system_prompt中提供一两个例子，能显著提升模型生成代码的格式和逻辑。

enhanced_system_prompt = """你是一个帮助用户操作计算机文件的智能助手。你的行动方式是生成一段Python代码来完成任务。 示例1： 任务：在桌面创建一个名为“笔记”的文件夹。 观察：当前桌面有文件A.txt, 图片B.jpg。 代码： ```python import os desktop_path = os.path.join(os.path.expanduser('~'), 'Desktop') new_folder = os.path.join(desktop_path, '笔记') os.makedirs(new_folder, exist_ok=True) print(f"文件夹创建成功：{new_folder}")

示例2： 任务：找出当前目录下所有扩展名为.txt的文件，并打印它们的文件名。 观察：当前目录有 a.txt, b.jpg, c.txt。 代码：

import os txt_files = [f for f in os.listdir('.') if f.endswith('.txt')] print("找到的文本文件：") for f in txt_files: print(f)

请遵循以下规则：

1. 只使用Python标准库。
2. 代码必须安全，避免删除或修改未指定的文件。
3. 输出清晰的结果信息。
4. 根据观察和任务生成代码。

现在，请根据以下观察和任务生成代码："""

**优化方向2：引导模型进行推理（Chain-of-Thought）** 要求模型在生成代码前，先以注释的形式写出思考步骤，这能让生成的代码逻辑更清晰，也便于我们调试。 ```python reasoning_prompt = """请先以#注释的形式，简要分析任务目标和当前环境，规划实现步骤。然后，生成实现上述步骤的Python代码。"""

在解析模型回复时，我们需要分离出注释部分和可执行代码部分。

优化方向3：增加安全约束在提示词中明确禁止某些操作，并建议使用更安全的替代方案。例如：

• “禁止使用os.system或subprocess调用shell命令，除非绝对必要。”
• “操作文件前，先检查路径是否存在。”
• “使用shutil.move而非os.rename以处理跨设备移动。”

实操心得：提示词优化是一个迭代过程。最好的方法是准备一个小型测试任务集，然后批量运行，统计任务成功率，并分析失败案例中模型生成的代码问题，针对性地修改提示词。例如，如果发现模型经常尝试删除文件，就在提示词中强调“未经用户明确许可，不要删除任何文件”。

4. 从演示到实用：关键挑战与解决方案

将上述演示代码转化为一个真正可用的系统，我们面临着几个核心挑战。解决这些挑战的过程，正是深入理解Code-Act价值所在。

4.1 环境观察的丰富性与表示

我们的演示只观察了文件列表。一个实用的智能体需要更丰富的环境状态。例如，对于“整理我的桌面”这个任务，智能体需要知道桌面上有哪些文件、它们的图标位置、甚至可能的内容预览。

解决方案：

• 屏幕捕捉与OCR：使用pyautogui截图，结合pytesseract进行OCR识别，获取屏幕上的文字信息。这对于操作图形界面软件（如资源管理器）是必要的。
• 可访问性API：在Windows上可以使用pywin32调用UI Automation API，在macOS上可以使用pyobjc调用Accessibility API。这能获取到窗口标题、按钮状态等结构化信息，比纯图像分析更可靠。
• 特定应用接口：对于目标软件（如Chrome浏览器），可以使用selenium或pyppeteer来获取DOM状态；对于IDE，可能提供专门的插件或LSP接口。

代码示例（简化版屏幕观察）：

import pyautogui from PIL import Image import io def get_screen_observation(): """获取屏幕截图并生成简化的文本描述（实际应用需接入视觉模型）""" screenshot = pyautogui.screenshot() # 此处简化处理，实际应接入GPT-4V或本地VLM模型描述图片 # 例如：image_bytes = io.BytesIO(); screenshot.save(image_bytes, format='PNG') # 调用多模态模型API分析image_bytes observation = "屏幕截图已捕获（此处应接入视觉模型生成描述）。" return observation

关键在于，需要将多模态的观察（图像、文本、结构化数据）整合成一个LLM能够理解的文本描述，作为下一轮“思考”的输入。

4.2 代码执行的安全沙箱

在我们的演示中，execute_code函数是极不安全的。它允许生成的代码执行任意Python代码，这在实际使用中是灾难性的。

解决方案：

• 使用Docker容器：这是最推荐的方式。每个任务会话在一个全新的、轻量级的Docker容器中启动。容器内只包含任务所需的最小化运行环境（如Python、必要的库）。任务结束后，容器立即销毁。这确保了环境的隔离性和状态的可重置性。
• 使用操作系统级别的沙箱：如seccomp、AppArmor或Sandboxie，可以限制进程的系统调用和文件访问范围。但这通常比Docker更复杂。
• 代码静态分析与过滤：在执行前，对生成的代码进行简单的静态分析，过滤掉明显危险的模块导入（如os.system,subprocess.Popen,shutil.rmtree）或敏感函数调用。但这是一种补充手段，不能替代运行时隔离。

一个基于Docker的简易安全执行器思路：

import docker class DockerCodeExecutor: def __init__(self): self.client = docker.from_env() self.image_name = "python:3.9-slim" # 基础镜像 def execute_in_container(self, code: str, input_files=None): # 1. 创建临时目录，写入代码文件 # 2. 使用docker SDK启动一个临时容器，挂载代码目录 # 3. 在容器内运行代码，并设置资源限制（CPU，内存） # 4. 捕获容器的输出和错误流 # 5. 无论成功与否，停止并删除容器 # 6. 返回执行结果 pass

使用Docker可以确保即使AI生成了rm -rf /这样的恶意代码，也只会影响容器内部，宿主机完全无损。

4.3 任务规划与长期记忆

我们的演示是单步的，模型基于当前观察生成代码。但复杂任务需要多步规划。例如，“下载一封邮件附件，用Excel打开，提取第二列数据，生成图表并保存”涉及多个软件和步骤。

解决方案：

• ReAct（Reasoning + Acting）模式：要求LLM在每一步不仅输出行动（代码），还输出一个“思考（Thought）”。这个思考是对当前状况的分析和下一步计划的简述。我们将这个思考也存入历史，作为后续决策的上下文。这能帮助智能体保持任务主线。
• 向量数据库存储历史：对于非常长的对话和行动历史，可以将历史观察、行动和结果转换成向量，存入如ChromaDB或FAISS中。当需要决策时，检索最相关的历史片段作为上下文，避免超过模型的令牌限制。
• 高层次任务分解：在开始执行具体代码前，先让LLM做一个高层次的任务分解计划。例如，先输出一个JSON格式的计划：[{"step": 1, "goal": "定位并下载邮件附件"}, {"step": 2, "goal": "用pandas读取Excel文件"}, ...]。然后智能体再逐步执行每个子目标。

5. 常见问题与调试技巧实录

在实际开发和测试Code-Act类智能体的过程中，我踩过不少坑。这里总结几个最常见的问题和解决思路，希望能帮你节省时间。

5.1 生成的代码语法错误或无法运行

这是初期最常见的问题。LLM生成的代码有时会有缩进错误、拼写错误的变量名或使用了不存在的库。

排查与解决：

1. 增加语法检查步骤：在执行前，先用py_compile或ast.parse模块快速检查代码语法。如果语法错误，直接将错误信息反馈给LLM，让它重新生成。

   import ast def validate_python_syntax(code): try: ast.parse(code) return True, None except SyntaxError as e: return False, f"语法错误：{e.msg} at line {e.lineno}"

2. 在提示词中强化规范：明确要求模型“生成可直接运行的、语法正确的Python代码”。提供更清晰的格式示例。
3. 使用更强大的模型：GPT-4在代码生成上的准确率远高于GPT-3.5。如果条件允许，优先使用GPT-4或Codex系列模型。
4. 后处理与修正：对于简单的缩进或常见拼写错误，可以编写简单的规则进行自动修正，作为兜底策略。

5.2 智能体陷入循环或偏离目标

智能体可能会重复执行相似的操作，或者在解决一个子问题后忘记了主要任务。

排查与解决：

1. 在观察中强化任务目标：在每一步传给LLM的观察信息里，都重复一遍最原始的任务描述，防止模型“失忆”。
2. 设置最大步数：像我们演示代码中那样，强制设定一个循环上限（如10步），避免无限循环。
3. 引入“放弃”或“求助”机制：当智能体连续几步都无法推进任务状态时（例如，生成的代码执行结果没有变化），可以让它输出一个特殊信号，如# 任务受阻，需要用户澄清，然后由外部流程介入。
4. 改进奖励设计（如果使用强化学习）：对于更高级的智能体，可以设计一个奖励函数，对接近目标的行为给予正奖励，对重复或无意义的行为给予负奖励，引导其学习。

5.3 执行环境与开发环境差异

在开发机上运行成功的代码，可能在智能体的沙箱环境中失败，因为缺少某个库或文件权限不同。

排查与解决：

1. 严格限制库的使用：在提示词中强制要求“仅使用Python标准库”。如果需要第三方库，必须在沙箱环境中预先安装好，并在提示词中明确告知模型可用的库列表。
2. 提供环境说明：在system_prompt中详细说明执行环境，例如：“你生成的代码将在Python 3.9的Linux环境中运行，工作目录是/workspace，已安装pandas和requests库。”
3. 模拟完整测试：在部署前，将智能体生成的典型任务代码在干净的沙箱环境（如Docker容器）中批量测试，确保环境一致性。

5.4 处理模糊或复杂的用户指令

用户可能会说“整理一下我的下载文件夹”，这是一个非常模糊的指令。不同的人对“整理”的定义不同。

排查与解决：

1. 引导用户澄清：设计智能体的第一反应不是直接行动，而是生成一段代码来“询问”用户。例如，它可以先运行一段代码，列出下载文件夹的所有文件类型，然后输出：“发现.pdf,.jpg,.zip等文件。请问您希望按文件类型、按日期还是按其他方式整理？” 将问题抛回给用户。
2. 提供默认策略并告知用户：智能体可以采用一种默认的、合理的整理策略（例如按文件后缀创建子文件夹），并在执行前输出：“我将按文件类型整理您的下载文件夹。即将创建‘文档’、‘图片’、‘压缩包’等子文件夹并移动文件。是否继续？” 这实现了“确认-执行”的安全模式。

我个人在实践中的一个深刻体会是，Code-Act智能体的可靠性，是“提示词工程”、“安全沙箱”和“任务设计”三者共同作用的结果。一个模糊的任务，再好的模型和提示词也可能失败。一个危险的任务，再安全的沙箱也可能有漏洞。因此，在应用设计时，要明确智能体的能力边界，优先让它处理定义清晰、范围受限、结果可验证的任务，比如“将指定文件夹内所有.csv文件合并为一个Excel文件”，而不是开放式的“帮我分析一下数据”。从简单、具体的场景入手，积累经验和信心，再逐步拓展到更复杂的领域，是构建实用AI智能体的稳妥路径。