A. 事件触发机制
用户发起任务
Agent 开始工作
准备调用工具
执行工具
获得工具结果
继续思考
准备结束任务
准备调用工具Hook：检查工具和参数允许执行？
执行工具阻止执行
第 11 课 Hook 与 Sandbox
理解 Agent 在关键节点如何通过 Hook 和 Sandbox 增加约束、控制风险。
预计 8 分钟 · 系列：从 0 到 1 设计一个 Agent
本课要点
- Hook 是关键节点自动触发的规则机制
- Sandbox 是受限的执行环境，用来限制 Agent 可访问的资源和权限
- Hook 决定这个动作要不要执行；Sandbox 限制这个动作最多能影响多大范围
前面我们一直在讲怎么让 Agent 在现实世界行动：给它工具、记忆、上下文，让它可以自己规划任务、调用工具、执行操作。
但 Agent 能做的事情越多，另一个问题就越重要：怎么避免它不要乱行动？
比如一个代码 Agent 为了完成任务，可能会：
- 读取文件
- 修改代码
- 执行 Shell 命令
- 访问互联网
- 调用企业内部系统
- 删除或覆盖数据
这些动作很多都是真实发生在环境里的。因此在 Agent 行动时，我们还需要增加一些约束机制，防止它造成一些不可逆的危害。
这一课介绍两个很重要的组件：Hook 和 Sandbox。
你可以先这样理解：Hook 负责在关键时刻强制触发系统的某些行为活动；Sandbox 负责限制 Agent 能在哪里活动，能接触到什么资源。
1. Hook
Hook 可以理解成一种事件触发机制：当程序运行到某个特定节点时，自动执行提前写好的逻辑。
1.1 什么是 Hook？
B. 典型案例
客服 Agent
调用退款接口前触发 Hook，检查退款金额是否超过 Agent 的自动处理额度。
数据分析 Agent
执行 SQL 前触发 Hook，禁止 DELETE、DROP 等可能修改生产数据的语句。
内容发布 Agent
正式发布文章前触发 Hook，自动执行敏感词和格式检查。
Hook 就像提前设置好的自动开关，事件发生时会自动运行。
1.2 为什么 Agent 需要 Hook？
因为很多事情不能只写在 Prompt 里。比如你在系统提示词里告诉 Agent：
删除文件之前，请先检查这个文件是不是重要文件。
Agent 有时候可能会遵守，但在长时间、多步骤执行任务时，会出现理解偏差，也可能受到上下文、工具返回内容的影响，不能保证这个动作总是稳定执行。
而有些重要规则我们希望做到：每次都执行。
这时候，就可以把它从 Prompt 里拿出来，变成 Hook，从靠 Agent 自觉执行，到靠规则强制执行。
Prompt：告诉 Agent 应该怎么做
“请只删除临时文件，不要删除重要数据。”
容易被忽略或绕过。Hook：在关键节点强制执行规则
Agent：我要删除 data.csvPreToolUse Hook
- 文件是否允许删除
- 当前用户有无权限
- 是否属于保护目录
通过 → 执行不通过 → 拒绝
很多重要规则不能只依赖 Prompt，而要做到每次都强制执行。
1.3 Hook 是怎么工作的？
任务开始
Hook
Agent 思考
准备调用工具
Hook
工具执行
Hook
继续思考
准备结束
Hook
任务完成
运行开始前
加载用户身份、初始化环境、检查权限
工具调用前
检查工具、参数、权限和风险
工具调用后
记录日志、检查结果、清理异常
运行结束前
检查结果是否完成，是否遗漏步骤、保存记录
1.4 使用 Hook 需要注意什么？
别什么都塞进 Hook
Hook 适合明确、稳定、可程序化判断的规则，例如禁止修改系统文件、限制文件大小、记录工具调用日志。复杂理解和灵活判断，仍应交给 Agent 自己处理。
要定义 Hook 失败后怎么办
根据场景选择合适的失败策略：继续运行、直接拒绝，或要求人工确认。涉及安全、资金、删除数据等高风险动作时，失败即放弃往往更重要。
2. Sandbox
Sandbox 是给 Agent 提供一个受限制的执行环境，用来限制它能在哪里活动、能接触到什么资源。
2.1 什么是 Sandbox？
安全范围内
（可访问）
（可访问）
- 创建文件
- 运行代码
- 安装部分依赖
- 修改项目代码
Sandbox受限制的执行环境
安全范围外
（不可访问）
（不可访问）
- 系统文件
- 用户私人文件
- 公司私密数据
- 任意互联网地址
2.2 为什么 Agent 需要 Sandbox？
Sandbox，中文通常叫沙箱。它本质上是：
给系统提供一个受限制的执行环境。
Agent 可以在里面运行命令、修改文件、执行代码，但它能访问什么、修改什么，都受到限制。你可以把它想象成给 Agent 准备了一间实验室。
Agent 可以在实验室里折腾
创建文件 ✓ 运行代码 ✓ 安装部分依赖 ✓ 修改项目代码 ✓
实验室之外还有很多东西
系统文件 × 用户私人文件 × 公司数据库 × 任意互联网地址 × 其他项目 ×
Agent 想走出去，就需要额外授权。OpenAI 在 Codex 中采用了类似设计：沙箱会限制 Agent 可以写入哪些目录、能否访问网络，以及哪些路径受到保护；跨越这些边界时，再结合审批机制决定是否允许执行。
2.3 Sandbox 是怎么工作的？
文件权限
/project 可读写；/tmp 可临时写；/system 和用户目录禁止访问。
网络权限
只允许白名单域名；限制外传下载；记录访问行为。
系统权限
限制可运行命令、进程和系统级操作。
资源限制
设置 CPU、内存、运行时间与磁盘容量上限。
2.4 使用 Sandbox 需要注意什么？
默认给最小权限
先给完成任务所需的最小权限，再根据需要逐步扩大。
Sandbox 和审批配合使用
沙箱内的低风险操作可自动执行，越过边界或涉及敏感信息时交给人工审批。
注意凭证和敏感数据
- 默认最小权限
- 按任务逐步放开
- 隔离不同用户
- 敏感信息不进上下文
- 记录凭证和调用数据
3. Hook 和 Sandbox 有什么区别？
Hook
Hook
控制的是：这个动作要不要执行
发生在：关键节点时检查
Sandbox
Sandbox
控制的是：这个动作最多能影响多大范围
发生在：执行环境中始终生效
Hook 在关键节点自动执行特定的行为，也可以自动检查、拦截、记录 Agent 的活动。Sandbox 则划定 Agent 真正可以活动的边界。两者配合起来，Agent 才能在拥有更多自主能力的同时把风险控制在一个相对可控的范围内。
4. 练习题
选择最合适的方案，完成后查看解析。
练习 1：什么时候需要 Hook？
内容发布 Agent 将要正式发布文章。以下哪种设计最合适？
练习 2：什么时候需要 Sandbox？
数据分析 Agent 需要运行代码、读写项目目录，但不能访问用户私人文件、系统目录或任意网络地址。应该优先使用什么？
判断关键动作前要不要强制执行规则，用 Hook；判断 Agent 能在哪些资源边界内活动，用 Sandbox。