美しいミズキ

目录#

• 一、模块关系
• 二、工具契约
  • （一）ToolSpec
  • （二）ToolDefinition
• 三、注册与准备
  • （一）ToolRegistry
  • （二）prepare 与 execute
• 四、权限策略
• 五、一次性批准
  • （一）拒绝覆盖
  • （二）只消费一次
  • （三）批准后的复查
• 六、统一控制
• 七、错误边界
• 八、测试与限制

Model Adapter 已经把模型响应转换成 ToolCall，接下来还差一步：确认工具并把结果交回模型。

直接根据 tool_name 调用 Python 函数，等于把模型生成的字符串接到了本地执行入口。Tool 板块要在中间加上几道明确的检查，让模型保留行动提议权，让运行时掌握实际执行权。

当前实现包含五个 Module：ToolRegistry、ToolRuntime、ToolPolicy、PendingApprovals 和 ToolController。它们共同完成下面这条链路：

1
ToolCall
2
   ↓
3
查找工具并校验参数
4
   ↓
5
PreparedToolCall
6
   ↓
7
PolicyDecision
8
   ├─ allow → 执行 handler → ToolResult
9
   ├─ ask   → ApprovalRequest
10
   └─ deny  → 错误 ToolResult

一、模块关系#

Tool 板块面对两类信息。模型需要知道工具叫什么、有什么用途、参数长什么样；运行时还需要参数校验器和真正执行操作的 Python handler。

把这些职责放进同一个函数，会让公开契约、权限判断和实际执行缠在一起。当前实现沿调用顺序拆开：

最外层只需要调用：

1
outcome = controller.handle(call)

返回值可能是 ToolResult，也可能是等待用户处理的 ApprovalRequest。调用者无需分别操作 Registry、Runtime 和 Policy。

二、工具契约#

1
@dataclass(frozen=True)
2
class ToolSpec:
3
    name: str
4
    description: str
5
    input_schema: Mapping[str, object]

1
ToolSpec(
2
    name="calculator",
3
    description="Add exactly two integers named a and b.",
4
    input_schema={
5
        "type": "object",
6
        "properties": {
7
            "a": {"type": "integer"},
8
            "b": {"type": "integer"},
9
        },
10
        "required": ["a", "b"],
11
        "additionalProperties": False,
12
    },
13
)

1
@dataclass(frozen=True)
2
class ToolDefinition:
3
    spec: ToolSpec
4
    validate_arguments: ToolArgumentValidator
5
    handler: ToolHandler

三、注册与准备#

1
for definition in definitions:
2
    name = definition.spec.name
3
    if name in definitions_by_name:
4
        raise DuplicateToolError(
5
            f"duplicate tool name: {name}"
6
        )
7
    definitions_by_name[name] = definition

1
registry.specs
2
registry.resolve("read_file")

1
prepare(call) → PreparedToolCall | ToolResult
2
execute(prepared) → ToolResult

1
ToolResult(
2
    call_id=call.call_id,
3
    content="unknown tool: delete_everything",
4
    is_error=True,
5
)

1
参数校验完成
2
    ↓
3
权限判断
4
    ↓
5
实际执行

四、权限策略#

ToolPolicy 返回三种决策：

1
class PolicyAction(StrEnum):
2
    ALLOW = "allow"
3
    ASK = "ask"
4
    DENY = "deny"

配置可以写成：

1
ToolPolicy(
2
    allowed_tools={"read_file"},
3
    confirmation_required_tools={"apply_patch"},
4
)

此时：

默认拒绝很重要。新增工具如果没有同步权限配置，会停在 DENY，不会因为遗漏配置自动获得执行权。

同一个工具也不能同时出现在 allow 和 ask 集合中。初始化时发现重叠会直接抛出 ValueError，避免一次调用同时匹配两套互相冲突的规则。

PolicyDecision 还会保存非空 reason。Controller 可以把拒绝原因放进 ToolResult，也可以把确认原因交给用户界面或未来的 EventStore。

五、一次性批准#

