企业官网建设流程全解析

Agent Tool Registry（ATR）实战指南：用 agent-governance-toolkit 构建类型安全的去中心化 Agent 工具注册表

【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit

本文是 Agent OS（AI Agent 内核级治理体系）中ATR - Agent Tool Registry模块的完整技术指南。ATR 是 Agent OS 生态中负责工具注册、运行时发现与 LLM 函数调用 Schema 生成的基础设施组件（Layer 2 Infrastructure），位于 agent-governance-python/agent-os/modules/atr 目录。读完本文，你将掌握：如何用 5 行代码注册一个可被 LLM 调用的工具、如何利用版本约束与标签检索工具、如何把工具导出为 OpenAI Function Calling / Anthropic Tool Use 格式，以及如何用 Docker 沙箱安全执行不可信代码。

为什么需要 ATR：Scale by Subtraction

大多数 Agent 框架把工具直接硬编码进运行时（hardcode tools directly into runtimes），这会带来严重的耦合问题：新增一个能力就要重启整个系统；修改一个函数签名就要更新数十个 Agent；"靠加法扩展"（Scale by addition）最终导致系统脆弱。

ATR 的设计哲学是Scale by Subtraction——把 Agent 逻辑与工具实现之间的依赖"减去"：

• 工具提供方（Tool Providers）与工具消费方（Tool Consumers）被彻底解耦；
• Agent 在运行时通过标准化接口动态发现能力，而不是在代码里写死；
• 工具注册不需要重启基础设施（tool registration should not require restarting your infrastructure）。

从实现上看，这种解耦体现在 ATR 的核心约定上：注册表只存规格（specs），不执行调用。Registry的 docstring 明确写道："This registry stores tool specifications and their callables but does NOT execute them. It's purely a lookup and discovery mechanism. The actual execution is handled by the Agent Runtime (Control Plane)."（见 registry.py）。执行发生在控制平面（Agent Control Plane），并配有完整的错误处理与可观测性。

安装与依赖

原版 ATR 文档给出的安装方式：

pip install agentmesh-tool-registry

若需要使用 Docker 沙箱执行（推荐用于不可信代码）：

pip install agentmesh-tool-registry[sandbox]

需要特别说明的是：当前仓库 pyproject.toml 中实际定义的发行包名为agent-governance-toolkit-tool-registry（版本 5.0.0，模块导入名仍为atr），Python 版本要求>=3.11，核心依赖仅pydantic>=2.4.0,<3.0.0，因此整个注册表在纯 Python 环境下非常轻量。sandbox可选依赖对应docker>=7.0.0,<8.0。

仓库还为atr提供了 CLI 入口（atr = "atr.cli:main"），并声明了py.typed标记，属于 Typing::Typed 包，IDE 与类型检查器可以完整推断 API 类型。

快速开始：5 行代码注册一个工具

注册一个工具只需要一个装饰器：

import atr @atr.register(name="calculator", tags=["math"]) def add(a: int, b: int) -> int: """Add two numbers.""" return a + b

发现并执行：

tool = atr.get_tool("calculator") schema = tool.to_openai_function_schema() # OpenAI-compatible func = atr.get_callable("calculator") result = func(a=5, b=3) # Returns 8 # Or use sandboxed execution (recommended for untrusted code) from atr import DockerExecutor docker_exec = DockerExecutor() result = atr.execute_tool("calculator", {"a": 5, "b": 3}, executor=docker_exec)

这里有一个关键细节值得注意：@atr.register()装饰器返回的是原始函数本身，而不是包装后的函数（"we don't wrap it"）。decorator.py中的__call__方法在提取签名、构建ToolSpec并完成注册后直接return func（见 decorator.py）。这意味着：

• 原有函数行为完全不变，add(5, 3)照常可用；
• 注册过程不会执行函数体——测试 test_decorator.py 中专门用计数器函数验证了"装饰后调用次数仍为 0"；
• 注册表通过ToolSpec._callable_func私有属性保存函数引用，但只在显式获取/执行时才调用。

仓库自带可运行的完整示例 examples/demo.py 与 examples/sandbox_demo.py，可以直接作为入门模板。

注册表核心 API 深入

atr包在__init__.py中暴露了一套面向全局注册表的便捷函数（所有实现最终都委托给全局Registry实例，见init.py）。

检索工具：get_tool / get_tool_handle / get_callable

