Hermes

The hermes-nimble-agent plugin connects Hermes to Nimble Agent API V2. It lets a Hermes user start a research run, walk away, and retrieve a cited answer later from any session. Agent API V2 is not a single search or extract call. It runs a stateful, asynchronous research workflow on Nimble’s infrastructure. The plugin returns durable identifiers the moment a run starts, then the research continues after Hermes returns. Any later Hermes session can resume the run using those identifiers.

The standalone plugin is the recommended path. A production MCP fallback exists for clients that cannot install the plugin, but it does not offer full parity.

Overview

The plugin adds five tools and one skill to Hermes:

Five tools cover the run lifecycle: discover an agent, create one from a template if needed, start a run, check status, and fetch the result.
One skill, nimble-agent:agent-research, teaches Hermes the reuse-first, poll-later workflow so runs are handled correctly without manual prompting.

Every run returns an answer with a trust block: overall confidence, per-claim citations, and verbatim source excerpts. That trust model is the reason to use Agent API V2 instead of a raw search result. The workflow is asynchronous by design:

Start a run. The plugin returns agent_id and run_id immediately and never blocks.
The research continues on Nimble’s infrastructure.
Check status later, from the same session or a new one, using the two identifiers.
Fetch the terminal result once the run completes.

Prerequisites

Hermes 0.19 or later

The plugin is built and tested against hermes-agent==0.19.0. Install it into the same Python environment as hermes-agent.

Python 3.11 or later

Supported on Python 3.11, 3.12, and 3.13. The plugin depends on nimble-python>=1.0.0,<2, which pip installs automatically.

Nimble account and API key

Create a Nimble account and generate an API key from Account Settings > API Keys. A free trial is available. No extra subscription, quota, or availability tier is required beyond a valid key.

Installation

Install the plugin, then enable it in Hermes.

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

The plugin slug is nimble-agent. Enabling adds it to the Hermes allow-list. Plugins are opt-in and stay disabled until enabled.

Enabling takes effect on the next session. Start a new Hermes session before the tools become visible.

Verify that the plugin and its five tools loaded:

hermes plugins list

If the tools do not appear, run HERMES_PLUGINS_DEBUG=1 hermes plugins list to see discovery details.

Authentication

The plugin reads your key from the NIMBLE_API_KEY environment variable. It is never passed as a tool argument.

export NIMBLE_API_KEY="your-nimble-api-key"

Use a placeholder or an environment variable. Never commit a real key or paste one into a prompt or config file.

Two behaviors protect the key:

Tools stay hidden when the key is missing. All five tools are gated on NIMBLE_API_KEY. If it is absent or empty, Hermes does not show them to the model. Set the key and start a new session to reveal them.
The key is scrubbed from errors. The plugin never stores, logs, or echoes the key, and replaces it with [REDACTED] in any error text before returning it.

The plugin also tags every request with the header X-Client-Source: hermes automatically. Nothing to configure.

Available tools

The toolset name is nimble_agent. Each tool returns a JSON string and never raises.

Tool	Purpose	Required inputs	Optional inputs
`nimble_agents_list`	List account agents. Discover an existing agent to reuse.	none	`limit` (1-50), `offset`
`nimble_agent_bootstrap`	List prebuilt templates, or create a persistent agent from one.	none	`template`, `display_name`
`nimble_agent_run_start`	Start an async run. Returns identifiers immediately.	`agent_id`, `task`	`effort`
`nimble_agent_run_status`	Check run status using the identifiers alone.	`agent_id`, `run_id`	none
`nimble_agent_run_result`	Fetch the terminal answer and trust metadata.	`agent_id`, `run_id`	none

How they connect:

nimble_agents_list and nimble_agent_bootstrap produce an agent_id (wsa_...). Reuse an existing agent before creating a new one.
nimble_agent_run_start takes that agent_id plus a task (the research question) and returns a run_id (task_run_...).
nimble_agent_run_status and nimble_agent_run_result take both identifiers. They work from any session, so the two identifiers are all a later session needs.

The agent-research skill

The plugin bundles a skill named nimble-agent:agent-research. It teaches the full lifecycle: reuse before create, return identifiers within the turn, avoid tight polling, resume from identifiers alone, handle not_ready and failed runs, and present answers with citations and confidence. Plugin skills are opt-in and do not appear in the system-prompt skill index. Load it explicitly when you want Hermes to follow the workflow:

skill_view('nimble-agent:agent-research')

Complete asynchronous workflow

This example uses placeholder identifiers and a generic research question. Identifier values shown are illustrative.

Select or create an agent

List existing agents and reuse one when possible:

nimble_agents_list()

If none fits, list templates and create an agent from one:

nimble_agent_bootstrap()                           # lists available templates
nimble_agent_bootstrap(template="<template-name>") # creates an agent from a listed template

