Skip to content

v0.12: Toolsets, MCP, And Execution Backends [PARTIAL]

Goal

Make tools safer and more modular without bloating the core.

Implementation Status

  • [x] ToolsetResolver for grouping and resolving tools.
  • [x] Per-message tool filtering in AgentLoop.
  • [x] MCP Client integration (stdio transport).
  • [x] MCP Client integration (SSE transport).
  • [x] MCP Client integration (streamable HTTP transport).
  • [x] Dynamic MCP tool registration.
  • [x] Grouping tools by capability.
  • [x] Docker execution backend (transient scaffold, not production-grade).

Scope

  • Group tools by capability.
  • Upgrade MCP configs and runtime behavior.
  • Refactor subagents around a shared runner.
  • Add execution backend strategy.

Toolsets

  • safe
  • file
  • terminal
  • web/search
  • vision
  • image generation
  • messaging
  • memory
  • skills
  • routines
  • MCP
  • code execution
  • subagents

MCP Upgrades

  • stdio, SSE, and streamable HTTP configs
  • schema normalization
  • per-tool timeouts
  • transient retry
  • OAuth only when needed
  • path traversal checks

Execution Backends

  • local default
  • Docker sandbox for risky tasks
  • SSH/VPS for always-on deployment
  • advanced backends later only when demanded

Module Targets

  • backend/agent/g_agent/agent/tools/toolsets.py
  • backend/agent/g_agent/mcp/manager.py
  • backend/agent/g_agent/agent/runner.py
  • backend/agent/g_agent/agent/subagent.py
  • backend/agent/g_agent/execution/local.py
  • backend/agent/g_agent/execution/docker.py
  • backend/agent/tests/test_mcp_*.py
  • backend/agent/tests/test_toolsets.py
  • backend/agent/tests/test_execution_backend_*.py

Acceptance Criteria

  • Tool exposure can be limited by toolset.
  • MCP tools have timeouts and transient retry.
  • Subagents support cancellation and status events.
  • Completion summaries route back to the origin channel.
  • Docker sandbox is optional, not a requirement for local default.

References

  • hermes-agent-ref/toolsets.py
  • hermes-agent-ref/tools/environments/
  • nanobot-ref/nanobot/agent/tools/mcp.py
  • nanobot-ref/nanobot/agent/runner.py

Agent Handoff

Current G-Agent State

  • ToolRegistry remains the low-level registry, but ToolsetResolver now groups registered tools into capability bundles plus dynamic MCP prefix groups.
  • AgentLoop._get_effective_tools() resolves per-message toolsets and allowed_tools.
  • tool_policy, risky_tools, and approval_mode exist.
  • SubagentManager, SpawnTool, and AgentRunner exist.
  • MCPManager connects stdio, SSE, and streamable HTTP servers, wraps remote tools/resources, normalizes schemas, and retries transient connection failures.
  • MCPToolWrapper and MCPResourceWrapper implement the abstract Tool properties required by the registry.
  • ExecTool uses LocalEnvironment and supports workspace restriction plus allowed_dirs.
  • execution/docker.py exists as a transient/stateless container scaffold with validation for invalid backend/image, network allowlist (none/bridge), timeout, and structured unavailable/timeout errors. Not production-grade stateful/hardened persistent backend like Hermes reference.
  • Missing pieces: MCP prompts, enabled_tools filtering, typed config, parallel connection, timeout/cancellation/schema normalization tests not all present; per-profile toolset policy.

Implementation Strategy

Add toolsets before adding MCP/backends. Toolsets give a safety boundary that MCP, subagents, routines, and Web UI can reuse.

Recommended shape:

  • agent/tools/toolsets.py: tool grouping and selection.
  • mcp/manager.py: MCP wrappers and connection management.
  • execution/base.py, execution/local.py, execution/docker.py: backend interface and implementations.
  • agent/runner.py: shared runner extracted later from AgentLoop.

Implementation Slices

  1. Add toolset metadata.
  2. safe, file, terminal, web, browser, vision, image, messaging, memory, skills, routines, MCP, subagents.
  3. Allow runtime to expose a subset of tools.
  4. Per character/profile later.
  5. Per routine sooner.
  6. Add MCP config schema.
  7. stdio, SSE, and streamable HTTP transports.
  8. enabled tools.
  9. timeout.
  10. Port MCP wrapper from Nanobot carefully.
  11. schema normalization
  12. per-tool timeout
  13. transient retry
  14. protocol pollution hints
  15. Add Docker execution backend.
  16. Keep local default.
  17. Docker only for configured risky workflows.
  18. Refactor subagent runner after tests exist.

Tests

  • test_toolsets.py
  • test_mcp_config.py
  • test_mcp_tool_wrapper.py
  • test_execution_local.py
  • test_execution_docker.py
  • test_subagent_tool_boundaries.py

Guardrails

  • Do not expose all MCP tools by default.
  • Do not allow MCP path traversal.
  • Do not make Docker mandatory.
  • Do not refactor the whole agent loop before toolset tests exist.

Shipped Slices

Toolset registry + tests + per-run tool filtering + MCP stdio/SSE/streamable HTTP registration. Docker execution exists as transient scaffold with focused validation tests (23 tests pass); production-grade stateful/hardened persistent backend remains later work.