前言：当智能体需要“动手”

你已经能让AI做判断了

从第一部**《智能体工程化实战：从“写Prompt”到“造智能体”》**走过来，你已经掌握了一套完整的工程化方法。

你知道怎么为智能体定义评测规范，怎么构建黄金标准测试集，怎么用AI帮你生成Prompt和运行脚本，怎么搭建评测体系，怎么基于数据做迭代优化。你用Claude Code和Trae分别实现过同一个项目，亲眼验证了“范式是永恒的，工具只是载体”。

你的项目目录里有一套完整的工程资产——规范文档、测试集、Prompt模板、评测脚本、迭代记录。你完成过一个企业级多智能体PRD评审系统，它可以直接写入你的简历。

你会做判断型Agent了。评论甄别、内容审核、需求评审——输入一段文本，输出一个判定，这类任务你已经驾轻就熟。

现在，是时候往上走一层了。

判断型Agent的边界在哪里？

第一部的智能体有一个共同特征：它们只能“说”，不能“做”。

评论甄别Agent能告诉你这条评论有没有参考价值，但它不能帮你去电商平台自动筛选评论。PRD评审Agent能分析需求文档的缺陷，但它不能帮你把修改后的文档保存到项目仓库。

更重要的是，面对需要外部信息的任务，纯推理Agent完全无能为力。

你让它分析一份期末考试成绩单。你给了它一个CSV文件，里面是全班50个学生的各科成绩。你问它：“哪些学生需要补考？各科平均分是多少？成绩波动最大的学生是谁？”

它只能回答：“你可以使用pandas库读取CSV文件，然后用mean()计算平均分，用条件筛选找出低于60分的学生……”

它对答如流，但都是废话。它看不到你的数据。 它的训练数据里没有你这个CSV的内容。它无法真正打开文件，无法执行任何一行代码，无法给你一个确切的数字。

你让它生成一份分析报告并保存到桌面。它洋洋洒洒写了几百字，最后补一句：“请将以上内容复制粘贴到文本编辑器中，保存为report.md。”

它是一个优秀的知识库，但它没有手。

什么是工具使用，为什么它是质变

大模型的本质是一个基于训练数据做概率预测的系统。它“知道”很多东西，但它不能跟外部世界交互。它不能读取一个它没见过的文件，不能执行精确的数学计算，不能操作你的电脑，不能查询今天的天气。

工具使用（Function Calling）改变了这个局面。

它的原理是这样的：你给模型描述一堆它可用的工具——“你能调用一个叫read_file的函数，它接收一个文件路径，返回文件内容”；“你能调用一个叫execute_python的函数，它接收Python代码，在沙盒中执行并返回结果”。当用户提出一个任务时，模型自己判断“我该调哪个工具、传什么参数”，然后由代码真正执行这个工具，执行结果再传回给模型，模型整合后输出最终回答。

这个过程的关键词是由代码真正执行。文件不是你让AI“想象”出来的，是代码打开的。计算结果不是AI“估算”的，是Python解释器算出来的。报告不是AI“建议你保存”的，是代码写进磁盘的。

有了工具，智能体从“知识库”变成了“执行器”。从“建议你怎么做”变成了“帮你做掉”。从“说”变成了“做”。

而让智能体能够自己创建新工具——当它发现现有工具箱里缺少某个功能，自己写一段Python代码、保存、注册、然后调用——这会让它从“执行器”再跃升为“自我扩展者”。

这才是AI Agent真正令人激动的形态。

本书要教你什么

第二部是第一部的延续和升级。

工具使用方面，你将学会：

• Function Calling的底层原理——模型如何决定调用哪个工具
• 工具描述规范——怎样写一段让AI能准确理解的工具说明
• 用Trae生成带工具调用的Agent脚本，让Agent能读文件、写文件、执行Python代码
• 构建工具增强型Agent的评测体系——不仅评“输出对不对”，还评“工具选对了吗、参数对了吗”

安全工程方面，你将学会：