Policy 返回 ASK 时，Controller 会创建 ApprovalRequest，handler 此时不会执行：

1
ApprovalRequest(
2
    approval_id="approval_1",
3
    call=call,
4
    reason="tool requires user confirmation",
5
)

请求随后进入 PendingApprovals。这里保存的是原始 ToolCall，用户批准时才能知道具体允许了哪次调用。

1
request = self._pending.pop(response.approval_id)

六、统一控制#

ToolController.handle() 把前面的 Module 按安全顺序接起来：

1
preparation = self._runtime.prepare(call)
2
if isinstance(preparation, ToolResult):
3
    return preparation
4

5
decision = self._policy.decide(preparation.call)
6

7
if decision.action is PolicyAction.ALLOW:
8
    return self._runtime.execute(preparation)
9

10
if decision.action is PolicyAction.DENY:
11
    return ToolResult(
12
        call_id=preparation.call.call_id,
13
        content=decision.reason,
14
        is_error=True,
15
    )
16

17
request = ApprovalRequest(...)
18
self._pending_approvals.add(request)
19
return request

这条链路中只有两个位置可以到达 runtime.execute()：Policy 直接返回 ALLOW，或者一次有效批准完成复查。模型输出、未知工具、非法参数、拒绝决定和等待确认都无法直接执行 handler。

call_id 会原样进入每个 ToolResult。下一轮模型拿到结果后，可以把它与此前的 ToolCall 对应起来。

真实 DeepSeek calculator 烟测也经过了这条链路：模型提出带 Provider call_id 的 calculator 调用，Controller 允许执行，本地 handler 返回 42，结果写回 history 后，模型才生成最终答案。

七、错误边界#

Tool 板块需要区分“模型可以看到的预期失败”和“程序应该暴露的实现缺陷”。

文件不存在、参数无效等情况可以成为下一轮模型的环境反馈。代码内部的 AttributeError 通常说明实现有缺陷，如果统一包装成工具错误，Agent 可能继续循环，并把程序崩溃误解成一次普通操作失败。

错误 ToolResult 也保留原 call_id：

1
ToolResult(
2
    call_id="call_3",
3
    content="file not found",
4
    is_error=True,
5
)

模型可以根据这份结果调整参数或选择其他工具，Loop 再决定是否继续。

八、测试与限制#

Tool 板块目前由五组测试覆盖：

验证命令：

1
.\.venv\Scripts\python.exe -m pytest -q -p no:cacheprovider `
2
    tests\test_tool_registry.py `
3
    tests\test_tool_runtime.py `
4
    tests\test_tool_policy.py `
5
    tests\test_tool_approval.py `
6
    tests\test_tool_controller.py

当前结果为 21 passed。整个 Agent Kernel 当前为 124 passed，mypy 严格检查 32 个源文件无错误。

现阶段还有几个明确限制：

• Policy 只根据工具名称判断，没有检查路径、参数值和运行环境风险。
• 待确认请求只保存在内存中，进程重启后无法恢复。
• 批准请求、Policy 决策和工具执行尚未写入新的 EventStore。
• 批准后重新校验以及策略变化路径还需要补充集成测试。
• ToolController 尚未接入正式 Agent Loop，目前真实闭环由 smoke 脚本编排。

Tool 板块的核心关系可以压缩成一句话：模型提出 ToolCall，Registry 解析能力，Runtime 验证并执行，Policy 决定权限，Approval 保存一次性确认，Controller 保证这些步骤按顺序发生。

相关代码：

• tool_registry.py
• tool_runtime.py
• tool_policy.py
• tool_approval.py
• tool_controller.pygent Loop，目前真实闭环由 smoke 脚本编排。

Tool 板块的核心关系可以压缩成一句话：模型提出 ToolCall，Registry 解析能力，Runtime 验证并执行，Policy 决定权限，Approval 保存一次性确认，Controller 保证这些步骤按顺序发生。

相关代码：

• tool_registry.py

• tool_runtime.py

• tool_policy.py

• tool_approval.py

• tool_controller.py