1. 从「工具调用」到「Code Mode」一场正在发生的 Agent 范式转移过去一年多我一直在做 AI Agent 相关的落地项目从最早的 Function Calling 到后来的多工具编排踩过的坑可以说能写满一个笔记本。但最近半年一个明显的变化让我意识到Agent 的底层交互范式正在发生一次根本性的转移。这个转移的核心就是从「工具调用」Tool Calling走向「Code Mode」——让 Agent 直接写代码来完成任务而不是一个一个去调用预定义的工具接口。如果你现在还在用传统的 Function Calling 方式搭建 Agent可能会发现几个越来越明显的瓶颈工具数量一多模型选择困难多步骤任务需要反复往返调用延迟高得离谱工具之间的数据传递要靠模型在上下文里搬运稍长一点就丢信息。而 Code Mode 的思路完全不同——它让模型生成一段可执行的代码在沙箱里跑完直接拿到结果。这不是简单的技术升级而是一次思维方式的切换。这篇文章适合正在做 Agent 开发、对工具编排感到头疼的工程师也适合想理解 AI Agent 下一步走向的产品和技术决策者。我会从范式转移的底层逻辑讲起拆解 Code Mode 的核心机制给出可复现的实操方案最后分享我在实际项目中踩过的坑和排查技巧。全文基于我自己的项目经验和对当前主流方案的观察不涉及任何特定厂商的绑定。2. 为什么「工具调用」正在触到天花板2.1 工具调用的本质与它的历史贡献要理解为什么需要 Code Mode得先搞清楚工具调用到底解决了什么问题以及它的边界在哪里。工具调用的本质是让语言模型输出一个结构化的 JSON描述我要调用哪个函数、传什么参数然后由外部运行时去执行这个函数再把结果塞回上下文。这个机制在 2023 年之后迅速成为 Agent 开发的标准范式因为它巧妙地绕开了模型不能直接操作外部世界的限制。我最早做的一个项目是帮一个内部团队做数据查询助手当时定义了大概十几个工具查数据库、调 API、发邮件、生成报表等等。刚开始效果很好模型能根据用户意图选对工具参数也填得八九不离十。但项目跑到第三个月工具数量涨到四十多个的时候问题就开始集中爆发了。模型选错工具的概率明显上升有时候明明该查订单表它去调了用户表有时候一个任务需要串联五六个工具中间任何一步参数传错整个链路就崩了。2.2 三个绕不开的结构性瓶颈我把工具调用遇到的问题归纳成三类这三类问题不是靠换个更强的模型就能解决的它们是范式本身带来的结构性瓶颈。第一类是工具选择的组合爆炸。当工具数量从 10 个涨到 100 个模型需要在更大的候选空间里做选择准确率会显著下降。这就像你让一个人从 10 把钥匙里找一把开门很容易但从 1000 把里找即使每把都有标签也会眼花。而且很多工具的功能是重叠的模型很难稳定地做出最优选择。第二类是多步任务的往返开销。一个稍微复杂的任务比如分析上个月的销售数据找出异常订单生成报告并发送给相关负责人在工具调用范式下需要查数据 → 分析 → 查异常 → 生成报告 → 发送每一步都是一次完整的模型推理加一次外部执行往返五六次是常态。每次往返都有延迟而且每次都要把前面的结果重新塞进上下文token 消耗巨大。第三类是上下文里的数据搬运损耗。工具调用的结果是以文本形式回到上下文的如果中间某个工具返回了一大段数据模型需要记住这些数据并在下一步使用。但上下文窗口是有限的数据一多就会被截断或稀释导致后续步骤丢失关键信息。我遇到过最典型的情况是查询返回了 200 条记录模型在生成报告时只看到了前 50 条后面的全丢了。2.3 一个具体的失败案例说个我印象最深的失败案例。当时做一个财务对账 Agent需要从三个不同的数据源拉数据做交叉比对找出差异项。用工具调用的方式我定义了三个查询工具加一个比对工具。测试的时候用少量数据跑得很好一上生产环境数据量一大就出问题模型在调用比对工具时需要把前三个查询的结果作为参数传进去但三个结果加起来超过了上下文的有效处理范围模型开始编造数据把不存在的差异项也报了出来。这个问题的根源不在于模型能力不够而在于工具调用范式强制要求所有中间数据都经过上下文这个窄管道。数据量一大管道就堵了。后来我改用 Code Mode 重写让模型直接生成一段 Python 代码在沙箱里完成查询、比对、输出数据全程不经过上下文问题迎刃而解。这就是范式转移的现实驱动力。3. Code Mode 到底是什么核心机制拆解3.1 一句话说清 Code Mode 的本质Code Mode 的核心思想可以用一句话概括让 Agent 把要做的事写成代码在受控环境里执行而不是把要做的事拆成一次次工具调用。模型不再输出调用哪个函数而是输出一段完整的、可执行的程序这段程序里可以包含任意逻辑——循环、条件判断、数据处理、甚至调用其他库。这个转变看起来只是输出格式的变化但带来的影响是深远的。工具调用是离散的、一次一步的Code Mode 是连续的、一次一段的。前者像用遥控器一个键一个键地操作后者像直接写一个脚本让电脑自己跑完。3.2 执行环境沙箱是 Code Mode 的地基Code Mode 能成立的前提是有一个安全、隔离、可控的执行环境。模型生成的代码不能直接在宿主机上跑否则一个死循环或者一个误删操作就可能造成灾难。所以沙箱是整个方案的地基。我实际用过的沙箱方案有几类轻量级的是进程级隔离用子进程加资源限制跑代码中等的是容器级隔离每个任务起一个容器重量级的是虚拟机级隔离。选哪种取决于你的安全要求和性能要求。对于大多数内部工具场景容器级隔离是性价比最高的选择——启动快、隔离性好、资源可控。沙箱需要配置几个关键限制执行超时防止死循环、内存上限防止内存爆炸、网络访问控制决定代码能不能访问外部、文件系统隔离防止读写敏感文件。这几个参数配不好要么不安全要么不好用。我一般会把超时设在 30 秒到 2 分钟之间内存给 512MB 到 2GB网络默认关闭需要时按白名单开放。3.3 代码生成模型需要什么样的提示Code Mode 对提示词的要求和工具调用完全不同。工具调用时代你要把每个工具的名称、描述、参数 schema 都写清楚让模型去选。Code Mode 时代你要告诉模型的是你能用哪些库、环境里有什么数据、输出格式是什么、有哪些限制。我总结的提示词结构是这样的先说明任务目标再列出可用的库和它们的能力然后给出环境约束比如不能访问网络只能读取 /data 目录最后明确输出要求比如把结果写到 /output/result.json。这个结构比工具调用的 schema 描述更接近给一个程序员派活的方式。有个关键细节要给模型提供足够的示例。纯文字描述库的用法模型容易用错 API。我一般会在提示里塞两三个简短的代码示例展示典型的数据读取、处理和输出方式。实测下来有示例的情况下代码一次跑通的概率能从 60% 提升到 85% 以上。3.4 结果回传只传结论不传过程Code Mode 相比工具调用最大的优势之一就是结果回传的瘦身。工具调用模式下每一步的中间结果都要回到上下文Code Mode 模式下代码在沙箱里跑完只有最终结果回到上下文。中间产生的所有临时数据、循环变量、调试信息全部留在沙箱里不占用宝贵的上下文空间。这个特性带来的直接好处是任务复杂度不再受上下文窗口的严格限制。你可以让 Agent 处理一个包含十万行数据的文件只要最终输出是一个几百字的摘要上下文压力就很小。这在工具调用范式下几乎不可能实现。3.5 和工具调用不是替代关系而是分层关系这里要澄清一个常见的误解Code Mode 不是要完全取代工具调用。实际上很多 Code Mode 的实现里代码本身就可以调用工具——只不过调用发生在代码内部而不是由模型在上下文里决策。比如代码里可以import requests去调 API可以import pandas去处理数据这些工具是以库的形式存在的。所以更准确的理解是工具调用是 Code Mode 的一个子集。Code Mode 把选择工具这个动作从模型的上下文推理下沉到了代码的逻辑里。模型只需要写对代码代码里的工具调用是确定性的、可测试的、可复现的。这比让模型在上下文里猜该调哪个工具要可靠得多。4. 实操从零搭一个 Code Mode Agent4.1 整体架构设计我以一个数据分析助手为例完整走一遍 Code Mode Agent 的搭建过程。这个助手的功能是接收一个数据文件路径和一个分析需求生成分析代码在沙箱里执行返回分析结果。整体架构分四层接入层负责接收用户请求和返回结果编排层负责调用模型生成代码、管理沙箱生命周期沙箱层负责安全执行代码数据层负责提供代码需要访问的数据。这四层里编排层和沙箱层是 Code Mode 特有的也是重点。我选择用 Python 作为代码生成的目标语言因为它的数据处理生态最成熟模型对它的掌握也最好。沙箱用容器实现每次任务起一个临时容器跑完就销毁。数据通过只读挂载的方式提供给容器代码只能读不能写原始数据输出写到单独的目录。4.2 沙箱环境的准备与配置沙箱的 Dockerfile 我一般这样写基础镜像用精简版的 Python 镜像预装常用的数据处理库pandas、numpy 等创建一个非 root 用户来跑代码设置好工作目录。关键是要预装库不能让模型生成的代码去 pip install那样既慢又不安全。FROM python:3.11-slim RUN pip install --no-cache-dir pandas numpy RUN useradd -m sandboxuser USER sandboxuser WORKDIR /workspace启动容器时的参数很关键我列一下我常用的配置docker run --rm \ --network none \ --memory 1g \ --cpus 1 \ --read-only \ --tmpfs /tmp:size256m \ -v /host/data:/workspace/data:ro \ -v /host/output:/workspace/output:rw \ sandbox-image \ timeout 60 python /workspace/script.py这里每个参数都有讲究。--network none彻底断网防止代码外联--memory 1g限制内存--read-only让根文件系统只读只有 /tmp 和 output 可写timeout 60是双保险容器层面和命令层面都设超时。这套配置我用了大半年稳定性很好。4.3 代码生成提示词的设计提示词是 Code Mode 的灵魂。我用的模板大致是这样的结构分五个部分第一部分是角色和任务你是一个数据分析代码生成器根据用户需求生成 Python 代码。第二部分是环境说明代码将在隔离沙箱中执行无网络访问可读取 /workspace/data 目录结果写入 /workspace/output。第三部分是可用库可使用 pandas、numpy禁止使用其他未列出的库。第四部分是输出要求代码必须将最终结果以 JSON 格式写入 /workspace/output/result.json。第五部分是示例给两三个典型任务的代码示例。这个模板的关键在于约束明确。模型最怕的是模糊指令你越明确地告诉它边界在哪它生成的代码越靠谱。我特别强调禁止使用其他库因为模型有时候会自作主张 import 一些环境里没有的库导致执行失败。4.4 执行流程与错误处理完整的执行流程是这样的用户提交需求 → 编排层组装提示词 → 调用模型生成代码 → 代码写入临时文件 → 启动沙箱容器执行 → 收集输出 → 返回结果。这个流程里错误处理是最容易被忽视但最重要的环节。代码执行失败的原因主要有几类语法错误、库使用错误、数据格式不符、超时、内存溢出。我的处理策略是分级重试语法错误和库使用错误把错误信息回传给模型让它修正代码最多重试两次数据格式不符检查数据本身超时和内存溢出直接返回失败不重试因为重试大概率还是失败。这里有个经验把沙箱的 stderr 完整回传给模型。模型看到具体的报错信息修正代码的准确率很高。我实测过第一次执行失败后把 traceback 回传第二次成功的概率在 70% 左右。如果不回传错误信息只是说执行失败模型基本靠猜成功率不到 30%。4.5 一个完整的代码示例假设用户需求是统计销售数据中每个品类的总金额找出金额最高的三个品类。模型生成的代码大概是这样import pandas as pd import json df pd.read_csv(/workspace/data/sales.csv) summary df.groupby(category)[amount].sum().reset_index() summary summary.sort_values(amount, ascendingFalse).head(3) result { top_categories: summary.to_dict(records), total_amount: float(df[amount].sum()) } with open(/workspace/output/result.json, w) as f: json.dump(result, f, ensure_asciiFalse)这段代码在沙箱里跑完只有 result.json 的内容回到上下文原始数据完全没进上下文。如果数据文件有十万行工具调用范式下根本处理不了Code Mode 下毫无压力。这就是范式的力量。5. 常见问题与排查技巧实录5.1 代码生成质量不稳定的排查最常见的问题就是模型生成的代码时好时坏。同样的需求有时候一次跑通有时候反复失败。排查这个问题我一般从三个方向入手。先看提示词是否足够具体。模糊的需求描述是代码质量不稳定的头号原因。比如分析一下数据这种需求模型每次理解都不一样。解决办法是把需求拆解成明确的输入、处理、输出三要素。再看示例是否覆盖了典型场景。如果示例太少或者太偏模型遇到新场景就容易翻车。我的经验是至少给三个示例覆盖读取、处理、输出三个环节而且示例要贴近实际任务的复杂度。最后看模型参数。温度设太高代码随机性大设太低又可能陷入固定模式。我一般把温度设在 0.2 左右兼顾稳定性和灵活性。5.2 沙箱执行超时的处理超时是另一个高频问题。代码逻辑没问题但就是跑不完。原因通常是数据量太大或者算法效率太低。我的处理分两步先看是不是数据量的问题如果是考虑在代码里加采样或者分块处理再看是不是算法问题比如用了嵌套循环处理大表这种情况引导模型用向量化操作。有个技巧很管用在提示词里明确数据规模。告诉模型数据文件约 50 万行模型就会倾向于选择高效的写法。如果不告诉它它可能按处理几百行的思路写代码一上大数据就超时。5.3 数据格式不匹配的排查数据格式问题也很常见。模型假设 CSV 有表头实际文件没有模型假设日期是标准格式实际是各种奇怪的写法。这类问题的根源是模型看不到真实数据。解决办法是在提示词里提供数据样例。取前几行数据作为示例塞进提示模型就能根据实际格式写代码。这个改动看似简单但能消除大部分格式相关的失败。我一般会取 3 到 5 行样例既能说明格式又不占太多上下文。5.4 常见问题速查表问题现象可能原因排查方向解决技巧代码语法错误提示词模糊、模型理解偏差检查提示词明确性回传 traceback 让模型修正执行超时数据量大、算法低效确认数据规模提示词中说明数据量内存溢出一次性加载大文件检查读取方式引导分块读取结果为空数据格式不符对比实际数据格式提示词中提供数据样例库导入失败使用了未预装的库检查 import 语句提示词中明确可用库输出格式错误输出要求不明确检查输出约束明确 JSON schema5.5 几个我踩过的坑第一个坑是沙箱里没有时区信息。有次处理时间数据代码里用了本地时间沙箱默认 UTC结果差了好几个小时。后来我在沙箱里统一设成 UTC并在提示词里说明问题解决。第二个坑是浮点数精度。财务数据用 float 处理累加之后出现了精度误差。后来改成用 Decimal并在提示词里强调财务数据要用 Decimal。第三个坑是并发执行时的资源竞争。多个任务同时跑共享的输出目录互相覆盖。解决办法是每个任务用独立的输出目录用任务 ID 区分。6. 范式转移背后的深层影响6.1 对 Agent 开发者的能力要求变了从工具调用到 Code Mode对开发者的能力要求发生了明显变化。工具调用时代核心能力是把任务拆解成工具能完成的步骤考验的是流程设计能力。Code Mode 时代核心能力变成了把任务描述成代码能理解的规格考验的是需求表达和约束设计能力。这个变化意味着Agent 开发者需要更懂编程——不是自己写代码而是理解代码的边界、性能特征、常见陷阱这样才能设计出好的提示词和沙箱约束。我身边做得好的 Agent 开发者往往都有扎实的编程背景这不是巧合。6.2 对系统架构的影响Code Mode 让 Agent 系统的架构重心从工具编排转向了执行环境管理。工具调用时代架构的核心是工具注册、路由、参数校验Code Mode 时代核心变成了沙箱管理、资源调度、安全隔离。这是一个从逻辑层到基础设施层的重心转移。这个转移带来的直接后果是Agent 系统对基础设施的依赖变重了。你需要容器编排、需要资源监控、需要安全审计。对于小团队来说这可能是个门槛。但好消息是这些基础设施都有成熟的方案可以复用不需要从零造轮子。6.3 对任务复杂度的解放最让我兴奋的是 Code Mode 对任务复杂度的解放。工具调用范式下任务复杂度受限于工具数量和上下文窗口天花板很明显。Code Mode 范式下只要代码能写出来任务复杂度几乎没有上限。你可以让 Agent 处理一个需要几十步、涉及大量数据的任务只要最终输出是精简的。这个解放意味着 Agent 能做的事情范围大大扩展了。以前只能做问答式的轻任务现在可以做工程式的重任务。我最近用 Code Mode 做了一个自动化的数据清洗流水线处理逻辑有十几步涉及多个数据源的合并和转换在工具调用范式下根本不敢想Code Mode 下跑得很稳。6.4 安全边界需要重新思考Code Mode 带来能力解放的同时也带来了新的安全挑战。工具调用时代模型能做的事情被工具列表严格限制安全边界清晰。Code Mode 时代模型能写任意代码安全边界转移到了沙箱的隔离能力上。这就要求我们在沙箱配置上更加谨慎。网络访问、文件系统、系统调用每一个都要仔细权衡。我的原则是默认全部关闭按需最小开放。宁可功能少一点也不能让安全出问题。毕竟一个能执行任意代码的 Agent如果沙箱有漏洞后果是灾难性的。7. 我个人的一些实践体会做了大半年的 Code Mode 项目有几个体会想分享。第一个是不要追求一步到位。刚开始我总想让模型一次生成完美的代码结果提示词越写越复杂效果反而不好。后来改成先生成、再修正的两段式第一段生成基础代码第二段根据执行结果修正整体成功率反而更高。第二个是沙箱的日志要留全。每次执行的代码、输入、输出、错误信息全部记录下来。这些日志在排查问题时价值巨大而且积累多了还能用来优化提示词——看看哪些错误反复出现就在提示词里提前规避。第三个是不要迷信模型能力。Code Mode 再强模型也有它不擅长的领域。复杂的算法、特定的业务逻辑、需要领域知识的处理模型生成的代码往往需要人工审核。我的做法是在关键任务上加一道人工确认模型生成代码后先给人看一眼确认没问题再执行。这个环节看起来降低了自动化程度但实际提升了整体可靠性。最后分享一个小技巧给模型提供代码模板。对于重复性高的任务我会准备几个代码骨架让模型在骨架上填充逻辑而不是从零生成。这样生成的代码结构统一可维护性好出错率也低。这个技巧在处理批量任务时特别管用值得一试。
1. 从「工具调用」到「Code Mode」一场正在发生的 Agent 范式转移过去一年多我一直在做 AI Agent 相关的落地项目从最早的 Function Calling 到后来的多工具编排踩过的坑可以说能写满一个笔记本。但最近半年一个明显的变化让我意识到Agent 的底层交互范式正在发生一次根本性的转移。这个转移的核心就是从「工具调用」Tool Calling走向「Code Mode」——让 Agent 直接写代码来完成任务而不是一个一个去调用预定义的工具接口。如果你现在还在用传统的 Function Calling 方式搭建 Agent可能会发现几个越来越明显的瓶颈工具数量一多模型选择困难多步骤任务需要反复往返调用延迟高得离谱工具之间的数据传递要靠模型在上下文里搬运稍长一点就丢信息。而 Code Mode 的思路完全不同——它让模型生成一段可执行的代码在沙箱里跑完直接拿到结果。这不是简单的技术升级而是一次思维方式的切换。这篇文章适合正在做 Agent 开发、对工具编排感到头疼的工程师也适合想理解 AI Agent 下一步走向的产品和技术决策者。我会从范式转移的底层逻辑讲起拆解 Code Mode 的核心机制给出可复现的实操方案最后分享我在实际项目中踩过的坑和排查技巧。全文基于我自己的项目经验和对当前主流方案的观察不涉及任何特定厂商的绑定。2. 为什么「工具调用」正在触到天花板2.1 工具调用的本质与它的历史贡献要理解为什么需要 Code Mode得先搞清楚工具调用到底解决了什么问题以及它的边界在哪里。工具调用的本质是让语言模型输出一个结构化的 JSON描述我要调用哪个函数、传什么参数然后由外部运行时去执行这个函数再把结果塞回上下文。这个机制在 2023 年之后迅速成为 Agent 开发的标准范式因为它巧妙地绕开了模型不能直接操作外部世界的限制。我最早做的一个项目是帮一个内部团队做数据查询助手当时定义了大概十几个工具查数据库、调 API、发邮件、生成报表等等。刚开始效果很好模型能根据用户意图选对工具参数也填得八九不离十。但项目跑到第三个月工具数量涨到四十多个的时候问题就开始集中爆发了。模型选错工具的概率明显上升有时候明明该查订单表它去调了用户表有时候一个任务需要串联五六个工具中间任何一步参数传错整个链路就崩了。2.2 三个绕不开的结构性瓶颈我把工具调用遇到的问题归纳成三类这三类问题不是靠换个更强的模型就能解决的它们是范式本身带来的结构性瓶颈。第一类是工具选择的组合爆炸。当工具数量从 10 个涨到 100 个模型需要在更大的候选空间里做选择准确率会显著下降。这就像你让一个人从 10 把钥匙里找一把开门很容易但从 1000 把里找即使每把都有标签也会眼花。而且很多工具的功能是重叠的模型很难稳定地做出最优选择。第二类是多步任务的往返开销。一个稍微复杂的任务比如分析上个月的销售数据找出异常订单生成报告并发送给相关负责人在工具调用范式下需要查数据 → 分析 → 查异常 → 生成报告 → 发送每一步都是一次完整的模型推理加一次外部执行往返五六次是常态。每次往返都有延迟而且每次都要把前面的结果重新塞进上下文token 消耗巨大。第三类是上下文里的数据搬运损耗。工具调用的结果是以文本形式回到上下文的如果中间某个工具返回了一大段数据模型需要记住这些数据并在下一步使用。但上下文窗口是有限的数据一多就会被截断或稀释导致后续步骤丢失关键信息。我遇到过最典型的情况是查询返回了 200 条记录模型在生成报告时只看到了前 50 条后面的全丢了。2.3 一个具体的失败案例说个我印象最深的失败案例。当时做一个财务对账 Agent需要从三个不同的数据源拉数据做交叉比对找出差异项。用工具调用的方式我定义了三个查询工具加一个比对工具。测试的时候用少量数据跑得很好一上生产环境数据量一大就出问题模型在调用比对工具时需要把前三个查询的结果作为参数传进去但三个结果加起来超过了上下文的有效处理范围模型开始编造数据把不存在的差异项也报了出来。这个问题的根源不在于模型能力不够而在于工具调用范式强制要求所有中间数据都经过上下文这个窄管道。数据量一大管道就堵了。后来我改用 Code Mode 重写让模型直接生成一段 Python 代码在沙箱里完成查询、比对、输出数据全程不经过上下文问题迎刃而解。这就是范式转移的现实驱动力。3. Code Mode 到底是什么核心机制拆解3.1 一句话说清 Code Mode 的本质Code Mode 的核心思想可以用一句话概括让 Agent 把要做的事写成代码在受控环境里执行而不是把要做的事拆成一次次工具调用。模型不再输出调用哪个函数而是输出一段完整的、可执行的程序这段程序里可以包含任意逻辑——循环、条件判断、数据处理、甚至调用其他库。这个转变看起来只是输出格式的变化但带来的影响是深远的。工具调用是离散的、一次一步的Code Mode 是连续的、一次一段的。前者像用遥控器一个键一个键地操作后者像直接写一个脚本让电脑自己跑完。3.2 执行环境沙箱是 Code Mode 的地基Code Mode 能成立的前提是有一个安全、隔离、可控的执行环境。模型生成的代码不能直接在宿主机上跑否则一个死循环或者一个误删操作就可能造成灾难。所以沙箱是整个方案的地基。我实际用过的沙箱方案有几类轻量级的是进程级隔离用子进程加资源限制跑代码中等的是容器级隔离每个任务起一个容器重量级的是虚拟机级隔离。选哪种取决于你的安全要求和性能要求。对于大多数内部工具场景容器级隔离是性价比最高的选择——启动快、隔离性好、资源可控。沙箱需要配置几个关键限制执行超时防止死循环、内存上限防止内存爆炸、网络访问控制决定代码能不能访问外部、文件系统隔离防止读写敏感文件。这几个参数配不好要么不安全要么不好用。我一般会把超时设在 30 秒到 2 分钟之间内存给 512MB 到 2GB网络默认关闭需要时按白名单开放。3.3 代码生成模型需要什么样的提示Code Mode 对提示词的要求和工具调用完全不同。工具调用时代你要把每个工具的名称、描述、参数 schema 都写清楚让模型去选。Code Mode 时代你要告诉模型的是你能用哪些库、环境里有什么数据、输出格式是什么、有哪些限制。我总结的提示词结构是这样的先说明任务目标再列出可用的库和它们的能力然后给出环境约束比如不能访问网络只能读取 /data 目录最后明确输出要求比如把结果写到 /output/result.json。这个结构比工具调用的 schema 描述更接近给一个程序员派活的方式。有个关键细节要给模型提供足够的示例。纯文字描述库的用法模型容易用错 API。我一般会在提示里塞两三个简短的代码示例展示典型的数据读取、处理和输出方式。实测下来有示例的情况下代码一次跑通的概率能从 60% 提升到 85% 以上。3.4 结果回传只传结论不传过程Code Mode 相比工具调用最大的优势之一就是结果回传的瘦身。工具调用模式下每一步的中间结果都要回到上下文Code Mode 模式下代码在沙箱里跑完只有最终结果回到上下文。中间产生的所有临时数据、循环变量、调试信息全部留在沙箱里不占用宝贵的上下文空间。这个特性带来的直接好处是任务复杂度不再受上下文窗口的严格限制。你可以让 Agent 处理一个包含十万行数据的文件只要最终输出是一个几百字的摘要上下文压力就很小。这在工具调用范式下几乎不可能实现。3.5 和工具调用不是替代关系而是分层关系这里要澄清一个常见的误解Code Mode 不是要完全取代工具调用。实际上很多 Code Mode 的实现里代码本身就可以调用工具——只不过调用发生在代码内部而不是由模型在上下文里决策。比如代码里可以import requests去调 API可以import pandas去处理数据这些工具是以库的形式存在的。所以更准确的理解是工具调用是 Code Mode 的一个子集。Code Mode 把选择工具这个动作从模型的上下文推理下沉到了代码的逻辑里。模型只需要写对代码代码里的工具调用是确定性的、可测试的、可复现的。这比让模型在上下文里猜该调哪个工具要可靠得多。4. 实操从零搭一个 Code Mode Agent4.1 整体架构设计我以一个数据分析助手为例完整走一遍 Code Mode Agent 的搭建过程。这个助手的功能是接收一个数据文件路径和一个分析需求生成分析代码在沙箱里执行返回分析结果。整体架构分四层接入层负责接收用户请求和返回结果编排层负责调用模型生成代码、管理沙箱生命周期沙箱层负责安全执行代码数据层负责提供代码需要访问的数据。这四层里编排层和沙箱层是 Code Mode 特有的也是重点。我选择用 Python 作为代码生成的目标语言因为它的数据处理生态最成熟模型对它的掌握也最好。沙箱用容器实现每次任务起一个临时容器跑完就销毁。数据通过只读挂载的方式提供给容器代码只能读不能写原始数据输出写到单独的目录。4.2 沙箱环境的准备与配置沙箱的 Dockerfile 我一般这样写基础镜像用精简版的 Python 镜像预装常用的数据处理库pandas、numpy 等创建一个非 root 用户来跑代码设置好工作目录。关键是要预装库不能让模型生成的代码去 pip install那样既慢又不安全。FROM python:3.11-slim RUN pip install --no-cache-dir pandas numpy RUN useradd -m sandboxuser USER sandboxuser WORKDIR /workspace启动容器时的参数很关键我列一下我常用的配置docker run --rm \ --network none \ --memory 1g \ --cpus 1 \ --read-only \ --tmpfs /tmp:size256m \ -v /host/data:/workspace/data:ro \ -v /host/output:/workspace/output:rw \ sandbox-image \ timeout 60 python /workspace/script.py这里每个参数都有讲究。--network none彻底断网防止代码外联--memory 1g限制内存--read-only让根文件系统只读只有 /tmp 和 output 可写timeout 60是双保险容器层面和命令层面都设超时。这套配置我用了大半年稳定性很好。4.3 代码生成提示词的设计提示词是 Code Mode 的灵魂。我用的模板大致是这样的结构分五个部分第一部分是角色和任务你是一个数据分析代码生成器根据用户需求生成 Python 代码。第二部分是环境说明代码将在隔离沙箱中执行无网络访问可读取 /workspace/data 目录结果写入 /workspace/output。第三部分是可用库可使用 pandas、numpy禁止使用其他未列出的库。第四部分是输出要求代码必须将最终结果以 JSON 格式写入 /workspace/output/result.json。第五部分是示例给两三个典型任务的代码示例。这个模板的关键在于约束明确。模型最怕的是模糊指令你越明确地告诉它边界在哪它生成的代码越靠谱。我特别强调禁止使用其他库因为模型有时候会自作主张 import 一些环境里没有的库导致执行失败。4.4 执行流程与错误处理完整的执行流程是这样的用户提交需求 → 编排层组装提示词 → 调用模型生成代码 → 代码写入临时文件 → 启动沙箱容器执行 → 收集输出 → 返回结果。这个流程里错误处理是最容易被忽视但最重要的环节。代码执行失败的原因主要有几类语法错误、库使用错误、数据格式不符、超时、内存溢出。我的处理策略是分级重试语法错误和库使用错误把错误信息回传给模型让它修正代码最多重试两次数据格式不符检查数据本身超时和内存溢出直接返回失败不重试因为重试大概率还是失败。这里有个经验把沙箱的 stderr 完整回传给模型。模型看到具体的报错信息修正代码的准确率很高。我实测过第一次执行失败后把 traceback 回传第二次成功的概率在 70% 左右。如果不回传错误信息只是说执行失败模型基本靠猜成功率不到 30%。4.5 一个完整的代码示例假设用户需求是统计销售数据中每个品类的总金额找出金额最高的三个品类。模型生成的代码大概是这样import pandas as pd import json df pd.read_csv(/workspace/data/sales.csv) summary df.groupby(category)[amount].sum().reset_index() summary summary.sort_values(amount, ascendingFalse).head(3) result { top_categories: summary.to_dict(records), total_amount: float(df[amount].sum()) } with open(/workspace/output/result.json, w) as f: json.dump(result, f, ensure_asciiFalse)这段代码在沙箱里跑完只有 result.json 的内容回到上下文原始数据完全没进上下文。如果数据文件有十万行工具调用范式下根本处理不了Code Mode 下毫无压力。这就是范式的力量。5. 常见问题与排查技巧实录5.1 代码生成质量不稳定的排查最常见的问题就是模型生成的代码时好时坏。同样的需求有时候一次跑通有时候反复失败。排查这个问题我一般从三个方向入手。先看提示词是否足够具体。模糊的需求描述是代码质量不稳定的头号原因。比如分析一下数据这种需求模型每次理解都不一样。解决办法是把需求拆解成明确的输入、处理、输出三要素。再看示例是否覆盖了典型场景。如果示例太少或者太偏模型遇到新场景就容易翻车。我的经验是至少给三个示例覆盖读取、处理、输出三个环节而且示例要贴近实际任务的复杂度。最后看模型参数。温度设太高代码随机性大设太低又可能陷入固定模式。我一般把温度设在 0.2 左右兼顾稳定性和灵活性。5.2 沙箱执行超时的处理超时是另一个高频问题。代码逻辑没问题但就是跑不完。原因通常是数据量太大或者算法效率太低。我的处理分两步先看是不是数据量的问题如果是考虑在代码里加采样或者分块处理再看是不是算法问题比如用了嵌套循环处理大表这种情况引导模型用向量化操作。有个技巧很管用在提示词里明确数据规模。告诉模型数据文件约 50 万行模型就会倾向于选择高效的写法。如果不告诉它它可能按处理几百行的思路写代码一上大数据就超时。5.3 数据格式不匹配的排查数据格式问题也很常见。模型假设 CSV 有表头实际文件没有模型假设日期是标准格式实际是各种奇怪的写法。这类问题的根源是模型看不到真实数据。解决办法是在提示词里提供数据样例。取前几行数据作为示例塞进提示模型就能根据实际格式写代码。这个改动看似简单但能消除大部分格式相关的失败。我一般会取 3 到 5 行样例既能说明格式又不占太多上下文。5.4 常见问题速查表问题现象可能原因排查方向解决技巧代码语法错误提示词模糊、模型理解偏差检查提示词明确性回传 traceback 让模型修正执行超时数据量大、算法低效确认数据规模提示词中说明数据量内存溢出一次性加载大文件检查读取方式引导分块读取结果为空数据格式不符对比实际数据格式提示词中提供数据样例库导入失败使用了未预装的库检查 import 语句提示词中明确可用库输出格式错误输出要求不明确检查输出约束明确 JSON schema5.5 几个我踩过的坑第一个坑是沙箱里没有时区信息。有次处理时间数据代码里用了本地时间沙箱默认 UTC结果差了好几个小时。后来我在沙箱里统一设成 UTC并在提示词里说明问题解决。第二个坑是浮点数精度。财务数据用 float 处理累加之后出现了精度误差。后来改成用 Decimal并在提示词里强调财务数据要用 Decimal。第三个坑是并发执行时的资源竞争。多个任务同时跑共享的输出目录互相覆盖。解决办法是每个任务用独立的输出目录用任务 ID 区分。6. 范式转移背后的深层影响6.1 对 Agent 开发者的能力要求变了从工具调用到 Code Mode对开发者的能力要求发生了明显变化。工具调用时代核心能力是把任务拆解成工具能完成的步骤考验的是流程设计能力。Code Mode 时代核心能力变成了把任务描述成代码能理解的规格考验的是需求表达和约束设计能力。这个变化意味着Agent 开发者需要更懂编程——不是自己写代码而是理解代码的边界、性能特征、常见陷阱这样才能设计出好的提示词和沙箱约束。我身边做得好的 Agent 开发者往往都有扎实的编程背景这不是巧合。6.2 对系统架构的影响Code Mode 让 Agent 系统的架构重心从工具编排转向了执行环境管理。工具调用时代架构的核心是工具注册、路由、参数校验Code Mode 时代核心变成了沙箱管理、资源调度、安全隔离。这是一个从逻辑层到基础设施层的重心转移。这个转移带来的直接后果是Agent 系统对基础设施的依赖变重了。你需要容器编排、需要资源监控、需要安全审计。对于小团队来说这可能是个门槛。但好消息是这些基础设施都有成熟的方案可以复用不需要从零造轮子。6.3 对任务复杂度的解放最让我兴奋的是 Code Mode 对任务复杂度的解放。工具调用范式下任务复杂度受限于工具数量和上下文窗口天花板很明显。Code Mode 范式下只要代码能写出来任务复杂度几乎没有上限。你可以让 Agent 处理一个需要几十步、涉及大量数据的任务只要最终输出是精简的。这个解放意味着 Agent 能做的事情范围大大扩展了。以前只能做问答式的轻任务现在可以做工程式的重任务。我最近用 Code Mode 做了一个自动化的数据清洗流水线处理逻辑有十几步涉及多个数据源的合并和转换在工具调用范式下根本不敢想Code Mode 下跑得很稳。6.4 安全边界需要重新思考Code Mode 带来能力解放的同时也带来了新的安全挑战。工具调用时代模型能做的事情被工具列表严格限制安全边界清晰。Code Mode 时代模型能写任意代码安全边界转移到了沙箱的隔离能力上。这就要求我们在沙箱配置上更加谨慎。网络访问、文件系统、系统调用每一个都要仔细权衡。我的原则是默认全部关闭按需最小开放。宁可功能少一点也不能让安全出问题。毕竟一个能执行任意代码的 Agent如果沙箱有漏洞后果是灾难性的。7. 我个人的一些实践体会做了大半年的 Code Mode 项目有几个体会想分享。第一个是不要追求一步到位。刚开始我总想让模型一次生成完美的代码结果提示词越写越复杂效果反而不好。后来改成先生成、再修正的两段式第一段生成基础代码第二段根据执行结果修正整体成功率反而更高。第二个是沙箱的日志要留全。每次执行的代码、输入、输出、错误信息全部记录下来。这些日志在排查问题时价值巨大而且积累多了还能用来优化提示词——看看哪些错误反复出现就在提示词里提前规避。第三个是不要迷信模型能力。Code Mode 再强模型也有它不擅长的领域。复杂的算法、特定的业务逻辑、需要领域知识的处理模型生成的代码往往需要人工审核。我的做法是在关键任务上加一道人工确认模型生成代码后先给人看一眼确认没问题再执行。这个环节看起来降低了自动化程度但实际提升了整体可靠性。最后分享一个小技巧给模型提供代码模板。对于重复性高的任务我会准备几个代码骨架让模型在骨架上填充逻辑而不是从零生成。这样生成的代码结构统一可维护性好出错率也低。这个技巧在处理批量任务时特别管用值得一试。
