Tools

Tools are the contract between the model and the environment: filesystem, shell, MCP, REST, and skills. The runtime collects schemas, routes tool_calls, and runs them through policy and hooks.

Use @tool / BaseTool in the SDK. Near / Studio uses STUDIO_TOOLS in agenticx/cli/agent_tools.py plus dispatch_tool_async. Do not assume every library tool is registered in Studio.

Worked example: one tool card, not one bubble per call

Scene. “List open issues on this repo” needs GitHub MCP.

1. Settings → MCP: the server must show Added (green). Connecting is not the same as mcp_call succeeding.
2. In chat, ask for the issue list. The model should call mcp_call (or a discovered tool name) through dispatch_tool_async.
3. Group chat must fold “calling tool / tool done” into one card for that avatar. A normal pane uses ToolCallCard, folded unless it needs inline confirm.

What you should see. A card aligned with the assistant bubble. Expand to read arguments and the result. Failures should show a readable error (missing npx, Docker hang, schema mismatch), not a silent spinner.

@tool decorator

Use agenticx.tools.function_tool.tool to turn a plain function into a FunctionTool (BaseTool).

Parameters

Behavior

• Docstrings are parsed (short + long description, per-parameter text).
• Parameters are mapped to a Pydantic model for JSON Schema export and runtime validation.

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

Built-in Studio tools

Studio sessions use STUDIO_TOOLS in agenticx.cli.agent_tools: a list of OpenAI-style function definitions wired to async handlers. Core categories:

Meta-only tools (delegation, resource checks, etc.) are defined separately (META_AGENT_TOOLS); avatars typically receive the Studio subset above.

MCP Hub

MCPHub (agenticx.tools.mcp_hub) aggregates multiple MCP servers:

• MCPClientV2: one client per MCPServerConfig, persistent session, discover_tools() / call_tool().
• discover_all_tools(): merges tool lists and builds a routing table (handles name collisions with prefixed routed names).
• get_tools_for_agent(): when auto_mode=True, returns MCPHubTool instances (BaseTool) ready for injection.
• MCPHubConfig: Pydantic model with servers: List[MCPServerConfig] and 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()

Configuration files

• load_mcp_config() in agenticx.tools.remote reads a JSON file (default ~/.cursor/mcp.json) into Dict[str, MCPServerConfig].
• You can maintain the same structure in a project-local file (for example mcp_config.json) and load it with an explicit path.

Remote tools

AgenticX does not ship a class named RemoteToolProvider. Remote capability is modeled as:

MCPServerConfig fields include command, args, env, timeout, optional cwd, enabled_tools, and assign_to_agents for filtering.

OpenAPI toolset

OpenAPIToolset (agenticx.tools.openapi_toolset) builds BaseTool instances from OpenAPI 3.x or Swagger 2.0:

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

Operations become callable tools with generated parameter models and HTTP execution aligned to the spec.

Skill bundle

Skills follow the Anthropic-style SKILL.md layout with YAML front matter. SkillBundleLoader (agenticx.tools.skill_bundle) scans standard locations (.agents/skills, .agent/skills, ~/.agents/skills, .claude/skills, package builtins, etc.), applies optional SkillGate rules (metadata.agenticx.gate), and exposes skills as tools (e.g. SkillTool) for list/read and progressive disclosure.

Session-level injection

• In Studio, skill_use / skill_list tie into the loader so activated skills affect the current session context.
• SkillBundleLoader accepts execution_backend for sandboxed or alternate execution paths when running skill payloads.

AGX Bundle installs also land in ~/.agenticx/skills/bundles/, which is automatically included in the scan paths, so bundled skills are discovered without any extra config.

AGX Bundle

An AGX Bundle (agenticx.extensions) is a distributable directory package that combines Skills, MCP server configs, Avatar presets, and Memory templates into a single distributable unit.

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

Key modules:

Quick install:

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)

See Extensions & Skill Ecosystem for the full guide including AGX Bundle format, marketplace configuration, and Desktop UI walkthrough.

Tool executor

ToolExecutor (agenticx.tools.executor) is the shared execution pipeline for BaseTool instances.

Typical flow (execute / aexecute)

1. Optional policy_stack.check(tool.name) — declarative deny rules (OpenClaw-inspired).
2. Resolve timeout from the tool and default_timeout.
3. Optional SafetyLayer.validate_tool_input — block or flag arguments before run.
4. tool.run / tool.arun — internally validates kwargs against args_schema (Pydantic).
5. Optional SafetyLayer.sanitize_tool_output for string results.
6. Optional post_state_hook on the tool for state sidecars.
7. ToolCallingRecord appended (success or failure), with rolling retention.

Retry and timeout

Retries skip obvious non-retriable cases (e.g. ToolTimeoutError).

Related

• ApprovalRequiredError bubbles out without being treated as a generic failure.
• sandbox_config: SandboxConfig enables advanced backends (subprocess, microsandbox, docker) for code execution helpers on the same class.

Credential management

CredentialStore (agenticx.tools.credentials) stores encrypted key–value material under ~/.agenticx/credentials by default (Fernet when cryptography is installed). Use it for API keys and tokens that tools or MCP env maps need at runtime.

SecurityManager (agenticx.core.security) also embeds a CredentialStore for higher-level permission and audit integration.

Sandbox integration

SandboxConfig (agenticx.tools.executor) selects a backend for advanced runs:

SandboxPolicy (agenticx.safety.sandbox_policy) recommends backends from risk level or tool name heuristics:

Optional ToolRiskProfile entries override inference per tool_name (force_backend, network_enabled, max_timeout).