第 1 章：Agent 是什么 — 一个有工具权限的协作者¶

📋 本章概览¶

第一次接触 Agent：先观察，不先授权¶

你不需要一上来就学会编程、命令行或所有专业名词。把 Agent 想象成一个能看材料、使用工具的协作者：你先给它一份没有隐私的测试材料，让它解释“看到了什么、准备做什么”，你再决定是否允许下一步。

第一次练习只选一个公开 README 或自己新建的空文本文件，任务可以是“请概括这份文件，并列出你实际读取的文件；不要修改、删除、安装、联网或提交”。如果 Agent 直接要求读取密钥、访问整个磁盘或执行你看不懂的命令，暂停并要求它解释原因。能说清范围、动作和结果，比让它一次完成更多事情更重要。

1.1 从聊天到任务循环¶

先区分三个词：聊天、工作流和 Agent¶

普通聊天的输入和输出都主要是文本：你提出问题，模型生成回答。它可以帮你解释报错、改写句子或给出代码，但通常不会主动读取你的项目，也不会替你确认文件是否真的发生了变化。

工作流是在聊天之外预先规定好步骤。例如“读取文档 → 总结 → 检查字数 → 输出 Markdown”，每一步和下一步都由程序或人提前安排，结果比较容易复现。

Agent 则是在目标和约束下，由模型根据当前结果决定下一步动作。它可能先读取目录，再打开相关文件，运行检查命令，发现错误后调整方案，最后把修改和验证结果交给你。Anthropic 的 Building effective agents 也强调，很多任务应先从简单、可组合的工作流开始，只有在确实需要动态决策时才引入 Agent。

这三种方式不是“低级到高级”的固定升级路线。一个只需要三步的任务，用工作流往往比 Agent 更稳定；一个需要观察报错、选择不同排查路径的任务，才适合让 Agent 参与决策。

一个 Agent 任务是怎样跑起来的¶

假设任务是：“检查一个 Python 项目为什么启动失败，并给出修复建议。”一个安全的任务循环大致如下：

1. 理解目标：确认“启动失败”指什么命令、什么错误和什么预期结果。
2. 收集上下文：查看目录结构、README、依赖文件和错误日志，只读取完成诊断所需的内容。
3. 提出计划：决定先检查 Python 版本和依赖，再复现错误，最后判断是代码问题还是环境问题。
4. 调用工具：运行 python --version、查看依赖文件，或执行一个不会修改数据的测试命令。
5. 观察结果：读取命令输出，判断原来的假设是否成立；如果不成立，就修改下一步计划。
6. 交付结论：说明证据、根因、建议的修复动作，以及哪些步骤还没有验证。

这里的关键不是“模型会不会说话”，而是它能不能在每一步都把动作、结果和下一步联系起来。工具调用失败、输出为空或出现新错误时，Agent 不应该假装任务完成，而应该停下来重新判断。

Agent 和普通聊天到底差在哪里¶

可以把聊天模型想象成坐在旁边的顾问，把 Agent 想象成拿着工作证进入项目现场的协作者：

• 顾问可以告诉你应该检查哪几个文件，但不一定看得到文件的真实内容。
• 协作者可以读取文件并运行检查，但只能使用被授予的工具。
• 顾问给出的建议需要你自己验证；协作者也可能误解目标，因此仍需要你检查 Diff、日志和测试结果。
• 协作者的动作会产生副作用：可能修改文件、安装依赖、消耗 API 额度，甚至访问网络。

所以，“Agent”不等于“自动完成一切”。它只是把“理解 → 行动 → 观察 → 调整”这个循环交给模型参与，最终责任和高风险决策仍应由人保留。

1.1 小练习：判断该用什么方式¶

把下面的任务分别归类为聊天、工作流或 Agent，并说明理由：

1. 把一段课程简介改成 100 字以内。
2. 把 20 个 Markdown 文件的标题统一成同一种格式。
3. 找出一个网页项目无法构建的原因，并在确认后修复。

判断标准不是“哪个听起来更智能”，而是：下一步是否固定、是否需要观察中间结果、是否会改变真实文件。

1.2 五个核心部件¶