• 设计执行沙盒——让AI生成的代码在受控环境中运行，不会损害你的电脑
• 沙盒的安全分层机制——临时文件隔离、超时终止、模块白名单
• 这是在真实企业环境中部署AI Agent的必备工程素养

自建工具方面，你将学会：

• 让Agent发现自己缺少某个功能时，自动生成工具代码
• Agent调用自己的“写文件”工具保存代码，注册新工具，然后调用它
• 一个Agent在多次任务中不断扩展自己的工具箱，能力持续增长

贯穿案例是一个数据分析助手Agent。它从最简单的“读CSV文件→计算平均值→输出结果”开始，逐步获得执行代码、写入文件的能力，最终学会在遇到新需求时自己造工具。这个案例的场景是每一个本科生都熟悉的——处理数据、分析成绩、生成报告。

本书的技术选择

在写这本书的时候，我对技术栈做了三个慎重的决定。

第一，全程只使用Trae一个开发工具。 第一部用了Claude Code和Trae两个工具对比教学，这是为了让你理解“范式通用、工具可替换”。这个认知你已经建立起来了。第二部只保留Trae，因为它有完整的可视化智能体编排、工具注册和评测面板，更适合多工具Agent的开发。

第二，Agent调用的模型选择DeepSeek。 Claude API好，但费用对本科生是一道硬门槛。DeepSeek的API则便宜的多，性价比极高，而且DeepSeek兼容OpenAI的接口格式，用Python的openai库就能直接调用，学习成本极低。

第三，全程极低费用。 Trae的AI辅助功能免费，DeepSeek价格便宜，所有依赖库都是开源的。你唯一需要的是：一台能联网的电脑，和一个DeepSeek开放平台的注册账号。

一个重要区分

在正式开始之前，必须理清一个贯穿全书的概念。这本书涉及两种AI调用，如果你把两者搞混了，后面的学习会很吃力。

Trae内置AI：这是你在开发过程中，Trae IDE自带的AI助手。你写需求，它帮你生成代码。它用什么模型，你不需要关心——这是Trae自动处理的。它就像你写代码时坐在旁边的一个资深程序员。

你的智能体调用的AI：这是你正在开发的Agent程序，在运行时调用的模型。比如数据分析助手Agent收到一个任务，它需要调用DeepSeek API来决定“我该用哪个工具”，然后再调用DeepSeek API来生成最终的分析结果。

简单说：Trae帮你写代码，DeepSeek帮你写的Agent完成任务。 两种调用，两个角色，各干各的。

你在第3章配置DeepSeek的API Key时，就是在为你自己的Agent准备运行所需的“大脑”。Trae自己的大脑已经内置好了，你不需要操心。

第二部如何与第一部衔接

如果你已经完成了第一部的全部实验，你会有一个叫comment-analyzer的项目目录，里面有规范文档、测试集、Prompt模板和评测脚本。那个项目是纯文本判断型的——Agent做的事情就是分析一段文本，输出一个JSON。

第二部的项目是一个全新的仓库。你将创建它，搭建它，让它从简单到复杂地生长。你会再次运用Harness五步法——规范定义、数据构建、Agent开发、自动化评测、迭代优化——但这五步将面对一个新的挑战：当Agent的行为不只是“输出文本”而是“选择工具→调用工具→解释结果”时，怎么定义规范？怎么构建测试集？怎么设计评测？

这些正是第二部要回答的问题。

第一部的工程资产你可以完全复用——规范文档模板、五步法指令模板、评测框架的设计思路，这些在新项目里依然是地基。你不是从零开始，你是在已有的地基上盖一栋更高的楼。

你将产出什么

学完本书，你将拥有：

