AI Agent范式转移：从工具调用到Code Mode的实战指南

1. 范式转移：不只是"多了一个按钮"这么简单

如果你最近半年一直在关注 AI Agent 相关的开发进展，大概会注意到一个明显的变化：各家产品都在往同一个方向使劲，从"让模型调用工具"变成"让模型直接写代码、跑代码、改代码"。这个变化来得很快，快到很多人还在把 Agent 当成"会调 API 的聊天机器人"时，新一代的产品已经把代码执行环境直接嵌进了推理流程里。

我最早接触"工具调用"（Function Calling / Tool Use）是在两年前。那时候的思路很清晰：模型不擅长计算，就给它一个计算器工具；模型不擅长查天气，就给它一个天气 API。整体架构像一个"大脑配手脚"的方案——模型负责理解意图、拆解任务，然后通过调用外部工具来补足自身能力的短板。这个思路本身没有错，而且确实解决了很多实际问题。但用久了你会发现一个尴尬的现状：工具是死的，任务是活的。你永远在"预先定义工具 → 模型在有限集合里挑选 → 执行并返回结果"这个循环里打转。遇到没定义过的场景，模型就只能干瞪眼。

Code Mode（代码模式）的出现，本质上是在回答一个问题：**与其给模型一万个预设工具，不如给它一个能自己创造工具的沙盒。**代码本身就是最通用的工具。当模型可以在沙盒环境里自由地写 Python、跑脚本、安装依赖、读取文件、调试报错，它其实就不再受限于你预先定义的工具列表了。它可以针对一个从没见过的任务，现场写一段代码来生成一个临时工具，用完即弃；也可以写一个复杂的多步骤脚本，把之前需要几十次工具调用的流程压缩成一次执行。

这是一个非常深刻的转变：**从"调用工具"到"创造工具"。**前者是使用者思维，后者是工程师思维。过去我们训练模型去理解"哪个工具适合当前任务"，现在我们在训练模型去理解"如何用代码解决当前问题"。两者的复杂度完全不在一个量级上。

这篇文章我想结合自己的实战经历，把这次范式转移的核心逻辑、技术架构变化、实际落地效果以及踩过的坑，完整地捋一遍。适合正在做 Agent 开发、或者准备把业务接入 Agent 能力的朋友参考。不管你现在用的是哪家的模型或框架，这篇文章里的思路应该都能帮你理解为什么"代码优先"正在成为下一代 Agent 的标配。

2. 为什么工具调用模式撑不住了

2.1 工具调用的本质是"有限选项的排列组合"

我们先把工具调用模式拆开来看。无论在哪个平台上实现，工具调用的核心流程几乎都是这样：

1. 开发者预先定义一批工具函数，每个函数有名称、描述、参数 schema。
2. 模型根据用户输入，从这批函数中挑一个或多个，并生成结构化的参数。
3. 外部系统执行这些函数，把结果返回给模型。
4. 模型基于返回结果继续推理，必要时再调用下一轮工具。

这套流程最大的问题，我总结为三个字：不够用。

举个例子。假设你做一个数据分析 Agent，你定义了读取 CSV、计算均值、绘制图表这三个工具。用户来了一个需求："帮我分析一下销售数据，看看哪个区域的增长率最异常，顺便做一个可视化。"模型会怎么处理？它先调用读取 CSV，再调用计算均值，再调用绘图……每个步骤都需要一次模型推理，每次都走一遍"意图理解 → 工具选择 → 参数生成 → 执行 → 结果解析"的完整链路。三次工具调用，三次往返延迟，而且这还是最简单的场景。

如果用户的需求再复杂一点："把上个月和这个月的数据做同比，按产品线拆分，找出下降超过 10% 的品类，并生成一份 PDF 报告。"你会发现工具列表根本不够用——你需要写一个新的工具来做"生成 PDF"，需要另一个工具来做"同比计算"，可能还需要一个工具来处理"数据清洗"。每一个新需求都意味着开发者要手动扩展工具列表。长期维护下来，工具的数量会爆炸，而每个工具的逻辑又很难复用。

