ToolBoundary Skill 技能

技能简介

ToolBoundary 是一个 Python 库，把「这次工具调用现在到底允不允许」这件事在本地、快速地回答掉。当前 v1.0.3，MIT 协议，要求 Python 3.9 以上，核心安装零依赖。作者的定位很直接：它是一个库而不是一个服务——不需要单独的 Web 应用、不需要起数据库、不用登录任何控制台，策略就是普通 Python 代码，跟你的代码一起进版本库。PyPI 近 30 天下载量约 211，GitHub 约 4 星、8 个 fork，仍属早期项目。

核心能力

1. 本地即决策：每次 Agent 试图调用工具时，由本地 Boundary 判定是否放行，不依赖外部服务。
2. 细粒度权限：按工具分别设定只读或执行模式、可设置每小时的调用次数上限、可设置金额等数值上限。
3. 禁止清单：blocked_operations 直接封禁删除等危险操作，命中即拒绝。
4. 全局限速：max_actions_per_hour 给整个 Agent 的动作量设天花板。
5. 紧急停止：设置 kill_switch_env 指定的环境变量（默认 TOOLBOUNDARY_KILL_SWITCH=1）后，该 Agent 后续所有调用立即被拒，无需重启也不需要改代码。
6. 两种执行方式：@guarded_tool 装饰器包住普通函数，或 guard_tools 包装 LangChain 的 BaseTool——后者把检查放进 LangChain 自己的工具执行路径，而不是靠 Agent 记得去调。
7. 外部授权提供方：以 EvidenceProvider 协议接入，ProviderMode.OBSERVE 只记录、ENFORCE 强制放行，外部服务不可用时优雅降级；提供方只能收紧本地策略，不能放宽。
8. 结构化审计：所有放行、拒绝、需审批的判定自动写入审计日志，类似密钥的参数名默认脱敏。

安装配置

1. 核心安装（零依赖）：pip install toolboundary。
2. LangChain 集成：pip install toolboundary[langchain]。
3. 多进程共享限流与令牌存储：pip install toolboundary[redis]，提供 RedisSlidingWindowRateLimiter 与 RedisTokenStore。
4. 构造 Boundary：指定 agent_name、autonomy（AutonomyLevel.LIMITED_AUTONOMOUS 等）、permissions 列表、blocked_operations、max_actions_per_hour 与 kill_switch_env。
5. 紧急停止：把 TOOLBOUNDARY_KILL_SWITCH=1 写进环境变量即可，不必改动代码。

使用步骤

1. 创建 Boundary 实例，登记每个工具的权限（ToolPermission 名称、access_mode、max_calls_per_hour、max_value）。
2. 在 Agent 的工具调用处调用 boundary.check(工具名, access_mode=...)；放行时静默通过。
3. 违规时抛出 BoundaryViolation（另有 KillSwitchActive、RateLimitExceeded 等子类），需要人工介入时抛 ApprovalRequired。
4. 用 @guarded_tool 装饰普通函数，可指定 value_arg 校验金额等数值，超限时函数体根本不会执行。
5. 使用 LangChain 时改用 guard_tools([...], boundary, default_access_mode=..., overrides={...}) 包装工具集合。
6. 事后从审计日志回溯每一次判定，确认哪些调用被拦下、哪些走了审批。

适用场景

1. 客服 Agent：允许只读工单库，限制发信频次，禁删工单。
2. 金融类 Agent：给转账工具设单笔金额上限与每小时调用次数上限。
3. 多 Agent 系统：给每个 Agent 单独定义权限边界与自动关停开关。
4. 审计与合规：需要完整、可检索的工具调用证据链。
5. 研究或测试中，想在本地复现「模型越权调用」并验证拦截行为。

适用人群

在生产环境跑 Agent 或 LLM 工具调用的后端工程师；关心 AI Agent 权限与合规的技术负责人；使用 LangChain 或自建工具链的开发者；做 Agent 安全评测的研究者。

工作原理

Boundary 是本地策略的最终裁决者：工具调用先被冻结为 FrozenToolCall，与本地权限规则比对后产出 LocalDecision，再可选地交给外部 EvidenceProvider 授权（提供方只能加严），最后由 ExecutionRecord 与 ProviderReceipt 落审计。装饰器方式让检查成为函数调用的必经路径，不存在绕过检查直连实现的代码路径；LangChain 方式把检查嵌进框架自身的工具执行环节。v1.0.3 补上了网络代理目标校验、操作白名单必须具名、数值上限的合法性校验、审计参数脱敏，以及「返回 None 也算成功执行」的判定修正。

官方链接

• PyPI：https://pypi.org/project/toolboundary/
• GitHub：https://github.com/Jaycubic/toolboundary
• API 文档：https://github.com/Jaycubic/toolboundary/blob/main/docs/API.md