Hermes Agent

About the Hermes Agent integration

Hermes Agent is an open-source agent that runs as a CLI and as a gateway behind Telegram, Discord, Slack, WhatsApp, and Teams. The community hermes-otel plugin subscribes to Hermes lifecycle hooks and turns every session, LLM call, API request, tool execution, and sub-agent delegation into OpenTelemetry spans using the gen_ai.* semantic conventions — exported as OTLP/HTTP protobuf straight to https://ingest.telemetry.dev. Configuration only, no code changes.

Key features

• Full agent-loop tracing: A session root span with nested llm.*, api.*, and tool.* children, plus sub-agent spans — the whole turn in one trace.
• gen_ai.* native: Token usage, model, provider, and operation names arrive on the conventions telemetry.dev indexes; sessions group by gen_ai.conversation.id.
• GenAI metrics: gen_ai.client.token.usage and operation-duration histograms land as time series for dashboards and token-usage alerts.
• Batched export: Spans are queued to a background worker during the turn; by default the plugin flushes exporters synchronously at session end (force_flush_on_session_end: false turns that off).
• Privacy controls: capture_previews: false strips prompt and tool previews from spans at the source; telemetry.dev adds server-side redaction before storage.

Get started

1. Create a telemetry.dev project API key.

2. Install and enable the plugin, then install its package — with the yaml extra, so it can read config.yaml — into the interpreter that runs Hermes:

   hermes plugins install briancaffey/hermes-otel
   hermes plugins enable hermes_otel
   ~/.hermes/hermes-agent/venv/bin/pip install -e "$HOME/.hermes/plugins/hermes_otel[yaml]"

   Plugins are disabled by default after install, and without PyYAML the plugin silently ignores config.yaml — both steps matter. The pip path assumes the standard managed install; if you run Hermes from a source checkout, install into that venv instead.

3. Declare telemetry.dev in ~/.hermes/plugins/hermes_otel/config.yaml, leaving headers: unset — values there are sent verbatim, with no env interpolation:

   backends:
     - type: otlp
       name: telemetry-dev
       endpoint: https://ingest.telemetry.dev/v1/traces

   Then pass the API key through the standard OTel env var, set in the environment Hermes actually runs in — with no headers: in the config, the plugin's exporters fall back to it automatically:

   export TELEMETRY_DEV_API_KEY="<your-project-api-key>"
   export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20$TELEMETRY_DEV_API_KEY"

4. Run hermes. Startup logs [hermes-otel] ✓ telemetry-dev at https://ingest.telemetry.dev/v1/traces, and each turn appears in telemetry.dev as a full session trace with token usage and tool activity.

Good to know

Log export is opt-in on the plugin side — set capture_logs: true to ship Hermes logs alongside traces and metrics; the plugin derives the /v1/metrics and /v1/logs endpoints automatically. Message and tool-argument previews follow the plugin's capture_previews setting, but the flag only covers previews: tool commands and targets are still recorded as hermes.tool.* attributes and rolled up into hermes.turn.tool_commands and hermes.turn.tool_targets, which can include sensitive commands, file paths, or URLs. It doesn't touch log bodies either: with logs enabled the plugin attaches to the root logger by default, so application and library logs export as-is — scope it with log_attach_logger or leave logs off if that's a concern. The same config works for CLI and gateway sessions, including cron jobs and sub-agent (delegate_task) runs.