工具调用模式的另一个隐藏成本是上下文污染。每次工具调用返回的结果都要塞进对话历史里。如果工具返回的是一个巨大的 JSON，比如 1 万行数据，那么这些内容都会占据上下文窗口，而且在下一次推理时还会被模型重新"读"一遍。我在实际项目中遇到过上下文被工具返回结果撑爆的情况，最后只能做截断，但截断又会丢失关键信息，两头不讨好。

2.2 硬编码工具链：维护噩梦和天花板

工具调用模式的本质，是"开发者把解决方案写死，模型负责搬运"。这就带来一个天然的瓶颈：Agent 的能力上限不会超过开发者预定义的工具上限。

你需要 Agent 能从网页抓数据？你得先写一个网页抓取工具。需要它操作 Excel？你得先写一个 Excel 处理工具。需要它调用公司内部 API？你得先写一个鉴权封装工具。每一个都是工作量，而且这些工具往往是一锤子买卖——这个项目里能用，换个项目就废了。

更头疼的是组合爆炸。真实业务需求几乎很少是单个操作能解决的，通常是"先 A 再 B 然后如果 C 就 D"。在硬编码工具的模式下，你只能在代码里写死这些流程分支，或者寄希望于模型能聪明地把多个工具串起来。但模型串工具的能力参差不齐，一旦中间某一步返回了预期之外的格式，整个流程就崩了——模型会开始"编造"工具返回结果，或者反复尝试同一个失败的调用，浪费大量 token。

我在某个内部项目里统计过，在工具调用模式下，一个 5 步以内的任务，成功率大概是 70% 左右。每次失败几乎都集中在"步骤之间数据格式不匹配"或者"工具返回内容超出预期"。后来迁移到 Code Mode，同样的任务成功率直接拉到 90% 以上。这不是模型变强了，而是代码模式天然具备容错性和灵活性——模型可以读取失败信息、现场修改代码、重新执行，这比"重新调用一次工具"要可靠得多。

2.3 一个真实对比：工具调用 vs Code Mode

为了更直观地说明差异，我在本地搭了个实验环境，同一个任务分别用两种模式跑了一遍。任务描述是：

读取当前目录下的 sales.csv 文件，统计每个月的总销售额，找出环比增长最高的月份，并把结果保存成 result.md。

工具调用模式下，我需要预先定义四个工具：读取文件、解析日期、聚合统计、写 Markdown。模型经过四轮工具调用完成了任务，耗时约 40 秒，Token 消耗约 8000，其中数据读取结果占了很大一部分上下文。

Code Mode 下，模型直接生成了一段 Python 脚本，用 pandas 一次性完成读取、聚合、环比计算、写文件全部操作，然后我在沙盒里执行。脚本本身约 30 行，执行耗时不到 2 秒，Token 消耗约 3000，其中大部分是模型在写代码时生成的，上下文里没有多余的数据污染。

两组数据的对比非常明显。更关键的是，在 Code Mode 下如果模型生成的脚本报错了，它可以读取错误信息、修改代码、重新执行，整个过程在沙盒内部闭环完成，不需要和外部系统反复交互。这种"自我纠正"的能力，在工具调用模式下很难实现，因为你每修一次就得重新走一遍"调用外部工具"的完整流程。

3. Code Mode 的核心架构与设计逻辑

3.1 沙盒执行环境：Agent 的"练功房"

Code Mode 的落地，首先需要一个可靠的代码执行沙盒。这不是简单地给模型一个终端，而是要在安全隔离的基础上，让模型拥有"写代码 → 跑代码 → 看结果 → 改代码"的完整循环能力。

沙盒的设计有几个关键考量。第一是资源隔离。模型生成的代码可能是恶意的，也可能只是无意中写了死循环或者内存爆炸的脚本，如果没有资源限制，一个 Ctrl+C 都拦不住的进程可能会拖垮整台机器。常见的做法是用容器或者虚拟机级别的隔离，限制 CPU、内存、磁盘和网络访问。第二是依赖管理。模型要跑数据分析就得装 pandas，要做爬虫就得装 requests。沙盒需要支持按需安装依赖，而且要快——每次重新创建环境显然不现实，所以最好是持久化的、可快照恢复的执行环境。第三是文件系统访问范围。模型应该只能读写指定工作目录下的文件，不能碰宿主机上的敏感数据。

