工具

工具是模型与环境的契约：文件系统、Shell、MCP、REST、技能。运行时收集 schema、路由 tool_calls，再经策略和钩子执行。

SDK 用 @tool / BaseTool。Near / Studio 用 agenticx/cli/agent_tools.py 里的 STUDIO_TOOLS 加 dispatch_tool_async。不要假设库里每个工具都会出现在 Studio。

实践案例：一张工具卡，不要每个调用一条气泡

场景。 「列出这个仓库的未关闭 issue」需要 GitHub MCP。

1. 设置 → MCP：该服务必须显示已添加（绿点）。「已连接」不等于 mcp_call 一定成功。
2. 在对话里要 issue 列表。模型应经 dispatch_tool_async 走 mcp_call（或已发现的工具名）。
3. 群聊要把「正在调用 / 工具完成」折进该分身一张卡。普通窗格用 ToolCallCard，默认折叠，只有需要行内确认才展开。

你会看到。 工具卡和助手气泡对齐。展开才能看参数和返回。失败应写出可读原因（找不到 npx、Docker 卡住、schema 不符），不能只有转圈。

`@tool` 装饰器

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

参数

行为

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

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

内置 Studio 工具

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

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

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。

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），并显式传入路径加载。

远程工具

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

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

OpenAPI 工具集

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

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

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

技能包

技能遵循 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，运行技能载荷时可走沙箱或替代执行路径。

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

关键模块：

快速安装：

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`）

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

重试与超时

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

相关

• ApprovalRequiredError 会直接抛出，不按普通失败处理。
• 同一类上的 sandbox_config: SandboxConfig 可为代码执行辅助启用高级后端（subprocess、microsandbox、docker）。

凭据管理

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

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

沙箱集成

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

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

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