感知·执行·协作

工具分类里由 agent 主动调用的四类中，最吃设计的是感知、执行、协作三类（用户沟通工具与事件触发工具留到事件驱动异步）。

感知工具：控制返回信息量

感知工具是 agent 获取外部信息的主要渠道，常面临返回信息量远超处理能力的挑战——一次搜索可能数万字符，一份 PDF 上百页，直接塞入上下文既耗尽窗口又淹没关键内容。通用应对是在工具层集成上下文感知压缩（超过阈值时按当前查询意图自动压缩）。几类感知工具各有设计要点：

• 搜索类的返回格式与分页：返回结构化候选列表（标题、位置、摘要片段）而非全文拼接，结果多时提供游标分页，由 agent 自主决定是否翻页，而不是一次性倾倒全部。
• 读取类的 offset/limit 与截断：支持按需读取大文件片段；必须截断时显式可见（“已显示第 1–200 行，共 5000 行，可用 offset 继续”）。静默截断很危险——agent 会误以为看到了全部。
• 只读性的工程红利：感知工具不改变外部世界，因此结果可安全缓存、多个感知调用可放心并行——执行工具没有这种自由。
• 多模态的输出形态：纯文字内容用文本提取（省 token），布局敏感的内容（UI、复杂表格、设计稿）保留图像（存空间结构）。

执行工具：安全是核心

执行工具的错误代价可能极高——误删的文件无法恢复，错误的命令可能导致服务中断，不当的 API 调用产生真实财务损失。它的设计是能力开放与安全约束之间的平衡，安全不应依赖单一机制，而应分层：

• 输入验证：执行前检查参数合法性——路径遍历（../../etc/passwd）、命令注入（分号/管道拼接）、类型格式。发现异常立即拒绝，不尝试“智能”修正。
• 权限控制：文件操作限定工作目录，命令维护黑名单，外部 API 检查配额。黑名单只是最基础一层——攻击者能用变形命令绕过字符串匹配，更健壮的是结合语义解析理解命令意图。
• 提议者-审核者：对不可逆的关键操作，用独立的第二视角检验第一视角的产出。事前审批——一个模型提议、另一个独立模型审批（像银行的经办/审核双签）；两个模型应来自不同家族、能力相近（认知多样性，不易在同一处犯同样的错）。事后验证的要诀是模态切换——不是重读一遍，而是换个模态检验（生成文档后渲染成图看排版、改配置后在沙盒实跑）。审批拒绝理由作为工具结果加入轨迹，agent 当作一次工具失败来处理。
• Sidecar：与主模型流式输出并行运行、对被审查的那次工具调用起门控作用的轻量安全校验。它只看结构化的工具调用数据（工具名、参数），不看主模型的自由文本思考——防止攻击者用话术诱导主模型复述、再骗过审查。判断的是结构化分类问题（这条命令是否越界），任务简单，轻量模型足矣；配拒绝熔断器，连续拒绝时回退到人工。
• 执行环境隔离：通用执行工具允许 agent 执行任意代码，须在沙盒中与宿主机隔离。注意 Python venv 不是沙盒（只隔离依赖）。按隔离强度递增：OS 级（Seatbelt / seccomp+namespaces）→ 容器（Docker，共享内核）→ microVM（Firecracker，独立内核硬件级）；任一层之上都应设 CPU/内存/磁盘/网络配额。
• 自动验证：结果可验证就自动验证——write_file 后立即跑 linter，把结构化错误列表作为返回值，形成“执行-验证-反馈”闭环。
• 长输出的截断与持久化：执行工具常产生冗长输出，超阈值（如 200 行 / 10000 字符）时只把头尾各若干行返回上下文（头部含初始输出或错误上下文、尾部含最终错误或成功标志），完整结果存临时文件并在中间标注“… [省略 N 行，完整输出已存至 /tmp/…] …”、引导用 read_file 取回。
• 可观测性：执行行为需可监控、审计、调试——详细日志（每次调用的时间、参数、结果、耗时）、审计追踪（谁在什么上下文下为何执行）、性能指标（频率、成功率、平均耗时）、告警（频繁失败 / 超时 / 资源超限时通知管理员）。
• 幂等性与取消：执行工具改变外部世界，必须回答“调用被取消/超时后，副作用发生了没有？”。核心是幂等性（携带 idempotency key 去重，或先查询后变更），让超时与重试变简单；发邮件/打电话/转账这类不可幂等的操作用预检-确认两段式（先校验预演 + 令牌，再凭令牌执行）。

协作工具：委托与整合

当任务超出单个 agent 的能力边界，协作工具把子任务委托给其他 agent 或人类、再整合结果。子 agent 的核心价值是专业化分工——与其一个全能 agent，不如一组各自专精、各自优化提示词与工具集的 agent。子 agent 的提示词要点：角色定义清晰、上下文来源明确标注（[FROM_MAIN_AGENT] / [FROM_USER] / [TOOL_RESULT]，防混淆与提示注入）、任务边界明确、输出格式标准化。协作接口可归纳为三组原语：启动与取消（spawn_subagent / cancel_subagent）、消息传递（send_message_to_subagent，双向）、发现（list_agents，与 MCP 的 tools/list 同思路，只不过列出的是 agent）。之上可承载同步/异步/流式/多轮多种协作形态——拓扑与分工属多 agent 架构，见多 Agent。

人工介入（HITL）在需要人类价值观、常识或领域判断的关键点仍必要：设超时与降级（“5 分钟无响应则采用保守策略”）、优先级队列（紧急多渠道、普通只发邮件），且不应是一次性交互——批准/拒绝及其理由构成反馈数据，可归纳的进 Skill、隐式偏好进后训练（见持续进化），但不能把一次人工判断未经归纳就推广为普遍规则。

工程实践

这三类工具在 Zapvol 里共享同一套 ServerToolConfig 契约，各自的设计要点落在契约的不同钩子上：

• 感知工具的“控制返回信息量”落在 compact 钩子——grep / read 类工具确定性削减（top-N 切片、首尾保留、中段标注省略），大输出的上下文感知压缩见压缩；知识库的 grep_docs / read_section 就是分页游标式感知工具的实例。
• 执行工具的隔离落在 ISandbox（createSandbox() 工厂按 SANDBOX_TYPE 分派，目前落地 Node、Daytona / E2B 占位），凭证经 KeyEncryption 端口隔离、不进沙箱；HITL 的 confirm / ask 结果由 normalize 钩子归一化成一条 user 消息。
• 协作工具落在 子代理 与 Agent Team。

相关阅读

• 工具设计——五类工具的分类与通用设计原则。
• 护栏与安全性——提议者-审核者、Sidecar 在 Harness“验证”层的位置。