就我自己的实践来说，用 Docker 容器做沙盒是目前最省心的方案。每个 Agent 实例配一个专属容器，挂载一个临时工作目录，限制网络白名单。容器内部预装 Python 环境和常用库，其他依赖在运行时通过 pip 按需安装。模型的每次代码执行都通过一个执行接口提交到容器里，输出（stdout/stderr）和返回状态再传回模型，形成闭环。

3.2 代码生成 → 执行 → 反馈循环：Agent 的"自我迭代"

Code Mode 和简单"让模型写一段代码给你"最大的区别在于，模型能看到自己代码的执行结果，并根据结果继续修改。这是整个机制的灵魂。

我把这个循环称为"写→跑→看→改"四步循环：

1. 写：模型根据当前任务和上下文，生成一段代码（通常是 Python 脚本）。
2. 跑：代码在沙盒中执行，系统捕获 stdout、stderr、退出码和运行时长。
3. 看：执行结果反馈给模型。如果成功，模型检查输出是否符合预期；如果失败，模型看到报错信息。
4. 改：模型基于反馈修改代码、调整逻辑、修复 bug，然后重新执行。

这个循环看起来简单，工程上有很多细节需要打磨。关键是"看"这一步的反馈质量。如果只是把 stdout 和 stderr 原样丢给模型，很多情况下信息是不够的。比如一个脚本运行了 30 秒还没结束，模型不知道是死循环还是正常计算——这时候就需要超时机制来打断，并把"运行超时"的提示作为反馈传给模型，引导它优化逻辑。再比如脚本运行时安装了额外的依赖，系统应该把"已安装 xxx 包"这类状态变更也通知到模型，否则它可能不知道新的库已经可用了。

我在实践中发现，反馈信息的颗粒度直接决定了模型的自我迭代效率。反馈太粗（比如只有"执行失败"），模型只能瞎猜哪里错了；反馈太细（比如把整个 10 万行的 traceback 都丢过去），又会浪费上下文空间，还可能让模型被无意义的报错细节带偏方向。比较好的做法是把错误信息做摘要处理，提取出错误类型、关键堆栈和出错行号，再附上标准输出的末尾几行。

3.3 从"一次性脚本"到"Code 智能体"：多文件项目能力

当 Code Mode 只停留在"生成一段脚本、执行、结束"这个层面时，它的威力还没有完全发挥出来。真正的升级是让模型可以持续维护一个代码项目——不仅写代码，还能创建多个文件、修改已有文件、组织项目结构，像一个真正的工程师一样工作。

举个例子，如果用户的需求是"写一个 Flask 应用，提供三个 API 接口，每个接口要做参数校验和错误处理"，单纯的一次性脚本模式只会得到一个散装代码片段，需要用户自己去整合。而在项目级的 Code Mode 下，模型会先规划目录结构：

my_app/ ├── app.py ├── routes/ │ ├── __init__.py │ ├── api_v1.py │ └── api_v2.py ├── utils/ │ ├── validators.py │ └── logger.py ├── tests/ │ └── test_api.py └── requirements.txt

然后逐个文件生成内容，跑测试，修 bug，最终交付一个可以直接启动的完整项目。这个能力目前在部分框架中被称为"Code Agent"或"Code Interpreter"，实现逻辑不算复杂——本质上就是给模型提供"创建文件""写入内容""读取文件""列出目录"这几个原生的代码操作工具，然后让模型自由组合。但体验上的差距是巨大的：从"给你一段代码"变成"给你一个能跑的工程"，这中间的跨越比想象中大得多。

我在实际项目中用这个能力做过一个内部工具网站，需求描述、原型参考、代码生成到部署上线，总共不到半天。生成的代码质量肯定比不上专业工程师的反复打磨，但作为内部工具已经完全够用。这个体验让我意识到，Code Mode 的真正潜力不在于"写一段脚本完成任务"，而在于"作为虚拟工程师，持续迭代一个项目"。

