> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openlit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent

> Send Hermes Agent turns, LLM calls, and tool calls to OpenLIT with the OpenLIT observer plugin

The OpenLIT plugin for [Hermes Agent](https://hermes-agent.nousresearch.com/docs/) registers Hermes lifecycle hooks and exports OpenTelemetry GenAI spans over OTLP. It works the same for an agent on your laptop and one deployed on a server.

The plugin only observes. It exports in the background, never changes what Hermes does, and a telemetry failure never reaches the agent.

> [!TIP]
>
> In OpenLIT, open the Agents page, choose **Add Coding Agent** (or the Coding Agents tab), and pick **Hermes Agent**. The snippet there is pre-filled with your OTLP endpoint and API key.

## Setup

**1. Install the plugin**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hermes plugins install openlit/openlit/plugins/hermes --enable
```

Hermes asks for consent to install the plugin's Python dependency, the `openlit` SDK. In headless installs, add `--yes-deps`.

To install by hand, copy `plugins/hermes` to `~/.hermes/plugins/openlit` and run `hermes plugins enable openlit`.

**2. Point it at OpenLIT**

Save your endpoint, and your API key if OpenLIT requires one, to Hermes's `~/.hermes/.env`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hermes config set OTEL_EXPORTER_OTLP_ENDPOINT "http://127.0.0.1:4318"
hermes config set OPENLIT_API_KEY "<openlit-api-key>"
```

Use `~/.hermes/.env` rather than a shell export. Chats run inside a background Hermes gateway, which doesn't see variables set in your shell. Any variable in the table below can be set the same way.

> [!NOTE]
>
> Without an endpoint the plugin stays disabled and logs a warning.

**3. Restart and check**

Stop the Hermes gateway so it reloads the plugin and the new settings:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hermes gateway stop
```

Your next Hermes chat starts the gateway again. If you run the gateway as a service (`hermes gateway install`), run `hermes gateway restart` instead. Without a service, `restart` runs the gateway in the foreground of your terminal.

Send a message to Hermes, then open the [Agents page](https://docs.openlit.io/latest/openlit/observability/agents/overview.md). `hermes-agent` appears on the Applications tab, and its turns are on the Traces page.

## Configuration

| Variable | Purpose | Default |
| - | - | - |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint. See the [OTLP receiver](https://docs.openlit.io/latest/openlit/otlp-receiver.md). | Required, unless `OPENLIT_URL` is set |
| `OPENLIT_URL` | OpenLIT URL, used when `OTEL_EXPORTER_OTLP_ENDPOINT` isn't set. | Not set |
| `OPENLIT_API_KEY` | Sent as `Authorization: Bearer <key>`. Ignored when `OTEL_EXPORTER_OTLP_HEADERS` is set. | Not set |
| `OTEL_EXPORTER_OTLP_HEADERS` | Custom OTLP headers. | Not set |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Set to `grpc` to export over OTLP/gRPC. | OTLP/HTTP |
| `OTEL_SERVICE_NAME` | Name shown in OpenLIT. Give each deployed agent its own. | `hermes-agent` |
| `OPENLIT_ENVIRONMENT` or `OTEL_DEPLOYMENT_ENVIRONMENT` | Deployment environment. | `default` |
| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Set to `true` to capture content. | Off |
| `OPENLIT_PRICING_JSON` | File path or URL of a pricing file, for cost calculation. | OpenLIT's published pricing |

If OpenLIT runs in a container and Hermes runs on the host, or the other way around, `127.0.0.1` points at the wrong machine. Use an address both can reach, such as `host.docker.internal` on Docker Desktop.

## What gets captured

Each user turn is one trace. Delegated subagent turns are nested inside the trace of the turn that started them. Turns in the same Hermes session share `gen_ai.conversation.id`.

| Span | Created for | Key attributes |
| - | - | - |
| `invoke_agent hermes` | One user turn, from start to finish, including failed and interrupted turns | `gen_ai.agent.name`, `gen_ai.request.model`, `hermes.platform`, `hermes.turn.exit_reason`, `hermes.turn.interrupted` |
| `chat <model>` | One provider attempt. A retried request produces one span per attempt, and failed attempts have `error.type` set | `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.usage.*`, `gen_ai.response.finish_reasons`, `server.address` |
| `execute_tool <name>` | One tool call, including blocked and cancelled calls | `gen_ai.tool.name`, `gen_ai.tool.call.id`, `hermes.tool.status` |

Auxiliary LLM calls, such as title generation and compression, are `chat` spans with `hermes.auxiliary_task` set. A call that runs outside a turn gets its own trace.

When Hermes stops a turn early, for example on an API error it won't retry, it doesn't report the turn's end. The plugin closes that turn when the next turn in the session starts, when the session ends, when Hermes exits, or, if nothing else happened in the turn, 60 seconds after an API error Hermes won't retry or 3 minutes after its final retry fails (Hermes may still wait up to 2 minutes and try again). Any model call in that window, such as a fallback or a recovery attempt, keeps the turn open. The span ends at the turn's last activity, `hermes.turn.exit_reason` is `abandoned`, and the turn is marked failed if its last LLM call failed.

Cost is calculated in `gen_ai.usage.cost` from OpenLIT's pricing data. It is `0` for models that aren't in that data, such as self-hosted models. Set `OPENLIT_PRICING_JSON` to price them.

## Content capture

Prompts, responses, tool arguments, and tool results aren't exported by default. To include them, add this to `~/.hermes/.env` and restart the gateway:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
```

This sets `gen_ai.input.messages` and `gen_ai.output.messages` on turn and LLM spans, including the tool calls a model requests and the tool results it receives, and `gen_ai.tool.call.arguments` and `gen_ai.tool.call.result` on tool spans. On LLM spans for providers that take the system prompt outside the messages, such as Anthropic, it also sets `gen_ai.system_instructions`; for other providers the system prompt is the first input message. Auxiliary LLM spans include the output only.

> [!WARNING]
>
> Captured content can include system prompts, file contents, and command output. Tool arguments and results are exported as Hermes reports them, without redaction. Turn this on only when your OpenLIT deployment is approved to store that data.

To limit how much is stored, set `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` to a maximum attribute length.

## Troubleshooting

> [accordion] No traces appear
>
> Run `hermes plugins list` and check that `openlit` is enabled. Then look for `OpenLIT plugin disabled` in `~/.hermes/logs/agent.log`, which means no endpoint was found. Run `hermes gateway stop` (or `hermes gateway restart` for a gateway service) after any change to `~/.hermes/.env`, because a running gateway keeps the old settings and plugin code.

> [accordion] Some spans are missing
>
> Look for `OpenLIT hook` warnings in `~/.hermes/logs/agent.log`. A hook that fails drops its span and logs the error there, and Hermes carries on.

> [accordion] OpenLIT is unreachable
>
> Hermes keeps working and turns aren't slowed down. Spans that can't be delivered are dropped.

> [accordion] Cost shows 0
>
> The model isn't in OpenLIT's pricing data, or pricing hadn't finished loading when Hermes started. Set `OPENLIT_PRICING_JSON` for self-hosted models.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.