http://akjamie.github.io/tags/tools/ Recent content in Tools on Jamie's Blog Hugo en-us Thu, 21 May 2026 00:00:00 +0000 http://akjamie.github.io/post/2026-05-21-hermes-agent-deep-dive/ Thu, 21 May 2026 00:00:00 +0000 http://akjamie.github.io/post/2026-05-21-hermes-agent-deep-dive/ <h1 id="hermes-agent--deep-dive-learning-notes">Hermes Agent — Deep Dive Learning Notes</h1> <blockquote> <p>Staff-engineer-level notes for senior AI engineers designing and implementing production agents. Written after reading <code>run_agent.py</code>, <code>model_tools.py</code>, <code>toolsets.py</code>, <code>agent/</code>, and <code>tools/</code> in full.</p> </blockquote> <hr> <h2 id="1-high-level-architecture">1. High-Level Architecture</h2> <pre tabindex="0"><code>┌─────────────────────────────────────────────────────────────────────┐ │ Entry Points │ │ cli.py (HermesCLI) │ gateway/run.py │ batch_runner.py │ │ tui_gateway/server │ acp_adapter/ │ run_agent.py __main__ │ └──────────────────────┬──────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ AIAgent (run_agent.py) │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ Conversation │ │ Tool Loop │ │ Provider / Transport │ │ │ │ History │ │ Orchestrator│ │ (Anthropic / OpenAI / │ │ │ │ (messages) │ │ │ │ Bedrock / Codex / ACP) │ │ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ ContextComp │ │ MemoryMgr │ │ CredentialPool │ │ │ │ -ressor │ │ (builtin + │ │ (multi-key failover) │ │ │ │ │ │ plugins) │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ └──────────────────────┬──────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ model_tools.py │ │ get_tool_definitions() │ handle_function_call() │ │ _run_async() │ _should_parallelize_tool_batch() │ └──────────────────────┬──────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ tools/registry.py (singleton) │ │ ToolRegistry.register() │ .dispatch() │ .get_definitions() │ └──────────────────────┬──────────────────────────────────────────────┘ │ ┌────────────┴────────────┐ ▼ ▼ ┌──────────────────┐ ┌──────────────────────────────────────────┐ │ tools/*.py │ │ plugins/&lt;name&gt;/__init__.py │ │ (built-in tools)│ │ (user / pip-installed plugins) │ └──────────────────┘ └──────────────────────────────────────────┘ </code></pre><p><strong>Key insight:</strong> The architecture is a strict layered DAG. <code>tools/registry.py</code> has zero imports from any other Hermes module — it is the root. Every tool file imports from it. <code>model_tools.py</code> imports from the registry and triggers discovery. <code>run_agent.py</code> imports from <code>model_tools.py</code>. This prevents circular imports and makes the tool system independently testable.</p>