4. 用 Code Mode 实战：从零搭一个数据自动化 Agent

4.1 场景需求与方案设计

理论说了不少，还是落到一个具体的实战项目上。我最近在帮一个团队做一个"自动生成周报"的 Agent，需求大概是这样：

• 每周自动从数据库里拉取业务数据；
• 分析关键指标的变化趋势，找出异常点；
• 生成一份图文并茂的 Markdown 周报，重点突出问题和建议；
• 把周报推送到内部的文档系统。

这个任务用传统工具调用模式来做，需要预先定义至少七个工具：数据库查询、数据聚合、异常检测、图表生成、Markdown 模板填充、文档上传、定时触发。每一个工具都要写单独的代码，维护成本不低。而且"异常检测"和"图表生成"这类工具的通用性很差，换个业务场景就得重写。

用 Code Mode 来做的话，整个 Agent 的架构变得异常简洁。我把 Agent 的工作流定义为四个阶段：

1. 拉取数据：模型生成 Python 代码，通过数据库连接串查询最近一周的业务数据。
2. 分析与可视化：模型用 pandas 清洗数据、计算环比和同比指标、用 matplotlib 生成趋势图。
3. 生成周报：模型把分析结果组织成 Markdown 文档结构，嵌入图表路径，生成最终报告文件。
4. 推送与验证：模型调用内部文档 API 上传文件，并检查返回状态确认推送成功。

整个流程的核心驱动是下面这个"执行循环"的接口，我用简洁的伪代码来展示：

def execute_and_feedback(code, sandbox): """ 在沙盒中执行模型生成的代码，并将结构化反馈返回给模型。 """ # 写入代码到沙盒工作目录 sandbox.write_file('agent_task.py', code) # 执行，捕获输出、错误、运行时间和退出码 result = sandbox.run('python agent_task.py', timeout=60) feedback = { 'stdout': result.stdout[-2000:], # 只保留末尾部分，防止过长 'stderr': result.stderr[-2000:], # 错误信息同样截断 'exit_code': result.exit_code, 'timed_out': result.timed_out, 'files_created': sandbox.list_workspace(), # 告诉模型它生成了哪些文件 } return feedback

模型在这个循环里扮演的角色更像一个"远程实习生"——你给它一个任务，它在工作目录里忙活，你只看它的产出和反馈，它遇到问题会自己查阅报错、修改代码、重试。这种交互模式的工程实现其实不大，但体验上比"一次性 API 调用"高级很多。

4.2 执行流程拆解：模型如何一步步完成任务

实际跑起来时，这个 Agent 的执行流程非常有代表性。我把关键步骤拆开来看。

第一步：模型规划代码结构。收到"生成周报"的指令后，模型没有直接开写，而是先输出了一段思考过程，大意是："我需要连接数据库获取原始数据，然后用 pandas 处理，计算周环比和关键指标，再用 matplotlib 画两张图，最后把结果渲染成 Markdown。"这段规划很重要，它决定了后续代码生成的方向。我在设计提示词时会特意强调"先规划，再编码"。

第二步：模型生成数据拉取代码并执行。模型生成的代码大致是这样的：

import pandas as pd import pymysql conn = pymysql.connect( host='db_host', user='agent_user', password='***', database='business_db', charset='utf8mb4' ) query = """ SELECT DATE(created_at) AS day, region, amount FROM orders WHERE created_at >= DATE_SUB(CURDATE(), INTERVAL 7 DAY) """ df = pd.read_sql(query, conn) df.to_csv('weekly_data.csv', index=False) print(f"数据已保存，共 {len(df)} 条记录")

第一次执行时模型忘了在数据库连接串里加字符集参数，导致中文乱码。但因为它能看到 stdout 里的乱码输出和数据库返回的警告信息，它自己就加上了charset='utf8mb4'和connect_timeout=10，第二次执行就成功了。这个修正过程完全不需要我介入，这就是 Code Mode 最珍贵的"自我纠错"能力。