Use a template value from the list the first call returns. Both paths yield an agent_id such as wsa_xxxxxxxxxxxx.

Start a research run

Start a medium-effort run. effort is optional; omit it to use the agent’s default.

nimble_agent_run_start(
  agent_id="wsa_xxxxxxxxxxxx",
  task="Summarize the main approaches to retrieval-augmented generation and cite sources.",
  effort="medium"
)

The response returns immediately:

{
  "run": { "run_id": "task_run_xxxxxxxxxxxx", "agent_id": "wsa_xxxxxxxxxxxx", "status": "queued", "effort": "medium", "is_active": true },
  "agent_id": "wsa_xxxxxxxxxxxx",
  "run_id": "task_run_xxxxxxxxxxxx",
  "next": "Save both identifiers. Check status later with nimble_agent_run_status."
}

Preserve the identifiers

Record agent_id and run_id. They are the only state needed to resume. You can now end the session or move on to other work.

Check status later

From the same session or a new one:

nimble_agent_run_status(agent_id="wsa_xxxxxxxxxxxx", run_id="task_run_xxxxxxxxxxxx")

status is queued or running while active, and completed, failed, or cancelled when terminal.

Fetch the result

Once the run is completed:

nimble_agent_run_result(agent_id="wsa_xxxxxxxxxxxx", run_id="task_run_xxxxxxxxxxxx")

The result carries the answer and its trust block. Present the answer, then list the sources and per-claim citations.

Medium and higher efforts can take several minutes. Return the identifiers to the user rather than holding a tool call open, and space status checks tens of seconds apart.

Result and trust model

nimble_agent_run_result returns the answer wrapped in the plugin’s result envelope:

{
  "success": true,
  "output": {
    "type": "text",
    "content": "Retrieval-augmented generation combines...",
    "trust": { "confidence": "high", "reasoning": "...", "sources": [ ... ], "claims": [ ... ] }
  },
  "sources_count": 7,
  "claims_count": 7,
  "agent_id": "wsa_xxxxxxxxxxxx",
  "run_id": "task_run_xxxxxxxxxxxx"
}

Envelope specifics:

output.type is text for a prose answer, or json when the agent is configured with an output schema. Structured runs return content as an object or array.
sources_count and claims_count are always present integers.

The trust block (overall confidence, per-claim citations, primary and secondary source classification, and verbatim excerpts) follows the standard Agent API V2 trust model. See Trust for how grades and citations work, and the run result schema for every field.

The trust block is present but its detail varies with effort. A low-effort run may consult few or no live sources, in which case it honestly reports low confidence with zero sources. Use medium or higher when citations matter.

Errors and recovery

Every failure returns a structured envelope: { "success": false, "error_type": "...", "error": "...", "retriable": true|false }. The agent_id and run_id are preserved even on validation errors, so a run is never lost to a client-side error.

`error_type`	Meaning	Action	Retriable
`not_ready`	Result requested before the run finished.	Check status, then retry the result later.	Yes
`terminal_failure`	Run failed or was cancelled.	Read the server message. Start a new run if appropriate.	No
`auth`	API key missing or invalid.	Set a valid `NIMBLE_API_KEY`.	No
`permission`	Key lacks access to the resource.	Check account permissions.	No
`not_found`	Unknown `agent_id` or `run_id`.	Confirm the identifiers.	No
`validation`	Bad or missing arguments.	Fix the arguments and retry.	No
`rate_limited`	Too many requests.	Back off, then retry. See Rate limits.	Yes
`timeout`	Request timed out in transit.	Retry. The run may still be active.	Yes
`connection`	Network error reaching Nimble.	Retry. The run may still be active.	Yes
`dependency`	`nimble-python` is not installed.	Install it in the Hermes environment.	No
`protocol`	Unexpected API response shape.	Retry status or result. Report if it persists.	No

A transport error such as timeout or connection does not necessarily end the server-side run. The run keeps going on Nimble’s infrastructure. Check status again with the same identifiers before starting over.

Poll considerately. Space status checks tens of seconds apart rather than in a tight loop.

Effort and runtime guidance

nimble_agent_run_start accepts an optional effort (low, medium, high, x-high, max). Omit it to use the agent’s default. Higher effort reads more sources and takes longer, from seconds at low to many minutes at higher tiers. See Efforts for the full tier list, typical run times, pricing, and the default. The bundled skill suggests medium or higher when citations matter. Because a run can take minutes, the plugin returns agent_id and run_id immediately rather than holding a tool call open. Let the model report the identifiers, then check status later and space checks tens of seconds apart.

Plugin or MCP?

