2026-10-16 07:13:37 网络安全文章来源：ZONE.CI 全球网 0 阅读模式

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 核心代码——这就是插件化的价值。