在 Agent 研究和工程实践中一个正在快速升温的方向是 “Code as Worlds”智能体不再把对环境的理解只保存在自然语言描述或网络参数里而是把环境规则写成一段可执行代码。也就是说Agent 用 Python 函数表示自己学到的东西通过运行这段代码来做预测、规划行动并在预测和真实环境反馈不一致时修改代码。这篇文章先解释这个概念解决什么问题再给出一个可以在本机跑通的最小案例最后讨论沙箱、反馈设计、常见坑和生产落地要点。1. 理解可执行世界表征为什么智能体需要把世界变成代码1.1 世界表征的演进从文本描述到可运行模型传统智能体系统里对世界的理解通常有两种载体。第一种是自然语言比如“房间左侧有一堵墙向右走会进入走廊”。这种描述人类容易读但机器很难直接执行。第二种是神经网络的隐式表征比如一个世界模型把观测编码成向量再通过网络预测下一步状态。这种表征能处理复杂视觉输入但难以解释也很难在发现逻辑错误时单独修正某一条规则。“Code as Worlds” 的核心主张是把世界表征写成代码。代码同时具备三个属性可执行step(state, action)可以直接跑起来输出确定性的预测结果。可检查规则写在函数体里哪一行判断错了人类和 Agent 都能看到。可修改如果预测错误只需要改代码里面的分支或常量不需要重新训练整个网络。用一句话概括自然语言描述世界代码运行世界。可执行世界表征让 Agent 在真实行动之前先在一个“由自己维护的迷你模拟器”里推演后果。1.2 “可执行”解决了哪几个具体问题第一个问题是规划。Agent 要完成多步任务时需要判断“如果先做 A 再做 B 会怎样”。如果世界模型是代码智能体可以在命名的计划阶段直接模拟执行step五次看最终状态是否满足目标。这个过程可以反复进行成本远低于每次真实环境交互。第二个问题是验证。代码表征是有明确输入输出契约的。给一组(state, action, expected_state)就可以写单测来验证 Agent 是否真的理解了世界。自然语言描述没法自动断言向量表征很难构造有效单测代码可以。第三个问题是可解释和可调试。行为出错时顺着代码的执行路径就能看到是哪个条件写错了是边界判断写反了还是障碍物坐标漏了。这种可追溯性对生产系统非常重要。需要澄清一个容易混淆的点Code as Worlds 不等于“Agent 会写代码完成任务”。编码 Agent 工具写代码是为了直接完成任务本身代码是动作而这里讨论的是把环境建模成代码代码是世界模型Agent 通过这份模型预测环境反馈。边界确实会重叠比如编码 Agent 先写测试再写实现本质上也是用测试代码表达对目标行为的可执行理解。理解这个区别有助于后续设计系统。1.3 适用边界不是所有环境都适合代码表征代码表征最适合规则明确、状态可枚举、动作空间确定的环境比如网格世界、棋类、订单状态机、设备控制逻辑。它不适合底层视觉感知也不适合无法用显式规则描述的连续物理过程。对于复杂环境更合理的设计是分层底层用神经网络处理视觉感知上层用可执行世界模型描述业务规则和转移逻辑。Agent 的规划走代码层感知信息的浓缩走网络层。注意代码世界模型是 Agent 对世界的假设不是世界本身。Agent 说“我理解了规则”并不代表它写出的函数就是真理必须通过执行结果和真实环境反馈对齐。2. 落地路径先在一个可控环境里验证闭环2.1 不同世界表征方案的对比在决定是否采用代码作为世界表征之前先看各类方案的取舍。下表适合作为设计阶段的速查。表征形式典型形态是否可执行可检查性可修改性典型场景自然语言文本一段规则说明否高中对话、需求解释结构化数据JSON、YAML 描述状态和转移表需要额外解释器高高静态配置、规则较少向量 / 嵌入LLM 内部隐藏状态否低低检索、隐式知识可执行代码Python 函数、DSL是高高世界模型、规划验证完整仿真器游戏引擎、物理模拟器是中低高保真模拟从表中可以看出代码方案在“可执行、可检查、可修改”三个维度上最均衡。缺点是需要额外的执行环境和安全沙箱实现成本比 JSON 高。2.2 为什么选择网格世界作为第一个实验环境网格世界是验证“可执行世界表征”的最小环境。它有明确的状态、四个确定性动作、边界和障碍物规则非常适合做闭环实验。它的优势是真实环境可以用十几行代码实现方便对照。状态空间足够小可以全量采样所有动作验证准确率。规则简单但存在边界条件能暴露 Agent 常见的理解偏差比如“撞障碍物时状态不变”和“出界时状态不变”容易被写错。学习这个最小案例时关注的不是网格世界本身而是“生成代码、执行预测、对比真实、反馈修正”这套机制。把环境替换成订单状态机、文件系统操作或 API 调用序列后机制完全一样。2.3 技术栈和依赖准备学习环境建议使用 Python 3.10 或更高版本安装一个 OpenAI 兼容的客户端 SDK。这里不绑定具体模型假设你有一个可通过base_url和api_key访问的模型服务。如果本机没有模型服务可以用任意兼容 OpenAI 协议的网关或本地推理服务。关键点是模型能输出 Python 函数并且支持多轮对话。python -m venv .venv source .venv/bin/activate pip install openai这里不要安装多余的框架。为了让读者看清机制示例里只依赖openai和 Python 标准库中的subprocess、ast、tempfile。3. 最小可运行案例让 Agent 用代码发现环境规则3.1 项目结构和模块职责整个示例拆成三个文件职责清晰便于扩展。code_as_worlds/ ├── env.py # 真实环境Agent 只能通过接口观察 ├── agent.py # 提示词、LLM 调用、代码抽取 └── executor.py # 子进程沙箱、代码执行、反馈构造真实环境是唯一的事实来源。Agent 的代码模型只是对环境的猜测必须通过与真实环境对比来修正。3.2 第一步定义真实环境env.py里实现一个 5x5 网格世界。状态是(x, y)元组(0, 0)是左上角动作是字符串。# env.py class GridWorldEnv: def __init__(self, width5, height5, obstaclesNone): self.width width self.height height self.obstacles set(obstacles or []) self.state (0, 0) def reset(self): self.state (0, 0) return self.state def step(self, action): moves { up: (0, -1), down: (0, 1), left: (-1, 0), right: (1, 0), } dx, dy moves[action] nx, ny self.state[0] dx, self.state[1] dy # 超出边界状态不变 if nx 0 or nx self.width or ny 0 or ny self.height: return self.state, False # 撞上障碍物状态不变 if (nx, ny) in self.obstacles: return self.state, False self.state (nx, ny) return self.state, True这里有两个容易写错的地方。第一self.state要保持元组类型否则和模型输出的比较会出现类型不一致。第二障碍物集合要在初始化时转换一次避免每次step都重复转换。3.3 第二步构造提示词并调用 LLMagent.py里定义系统提示词。提示词必须把状态格式、动作集合、函数签名、返回格式都交代清楚否则模型输出的函数很可能不符合调用约定。# agent.py import os import re SYSTEM_PROMPT 你是一个会写代码的智能体。你正在观察一个 5x5 网格世界并通过写 Python 函数来表示你学到的规则。 世界规则 - 状态用 (x, y) 表示(0, 0) 是左上角。 - 动作只有四种up、down、left、right。 - 走出边界时状态保持不变动作无效。 - 撞到障碍物时状态保持不变动作无效。 - 其他情况状态沿动作方向移动一格。 请输出一个完整的 Python 函数 def step(state, action): # state: (x, y) 元组 # action: up | down | left | right # 返回 (new_state, valid)valid 表示动作是否有效 只输出这个函数不要输出解释文字。 def call_llm(messages, modeldeepseek-chat): 调用 OpenAI 兼容接口。实际项目按自己的网关调整。 import openai client openai.OpenAI( api_keyos.environ.get(LLM_API_KEY), base_urlos.environ.get(LLM_BASE_URL, https://api.deepseek.com), ) resp client.chat.completions.create( modelmodel, messagesmessages, temperature0.2, max_tokens1024, ) return resp.choices[0].message.content def extract_code(text): 从模型输出中抽取出 step 函数定义。 block re.search(r(?:python)?\s*(.*?), text, re.S) if block: text block.group(1) idx text.find(def step) if idx -1: return None return text[idx:].strip()extract_code先尝试解析 markdown 代码块再退回到直接定位def step。实际项目中模型输出经常夹杂解释文字这个防御式抽取很必要。3.4 第三步在子进程沙箱里执行模型生成的代码executor.py是整套机制里最关键也最容易出问题的部分。模型生成的代码来自不可信来源不能直接用exec在当前进程里运行。示例使用子进程加临时目录的方式做基础隔离。# executor.py import ast import os import subprocess import sys import tempfile def run_prediction(code, state, action, timeout5): 在子进程中执行模型生成的 step 函数返回预测结果或错误信息。 with tempfile.TemporaryDirectory() as tmpdir: mod_path os.path.join(tmpdir, wm.py) with open(mod_path, w, encodingutf-8) as f: f.write(code) script ( import sys\n fsys.path.insert(0, {tmpdir!r})\n import wm\n fprint(wm.step({state!r}, {action!r}))\n ) try: proc subprocess.run( [sys.executable, -c, script], capture_outputTrue, textTrue, timeouttimeout, ) except subprocess.TimeoutExpired: return None, subprocess timeout if proc.returncode ! 0: return None, proc.stderr.strip() try: return ast.literal_eval(proc.stdout.strip()), None except Exception as exc: return None, fparse error: {exc}这里用了ast.literal_eval解析子进程标准输出而不是eval。因为子进程的输出期望是一个元组字面量ast.literal_eval只解析字面量不会执行任意表达式更安全。3.5 第四步对比真实环境并构造反馈主循环里完成“采样状态 - 执行真实动作 - 执行模型代码 - 比较结果 - 返回反馈”的闭环。# agent.py 追加部分 from env import GridWorldEnv from executor import run_prediction ACTIONS [up, down, left, right] def build_feedback(pred, actual, state, action): if pred is None: return f在状态 {state} 执行 {action} 时你的代码执行失败请修正。 expected_state, expected_valid actual got_state, got_valid pred return ( f在状态 {state} 执行动作 {action} 时\n f真实结果: state{expected_state}, valid{expected_valid}\n f你的预测: state{got_state}, valid{got_valid}\n 请根据差异修正 step 函数。 ) def main(): env GridWorldEnv(width5, height5, obstacles[(1, 1), (3, 2)]) messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: 请先生成第一版世界模型代码。}, ] # 采样一组代表状态覆盖普通位置、边界附近和障碍物附近 sample_states [(0, 0), (0, 4), (2, 2), (3, 1), (4, 4)] for round_no in range(6): reply call_llm(messages) code extract_code(reply) if code is None: messages.append({role: assistant, content: reply}) messages.append({role: user, content: 输出里没有找到 def step请重新只输出函数。}) continue env.reset() errors 0 total 0 feedback_lines [] for state in sample_states: for action in ACTIONS: # 测试用直接把真实环境状态设置到采样状态 env.state state actual env.step(action) pred, err run_prediction(code, state, action) total 1 if err or pred ! actual: errors 1 feedback_lines.append(build_feedback(pred, actual, state, action)) acc (total - errors) / total print(f[round {round_no}] 模型预测准确率: {acc:.2%} ({total - errors}/{total})) if errors 0: print(Agent 发现了可执行世界表征停止训练。) print(code) return feedback ( f第 {round_no} 轮预测准确率为 {acc:.2%}。\n \n.join(feedback_lines[:3]) \n请重新输出修正后的 step 函数。 ) messages.append({role: assistant, content: reply}) messages.append({role: user, content: feedback}) print(达到最大轮数未收敛。)运行方式export LLM_API_KEY你的密钥 export LLM_BASE_URLhttps://api.deepseek.com python agent.py如果模型第一轮就写对了规则输出类似[round 0] 模型预测准确率: 100.00% (20/20) Agent 发现了可执行世界表征停止训练。如果环境规则更复杂会看到准确率逐轮提升最后一轮收敛。4. 关键机制拆解执行、验证、反馈三要素4.1 为什么不能在当前进程直接执行 Agent 生成的代码模型生成的代码可能包含死循环、资源耗尽操作、文件读写、系统调用甚至恶意代码。直接exec会在宿主进程里运行这些代码后果不可控。示例采用两层防线。第一层用临时目录隔离模块避免污染项目目录。第二层用subprocess启动独立 Python 进程并通过timeout控制最大执行时间。但要注意子进程隔离不等于安全隔离。子进程仍然可以访问宿主机的文件系统、网络和环境变量。生产环境需要更严格的方案比如 Docker 容器、gVisor、Firecracker 微虚拟机或者远程代码执行服务。是否引入容器取决于代码来源的可信度。对于完全不可信的模型输出应该假设它可能尝试读取敏感文件或访问内网。注意示例里的沙箱只用于学习和原型验证。真实环境中请把 Agent 生成代码的执行放到专用沙箱服务里并且不允许它访问生产网络和密钥。4.2 反馈信息要结构化而不是只说“你错了”反馈循环是否收敛很大程度上取决于反馈质量。只写“预测结果不对”对模型几乎没有修正价值。好的反馈包含三部分触发错误的输入state(0,0), actionleft。真实输出环境返回的(state, valid)。模型输出Agent 预测的(state, valid)。示例里的build_feedback就是按这个结构构造的。每轮最多保留前三条错误样本避免上下文过长。还需要注意一个细节如果模型代码执行出错也要把错误信息返回给模型。很多情况下Agent 不是不知道规则而是函数签名写错了比如返回了(valid, state)而不是(state, valid)。把stderr截断后附进反馈模型能很快修正调用契约。4.3 采样策略决定验证质量全量采样网格世界所有状态会得到最准确的评估但真实场景往往面临组合爆炸。示例里选了 5 个代表性状态采样状态覆盖目标(0, 0)左上角边界(0, 4)左下角边界(2, 2)普通内部区域(3, 1)障碍物附近(4, 4)右下角边界每个状态执行四个动作共 20 次预测。这个样本量足够发现最典型的规则错误比如“出界处理缺失”“障碍物坐标写错”“动作方向映射错误”。如果环境规则更复杂建议按以下原则扩展采样覆盖所有边界条件、覆盖所有特殊对象邻域、加入随机采样、对关键转移路径做穷举。4.4 关键参数说明示例里有几个参数可以直接调整理解它们的含义比抄代码更重要。参数示例值作用调小的效果调大的效果temperature0.2控制模型输出随机性更稳定但可能陷入同一个错误循环更容易跳出局部错误但可能越改越乱max_tokens1024限制生成内容长度可能截断函数定义允许更长的代码但增加延迟最大轮数6限制训练循环次数可能没来得及收敛增加耗时也可能让上下文过长timeout5 秒单次代码执行超时可能误杀正常代码死循环代码会阻塞更久对于网格世界这类简单环境temperature0.2到0.4比较合适。复杂模型可以适当调高但必须配合反馈防抖比如连续两轮完全相同的结果就不再重新提交相同内容。4.5 学习环境与生产环境的差异维度学习环境生产环境沙箱子进程 临时目录容器、微虚拟机、远程执行服务模型来源一个兼容 API多个模型、版本切换、灰度反馈日志print 到终端结构化日志、链路追踪收敛判断本地变量指标上报、告警代码审批无高风险操作需人工审批成本控制忽略需要 token 计量和配额生产环境的反馈循环往往不是一次交互闭环而是要接入任务队列、失败重试、人工审核和审计日志。这些在原型阶段可以暂时不管设计时心里要有数。5. 运行验证与结果观察5.1 怎么判断一次训练真的成功代码能运行不等于 Agent 发现了世界表征。判断成功的标准是在采样状态上预测准确率达到 100%。对未参与采样的状态和动作组合也能用代码正确预测。生成的代码结构稳定不同轮次之间没有大幅随机波动。人工审查代码时能确认边界条件和障碍物判断与真实环境一致。建议在代码里加一段“留出测试集”逻辑比如只用sample_states的一部分生成反馈另一部分做最终验证。这样可以避免 Agent 只是把反馈里的错误样本背下来而不是真正学到规则。5.2 失败模式的观察如果循环达到最大轮数仍未收敛通常看到三类现象。第一类是准确率停留在某个固定值。比如一直卡在 80%说明 Agent 没学到某个特定规则往往是边界判断。此时要看前三条错误样本是否集中在同一类转移上。第二类是代码在语法上不断变化但语义不变。模型每次都在改括号、缩进却始终忽略障碍物规则。这种情况要降低temperature并在系统提示词里补充“障碍物为 (1,1) 和 (3,2)”。第三类是反馈循环越来越长但每轮准确率没有提升。此时需要人工介入检查提示词是否把早期观察到的规则冲掉了。常见做法是把历史确认规则单独放在提示词开头。6. 常见问题排查6.1 问题现象与处理方案速查问题现象可能原因检查方式处理建议生成的代码有语法错误模型输出混入解释文字或抽取逻辑失效打印模型原始输出检查extract_code是否截断强化提示词只输出函数用代码块解析保存每轮原始输出代码能运行但预测全部错误调用契约不匹配比如返回(valid, state)打印一次pred和actual的原始结果把函数签名和返回顺序写进系统提示词并在反馈里附错误样例准确率稳定但不收敛缺少某类规则上下文或反馈样本不足统计错误分布看集中在哪个动作或状态增加采样状态把少量确定性规则写成“已知事实”加入提示词子进程超时模型生成死循环或超大循环检查 stderr 里的 timeout 标识降低 timeout在提示词里限制循环次数或对代码做静态检查每轮输出不稳定temperature 过高对比两轮代码 diff降低 temperature限制为 0.2 或更低上下文过长导致模型忽略早期信息多轮反馈全部堆在 messages 里查看 token 消耗把历史反馈摘要成“已知规则”只保留最近两轮细节6.2 排查顺序遇到任何问题时按下面的顺序排查不要直接怀疑模型能力。输入是否正确动作字符串是否一致状态元组是否和模型代码约定匹配。路径和命名模型生成的模块名、函数名、导入语句是否和调用脚本一致。依赖版本openaiSDK 版本是否支持当前模型接口base_url是否正确。配置是否生效环境变量LLM_API_KEY、LLM_BASE_URL是否真的传入。沙箱行为子进程是否因为权限、依赖缺失、路径问题而失败。反馈质量错误信息是否包含原始输入和输出是否足够定位差异。模型服务本身是否限流、超时、返回空内容。6.3 一个典型案例模型一直漏掉障碍物规则最常见的现象是Agent 生成的代码正确处理了边界但对障碍物视而不见准确率稳定在 85% 左右。原因是第一版反馈里恰好没有“撞上障碍物”的样本或者障碍物坐标只出现在一个状态组合里模型没有足够证据推断障碍物是一组集合而不是一个点。解决办法有两种。第一是在采样状态里显式加入障碍物邻域比如(0,1)、(1,0)、(2,1)、(3,3)让反馈必然覆盖障碍物命中场景。第二是在系统提示词里明确写出“环境中存在障碍物”把障碍物坐标作为待发现信息而不是完全隐藏在交互数据里。7. 从玩具环境到真实 Agent 工程7.1 可执行世界表征在真实项目里的三种形态第一种是任务规划器中的环境模型。智能体要操作订单系统时可以把订单状态机写成代码transition(order, event)。规划时先模拟几条事件序列找出能到达终态的那条再真实调用 API。第二种是测试优先的代码 Agent。Agent 在改代码前先生成一组测试用例这些测试本身就是对目标行为的可执行表征。随后实现只要满足测试即可。这个模式在 Claude Code、Codex 等编码工具的工作流里越来越常见本质就是把“对目标世界的理解”落实成可运行断言。第三种是模拟器集成。在游戏、机器人、运维演练场景里Agent 维护一份轻量级模拟器用来评估策略。模拟器可以逐步从代码假设升级到完整仿真但任何时候都保留代码层便于快速验证和高频调用。这些形态的共同点是世界表征必须能运行、能验证、能修改。这和玩具案例里的机制完全一致只是环境替换成了真实业务。7.2 与现有 Agent 框架的关系当前热门的 Agent 框架例如 Dify、Coze、LangGraph 等更多在解决“Agent 如何编排工具、如何管理对话状态、如何调用模型”的问题。Code as Worlds 关注的是另一层Agent 如何维护对环境的可执行理解。两者可以结合。框架负责调度和工具调用应用层维护一份可执行世界模型Agent 在计划阶段调用这份模型做推演。引入框架时关键是评估它的状态管理和工具调用机制是否能承载“代码生成 - 执行 - 反馈 - 更新”的循环。很多框架支持自定义工具可以把run_prediction和build_feedback封装成工具由 Agent 自己决定何时调用。7.3 生产落地检查清单在设计真实系统之前建议逐项检查以下清单沙箱方案是否隔离了文件系统、网络、环境变量和密钥。执行超时、内存限制、CPU 配额是否配置。Agent 生成的代码是否有审计日志原始输出、抽取代码、执行结果是否都可追溯。是否存在人工审批入口特别是高风险操作。采样策略是否覆盖边界条件和特殊对象。反馈信息是否结构化错误样本是否截断到模型可处理的长度。是否设置了轮次上限和 token 预算。模型输出是否经过语法校验和基础静态检查后再执行。训练循环和真实业务调用是否隔离避免验证占用生产资源。是否保留“回滚上一版本世界模型”的能力。7.4 扩展方向从最小案例出发可以按三个方向扩展。方向上把网格世界换成状态机或 API 流程让 Agent 发现业务系统的工作流规则。这时候世界模型从“环境模拟”变成“业务流程模拟”更有实际价值。方向二引入多智能体。每个 Agent 维护自己的世界模型通过共享反馈池互相校验。这能暴露单个 Agent 无法发现的盲区。方向三加入不确定性和对抗。真实环境往往有随机扰动比如动作有 10% 概率失败。Agent 的代码模型需要引入概率分支验证时也要多次采样统计分布。这一步会让反馈设计和收敛判断复杂很多但也是从玩具走向生产必须跨过的一步。回头再看开头的判断可执行世界表征的价值不在于用代码描述环境而在于让环境理解变得可运行、可验证、可修正。这种能力是神经网络隐式表征和自然语言描述都难以直接提供的。对正在做 Agent 工程的人来说最务实的起点就是今天这个最小闭环生成环境代码运行它让它和真实世界对答案。把这一圈跑通再往业务场景里迁移时核心机制不会变变的只是环境定义和沙箱强度。