1. 一个数据分析助手Agent，它能读取CSV和JSON文件，在沙盒中安全地执行Python代码进行计算和分析，将结果写入文件。
2. 一个可自我扩展的Agent框架，Agent在遇到现有工具无法完成的需求时，能够自己生成工具代码、注册工具、调用新工具。
3. 一套工具增强型Agent的评测体系，包含工具调用审计维度和扩展后的GT测试集。
4. 一个结业实战项目——代码仓库健康度分析Agent，可直接用于课程设计、竞赛或求职作品集。
5. 一份不断增长的工程资产库，在第一部的基础上新增了工具定义规范、沙盒安全模块、工具审计Prompt模板。

让我们开始吧

第二部的学习曲线和第一部一样平缓。每一章你都会用Trae的AI对话面板下指令，让AI帮你生成代码，然后你审查、运行、理解它做了什么。你不会被要求手写复杂的Python逻辑，但你会被反复要求理解AI生成的每一段代码在做什么、为什么这样设计。

从第1章开始，你将亲手撞上纯推理Agent的那堵墙，然后亲手用工具把它推倒。

第1章 纯推理智能体的边界

本章你将学到：

• 用第一部的方法快速开发一个“数据分析顾问”Agent
• 亲身体验纯推理Agent在面对真实数据时的无力感
• 理解“知识库”和“执行器”之间的根本区别
• 明确工具使用要解决的核心问题

本章你将产出：一个纯推理型数据分析顾问Agent，以及一次深刻的“它能说但不能做”的体验
全部章节：收录在专栏《AI应用工程化实战教程》之【智能体工具使用实战】

---

1.1 场景：做一个“数据分析顾问”

期末考试刚结束。班长给了你一份CSV文件，里面是全班45个同学的期末成绩。包含学号、姓名、高数、线性代数、Python程序设计、大学英语四列成绩。

你答应帮全班做一个快速分析：各科平均分是多少？哪些同学有科目不及格需要补考？成绩波动最大的学生是谁？

你打开这份CSV，前几行看起来是这样的：

学号,姓名,高数,线代,Python,英语
2024001,张三,78,82,90,75
2024002,李四,55,68,72,80
2024003,王五,92,88,95,91
2024004,赵六,61,59,70,68
...

45行数据，四门课。如果用pandas，几行代码就出结果。但这次你想偷个懒——你刚刚学完第一部，已经会造智能体了。为什么不让AI帮你分析？

你在Trae中打开一个新项目 data-analyst-agent，在AI对话面板里输入了和第一部类似的指令：

请帮我创建一个"数据分析顾问"智能体。

要求：
1. 角色：你是数据分析专家，擅长解读数据、发现问题、给出建议。
2. 输入：用户描述一段数据分析需求，并提供数据的基本信息。
3. 输出：详细的分析结果，包括统计指标、发现的问题、改进建议。
4. 保存为 advisor_agent.py，使用DeepSeek API（openai库，base_url指向DeepSeek）。
5. 包含一个 analyze(user_request, data_description) 函数。

几分钟后，advisor_agent.py 生成了。代码结构和你在第一部写的评论甄别Agent很像——一个系统提示词，一个调用DeepSeek的函数，JSON格式的输出。

你迫不及待地想试试。

---

1.2 第一次尝试：请帮我分析这份成绩单

你写了一段测试脚本：

from advisor_agent import analyze

request = """
我有一份CSV文件 scores.csv，包含全班45个学生的成绩。
列名：学号、姓名、高数、线代、Python、英语。
请帮我计算：
1. 各科平均分
2. 各科最高分和最低分
3. 需要补考的学生名单（任何一科低于60分）
4. 哪位学生的四科成绩波动最大（标准差最大）
"""

data_description = "文件路径：scores.csv，共45行数据，编码UTF-8"

result = analyze(request, data_description)
print(result)

你运行了脚本。Agent的回复很快返回了：

根据您描述的数据结构，我为您提供以下分析思路：

1. 各科平均分计算：
   您可以使用pandas的mean()函数计算每列的平均值。
   示例代码：
   import pandas as pd
   df = pd.read_csv('scores.csv')
   averages = df[['高数','线代','Python','英语']].mean()

2. 最高分和最低分：
   使用max()和min()函数即可。

