> For the complete documentation index, see [llms.txt](https://levon.gitbook.io/agent-engineering/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://levon.gitbook.io/agent-engineering/01agent-ji-chu.md).

# 第 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 课](/agent-engineering/03-gong-ju-diao-yong-xun-huan.md)展开。

## 资料

1. [Anthropic：Building Effective AI Agents](https://www.anthropic.com/research/building-effective-agents)，本章沿用其对预设流程与模型动态决策的架构区分。
2. [第 1～5 课资料复核](https://github.com/unix2dos/agent-engineering-book/tree/main/research/01-05-chapter-promotion-sources.md)。资料供追溯，理解正文不要求同时打开链接。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://levon.gitbook.io/agent-engineering/01agent-ji-chu.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.