# 获取 ToolSpec（规格，不执行） spec = atr.get_tool("calculator", version=">=1.0.0") print(spec.metadata.description) # 获取 ToolHandle（带全部策略的执行句柄，推荐） tool = atr.get_tool_handle("pdf_parser", version=">=1.0.0") result = await tool.call_async(file_path="doc.pdf") # 或同步执行 result = tool.call(file_path="doc.pdf") # 直接取回原始函数（调用方自行执行） func = atr.get_callable("calculator") result = func(a=1, b=2)

ToolHandle是官方推荐的生产级执行入口：它自动叠加限流（rate limiting）、重试（retries）、指标采集（metrics collection）、依赖注入（dependency injection），并通过call()/call_async()提供同步/异步两种执行方式（见 schema.py）。

版本约束语法

Registry内置了完整的语义化版本（SemVer）匹配引擎version_matches()（见 registry.py），支持：

安全设计：协议前缀（git+、file:、http:、https:、ssh:、npm:、workspace:）和非 SemVer 标签（latest、next、canary、nightly）会被显式拒绝为不匹配——这是为了防止依赖混淆与供应链攻击。

查询版本时若不传version，则默认返回最高版本（max(available.keys(), key=parse_version)）。同一工具可以注册多个版本，get_all_versions(name)按新到旧排序返回。

发现与筛选：list_tools / search_tools

# 按标签筛选 math_tools = atr.list_tools(tag="math") # 按成本等级筛选（CostLevel.FREE/LOW/MEDIUM/HIGH） cheap_tools = atr.list_tools(cost=CostLevel.LOW) # 按副作用类型筛选（SideEffect.READ/WRITE/DELETE/NETWORK/FILESYSTEM） read_only = atr.list_tools(side_effect=SideEffect.READ) # 关键词搜索（大小写不敏感，匹配 name/description/tags） results = atr.search_tools("scrape")

生命周期管理

# 查看某工具全部版本 versions = atr.get_all_versions("pdf_parser") # ["2.0.0", "1.1.0", "1.0.0"] # 废弃某个版本（可附迁移指引），默认查询会跳过废弃版本 atr.deprecate_tool("pdf_parser", "1.0.0", "Use version 2.0.0 instead.") # 反注册与清空 registry.unregister_tool("pdf_parser", "1.0.0") # 移除指定版本 registry.clear() # 清空全部

注册表定义了三种专有异常：ToolNotFoundError（工具不存在或全部版本已废弃）、ToolAlreadyExistsError（同名同版本重复注册，可用replace=True覆盖）、VersionConstraintError（无版本满足约束），方便上层 Agent 运行时做精确的错误处理。

注册表配置

若需要为全局注册表注入依赖容器、指标采集器或访问控制管理器：

from atr import DependencyContainer, configure_registry container = DependencyContainer() container.register(Config, Config(api_key="secret")) configure_registry(container=container) registry = atr.get_registry() # 官方推荐的方式，而非直接访问私有 _global_registry

@register 装饰器：严格类型检查与 Schema 自动生成

@atr.register()的核心价值在于把 Python 函数签名自动翻译为机器可读的 ToolSpec，其实现分四步（见 decorator.py）：

1. 提取元数据：工具名默认取函数名，描述默认取 docstring，is_async通过asyncio.iscoroutinefunction自动检测；
2. 提取参数：用inspect.signature+get_type_hints遍历参数，把 Python 类型映射为ParameterType（str→string、int→integer、float→number、bool→boolean、list→array、dict→object；Optional[X]会解包为 X，List[str]/Dict[str, int]会映射为 array/object）；
3. 提取返回值：有-> T注解时生成returns规格；
4. 注册：构建ToolSpec并存入注册表。

强约束：禁止魔法参数（No Magic Arguments）

这是 ATR 与普通装饰器最大的不同：所有参数必须有类型注解，否则注册时直接抛ValueError。测试 test_decorator.py 验证了无类型注解的函数def bad_func(url, timeout=30)会触发"must have a type hint"错误。这保证了生成的 LLM Schema 永远完整、可用，不会出现模型无法推断的参数类型。

完整注册参数一览

高级用法示例（来自 decorator.py 与包文档）：

from atr import register, RetryPolicy, inject @register( name="pdf_parser", version="1.0.0", async_=True, rate_limit="10/minute", permissions=["claims-agent"], retry_policy=RetryPolicy(max_attempts=3, backoff="exponential"), ) async def pdf_parser(file_path: str, config: Config = inject()) -> dict: """Parse a PDF document.""" ...

ToolSpec：Pydantic 强类型规格与 Schema 导出

ToolSpec是整个 ATR 的数据核心（见 schema.py），由三部分组成：