3. 需要补考的学生：
   使用条件筛选：
   df[(df['高数']<60) | (df['线代']<60) | (df['Python']<60) | (df['英语']<60)]

4. 成绩波动最大的学生：
   计算每行的标准差，使用df.std(axis=1)，然后找到最大值。

建议您直接运行以上代码获取精确结果。

你盯着屏幕，愣住了。

这回答对吗？对。有用吗？没有。

你让它分析数据，它告诉你怎么分析数据。你把数据描述给它，它给你返回了pandas教程。它就像一个只会说“你去查一下XX书第X章”的助教——知识渊博，但不动手。

它没有读取你的CSV文件。它不知道张三高数考了多少分。它给不了一个具体的数字。

---

1.3 第二次尝试：你直接给它数据

你不死心。也许问题出在“你没有给它具体数据”？你把CSV的前10行复制出来，直接粘贴进请求里：

request = """
以下是scores.csv的前10行数据：

学号,姓名,高数,线代,Python,英语
2024001,张三,78,82,90,75
2024002,李四,55,68,72,80
2024003,王五,92,88,95,91
2024004,赵六,61,59,70,68
2024005,孙七,43,55,60,72
2024006,周八,88,90,85,93
2024007,吴九,72,71,68,70
2024008,郑十,95,89,92,88
2024009,陈一,60,61,58,65
2024010,林二,77,80,82,79

请计算这10个人的各科平均分，并指出谁需要补考。
"""

Agent的回复：

根据提供的数据，我手动计算如下：

高数平均分：(78+55+92+61+43+88+72+95+60+77)/10 = 72.1
线代平均分：(82+68+88+59+55+90+71+89+61+80)/10 = 74.3
Python平均分：(90+72+95+70+60+85+68+92+58+82)/10 = 77.2
英语平均分：(75+80+91+68+72+93+70+88+65+79)/10 = 78.1

需要补考的学生（任何一科低于60分）：
- 李四：高数55分
- 孙七：高数43分，线代55分
- 赵六：线代59分
- 陈一：Python 58分

以上为手动计算结果。如需处理全部45行数据，建议使用pandas。

你盯着这些数字，心情复杂。它居然真的算了——像一个认真但不知道有计算器这种东西的人，硬生生手算了一遍。

这暴露了三个问题：

第一，你不可能每次都手动粘贴数据。 10行数据就占了半屏，45行、450行呢？更不用说数据不是CSV而是JSON或者数据库的情况。

第二，它会算错。 你又核对了一遍——Python平均分应该是77.2吗？你用计算器重新加了一遍：90+72=162，+95=257，+70=327，+60=387，+85=472，+68=540，+92=632，+58=690，+82=772。772/10=77.2。这次它算对了。但下次呢？如果你给的是50行数据，你能逐条核验吗？大模型做精确数学计算本身就不稳定——它本质上是“预测下一个token”，不是“执行浮点运算”。

第三，更根本的问题：你让它分析数据，它却成了数据本身的中转站。 你从文件里读数据，贴给AI，AI“算”完再告诉你。整个过程里，真正的执行者还是你——是你在打开文件，是你在复制粘贴，是你在核验结果。AI只是一个说话很有条理但手被绑住的参谋。

---

1.4 停下来，思考：到底缺了什么？

回顾你刚才的经历，你会发现一个清晰的边界线。这条线的一边，是纯推理Agent能做到的事；另一边，是它永远做不到的事。

它能做的：基于训练数据中的知识，给出建议、写出示例代码、解释概念。它的脑子里装着整个pandas文档，能告诉你每条命令怎么用。

它不能做的：

• 读取文件——它看不到你的硬盘上有什么。它不能在文件系统里打开 scores.csv 然后读取内容。
• 执行代码——它能把Python代码写给你，但它自己没有Python解释器。它不能真正运行 df.mean() 然后拿到结果。
• 持久化结果——它不能把分析报告写进你桌面上的 report.md。它的输出只在对话框里，关掉就没了。

