4.4 感知工具

感知工具是Agent获取外部信息的主要渠道，设计需要在粒度、组织方式、输出格式等多个维度权衡。
感知工具普遍面临信息过载问题：搜索结果、PDF文档等原始内容字符量巨大，直接送入上下文会耗尽窗口，关键信息淹没在噪声中。通用解决方案是集成上下文感知压缩，当输出超过阈值（例如10000字符），基于Agent当前查询意图自动压缩内容。

搜索类工具

返回结构化候选列表，包含标题、位置、摘要片段，不直接拼接全文。结果数量较多时，提供分页或cursor游标参数，默认仅返回少量条目，同时标注结果总数和下一页获取方式，交由Agent自主判断是否继续翻页读取。

读取类工具

支持offset/limit参数，可以按需读取大文件指定片段。内容超出阈值需要截断时，必须显式标记：写明省略内容规模、剩余内容读取方式。严禁静默截断，否则Agent会误以为读取了完整信息，基于残缺信息做出错误判断。

只读特性带来的工程红利

感知工具属于只读操作，不会修改外部世界，带来两大工程优势：

1. 结果支持缓存，相同查询可直接复用缓存结果，节省调用开销与耗时
2. 多个感知调用能够并行执行，互不干扰

执行工具不具备该特性，调用顺序和副作用必须严格管控

多模态感知的输出选择

针对截图、图表、扫描件等多模态输入，有两种输出方案：

1. 直接返回图像交给视觉模型：保留布局与视觉细节，但Token消耗更高
2. 通过OCR、图表解析转为文本：精简高效，但容易丢失行列关系这类空间结构信息

实践选型：纯文字内容提取为文本；UI界面、复杂表格、设计稿这类对布局敏感的内容，保留图像输入。

4.5 执行工具

感知工具是Agent的“感官”，执行工具是Agent的“手脚”。执行工具会改变外部世界，一旦出错代价很高，例如误删文件、服务中断、产生资金损失。设计核心是在能力开放和安全约束之间取得平衡。

分层安全机制

1. 输入验证：执行前校验全部参数合法性，防御路径遍历、命令注入等攻击；检测异常输入直接拒绝，不尝试自动修正。
2. 权限控制：限制文件操作仅能访问指定工作目录，维护危险命令黑名单，管控外部API的访问配额与速率。黑名单仅作为基础防护，更可靠的方案是语义解析，识别命令真实意图，而不只是简单字符串匹配。

提议者-审核者 Proposer-Reviewer

用于高风险、不可逆操作，包含两种工作机制：

1. 事前审批：Proposer模型提出待执行动作，独立的Reviewer模型负责审批。
   • 模型配对要点：模型能力水平相近，但来自不同模型家族，带来认知多样性；两者底层规则保持一致，但关注点区分，提议侧侧重完成任务，审核侧侧重风险。
   • 审批失败：拒绝理由作为工具调用结果返回给Agent；支持风险分级审批，模型无法判定时升级人工审核。
2. 事后验证：操作执行完成后再校验结果。优先采用模态切换的验证方式，规避同一模态下的思维盲区，比如将生成代码渲染成截图，再检查排版效果。

Sidecar 边车安全机制

Sidecar是伴随主Agent思考循环并行运行的轻量LLM校验，作为工具调用的门控，危险操作未通过校验不能执行。

• 只读取结构化工具调用数据（工具名、参数），隔离主模型自由思考文本，抵御提示注入攻击。
• 典型用途：安全权限分类、记忆相关性筛选、工具输出摘要。
• 熔断器机制：多次连续判定风险拒绝操作时，停止自动重试，转交人工确认。

提议者-审核者 vs Sidecar

• 提议者-审核者：时机为操作前审批 / 操作后验证；审查操作合理性或最终结果；独立模型评审；适用不可逆操作、内容生成场景
• Sidecar：和主模型流式输出并行；审查单次工具调用本身；安全分类校验；权限判断、记忆筛选

执行-验证反馈闭环

凡是结果可校验的操作，执行后自动验证。示例：调用write_file写入代码文件后，自动调用linter做静态语法检查，返回结构化错误信息，Agent基于错误信息迭代修正。

长输出截断与持久化

执行工具输出内容过大时，仅保留头部、尾部片段返回上下文；完整输出保存到临时文件，在返回文本中提示文件路径，引导Agent使用read_file读取完整内容。

沙盒隔离层级（隔离强度递增）

1. OS级隔离：Linux seccomp、namespaces，macOS Seatbelt，适合本地开发场景
2. 容器Docker：独立文件系统与网络栈，共享宿主机内核
3. microVM/Firecracker：独立内核，硬件级强隔离，用于运行不可信代码

重要提醒：Python venv仅隔离包依赖，不是安全沙盒。
所有隔离层级都应附加资源配额，限制CPU、内存、磁盘、网络上限，防止资源耗尽。

可观测性

执行工具需要完整可观测能力，包含详细调用日志、审计追踪记录、性能指标，以及异常告警，方便监控、审计与调试Agent行为。

幂等性与取消语义

执行操作存在副作用，必须处理超时、调用中断后的重试问题。

1. 幂等操作：使用idempotency key唯一标识请求，或者执行前先查询资源状态，保证多次调用外部效果不变，可以安全重试。
2. 不可幂等操作（邮件、转账等）：采用预检-确认两段式。预检阶段校验信息并生成令牌，凭令牌执行真实操作；执行失败不盲目重试，回到上层重新预检。