一个可控的 Agent 系统至少要看清五个部件。少看任何一个，都容易把“模型的一次回答”误认为“可靠的自动化”。

1.2.1 模型：会推理，不代表知道事实¶

模型负责根据输入预测下一段内容或下一步动作。它可以把错误信息整理成假设，也可以比较几种修复方案，但它并不天然知道你的电脑状态、仓库最新内容或命令是否真的执行成功。

常见误区是把“说得很确定”当作“已经验证”。例如，Agent 说“依赖已经安装成功”，真正的证据应该是安装命令的退出状态、版本输出或测试结果，而不是这句话本身。

使用模型时，至少保留三层区分：

1. 模型的判断：它认为可能发生了什么。
2. 工具的结果：命令、文件读取或 API 返回了什么。
3. 人的验收：结果是否满足实际目标，是否引入了副作用。

1.2.2 上下文：Agent 看到的世界有边界¶

上下文不只是聊天记录，还可能包含系统指令、项目规则、当前目录、打开的文件、命令输出和前面步骤留下的摘要。上下文越相关，Agent 越容易做出正确动作；无关内容过多，也可能让重要约束被淹没。

下面这些内容经常导致上下文判断失真：

• 只打开了一个文件，却以为自己理解了整个项目。
• 看到旧日志，却把它当成刚刚运行的结果。
• 项目规则写在 README 里，但 Agent 没有读取它。
• 对话很长，前面的范围限制已经被忽略。
• 任务目标没有写清楚，模型只能根据猜测补全。

因此，好的任务描述要明确“要看什么、不要看什么、结果以什么为准”。不要一上来把整个磁盘或整个仓库都交给 Agent；先给它最小但足够的上下文。

1.2.3 工具：能力越多，边界越重要¶

工具是 Agent 与现实世界之间的接口。常见工具可以按影响程度分成四类：

工具名称本身不能说明安全性。例如“运行测试”通常是低风险动作，但如果测试脚本会删除临时目录、访问网络或写入数据库，就不能只看它叫 test 而直接批准。

1.2.4 权限：先给工作证，再给钥匙¶

权限回答的是“Agent 能做什么”，不是“Agent 想做什么”。实用的权限顺序是：

1. 先允许读取和分析。
2. 再允许修改明确列出的文件。
3. 需要执行命令时逐条确认命令、目录和影响。
4. 涉及删除、发布、支付、账号、密钥或外部通信时，默认暂停等待人工确认。

安全 Agent 的目标不是让它“什么都不能做”，而是让每次授权都与当前任务匹配。任务结束后，检查权限是否可以收回，检查 Diff、生成文件和命令记录中是否出现敏感信息。

1.2.5 验收与停止：让“完成”有证据¶

没有验收标准的 Agent 任务，很容易在“看起来差不多”时提前结束。验收至少应该包含：

• 产物：哪些文件、报告或命令输出必须存在。
• 正确性：用什么测试、构建或人工检查证明它正确。
• 范围：允许改哪些文件，哪些文件必须保持不变。
• 停止条件：遇到什么情况必须暂停，例如需要删除文件、联网、暴露密钥或修改依赖。
• 回滚方式：如何通过 Git、备份或撤销操作恢复到任务前状态。

可以把任务写成下面这样：

目标：找出项目启动失败的原因并给出修复补丁
范围：只检查 src/、pyproject.toml 和错误日志；只允许修改 src/main.py
允许：读取文件，运行不修改数据的测试，编辑 src/main.py
禁止：删除文件，升级依赖，读取 .env，访问生产服务，推送远程仓库
验收：测试通过，git diff 只包含 src/main.py，并说明仍未验证的部分
停止：需要修改依赖、执行未知脚本或发现密钥时立即暂停

这张任务卡既是给 Agent 的说明，也是给人的检查清单。Anthropic 在 Trustworthy agents in practice 中把人的控制、透明性、隐私和安全交互视为 Agent 设计的重要部分；在实际使用中，最简单的做法就是让范围、权限、证据和停止边界提前写出来。

🔮 下一章预告¶

下一章会在 OpenCode Desktop 中接入 DeepSeek API Key，并完成第一次安全验证。