Hermes Agent tracing¶
AgentLoop observes Hermes Agent through its supported plugin hooks. It writes one native JSON trace per turn, which you can analyze, store, or compare with the usual AgentLoop commands.
This integration is included in AgentLoop 0.1.1 and newer. The directory
plugin uses only Python's standard library and does not add dependencies to
Hermes's managed environment.
The published release's tested hook contract is Hermes 0.21.6, revision
818c13be1dc4.
| AgentLoop distribution | Accepted Hermes versions | Validation |
|---|---|---|
| Published 0.1.1 | >=0.21.6,<0.22 |
0.21.6 hook contract and standalone plugin tests |
| 0.2.0 | >=0.21.6,<0.24 |
Also real v0.22.7 and v0.23.1 runtime dispatch with a local deterministic provider |
For Hermes 0.22.x or 0.23.x, install AgentLoop 0.2.0 or newer and export its plugin. See the runtime pilot for exact pins, reproduction commands, and the limits of this evidence.
Create and enable the plugin¶
Install the release in a Python 3.11+ environment, then export the plugin:
python -m pip install agentloop-profiler==0.2.0
agentloop hermes export-plugin runs/hermes-agentloop
This creates a fresh directory containing plugin.yaml, the observer, its loader,
and the Apache license. It refuses to replace an existing directory.
Copy that directory to plugins/agentloop under your active Hermes profile home,
then enable it:
Restart the Hermes CLI or gateway after enabling it. Use the profile selected by your Hermes installation; copying files into a different profile does not enable capture there. The plugin does not install Hermes or configure a model provider.
For development changes, use a separate AgentLoop environment.
python -m pip install /path/to/agentloop-checkout
agentloop hermes export-plugin runs/hermes-agentloop-source
By default, each completed turn writes a file such as
agentloop/traces/run_hermes_<id>.json under that profile home. Analyze a file with
AgentLoop:
agentloop analyze /path/to/profile/agentloop/traces/run_hermes_ID.json --html runs/hermes-report.html
The plugin's own code needs no AgentLoop installation inside Hermes. Owners of
an unmanaged Python environment can also install AgentLoop 0.1.1 or newer
there and enable its hermes_agent.plugins entry point. Use the directory plugin
with managed Hermes installations.
What the trace contains¶
| Evidence | Capture behavior |
|---|---|
| Turn boundary and outcome | Completed, failed, interrupted, or incomplete turns remain explicit. |
| Model requests | Each main-loop provider attempt retains host timestamps, duration, model identity, and reported usage. |
| Retries | A reported retry records a separate retry event; failed attempts remain in the trace. |
| Tool calls | Tool name, host-reported status and duration, with an interval inferred from callback time. |
| Delegation | Parent/child session links; child usage is not copied into the parent's totals. |
| Missing evidence | Dropped events, unfinished requests, and missing start/timing data mark capture incomplete. |
Hermes reports uncached input, cache-read, and cache-write counts separately. AgentLoop combines them into prompt tokens and preserves the buckets. Reasoning tokens already belong to output usage and are not added again. Missing or invalid usage stays unavailable. AgentLoop's configured model-cost estimates do not reproduce Hermes's cache-specific prices or subscription billing.
The recorder covers main-loop request hooks, including normalized streaming responses. Auxiliary calls such as titling, compression, and MoA calls have a separate Hermes hook family and are outside this capture. It cannot reconstruct events omitted by Hermes or certify task correctness. Use your own quality fixtures when comparing candidate runs.
AgentLoop 0.2.0 fails replay and CI capture-integrity gates when either Hermes turn is incomplete, interrupted, or failed, or reports unfinished requests or dropped events. Keep independent task-quality checks alongside capture and performance gates.
Settings and retained content¶
Set options in your profile's config.yaml:
plugins:
entries:
agentloop:
settings:
export_dir: agentloop/traces
capture_content: false
max_active_turns: 64
max_events: 2048
Relative export paths resolve under the profile home. Absolute paths are also
supported. Output text is off by default. Setting capture_content: true retains
tool/model/final output text up to 10,000 characters; oversized outputs are omitted,
not shortened into quality evidence. Prompts, arguments, histories, request bodies,
base URLs, and raw error messages remain excluded. Names and opaque host IDs still
need review before sharing.
Callbacks return None; they do not inject prompts, approve tools, change results,
or make network calls. Teardown and unload flush unfinished turns as incomplete.
Failed exports are retried on flush, with a bounded buffer of sixteen traces. The
recorder uses atomic publication through a hard link in the export directory;
the filesystem must support hard links. Existing trace files are never replaced.
Export failures produce a local log warning and do not stop Hermes execution.
Programmatic registration¶
Inside your own Hermes plugin, with current AgentLoop source installed:
from agentloop.integrations.hermes import register_hermes
def register(ctx):
recorder = register_hermes(ctx)
agentloop.instrument(ctx, integration="hermes") uses the same registration path.
Registration is idempotent for the supplied context. For an explicitly chosen
output directory, construct HermesRecorder(path) and call recorder.register(ctx).
recorder.summary() reports active turns, unscoped events, and export failures.
See Hermes's plugin guide and hook reference for the host's configuration and delivery behavior.