Consideration	Standalone plugin	Production MCP fallback
Recommended status	Primary	Secondary fallback
Installation	PyPI plus `hermes plugins enable`	`~/.hermes/config.yaml` MCP server entry
Run lifecycle	Five dedicated tools (list, bootstrap, start, status, result)	Generic Nimble agent MCP tools
Identity requirement	Requires `agent_id`	Requires `agent_id`
Resumable runs	Yes, from identifiers alone	Yes, same durable identifiers
Trust and citations	Full trust block mapped for you	Raw API result; presentation is up to you
Attribution	`X-Client-Source: hermes` sent automatically	Set the header manually in config
Tool filtering	Fixed five-tool toolset	Allowlist you define
Credential redaction	Built in	Not provided
Bundled skill	`nimble-agent:agent-research` included	Not included

The plugin is the recommended path. Generic MCP connectivity to Nimble does not by itself provide the plugin’s lifecycle handling, trust mapping, credential redaction, or bundled skill.

Production MCP fallback

Use this path only when installing the plugin is not possible. It connects Hermes to the production Nimble MCP server over Streamable HTTP. Treat the block below as a starting configuration and validate it against your Hermes and Nimble MCP versions before relying on it. Add the server to ~/.hermes/config.yaml:

mcp_servers:
  nimble:
    url: "https://mcp.nimbleway.com/mcp"
    headers:
      Authorization: "Bearer ${NIMBLE_API_KEY}"
      X-Client-Source: "hermes"
    timeout: 60
    tools:
      include:
        - nimble_agents_list
        - nimble_agents_run
        - nimble_agents_run_status
        - nimble_agents_run_result

Notes:

Authentication uses a bearer token. Keep the key in the NIMBLE_API_KEY environment variable and reference it with ${NIMBLE_API_KEY}.
Attribution over MCP is manual. Add X-Client-Source: hermes to the headers as shown. It is not sent automatically the way the plugin sends it.
The tool allowlist limits Hermes to the agent run lifecycle. Confirm the exact tool names against your server’s advertised tool list, since a name that does not match is silently filtered out, and adjust the list to your needs.
Timeouts should allow for research that runs for minutes. Runs continue server-side even if a request times out.
Reload the server mid-session with /reload-mcp, or restart Hermes.

The MCP fallback requires an explicit agent_id, the same as the plugin. It does not provide the plugin’s trust mapping, credential redaction, or bundled skill, and is not a full-parity replacement. See the Nimble MCP Server docs for the full server reference.

Troubleshooting

Symptom	Cause	Action
Plugin does not appear	Not enabled	Run `hermes plugins enable nimble-agent`, then start a new session.
Tools are hidden	`NIMBLE_API_KEY` missing	Set the key, then start a new session.
Enabled but no tools this session	Enabling applies to the next session	Start a new Hermes session.
Wrong Python environment	Plugin not in the `hermes-agent` environment	Reinstall in the same environment. Confirm with `hermes plugins list`.
`auth` error	Key missing or invalid	Set a valid `NIMBLE_API_KEY`.
Run stays `queued` or `running`	Research still in progress	Wait and check status again. Higher effort takes longer.
Lost identifiers	`agent_id` or `run_id` not saved	Use `nimble_agents_list` to find the agent. Preserve identifiers next time.
Result says `not_ready`	Run not finished	Check status, then retry the result.
`rate_limited`	Too many requests	Back off, then retry.
MCP auth or timeout failure	Bad header or short timeout	Check the `Authorization` header and raise `timeout`.

PyPI package

Install hermes-nimble-agent from public PyPI.

GitHub repository

Source, README, and release notes.

Search Agent

Learn how Nimble Agent API V2 research runs work.

Trust and citations

How confidence, sources, and per-claim citations are produced.

Nimble MCP Server

Full reference for the production MCP fallback.

Hermes plugins

How Hermes discovers and enables plugins.

Agent Skills

MCP Server

Partnerships

Connectors

Proxy

Overview

Prerequisites

Installation

Authentication

Available tools

The agent-research skill

Complete asynchronous workflow

Result and trust model

Errors and recovery

Effort and runtime guidance

Plugin or MCP?

Production MCP fallback

Troubleshooting

PyPI package

GitHub repository

Search Agent

Trust and citations

Nimble MCP Server

Hermes plugins

​Overview

​Prerequisites

​Installation

​Authentication

​Available tools

​The agent-research skill

​Complete asynchronous workflow

​Result and trust model

​Errors and recovery

​Effort and runtime guidance

​Plugin or MCP?

​Production MCP fallback

​Troubleshooting

​Related resources

PyPI package

GitHub repository

Search Agent

Trust and citations

Nimble MCP Server

Hermes plugins

Overview

Prerequisites

Installation

Authentication

Available tools

The agent-research skill

Complete asynchronous workflow

Result and trust model

Errors and recovery

Effort and runtime guidance

Plugin or MCP?

Production MCP fallback

Troubleshooting

Related resources