工具

AgenticX 工具系统概览与用法。

工具

概览

工具是语言模型与运行环境之间的契约。在 AgenticX 中，它们位于智能体推理与副作用之间：文件系统、Shell、MCP 服务器、由规范生成的 REST 调用以及打包的技能。运行时收集工具 schema 供模型使用，将 tool_calls 路由到具体实现，并通过统一的策略、安全与审计钩子执行。

关注点	主要组件
声明工具	`@tool`、`FunctionTool`、`BaseTool` 子类
Studio / 工作区	`STUDIO_TOOLS`（OpenAI 风格 function schema + 分发）
外部 MCP	`MCPHub`、`MCPClientV2`、`RemoteTool`
规范驱动 HTTP API	`OpenAPIToolset`
技能包	`SkillBundleLoader`、`SkillTool`
执行	`ToolExecutor`（`agenticx.tools.executor`）
隔离提示	`SandboxPolicy`、`SandboxConfig`

!!! note "命名说明"

公开 Python API 位于 agenticx.tools 与 agenticx.safety。部分旧版或适配层仍引用 agenticx.core.executor.ToolExecutor；下文所述沙箱、安全层与审计能力请优先使用 agenticx.tools.executor.ToolExecutor。

`@tool` 装饰器

使用 agenticx.tools.function_tool.tool 将普通函数转为 FunctionTool（BaseTool）。

参数

参数	作用
`name`	暴露给模型的工具 id；默认为函数名
`description`	覆盖从 docstring 自动解析的摘要
`args_schema`	可选 Pydantic `BaseModel`；省略时根据类型注解与 docstring `Args` 构建
`timeout`	单工具超时（秒），与 executor 默认值合并
`organization_id`	可选租户范围，用于策略 / 存储

行为

解析 docstring（短描述、长描述、各参数说明）。
将参数映射为 Pydantic 模型，用于导出 JSON Schema 与运行时校验。

python

1from agenticx.tools.function_tool import tool
2
3@tool(name="add", description="Add two integers.", timeout=5.0)
4def add(a: int, b: int) -> int:
5    """Add a and b.
6
7    Args:
8        a: First operand.
9        b: Second operand.
10    """
11    return a + b

!!! tip "显式 schema"

若需稳定的对外契约，请传入专用 Pydantic 模型的 args_schema=，而非仅依赖类型推断。

内置 Studio 工具

Studio 会话使用 agenticx.cli.agent_tools 中的 STUDIO_TOOLS：一组 OpenAI 风格 function 定义，绑定异步 handler。核心类别：

名称	用途
`bash_exec`	在工作区执行 Shell 命令（含守卫与确认流程）
`file_read`	读取文件内容，可选行范围
`file_write`	diff 预览与用户确认后整文件写入
`file_edit`	diff 预览与用户确认后局部替换
`list_files`	列出工作区文件
`codegen`	驱动代码生成引擎（agent / workflow / tool / skill 目标）
`mcp_connect`、`mcp_call`、`mcp_import`	连接 MCP 服务器、调用工具、导入外部 MCP JSON
`skill_use`、`skill_list`	激活或枚举技能包
`todo_write`	会话结构化任务列表
`scratchpad_read`、`scratchpad_write`	会话草稿板
`memory_append`、`memory_search`	轻量记忆辅助
`lsp_goto_definition`、`lsp_find_references`、`lsp_hover`、`lsp_diagnostics`	LSP 导航与诊断

仅 Meta 可用的工具（委派、资源检查等）单独定义（META_AGENT_TOOLS）；分身通常获得上述 Studio 子集。

!!! warning "破坏性写入"

file_write 与 file_edit 设计为需确认的流程。自动化也应遵守 Studio 服务端相同的 UX 保障。

MCP Hub

MCPHub（agenticx.tools.mcp_hub）聚合多个 MCP 服务器：

`MCPClientV2`：每个 MCPServerConfig 一个客户端，持久会话，discover_tools() / call_tool()。
`discover_all_tools()`：合并工具列表并构建路由表（名称冲突时用前缀路由名处理）。
`get_tools_for_agent()`：当 auto_mode=True 时返回可注入的 MCPHubTool 实例（BaseTool）。
`MCPHubConfig`：Pydantic 模型，含 servers: List[MCPServerConfig] 与 auto_mode。

python

1from agenticx.tools.mcp_hub import MCPHub, MCPHubConfig
2from agenticx.tools.remote_v2 import MCPServerConfig
3
4config = MCPHubConfig(
5    servers=[
6        MCPServerConfig(name="docs", command="npx", args=["-y", "@some/mcp-server"]),
7    ],
8    auto_mode=True,
9)
10# hub = MCPHub.from_config(config)  # then await hub.discover_all_tools()

配置文件

agenticx.tools.remote 中的 load_mcp_config() 读取 JSON 文件（默认 ~/.cursor/mcp.json）为 Dict[str, MCPServerConfig]。
可在项目本地维护相同结构（例如 mcp_config.json），并显式传入路径加载。

!!! note "传输层"

`MCPHub` / `MCPClientV2` 内置 MCP 客户端路径以 stdio 为主（子进程）。HTTP 或 SSE MCP 端点通常需本地命令或代理转为 stdio 与 AgenticX 通信。

远程工具

AgenticX 不提供名为 RemoteToolProvider 的类。远程能力建模如下：

类型	用途
`RemoteTool`	包装单个 MCP 工具的 `BaseTool`，绑定 `MCPServerConfig`
`MCPClient`	旧版客户端，列出工具并构造 `RemoteTool`
`MCPClientV2`	推荐的基于会话的客户端；`MCPHub` 内部使用