• metadata: ToolMetadata：名称、描述、版本、作者、成本等级、副作用、标签、is_async、权限、限流、废弃标记；
• parameters: List[ParameterSpec]：每个参数的名字、类型、描述、是否必填、默认值，以及 array 的items、object 的properties、枚举的enum；
• returns: Optional[ParameterSpec]：返回值规格。

ParameterSpec内置一条校验规则：必填参数不能设置默认值（validate_default会在两者冲突时抛错），确保 Schema 语义自洽。

导出为 LLM 函数调用格式

spec = atr.get_tool("calculator") # OpenAI Function Calling 格式 openai_schema = spec.to_openai_function_schema() # -> {"name": ..., "description": ..., "parameters": {"type": "object", # "properties": {...}, "required": [...]}} # Anthropic Tool Use 格式 anthropic_schema = spec.to_anthropic_tool_schema() # -> {"name": ..., "description": ..., "input_schema": {...}}

这两个方法把ToolSpec翻译为标准 JSON Schema 风格的函数描述，是 Agent 与 LLM 之间函数调用（Function Calling）的桥接层。配合search_tools/list_tools，Agent 可以在运行时动态把全部可用工具批量导出给模型，实现"能力即插即用"。

预置安全工具集（Safe Toolkit）

仓库还提供了一批预配置的安全工具，通过 atr/tools/safe/toolkit.py 的create_safe_toolkit(preset, config)工厂按预设创建：

例如restricted预设要求allowed_domains=[]、sandbox_paths=[]必须由调用方显式配置，HTTP 限流降至 10 次、响应体上限 1MB，文件读取默认关闭符号链接（follow_symlinks=False）。这些工具类是"受限工具集"的最佳实践模板，配合 ATR 的沙箱执行可以构建纵深防御。

沙箱执行：Docker 隔离运行不可信代码

SDLC Agent 和 LLM 可能生成你不能安全地在宿主机直接运行的 Python 或 Bash 脚本。ATR 的DockerExecutor让这类代码在一次性容器中执行。

为什么需要沙箱执行

• 隔离（Isolation）：代码运行在临时容器中，与宿主机完全隔离；
• 安全（Security）：无网络访问、内存受限、自动清理；
• 安全（Safety）：防御恶意代码、资源耗尽（resource exhaustion）和意外副作用。

使用方式

import atr from atr import DockerExecutor @atr.register(name="processor", tags=["data"]) def process_data(numbers: list) -> int: """Process data safely in a sandbox.""" return sum(numbers) # Option 1: Direct execution (NOT sandboxed - trusted code only) result = atr.execute_tool("processor", {"numbers": [1, 2, 3, 4]}) # Option 2: Sandboxed execution (RECOMMENDED for untrusted code) docker_exec = DockerExecutor() result = atr.execute_tool( "processor", {"numbers": [1, 2, 3, 4]}, executor=docker_exec, timeout=30 )

execute_tool(name, args, executor, timeout)是便捷函数：不传 executor 时默认使用LocalExecutor（宿主机直跑，仅限可信代码）；传入DockerExecutor即进入沙箱模式（见init.py）。

执行模式对比

DockerExecutor 实现细节

从 executor.py 可以看到完整的沙箱链路：

1. 序列化函数源码：用inspect.getsource提取函数定义（剥离装饰器、反缩进），内置函数/lambda 因拿不到源码会报ExecutorError；
2. 生成执行脚本：将参数 JSON 序列化嵌入脚本，用__RESULT_START__/__RESULT_END__标记包裹结果输出；
3. 启动临时容器：默认镜像python:3.9-slim（auto_pull=True时自动拉取），通过卷挂载把脚本以只读方式传入/app，关键安全参数为：
   • network_mode="none"：禁用网络；
   • mem_limit="512m"：内存上限 512MB；
   • 执行后强制stop+remove：自动清理容器；
4. 超时控制：container.wait(timeout=timeout)超时抛出ExecutionTimeoutError；
5. 结果解析：从日志中提取标记间 JSON，成功返回result，失败抛ExecutorError并携带容器日志。

沙箱执行最佳实践（来自 sandbox_demo.py）

1. 对不可信或 Agent 生成的代码始终使用 DockerExecutor；
2. 设置合理的 timeout 防止执行挂起；
3. LocalExecutor 只用于可信、预先审查过的代码；
4. 生产环境监控 Docker 资源使用；
5. 考虑使用依赖最少的自定义 Docker 镜像；
6. 上线前先在 Docker 中测试你的工具。

策略引擎：重试、限流、健康检查与访问控制