第三步：数据分析和异常检测。模型加载 CSV，按天和地区做透视表，计算环比变化率。然后它用了一个比较朴素但有效的方法来定义"异常"：环比超过正负 15% 的地区，或者绝对值超过平均值两倍标准差的指标点。代码逻辑不复杂，但胜在自定义程度高——这个逻辑如果做成工具，服务端很难设计得这么灵活。

w = pd.read_csv('weekly_data.csv', parse_dates=['day']) w['day'] = w['day'].dt.strftime('%Y-%m-%d') pivot = w.pivot_table(index='day', columns='region', values='amount', aggfunc='sum') pct_change = pivot.pct_change(fill_method=None).replace([float('inf'), -float('inf')], 0) abnormal = pct_change[pct_change.abs() > 0.15].stack() print("异常区域和日期：") print(abnormal)

第四步：生成图表和 Markdown 报告。模型用上次生成的weekly_data.csv画了两张图：一张按地区分组的 7 天趋势折线图，一张全国销售额的周环比柱状图。随后把图表链接和异常分析结果嵌进 Markdown 模板，生成了一份相对完整的周报初稿。这里面一个值得注意的细节是：模型并没有一次性生成"完美的周报"，而是先生成一个"差不多"的版本，在后续反馈里发现缺了一个汇总表格后，又补了一段代码来完善。

整个任务从开始到最终交付报告，模型一共生成了 6 轮代码，前 2 轮是为了完成数据拉取和分析，第 3 轮报了错，第 4 轮修复，第 5 轮生成图表，第 6 轮推送文档。总耗时约 4 分钟，Token 消耗约 1.5 万。相比工具调用模式需要开发者手动维护工具集，这个开发成本基本降到了零。

4.3 沙盒细节配置：内存、超时与依赖管理

Code Mode 跑得顺不顺，沙盒配置占了很大的决定因素。我在几轮迭代里把沙盒的参数调成了这样：

这里尤其要提一下超时机制。模型写的代码偶尔会出现死循环，或者某个网络请求一直等不到响应。如果不加超时，整个 Agent 会被卡住，而且模型拿不到任何反馈，只能一直等。设了超时后，每次执行最多 60 秒，超时信息作为反馈返回给模型，它通常会很快意识到问题并重写逻辑。这个机制是 Code Mode 稳定性的兜底保障。

依赖管理也是一个容易被忽略的点。沙盒预装不了所有库，所以模型常常会生成pip install xxx的命令。我在沙盒里做了一个小优化：拦截 pip install 调用，在后台安装的同时把安装日志的结尾返回给模型，这样它知道依赖正在安装、以及安装完成后可以立即使用。实测下来，依赖安装的成功率很高，模型很少会因为"找不到模块"而无脑重试。

5. 踩坑实录与性能对比：哪些地方容易翻车

5.1 我踩过的四个典型坑

Code Mode 虽然强大，但绝不是"放进去就能用"的银弹。这几轮实战下来，我踩了不少坑，挑四个最典型的分享出来。

第一个坑是模型的代码风格不稳定。同一个模型，有时候生成的是整洁的函数封装型代码，有时候是散装的脚本型代码。在短任务里这无所谓，但在长任务里，如果模型在后续步骤中需要复用前一步的结果，散装代码往往会导致变量名拼写不一致、重复计算等低级错误。我的解决办法是在系统提示词里明确要求"用函数组织代码，把每个步骤封装成独立的函数，并在 main 函数中调用"。这样即使模型某个函数写错了，它可以在后续迭代中只修这一个函数，影响范围可控。

第二个坑是反馈信息的截断策略太激进。最开始我把 stdout 限制在末尾 500 字符，结果模型经常因为看不到完整的报错堆栈而反复猜测。后来调整到 2000 字符，并把"错误类型和堆栈摘要"优先保留，体验好了很多。实际上不同任务的反馈长度需求不同，我现在的做法是：成功时返回 stdout 末尾 1000 字符；失败时优先返回 stderr 的前 500 字符和末尾 1500 字符——前面定位错误类型，后面看完整堆栈。