MCPServerConfig 字段包括 command、args、env、timeout、可选 cwd、enabled_tools 与 assign_to_agents（用于过滤）。

!!! tip "密钥"

将 token 放在 MCPServerConfig 的 env 中，或在构建配置前从 CredentialStore 解析。

OpenAPI 工具集

`OpenAPIToolset`（`agenticx.tools.openapi_toolset`）从 OpenAPI 3.x 或 Swagger 2.0 构建 BaseTool 实例：

OpenAPIToolset.from_file(path)
OpenAPIToolset.from_url(url)

各 operation 成为可调用工具，带生成的参数模型与按规范执行的 HTTP 请求。

!!! warning "鉴权与副作用"

生成的工具会发起真实 HTTP 请求。请限制 base URL、固定 spec 并谨慎提供凭据——应像生产 API 客户端一样对待。

技能包

技能遵循 Anthropic 风格 `SKILL.md` 布局与 YAML front matter。`SkillBundleLoader`（`agenticx.tools.skill_bundle`）扫描标准路径（`.agents/skills`、`.agent/skills`、`~/.agents/skills`、`.claude/skills`、包内置等），应用可选 `SkillGate` 规则（`metadata.agenticx.gate`），并将技能暴露为工具（如 `SkillTool`）以支持列表/读取与渐进披露。

会话级注入

Studio 中 skill_use / skill_list 与 loader 联动，激活的技能影响当前会话上下文。
SkillBundleLoader 接受 execution_backend，运行技能载荷时可走沙箱或替代执行路径。

!!! note "SkillBundle 与 loader"

代码以 SkillBundleLoader 与 SkillMetadata 为中心；没有单独的 SkillBundle 类。概念上的「bundle」指从配置搜索路径加载的技能集合。

AGX Bundle 安装也会落在 `~/.agenticx/skills/bundles/`，该路径自动纳入扫描，无需额外配置即可发现 bundled 技能。

AGX Bundle

AGX Bundle（agenticx.extensions）是可分发目录包，将 Skills、MCP 服务器配置、Avatar 预设与 Memory 模板组合为单一单元。

1my-bundle/
2├── agx-bundle.yaml
3├── skills/
4│   └── my-skill/SKILL.md
5├── mcp/
6│   └── server.json
7├── avatars/
8│   └── preset.yaml
9└── memory/
10    └── template.md

关键模块：

模块	用途
`agenticx.extensions.bundle`	解析 `agx-bundle.yaml`，强制安全相对路径
`agenticx.extensions.installer`	安装/卸载 bundle，管理 `~/.agenticx/bundles.json`
`agenticx.extensions.registry_hub`	多源市场搜索与安装

快速安装：

python

1from pathlib import Path
2from agenticx.extensions.installer import install_bundle
3
4result = install_bundle(Path("./my-bundle"))
5print(result.skills_installed, result.mcp_servers_installed)

详见扩展与技能生态，含 AGX Bundle 格式、市场配置与 Desktop UI walkthrough。

工具执行器

ToolExecutor（agenticx.tools.executor）是 BaseTool 实例的共享执行流水线。

典型流程（`execute` / `aexecute`）

可选 `policy_stack.check(tool.name)` — 声明式拒绝规则（受 OpenClaw 启发）。
从工具与 `default_timeout` 解析超时。
可选 `SafetyLayer.validate_tool_input` — 运行前拦截或标记参数。
`tool.run` / `tool.arun` — 内部按 `args_schema`（Pydantic）校验 kwargs。
可选对字符串结果执行 `SafetyLayer.sanitize_tool_output`。
工具上可选 `post_state_hook` 处理状态 sidecar。
追加 `ToolCallingRecord`（成功或失败），滚动保留。

重试与超时

构造参数	含义
`max_retries`	失败后额外尝试次数（默认 `3`）
`retry_delay`	重试间隔（秒）
`default_timeout`	工具未设 `timeout` 时的回退值

明显不可重试的情况（如 ToolTimeoutError）会跳过重试。

凭据管理

`CredentialStore`（agenticx.tools.credentials）默认在 ~/.agenticx/credentials 下存储加密的键值材料（安装 cryptography 时使用 Fernet）。供工具或 MCP env 映射在运行时需要的 API 密钥与 token。

`SecurityManager`（agenticx.core.security）也内嵌 CredentialStore，用于更高层的权限与审计集成。

!!! warning "文件系统权限"

加密密钥与存储目录相邻（encryption.key）。共享机器上请确保 ~/.agenticx 仅当前用户可访问。

沙箱集成

`SandboxConfig`（agenticx.tools.executor）为高级运行选择后端：

后端	隔离
`subprocess`	独立 OS 进程
`microsandbox`	沙箱运行时（可用时）
`docker`	容器隔离
`auto`	解析器自动选择实现

`SandboxPolicy`（`agenticx.safety.sandbox_policy`）根据风险等级或工具名启发式推荐后端：

推断/指定风险	建议后端
`LOW`	不强制后端（`None`）
`MEDIUM`	`subprocess`
`HIGH` / `CRITICAL`	`docker`

可选 `ToolRiskProfile` 按 tool_name 覆盖推断（force_backend、network_enabled、max_timeout）。

!!! tip "策略与执行器对齐"

用 SandboxPolicy.recommend() 构建或调优 ToolExecutor 的 SandboxConfig；即使默认 Studio 工具在工作区进程内运行，高风险工具仍应使用更强隔离。