hermes-nimble-agent 0.1.0

Nimble Agent API V2 plugin for Hermes — durable, cited deep-research runs you can start now and resume from any session

hermes-nimble-agent

Nimble Agent API V2 plugin for Hermes — durable, citation-backed deep-research runs your agent can start now and resume from any session.

Ask Hermes for researched answers from Telegram, Slack, Discord, or the CLI: the run executes on Nimble's infrastructure (tens of seconds to minutes), Hermes replies immediately with a durable run id, and any later conversation — even in a different process, days later — can pick up the cited result with the id alone.

This is a standalone plugin, installed the way Hermes's third-party-integration policy prescribes: into ~/.hermes/plugins/ or via the hermes_agent.plugins pip entry point. It never modifies Hermes core.

What you get

Five tools in a nimble_agent toolset, visible to the model only when NIMBLE_API_KEY is set:

Tool	Purpose
nimble_agents_list	Discover the Web Search Agents already in your account (reuse first)
nimble_agent_bootstrap	List Nimble's prebuilt research templates, or materialize an agent from one
nimble_agent_run_start	Start an async research run — returns run_id + status immediately
nimble_agent_run_status	Check any run later, from any session, with the ids alone
nimble_agent_run_result	Fetch the terminal answer: prose or structured JSON plus trust metadata — overall confidence with reasoning, sources (primary/secondary), and per-claim citations with verbatim excerpts

Plus a bundled orchestration skill, nimble-agent:agent-research, that teaches the model the full lifecycle (load it with skill_view("nimble-agent:agent-research")).

Install

Requires Hermes ≥ 0.19 and Python ≥ 3.11.

Via pip (recommended):

pip install hermes-nimble-agent        # same environment as hermes-agent
hermes plugins enable nimble-agent

As a directory plugin: copy the inner package directory into your Hermes home:

cp -r src/hermes_nimble_agent ~/.hermes/plugins/nimble-agent
pip install "nimble-python>=1.0.0,<2"   # the SDK must be importable by Hermes
hermes plugins enable nimble-agent

Both modes are exercised by the test suite against the real Hermes plugin loader.

Authentication

Set NIMBLE_API_KEY in Hermes's .env (get a key from your Nimble account). Without the key the tools stay hidden from the model — no crash, no half-working state. The key is read by the SDK from the environment; the plugin never stores, logs, or echoes it, and scrubs it from any error text defensively.

Every request the plugin makes carries X-Client-Source: hermes so Nimble can attribute Hermes-originated traffic.

The lifecycle in practice

You:    Research the current state of EU AI Act enforcement. Use the Nimble
        research agent, medium effort, and give me the run id.

Hermes: → nimble_agents_list            (finds your research agent, wsa_…)
        → nimble_agent_run_start        (returns immediately)
        Started! Run task_run_4f2… on agent wsa_1ab… — medium effort usually
        takes a couple of minutes. Ask me to check it anytime.

[ … later, any session, even another device … ]

You:    Check Nimble run task_run_4f2… and give me the answer.

Hermes: → nimble_agent_run_status       (completed)
        → nimble_agent_run_result
        Here's what the research found … [cited answer]
        Sources: 8 (5 primary) · Confidence: high — "multiple official
        sources agree on the enforcement timeline."

First time in an account with no agents? nimble_agent_bootstrap lists Nimble's prebuilt templates (company-profile, due-diligence, competitive-intelligence, market scans, …) and creates a persistent agent from the one you pick. Creation is deliberate — the plugin never auto-creates agents behind your back.

Effort levels

low → medium → high → x-high → max. Higher is slower and more thorough. low can finish in under a minute but may consult few or no live sources (the trust block will honestly say so); use medium or higher when citations matter.

Output shape

Every tool returns JSON. A completed result looks like:

{
  "success": true,
  "run": {"run_id": "task_run_…", "agent_id": "wsa_…", "status": "completed", "effort": "medium", "…": "…"},
  "output": {
    "type": "text",
    "content": "The researched answer …",
    "trust": {
      "confidence": "high",
      "reasoning": "Multiple primary sources agree.",
      "sources": [{"url": "https://…", "title": "…", "type": "primary"}],
      "claims": [{"callout": 1, "confidence": "high", "citations": [{"url": "https://…", "excerpts": ["…"]}]}]
    }
  },
  "sources_count": 8,
  "claims_count": 5
}

Structured runs (agents configured with an output schema) return "type": "json" with content as an object/array and claims keyed by JSON path.

Errors you'll actually see

All failures come back as structured JSON with a stable error_type, a retriable flag, and — always — whatever agent_id/run_id were in play, so a run is never lost to an error message:

error_type	Meaning	What to do
not_ready	Result requested while the run is still queued/running (HTTP 409); payload includes the live status	Check status, retry later
terminal_failure	Run failed/cancelled (HTTP 422); includes the server's error message	Start a new run
auth / permission	401 / 403	Check NIMBLE_API_KEY; confirm the account has access to the operation
not_found	Unknown agent_id/run_id	Verify ids via nimble_agents_list
rate_limited	429	Wait and retry; started runs keep executing
timeout / connection	Transport trouble	Retry; server-side runs are unaffected
validation	Bad/missing arguments (caught before any API call)	Fix the arguments
dependency	nimble-python not installed (directory installs)	pip install "nimble-python>=1.0.0,<2"
protocol	The API answered outside its documented contract	Report it — includes the ids

Troubleshooting

• Tools don't appear in the model's toolset — is NIMBLE_API_KEY set in Hermes's .env? Is the plugin enabled (hermes plugins list)? Enabling takes effect on the next session.
• Plugin doesn't show in hermes plugins list — pip mode: is it installed in the same environment as hermes-agent? Directory mode: the folder must be ~/.hermes/plugins/nimble-agent/ containing plugin.yaml and __init__.py directly. Debug any discovery issue with HERMES_PLUGINS_DEBUG=1 hermes plugins list.
• not_ready keeps coming back — higher efforts genuinely take minutes; space checks tens of seconds apart (each check is an API call).
• Lost the run id — recent runs are visible in your Nimble dashboard; the id is also in the conversation where the run was started.

Development

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest -q        # the full suite drives the REAL Hermes plugin loader
.venv/bin/ruff check src tests && .venv/bin/ruff format --check src tests
.venv/bin/mypy
.venv/bin/python -m build

The test suite exercises both install modes through the actual hermes_cli PluginManager from the released hermes-agent wheel — discovery, opt-in enable flow, registration, model-visibility gating, the full error matrix, credential redaction, and on-the-wire X-Client-Source evidence via a mocked HTTP transport.

License

MIT