控制台 退出登录
持续迭代 · 2026 AI 智能体 / 工具调用 / 上下文工程

SafeTool-Loop · 受控 AI 智能体工具调用执行器

拒绝把大模型输出的 JSON 直接丢进 `eval` 或裸调系统命令:通过严格的参数 Schema 校验、读写权限分级拦截、超时熔断与结构化错误自愈回传,让 AI 智能体的每一步工具调用都可预期、可审计。

Python 3.11 Pydantic v2 Schema Function Calling Context Engineering Audit Trace
SAFETOOL-LOOP RUNTIME INSPECTOR · SESSION #st_409a MAX_STEPS: 6 · GUARD: ON Step #1 · 模型输出参数不合法 → 拦截并触发结构化纠错回传 Model Raw : {"tool": "query_service_logs", "args": {"lines": 99999, "env": "prod"}} Validator : Reject! `lines` must be <= 200 (prevent context window overflow). Action : Returned structured hint to LLM without executing tool. Step #2 · 模型自动修正参数 → 校验通过并受控执行 Model Fix : {"tool": "query_service_logs", "args": {"lines": 100, "env": "prod"}} Sandbox : Policy=READ_ONLY | Timeout=3.0s | Elapsed=138ms | Output=2.1KB (Truncated Safe) AuditLog : Written to trace_202603.jsonl · Hash verified Step #3 · 写操作权限闸门 (Policy=CONFIRM_REQUIRED) Model Call: {"tool": "restart_container", "args": {"name": "nginx-proxy"}} Gate State: Paused for explicit human confirmation token before execution.

01 能做什么(核心应用场景)

场景 A · 拦截模型幻觉参数与自愈重试

把报错变成模型能读懂的修正提示

当模型传错字段名、枚举值越界或漏传必填项时,执行器在进入业务函数前直接用 Pydantic 拦截,并将精简的字段级错误原因回填给模型,平均 1 次重试即可自动修正。

场景 B · 读写权限分级与高危操作熔断

只读查询自动放行,修改/删除强制挂起确认

每个注册工具必须声明安全级别(`READ_ONLY` / `SIDE_EFFECT` / `DANGEROUS`)。查日志、读配置可全自动闭环;涉及重启服务或写文件的调用必须经过人工确认钩子。

场景 C · 防止上下文爆炸与死循环

输出长度硬裁剪与重复调用熔断

当工具返回上万行日志时自动提取头尾摘要并限制字节数,防止撑爆 Context Window;同时检测同一参数组合的连续重复调用,超过阈值立即终止循环。

02 我是怎么实现的(五步受控执行链路)

受控工具调用五步闭环架构(支持点击放大查看)
1. 意图解析层 提取 tool_calls JSON 容错修复 拦截未知工具名 2. Schema 校验 Pydantic 类型检查 数值范围/路径白名单 失败→生成纠错提示 3. 权限与幂等闸门 读写分级策略检查 重复调用指纹去重 最大步数预算扣减 4. 超时沙箱执行 独立超时控制 异常捕获不崩主程 记录耗时与审计日志 5. 观测结果整形 超长输出安全截断 敏感字段脱敏 回注上下文进入下轮 ← 结构化 Tool Observation / Error Hint 回传下一轮推理

关键技术选择与原因

  • 为什么不直接用重型 Agent 框架而要自研执行层:主流大而全框架把 Prompt 模板、工具调度和重试隐藏在深层黑盒里,一旦线上出现死循环或幻觉参数很难精细干预;自研 400 行核心调度器能让每一步拦截规则与审计日志完全透明可控。
  • 为什么把“错误提示整形”作为核心模块:如果直接把 Python 冗长的 Traceback 塞回给模型,不仅浪费 Token 还会干扰后续推理;转换为简短的字段级修复建议后,自愈成功率大幅提升。

遇到的典型问题与工程取舍

  • 问题:模型在工具报错后陷入完全相同参数的死循环重试 —— 解决:对 `(tool_name, canonical_args_json)` 计算哈希指纹,同一会话内如果连续 2 次调用完全相同的失败参数,立即触发熔断并强制模型切换策略或向用户求助。
  • 取舍:工具描述数量控制在 8~12 个以内 —— 实践证明单次挂载过多工具会显著拉低小参数模型的选择准确率,因此采用按任务阶段动态挂载工具子集的策略。

03 如何使用(工具声明与执行器配置示例)

1. 声明带安全边界的工具 Schema

from pydantic import BaseModel, Field
from safetool import tool_register, RiskLevel

class QueryLogsArgs(BaseModel):
    service: str = Field(pattern=r"^[a-z0-9\-]+$")
    lines: int = Field(default=50, ge=1, le=200)

@tool_register(
    name="query_service_logs",
    risk=RiskLevel.READ_ONLY,
    timeout_sec=3.0,
    max_output_chars=4000,
)
def query_service_logs(args: QueryLogsArgs) -> dict:
    ...

2. 启动受控执行循环

runner = SafeToolRunner(
    tools=[query_service_logs, restart_container],
    max_steps=6,
    duplicate_call_limit=2,
    on_confirm_required=prompt_cli_confirmation,
    audit_log_path="logs/tool_trace.jsonl",
)
result = runner.run_conversation(messages)

公开范围与已知限制说明:本模块完整的设计原则、状态机拆解与上下文工程策略已在下方两篇技术长文中公开;它定位于轻量级单智能体受控工具执行层,暂不包含跨多智能体的分布式消息编排。

04 开发记录与关联文章

版本演进与下一步计划

  1. v1.2 · 2026-03

    加入重复调用哈希指纹检测与工具输出长度自适应头尾裁剪机制。

  2. v1.0 · 2026-02

    完成基于 Pydantic 的工具注册装饰器、读写分级闸门与 JSONL 审计日志落盘。

  3. Next · 规划中

    结合树莓派环境监测节点,增加面向本地运维诊断的只读巡检工具集。