第三个坑是临时文件管理混乱。模型跑数据任务时会生成各种中间文件：清洗后的数据、图片、日志、缓存。如果每次执行都在同一个工作目录里累积，很快就会堆满，而且模型自己也会被搞混，不知道现在目录里哪个文件是最新版本。后来我在每个"会话"开始时创建一个新工作子目录，并把"清空工作目录"作为每个任务起点的默认操作。模型在上下文中能看到当前目录结构，这样一来文件管理变得清晰很多。

第四个坑是模型在"自我纠错"时容易陷入无限循环。有一次模型生成的代码一直报一个第三方库的兼容性错误，它连续试了 5 次修改方案，全都不行。最后我加了一个"最大重试次数"的硬限制——每次任务最多 8 轮代码执行，超过就强制转向"向用户求助"，而不是继续空转。这个保护机制很重要，不然一次复杂任务可能空耗十几轮对话，Token 和时间都浪费了。

5.2 对比数据：Code Mode 的实际提效幅度

我在同一个数据集上，用工具调用模式和 Code Mode 各跑了一遍前面提到的"周报生成"任务，记录的对比数据很有参考价值：

当然，这个对比只是一个内部项目的参考数据，不同任务类型、不同模型配置下的结果会有差异，但趋势是很明确的：Code Mode 在灵活性和效率上都有数量级的优势。

需要说明的是，这并不意味着工具调用模式完全没有价值。在需要精确控制行为、强约束输出格式、与企业内部系统深度集成的场景里，预先定义工具仍然是更可靠的选择。比如金融交易场景，你肯定不希望模型"现场写代码"去下单，而是希望它能调用一个经过严格审核的交易 API。工具调用的"确定性"和 Code Mode 的"灵活性"之间，没有绝对的好与坏，只有适合与不适合。

6. 从 Code Mode 到更远的未来：Agent 能力边界的扩展方向

Code Mode 带来的范式转移，目前还只是开始。我观察到的几个有意思的演进方向，值得所有做 Agent 的人提前关注。

第一个方向是沙盒内自我进化。当前的 Code Mode 还停留在"模型为每个任务临时写代码"的阶段，但下一步很可能是让模型在沙盒内沉淀工具库——它自己写完的一段高质量代码，可以被抽象成通用工具，存进工具库，下次遇到类似任务直接加载。这其实是把"即时生成的代码"变成了"可复用的长期资产"。从工程视角来看，这就像给 Agent 装了一个"成长型工具箱"，越用越强。

第二个方向是多模态执行环境。现在的沙盒大多只能跑 Python 代码，但 Agent 的想象空间早就超出文本和数值了。未来的沙盒应该能跑 HTML/JavaScript 渲染出的网页，能操作图像处理软件，能生成和编辑视频，甚至能连接外部仿真环境。模型不只是写 Python 脚本，而是操作一个完整的"数字工作台"。

第三个方向是人机协同的代码审查机制。当模型可以自主写代码、改代码时，代码质量和安全性就成了必须正面处理的问题。一些团队已经在尝试让模型在完成代码后，自己生成测试用例并跑测试，再生成代码审查意见。虽然模型自审自测肯定会有盲区，但能在一定程度上兜住低级错误。我预期后面会有更多"AI 写代码 → AI 测试 → AI 审查 → 专家审核"的流水线玩法出现。

对我个人来说，Code Mode 最打动我的不是"它能写代码"，而是"它愿意看着自己写的代码跑起来，然后根据结果不断改"。这种踏实劲儿，比很多只会嘴上计划、手上不动的人要靠谱得多。如果你也在做 Agent 相关的东西，我强烈建议你别只在"让模型调用工具"这个层面打转，早点拥抱 Code Mode——让模型亲手写代码、亲手调试，你会看到另一个量级的可能性。

最后分享一个小技巧：在设计你的 Agent 反馈循环时，把"执行结果摘要"做得结构化一些——比如统一用状态: 成功/失败, 关键信息: ..., 建议下一步: ...这样的格式返回给模型。模型对这种结构化反馈的利用率，远高于对一段自由散漫的日志的利用率。这个小改动，实测能把自我纠错的成功率再拉高 10% 左右。