核心小节二：Harness 真正要做什么——解析、查找、校验、执行，一个都不能少

现在我们已经有：

{
  "name": "read_file",
  "arguments": {
    "path": "app.py"
  }
}

接下来 Harness 要干什么？

最简单的链路就是：

解析 JSON
   ↓
寻找函数
   ↓
参数校验
   ↓
执行函数
   ↓
返回结果

这几步看起来简单，但每一步都很重要。

为了把这条链路看得更完整一些，可以先对照下面这张流程图。它把“解析、查找、校验、执行、封装结果”几个动作串成了一条比较清晰的控制链。

你可以把它理解成 Tool Executor 的骨架。工具类型可以变化，但这条主流程尽量不要散，这样后面加新 Tool 时才不会每次都重写一套处理逻辑。

第一步：解析 Tool Call

Tool Call 可能来自：

• 模型 SDK 的结构化对象；
• JSON 字符串；
• ProviderResponse；
• FakeProvider。

我们内部最好统一成：

from dataclasses import dataclass
from typing import Any


@dataclass
class ToolCall:
    name: str
    arguments: dict[str, Any]

这样 Agent Engine 不需要关心原始格式。

第二步：寻找工具

最简单写法：

TOOLS = {
    "read_file": read_file,
    "list_files": list_files,
}

然后：

tool = TOOLS[tool_call.name]

这就是最简 Tool Registry。

下一节我们会专门把它做成独立组件。

第三步：参数校验

模型可能返回：

{
  "name": "read_file",
  "arguments": {}
}

缺少：

path

也可能：

{
  "name": "read_file",
  "arguments": {
    "path": 123
  }
}

类型不对。

如果直接：

read_file(**arguments)

程序可能异常。

所以 Harness 必须验证。

第四步：真正执行

通过校验后才调用：

result = tool(**arguments)

注意，这一刻才是真正的 Tool Execution。

第五步：统一 Tool Result

不要直接让返回值随便飘。

更推荐：

{
    "ok": True,
    "tool": "read_file",
    "result": "..."
}

失败：

{
    "ok": False,
    "tool": "read_file",
    "error_type": "FileNotFoundError",
    "error": "app.py"
}

这样后面 Observation 处理更稳定。

这里有个细小但重要的边界：统一结果不是把所有返回值都强制转成一句字符串。结构化数据尽量保持结构，超长输出可以保存成 Artifact，再在 Observation 中放摘要和引用。过早把结果压成字符串，后面做错误判断、指标统计和界面展示都会多一次不可靠的解析。

写一个最小 Tool Executor

下面代码完整可运行：

你会看到三种结果：

成功
文件不存在
未知工具

而整个 Python 进程不会因为局部错误直接崩掉。

这就是一个合格 Tool Executor 的雏形。

参数校验为什么要单独讲？

这一节之所以要单拎出来讲，是因为“校验”从来不是一步。只检查类型，远远不够；只检查字段完整性，也不够。更稳妥的做法，是把它拆成几层分别处理。

这样一拆，你就会发现很多看似“参数没问题”的输入，其实只是过了前面一两层，距离真正可执行还差得很远。

因为模型输出不是传统程序员手写参数。

它有可能：

• 少字段；
• 多字段；
• 类型错；
• 格式错；
• 值范围不合理。

例如：

{
  "name": "query_data",
  "arguments": {
    "limit": -100
  }
}

Python 类型可能是 int，表面“合法”。

但业务上不合法。

所以参数校验至少分两层：

结构校验
+
业务校验

结构校验：

是不是 int
有没有字段

业务校验：

limit 是否 1~1000
日期是否超过 30 天
path 是否在 workspace

后面 Tool Schema 和 Middleware 会继续深化。