ToolHandle之所以是生产级执行入口，是因为它在执行前自动叠加四类策略（见 schema.py 与 policies.py）：

• 限流（RateLimitPolicy）：rate_limit="10/minute"会解析为令牌桶策略，超限抛RateLimitExceeded，支持同步acquire与异步acquire_async；
• 重试（RetryPolicy）：max_attempts（含首次）、backoff（constant/linear/exponential/fibonacci）、initial_delay、max_delay、jitter（随机抖动防惊群）、retry_on（指定可重试的异常类型）以及on_retry回调，提供with_retry/with_retry_async；
• 依赖注入：配置container后，InjectionResolver会解析inject()标记的参数；
• 指标采集：每次调用记录latency_ms、success、error、rate_limited到MetricsCollector。

此外还有HealthCheck（CallableHealthCheck/HttpHealthCheck/TcpHealthCheck，支持check()/check_async()）与AccessPolicy（Principal/Permission/AccessControlManager），分别用于工具可用性探活与细粒度授权。测试 test_v2_features.py 覆盖了这些增强特性的行为。

架构定位与生态地图

atr位于Agent OS 栈的第 2 层（Infrastructure）。

职责：工具注册、发现与 Schema 生成。不负责：工具执行（由 Agent Control Plane 处理）——"The registry stores specifications, not callables. Execution happens in the control plane with proper error handling and observability."

设计要点

• 注册表：基于内存字典的轻量查找（本地或分布式）；
• 装饰器：@atr.register()提取类型签名并强制严格类型检查；
• 规格：Pydantic Schema 强制校验输入、输出、副作用与元数据；
• Schema 导出：转换为 OpenAI、Anthropic 及其他 LLM 函数调用格式。

在 Agent OS 生态中的位置

ATR 是一个模块化 Agent OS 中的组件，每一层解决一个特定问题：

• Primitives（Layer 1）：caas（Context-as-a-Service，Agent 记忆与状态管理）、cmvk（Context Verification Kit，上下文完整性密码学验证，见 modules/cmvk）、emk（Episodic Memory Kit，长期记忆存取）；
• Infrastructure（Layer 2）：iatp（Inter-Agent Trust Protocol，安全消息认证，见 modules/iatp）、amb（Agent Message Bus，解耦事件传输，见 modules/amb）、atr（Agent Tool Registry，工具发现与 Schema 生成，即本模块）；
• Framework（Layer 3）：agent-control-plane（Agent 编排与生命周期管理，见 modules/control-plane）、scak（Self-Correction Agent Kit，自动化错误恢复与学习）。

这种分层设计让 ATR 只做"工具能力的注册表"，把执行、编排、信任交给相邻层，正是"Scale by Subtraction"在能力层（capability layer）的落地。

测试与验证

模块自带完整测试套件（位于 tests/，通过pytest运行，配置了覆盖率统计）：

• test_decorator.py：装饰器类型映射、参数/返回类型提取、无类型注解报错、函数原样保留、装饰不执行、非法 cost/side_effect 回退；
• test_registry.py：注册/查询/版本约束/废弃/搜索/异常路径；
• test_schema.py：ToolSpec 校验与 OpenAI/Anthropic Schema 导出；
• test_executor.py 与 test_integration_executor.py：本地/沙箱执行与超时；
• test_v2_features.py：限流、重试、注入等增强特性。

模块另附 CHANGELOG.md、IMPLEMENTATION_SUMMARY.md 与 docs/PYPI_SETUP.md，可进一步了解演进历史与发布配置。

引用与许可

如果在研究中使用 ATR，请引用：

@software{atr2024, title={ATR: Agent Tool Registry}, author={Siddique, Imran}, year={2024}, note={Part of the Agent OS ecosystem} }

ATR 采用 MIT 许可（详见仓库根目录 LICENSE）。

小结

ATR（Agent Tool Registry）是 Agent OS 基础设施层中"能力解耦"的关键一环：它以"注册表只存规格、执行交给控制平面"的边界划分，通过@atr.register()自动把带类型注解的 Python 函数转化为 Pydantic 强校验的ToolSpec，原生导出 OpenAI / Anthropic 函数调用 Schema，并提供版本约束、标签检索、废弃管理、重试/限流/健康检查/访问控制等治理策略，最后用DockerExecutor为不可信代码提供无网络、限内存、自动清理的隔离沙箱。对于需要在 Agent 体系中构建可动态扩展、可治理的工具能力层的开发者，这套"注册-发现-导出-沙箱执行"的完整链路可以直接作为生产方案参考。

【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit