文章总结： 本文介绍AgentHarness框架的AgentTool架构设计，采用插件化分层与契约驱动思路，通过六层架构（推理层、路由、契约校验、权限风控、插件池、沙箱）及审计日志等横向能力，解决工具定义分散、参数随意、无权限审计等痛点，并给出契约优先、风险分级与ReAct打通等实战要点。 综合评分： 85 文章分类： AI安全,安全开发,安全建设
Agent Harness 实战：Agent Tool 架构
原创
Z Z
威胁情报Z分析
2026年9月29日 12:35 广东
在小说阅读器读本章
去阅读
在公众号小说中沉浸阅读
Agent Harness 实战：Agent Tool 架构
Agent Tool 架构是 Agent Harness 框架的工具能力底座，负责统一管理、调度、校验、执行所有 Agent 可用的工具。原生 Agent 工具体系常见的痛点——工具定义分散、参数随意、执行无权限无审计、结果格式不统一——都在这一层解决。整体设计思路是插件化、分层、契约驱动：工具与 Agent 核心推理引擎解耦，工具层可以独立开发、测试和热插拔。
整体执行流程
下图展示一次工具调用从 Agent 输出意图、经过各层校验、到最终执行并回填 Observation 的完整链路。每一层都是独立的”门卫”，任何一层不通过都会把标准化错误回填给 Agent 重试。
分层架构总览
架构自上而下分为六层，外加三个贯穿各层的横向通用能力。
各层职责详解
L1 · Agent 推理层
就是前一篇讲的两阶段 ReAct 引擎。Think 阶段输出工具调用意图和推理理由，Act 阶段生成工具入参。Agent 只表达”想调用哪个工具”，完全不关心工具内部怎么实现——这是工具层可以独立演进的前提。
L2 · Tool Router 工具路由器
工具架构的入口，核心职责有四项：
- 从工具注册中心读取全部已注册工具的元信息；
- 根据 Agent 输出的工具名称，路由到对应工具插件；
- 工具版本匹配（支持同一工具多版本共存）；
- 过滤被禁用的工具。
工具注册中心存储每个工具的元数据：名称、描述、JSON Schema、分类、风险等级、是否启用、版本。工具支持运行时动态注册——新增插件不需要重启 Agent 主引擎。
L3 · 契约校验层
这是生产环境最关键的一层。每个工具在注册时必须用 JSON Schema 预先声明入参字段、类型、是否必填、枚举范围、数值边界。LLM 生成参数后，在校验层提前拦截非法参数，而不是把错误参数下发到业务插件。
校验失败时返回统一格式的错误信息（哪个字段、期望什么类型、实际是什么），Agent 拿到后可以针对性修正参数重新生成。示例工具契约如下：
{ ”name”: ”query_order”, ”description”: ”根据订单号查询订单信息”, ”risk_level”: ”low”, ”parameters”: { ”type”: ”object”, ”required”: [”order_id”], ”properties”: { ”order_id”: { ”type”: ”string”, ”description”: ”订单编号”, ”pattern”: ”^ORD-\\d{8}$” } } } }
L4 · 权限与风控层
参数合法不代表可以执行。这一层根据工具的风险等级做策略判断：
| 风险等级 | 典型工具 | 处理策略 | | — | — | — | | 低风险 | 查询订单、搜索、读取文件 | 直接执行，记录审计日志 | | 中风险 | 修改数据、发邮件、创建资源 | 检查调用方角色权限，通过后执行 | | 高风险 | 删除数据、支付、对外发布 | 暂停循环，触发人工审批检查点（对接两阶段 ReAct 的中间插槽） |
L5 · 工具插件池
所有工具实现统一接口，标准化开发，分为三类：
- **HTTP API 插件：**调用第三方或内部 HTTP 接口，是最常见的类型；
- **内置函数插件：**内存函数，负责数据计算、文本处理等纯逻辑；
- **本地执行插件：**Shell 命令、文件读写，受沙箱严格限制。
统一插件接口的最小骨架：
class BaseToolPlugin: name: str description: str schema: dict risk_level: str def run(self, params: dict) -> dict: # 工具实际执行逻辑 raise NotImplementedError
新增工具只需要实现这个接口并注册到注册中心，不需要修改 Agent 核心代码——这就是插件化的价值。
L6 · 执行沙箱与资源管理
工具执行的隔离层，防止错误或恶意工具破坏系统：
- **超时控制：**单工具最大执行时间，超时强制终止；
- **限流：**单个 Agent 或全局维度的工具调用 QPS 限制；
- **熔断：**工具连续多次失败后自动熔断，一段时间内禁止调用；
- **资源隔离：**限制文件读写路径、网络访问范围。
横向通用能力
三个能力贯穿 L2 到 L6，不属于任何单一层：
**审计日志：**每次工具调用完整记录 Agent ID、工具名、入参、出参、耗时、成功/失败，用于问题溯源和行为分析。
**结果缓存：**查询类工具可开启缓存，相同参数直接返回历史结果，节省外部调用成本。写操作类工具不缓存。
**工具注册中心：**所有工具元数据的唯一真相来源，支持动态注册、下线、版本切换。
工具生命周期
把上面各层串起来，一次完整的工具生命周期是这样的：
- 开发者编写插件、定义 Schema、注册到注册中心；
- Agent 的 Think 阶段确定需要调用哪个工具；
- Act 阶段生成工具参数；
- Router 匹配工具并做版本路由；
- 契约校验层校验参数合法性；
- 权限风控层判断是否需要审批；
- 沙箱内执行插件逻辑；
- 结果标准化封装为 Observation；
- Observation 回填 Agent 上下文，进入下一轮 ReAct 循环；
- 全程写入审计日志。
实战要点
落地这套架构时，有几条经验值得直接复用：
**契约优先。**不允许任何无 Schema 的工具上线。强制契约能把 LLM 参数错误率显著压低，因为错误在执行前就被拦截了。
**风险分级要和两阶段 ReAct 打通。**高风险工具的审批直接复用 Think 和 Act 之间的检查点，不需要在工具层另造一套暂停机制。
**插件尽量无状态。**无状态插件才能热插拔、才能水平扩展。有状态的连接（数据库连接池、HTTP session）放在沙箱管理层统一管理，不放在插件内部。
**错误要分类。**所有工具异常统一格式返回，让 Agent 能区分”参数错了””权限不够””外部服务挂了”三种情况，分别采取重试、换工具、上报不同策略。
**工具不直接操作 Agent 内存。**所有数据传递通过 Observation 这个标准化出口，避免工具和 Agent 状态紧耦合。
与两阶段 ReAct 的关系
两阶段 ReAct 引擎负责思考和决策，Agent Tool 架构负责安全可靠地执行。两者组合才构成完整的 Agent Harness 运行时：ReAct 输出”想做什么”，Tool 架构决定”能不能做、怎么做、做了之后怎么回来”。下一篇会讲这个运行时的第三个支柱——记忆架构。
免责声明：
本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。
任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。
本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。
本文转载自：威胁情报Z分析 Z Z《Agent Harness 实战：Agent Tool 架构》
版权声明
本站仅做备份收录，仅供研究与教学参考之用。
读者将信息用于其他用途的，全部法律及连带责任由读者自行承担，本站不承担任何责任。
评论