第 1 课：Agent 基础——从语言模型到行动系统

“订单接口报 500 了，帮忙查一下。”接到这个需求，助手需要找到故障位置、引用证据，并给出修复建议。

GET /orders/order_404
HTTP 500

这是一个虚构的订单服务，错误可以在配套程序中复现。HTTP 500 只说明服务器处理请求时出了错，原因还在日志和代码里。本课先解决设计问题：这项工作需要一次模型调用、固定流程，还是 Agent？

1. Model 与 Tool：推理和执行的边界

语言模型（Model）根据收到的信息生成回答。只给它上述请求，它可以列出可能原因；但日志没有传入、读取工具也没有接入，它就拿不到这次故障的现场。回答里写“正在检查”，不会让磁盘自动多出一次读取。进度播报倒是先开工了。

人可以打开日志，把内容贴给模型。若希望程序承担读取，就要提供一个实际执行动作的工具（Tool），例如 read_file。接入工具后，一次读取的职责关系是：

模型提出读取申请：read_file，路径为 server.log
-> 宿主程序检查工具和路径是否允许
-> 读取工具打开文件，返回内容或错误
-> 宿主程序把结果交给模型
-> 模型依据结果继续判断

这张申请叫 Tool Call（工具调用请求），实际返回的内容或错误叫 Tool Result（工具结果）。申请存在，不代表文件已经读到；读取失败时，也不能把模型猜测的内容充当结果。

模型负责提出动作，宿主程序负责检查、执行和回传。权限来自程序与运行环境，不能由模型在回答里自行声明。

2. Workflow 与 Agent：任务控制方式

接上工具以后，还要决定由谁安排步骤。先看一个固定收集材料的方案：

读取指定日志和配置
-> 把收集到的材料交给模型解释
-> 返回解释和引用的原文

步骤和分支规则由代码提前规定，这种组织方式叫 Workflow（工作流）。模型可以承担其中的解释或分类工作，但不能自行改写整条流程。[1]

例如，程序先让模型判断错误类别，再规定“连接超时就读取网络配置，类型错误就读取报错文件”。这里有模型，也有条件分支，后续路线仍由预设规则控制。

如果排查需要不断补充材料，可以让模型根据目标和新证据，决定下一步读哪个文件、查哪项配置，或者请求用户补充信息。把这部分推进任务的选择交给模型，就是本书讨论的 Agent。[1]

设想日志指向订单函数，模型申请继续读那份源码；若源码还不能解释错误，它再决定是否检查调用方。开发者提供可用工具和执行限制，不必为每一种调查路线逐条写规则。这是设计示意，尚不代表配套模型已经验证了这些能力。

比较项	Workflow	Agent
谁安排后续步骤	代码预设步骤与分支规则	模型依据目标和运行中取得的信息选择
在排查任务中的表现	按规定收集材料，再解释或分类	根据线索决定继续查什么
开发者仍须控制什么	执行权限、异常处理、预算与停止条件	执行权限、异常处理、预算与停止条件

关键区别是后续步骤由谁决定，不能只数工具数量或模型调用次数。Workflow 也能反复调用模型；Agent 也可能拿到一次工具结果就结束。

两者可以组合：固定流程收集指定日志，Agent 调查未解释的异常，程序再检查报告是否满足交付要求。模型能选择调查路线，不等于它可以取消检查或扩大读取范围。

3. 架构选型：单次调用、Workflow 与 Agent

同一个“故障排查”需求，范围不同，合适的实现也不同：

实际需要	优先考虑	需要承担的工作或代价
用户已给出完整材料，只需解释	单次模型调用	人或上游程序负责收集材料，仍要核对解释
材料位置与处理路线可以预先规定	Workflow	编写和维护规则，处理规则未覆盖的情况
需要根据新证据持续调整调查方向	Agent	约束模型选择，承受额外等待、调用费用和失败路径

我建议从满足需求的最小方案开始。如果常见故障只有几类，现有规则已经够用，就没有必要把每一步都交给模型。需要它适应未知情况时，再比较省下的人工判断与增加的运行成本。

固定流程的路线更容易预先检查，但其中的模型输出仍可能出错。Agent 更灵活，也不意味着更准确。选型之后，都要用实际任务结果验证效果。

4. 项目定义：只读故障诊断助手

本书先让模型参与选择排查材料，项目范围限定如下：

• 输入：故障请求、日志位置和允许读取的项目文件。
• 输出：故障位置、支持判断的证据及修复建议；证据不足时，明确还缺什么。
• 执行边界：只读授权材料，不修改服务、不部署，也不把“诊断完成”写成“修复完成”。

配套服务可以真实产生 HTTP 500 和日志，但演示使用预设模型替身，先验证工具执行与结果回传。真实模型能否自主选择正确材料，仍需另外验证。

下一课从一次读取卡住开始：模型已经提出申请，为什么日志迟迟没有回来？我们沿着这次请求，拆清 Model、Harness、Tool 与 Environment 的职责。

本课不要求额外写程序。工具申请、执行和回传将在第 3 课展开。

资料

1. Anthropic：Building Effective AI Agents，本章沿用其对预设流程与模型动态决策的架构区分。
2. 第 1～5 课资料复核。资料供追溯，理解正文不要求同时打开链接。