这三件事有一个共同特征：它们需要和外部世界交互。 读文件是和文件系统交互，执行代码是和Python解释器交互，写文件是和磁盘交互。而大模型本身是一个封闭的推理系统——它有输入和输出，但没有“手脚”去触碰外面的世界。

这就是“知识库”和“执行器”之间的根本区别：

	知识库（纯推理Agent）	执行器（工具增强型Agent）
能做什么	回答已知信息、给出建议、解释概念	读取外部数据、执行代码、操作文件
数据来源	训练数据+用户输入	训练数据+用户输入+工具获取的实时数据
计算能力	概率性文本生成（不稳定）	确定性代码执行（稳定）
产出	对话内容	对话内容+文件+数据+可复用的产物
限制	不能访问外部世界	受沙盒安全边界限制

你在第1.3节手动粘贴了10行数据，那是你在充当Agent的“手”——替它读取文件，替它把数据喂进来。但这不是一个可持续的模式。如果Agent能自己读文件、自己执行代码、自己写报告，你只需要把CSV的路径告诉它，然后等着收结果。

这就是工具使用要解决的问题。

---

1.5 解法方向：给Agent装上手脚

想象一下，如果Agent能调用这样几个函数：

# 工具1：读取文件
read_file("scores.csv")
# 返回：文件内容的字符串

# 工具2：执行Python代码
execute_python("""
import pandas as pd
df = pd.read_csv('scores.csv')
print(df.describe())
""")
# 返回：代码执行的标准输出

# 工具3：写入文件
write_file("analysis_report.md", report_content)
# 返回：文件写入成功

当用户说“帮我分析这份成绩单”时，流程就变成了：

1. Agent判断：“我需要先读取文件”，调用 read_file("scores.csv")
2. Agent拿到文件内容，判断：“我需要用pandas计算统计指标”，调用 execute_python(...)
3. Agent拿到计算结果，生成分析文字
4. Agent判断：“用户需要报告”，调用 write_file(...) 保存

每一步都是代码真正在执行，不是AI在“想象”。读文件是Python的 open() 在干活，算平均分是pandas的 mean() 在运算，写文件是操作系统在落盘。

Agent的角色变了——它不再是那个“只能给你出主意的人”，而是“能帮你干活的人”。它从“你应该……”“你可以……”变成了“我已经……”“结果是……”。

这正是第二部要教你搭建的系统。

---

1.6 本章小结

• 纯推理Agent是一个知识库，它能回答问题、给出建议、解释概念，但不能和外部世界交互。
• 它不能读文件、不能执行代码、不能持久化结果——这三件事恰好是大多数实际任务必需的。
• 当它被要求处理具体数据时，它的行为模式是“教你做”而不是“帮你做”。它给你pandas教程，而不是分析结果。
• 解决方向是给Agent工具——让它可以调用函数来读取文件、执行代码、写入结果。每个工具由真正的Python代码执行，不是AI在预测。
• 这需要一个新的能力：Agent需要知道“什么时候该用哪个工具、传什么参数”。这是下一章的核心内容。

本章你亲手验证了纯推理Agent的那堵墙。你知道它能做什么，也知道它的边界在哪里。现在，我们要开始拆墙了。

---

课后练习

1. 运行你生成的 advisor_agent.py，给它一份真实的数据集（你自己找一份或者编一份20行左右的CSV），观察它的回答。它是否尝试“手动计算”？计算的结果对吗？
2. 在请求中，要求Agent生成一份分析报告的Markdown文件。观察它的反应——它能真正创建文件吗？还是只能把Markdown内容输出在对话框里让你自己保存？
3. 思考：除了读取文件、执行代码、写入文件之外，你还能想到哪些Agent需要的“工具”？列出三个，并描述每个工具的输入、输出和用途。
4. （预备思考）如果Agent可以调用 read_file 和 execute_python，你觉得它完成1.3节那个任务（分析全部45行数据）需要几步工具调用？写出你设想的调用序列。

---