Skip to content

Commit d5e7c9c

Browse files
JetoPistolaclaude
JetoPistola
and
claude
committed
[OPIK-7234] [FE] feat: add Hermes to onboarding integrations and docs
Surface the Hermes integration (comet-ml/opik-hermes) to users the same way OpenClaw is: add it to the onboarding integrations grid and to the docs integrations section, linking to the opik-hermes repository. Implements OPIK-7234: add Hermes to onboarding integrations list and docs Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent b502876 commit d5e7c9c

9 files changed

Lines changed: 274 additions & 0 deletions

File tree

‎apps/opik-documentation/documentation/fern/docs-v2/integrations/hermes.mdx‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
description: Install and configure the Hermes community plugin to export LLM,
3+
tool, and agent traces to Opik.
4+
headline: Hermes | Opik Documentation
5+
og:description: Connect Hermes to Opik with the opik-hermes plugin.
6+
og:site_name: Opik Documentation
7+
og:title: Hermes Integration - Opik
8+
title: Observability for Hermes with Opik
9+
canonical-url: https://www.comet.com/docs/opik/integrations/hermes
10+
---
11+
12+
The [Hermes agent](https://github.com/NousResearch/hermes-agent) can send trace data to Opik through the community plugin package `opik-hermes`, maintained at [comet-ml/opik-hermes](https://github.com/comet-ml/opik-hermes).
13+
14+
This integration captures:
15+
16+
- A **root trace** per agent turn (`Hermes turn`), grouped into Opik threads by Hermes `session_id`.
17+
- An **LLM span** (`type=llm`) per API call, with input messages, assistant output, model/provider, token usage, and USD cost.
18+
- A **tool span** (`type=tool`) per tool call, with arguments and results.
19+
20+
## Prerequisites
21+
22+
- A working [Hermes agent](https://github.com/NousResearch/hermes-agent) installation.
23+
- Opik project/workspace details (for cloud or enterprise deployments).
24+
25+
## Setup
26+
27+
<Steps>
28+
<Step title="1. Install the plugin">
29+
Install the package into the same Python environment as Hermes. This pulls in the `opik` SDK automatically and registers the plugin via the `hermes_agent.plugins` entry point.
30+
31+
```bash
32+
pip install opik-hermes
33+
```
34+
</Step>
35+
<Step title="2. Enable the plugin">
36+
```bash
37+
hermes plugins enable observability/opik
38+
```
39+
</Step>
40+
<Step title="3. Point Hermes at your Opik">
41+
Set these in `~/.hermes/.env` (or via `hermes tools`). The Opik Python SDK reads the `OPIK_*` env vars directly — no interactive step is required. On Opik Cloud the SDK already defaults to the Cloud URL, so the API key is enough; for local or self-hosted Opik, set `OPIK_URL_OVERRIDE` to route traces there.
42+
43+
**Opik Cloud:**
44+
45+
```bash
46+
# ~/.hermes/.env
47+
OPIK_URL_OVERRIDE=https://www.comet.com/opik/api
48+
OPIK_API_KEY=your-api-key-here
49+
OPIK_WORKSPACE=default
50+
OPIK_PROJECT_NAME=hermes
51+
```
52+
53+
**Self-hosted / local (open-source Opik) — no API key required:**
54+
55+
```bash
56+
# ~/.hermes/.env
57+
OPIK_URL_OVERRIDE=http://localhost:5173/api
58+
OPIK_WORKSPACE=default
59+
OPIK_PROJECT_NAME=hermes
60+
```
61+
62+
<Tip>
63+
With no config at all, the SDK defaults to Opik Cloud and, without an API key, logs a repeated `API key must be specified` warning and sends nothing. The plugin still fails open (its hooks never crash Hermes) — so for any non-Cloud target, set `OPIK_URL_OVERRIDE` so traces are routed correctly.
64+
</Tip>
65+
66+
As an interactive alternative for local setup, run the Opik SDK's CLI, which writes `~/.opik.config`:
67+
68+
```bash
69+
opik configure
70+
```
71+
</Step>
72+
</Steps>
73+
74+
## Validate setup
75+
76+
<Steps>
77+
<Step title="1. Check the plugin is enabled">
78+
```bash
79+
hermes plugins list
80+
```
81+
82+
`observability/opik` should show as `enabled`.
83+
</Step>
84+
<Step title="2. Send a message">
85+
```bash
86+
hermes chat -q "hello"
87+
```
88+
89+
You can also open the Hermes web UI at `http://localhost:9119` and use the Chat tab.
90+
</Step>
91+
<Step title="3. Verify traces in Opik">
92+
Open Opik and look for a trace named after your message in the configured project (`hermes` by default), with an LLM span and a span per tool call.
93+
</Step>
94+
</Steps>
95+
96+
## Optional tuning
97+
98+
Set these in `~/.hermes/.env` to adjust plugin behavior:
99+
100+
```bash
101+
HERMES_OPIK_TAGS=production,team-x # extra tags applied to every trace
102+
HERMES_OPIK_MAX_CHARS=12000 # max chars per field (default: 12000)
103+
HERMES_OPIK_DEBUG=true # verbose plugin logging
104+
```
105+
106+
For the full configuration reference, see the [opik-hermes](https://github.com/comet-ml/opik-hermes) repository.
107+
108+
## Next step
109+
110+
For OTEL-native pipelines, see [OpenTelemetry integration](/integrations/opentelemetry).

‎apps/opik-documentation/documentation/fern/docs-v2/integrations/overview.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,7 @@ Connect your AI coding assistant directly to your Opik workspace with the MCP se
194194
<Card title="Cursor" href="/integrations/cursor" />
195195
<Card title="Dify" href="/integrations/dify" />
196196
<Card title="Flowise" href="/integrations/flowise" />
197+
<Card title="Hermes" href="/integrations/hermes" />
197198
<Card title="Langflow" href="/integrations/langflow" />
198199
<Card title="n8n" href="/integrations/n8n" />
199200
<Card title="OpenClaw" href="/integrations/openclaw" />

‎apps/opik-documentation/documentation/fern/docs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -235,6 +235,9 @@ redirects:
235235
- source: "/docs/opik/tracing/integrations/haystack"
236236
destination: "/docs/opik/integrations/haystack"
237237
permanent: true
238+
- source: "/docs/opik/tracing/integrations/hermes"
239+
destination: "/docs/opik/integrations/hermes"
240+
permanent: true
238241
- source: "/docs/opik/tracing/integrations/instructor"
239242
destination: "/docs/opik/integrations/instructor"
240243
permanent: true

‎apps/opik-documentation/documentation/fern/docs/tracing/integrations/hermes.mdx‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
description: Install and configure the Hermes community plugin to export LLM,
3+
tool, and agent traces to Opik.
4+
headline: Hermes | Opik Documentation
5+
og:description: Connect Hermes to Opik with the opik-hermes plugin.
6+
og:site_name: Opik Documentation
7+
og:title: Hermes Integration - Opik
8+
title: Observability for Hermes with Opik
9+
canonical-url: https://www.comet.com/docs/opik/integrations/hermes
10+
---
11+
12+
The [Hermes agent](https://github.com/NousResearch/hermes-agent) can send trace data to Opik through the community plugin package `opik-hermes`, maintained at [comet-ml/opik-hermes](https://github.com/comet-ml/opik-hermes).
13+
14+
This integration captures:
15+
16+
- A **root trace** per agent turn (`Hermes turn`), grouped into Opik threads by Hermes `session_id`.
17+
- An **LLM span** (`type=llm`) per API call, with input messages, assistant output, model/provider, token usage, and USD cost.
18+
- A **tool span** (`type=tool`) per tool call, with arguments and results.
19+
20+
## Prerequisites
21+
22+
- A working [Hermes agent](https://github.com/NousResearch/hermes-agent) installation.
23+
- Opik project/workspace details (for cloud or enterprise deployments).
24+
25+
## Setup
26+
27+
<Steps>
28+
<Step title="1. Install the plugin">
29+
Install the package into the same Python environment as Hermes. This pulls in the `opik` SDK automatically and registers the plugin via the `hermes_agent.plugins` entry point.
30+
31+
```bash
32+
pip install opik-hermes
33+
```
34+
</Step>
35+
<Step title="2. Enable the plugin">
36+
```bash
37+
hermes plugins enable observability/opik
38+
```
39+
</Step>
40+
<Step title="3. Point Hermes at your Opik">
41+
Set these in `~/.hermes/.env` (or via `hermes tools`). The Opik Python SDK reads the `OPIK_*` env vars directly — no interactive step is required. On Opik Cloud the SDK already defaults to the Cloud URL, so the API key is enough; for local or self-hosted Opik, set `OPIK_URL_OVERRIDE` to route traces there.
42+
43+
**Opik Cloud:**
44+
45+
```bash
46+
# ~/.hermes/.env
47+
OPIK_URL_OVERRIDE=https://www.comet.com/opik/api
48+
OPIK_API_KEY=your-api-key-here
49+
OPIK_WORKSPACE=default
50+
OPIK_PROJECT_NAME=hermes
51+
```
52+
53+
**Self-hosted / local (open-source Opik) — no API key required:**
54+
55+
```bash
56+
# ~/.hermes/.env
57+
OPIK_URL_OVERRIDE=http://localhost:5173/api
58+
OPIK_WORKSPACE=default
59+
OPIK_PROJECT_NAME=hermes
60+
```
61+
62+
<Tip>
63+
With no config at all, the SDK defaults to Opik Cloud and, without an API key, logs a repeated `API key must be specified` warning and sends nothing. The plugin still fails open (its hooks never crash Hermes) — so for any non-Cloud target, set `OPIK_URL_OVERRIDE` so traces are routed correctly.
64+
</Tip>
65+
66+
As an interactive alternative for local setup, run the Opik SDK's CLI, which writes `~/.opik.config`:
67+
68+
```bash
69+
opik configure
70+
```
71+
</Step>
72+
</Steps>
73+
74+
## Validate setup
75+
76+
<Steps>
77+
<Step title="1. Check the plugin is enabled">
78+
```bash
79+
hermes plugins list
80+
```
81+
82+
`observability/opik` should show as `enabled`.
83+
</Step>
84+
<Step title="2. Send a message">
85+
```bash
86+
hermes chat -q "hello"
87+
```
88+
89+
You can also open the Hermes web UI at `http://localhost:9119` and use the Chat tab.
90+
</Step>
91+
<Step title="3. Verify traces in Opik">
92+
Open Opik and look for a trace named after your message in the configured project (`hermes` by default), with an LLM span and a span per tool call.
93+
</Step>
94+
</Steps>
95+
96+
## Optional tuning
97+
98+
Set these in `~/.hermes/.env` to adjust plugin behavior:
99+
100+
```bash
101+
HERMES_OPIK_TAGS=production,team-x # extra tags applied to every trace
102+
HERMES_OPIK_MAX_CHARS=12000 # max chars per field (default: 12000)
103+
HERMES_OPIK_DEBUG=true # verbose plugin logging
104+
```
105+
106+
For the full configuration reference, see the [opik-hermes](https://github.com/comet-ml/opik-hermes) repository.
107+
108+
## Next step
109+
110+
For OTEL-native pipelines, see [OpenTelemetry integration](/v1/integrations/opentelemetry).

‎apps/opik-documentation/documentation/fern/docs/tracing/integrations/overview.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,7 @@ Opik helps you easily log, visualize, and evaluate everything from raw LLM calls
185185
<Card title="Cursor" href="/v1/integrations/cursor" />
186186
<Card title="Dify" href="/v1/integrations/dify" />
187187
<Card title="Flowise" href="/v1/integrations/flowise" />
188+
<Card title="Hermes" href="/v1/integrations/hermes" />
188189
<Card title="Langflow" href="/v1/integrations/langflow" />
189190
<Card title="n8n" href="/v1/integrations/n8n" />
190191
<Card title="OpenClaw" href="/v1/integrations/openclaw" />

‎apps/opik-documentation/documentation/fern/versions/latest.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -852,6 +852,9 @@ navigation:
852852
- page: Flowise
853853
path: ../docs-v2/integrations/flowise.mdx
854854
slug: flowise
855+
- page: Hermes
856+
path: ../docs-v2/integrations/hermes.mdx
857+
slug: hermes
855858
- page: Langflow
856859
path: ../docs-v2/integrations/langflow.mdx
857860
slug: langflow

‎apps/opik-documentation/documentation/fern/versions/v1.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -664,6 +664,9 @@ navigation:
664664
- page: Flowise
665665
path: ../docs/tracing/integrations/flowise.mdx
666666
slug: flowise
667+
- page: Hermes
668+
path: ../docs/tracing/integrations/hermes.mdx
669+
slug: hermes
667670
- page: Langflow
668671
path: ../docs/tracing/integrations/langflow.mdx
669672
slug: langflow

‎apps/opik-frontend/public/images/integrations/hermes.svg‎

Lines changed: 7 additions & 0 deletions
Loading

‎apps/opik-frontend/src/constants/integrations.ts‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ import deepseekLogoUrl from "/images/integrations/deepseek.png";
2222
// import difyLogoUrl from "/images/integrations/dify.png";
2323
import googleAdkLogoUrl from "/images/integrations/google-adk.png";
2424
import guardrailsaiLogoUrl from "/images/integrations/guardrailsai.png";
25+
import hermesLogoUrl from "/images/integrations/hermes.svg";
2526
import ollamaLogoUrl from "/images/integrations/ollama.png";
2627
import ollamaWhiteLogoUrl from "/images/integrations/ollama-white.png";
2728
import openclawLogoUrl from "/images/integrations/openclaw.svg";
@@ -190,6 +191,41 @@ export const INTEGRATIONS: Integration[] = [
190191
],
191192
docsLink: buildDocsUrl("/integrations/openclaw"),
192193
},
194+
{
195+
id: "hermes",
196+
title: "Hermes",
197+
description: "Frameworks & tools",
198+
category: INTEGRATION_CATEGORIES.FRAMEWORKS_TOOLS,
199+
icon: hermesLogoUrl,
200+
code: "",
201+
installCommand: "pip install opik-hermes",
202+
installTitle: "1. Install the Opik plugin",
203+
installDescription:
204+
"Install the package into the same Python environment as Hermes. This pulls in the opik SDK and registers the plugin via the hermes_agent.plugins entry point.",
205+
additionalSteps: [
206+
{
207+
title: "2. Enable the plugin",
208+
description: "Enable the Opik observability plugin in Hermes.",
209+
code: "hermes plugins enable observability/opik",
210+
language: SUPPORTED_LANGUAGE.bash,
211+
},
212+
{
213+
title: "3. Point Hermes at your Opik",
214+
description:
215+
'Add your Opik connection to ~/.hermes/.env (or run "opik configure"). On Opik Cloud the API key is enough; for local or self-hosted Opik set OPIK_URL_OVERRIDE and omit the key. Traces stream into your "PROJECT_NAME_PLACEHOLDER" project.',
216+
code: "OPIK_API_KEY=<your-api-key>\nOPIK_WORKSPACE=<your-workspace>\nOPIK_PROJECT_NAME=PROJECT_NAME_PLACEHOLDER\n# Local / self-hosted only:\n# OPIK_URL_OVERRIDE=http://localhost:5173/api",
217+
language: SUPPORTED_LANGUAGE.bash,
218+
},
219+
{
220+
title: "4. Talk to Hermes and verify traces in Opik",
221+
description:
222+
"Every turn is traced. Run a chat and confirm traces appear in the configured Opik project.",
223+
code: 'hermes chat -q "hello from hermes"',
224+
language: SUPPORTED_LANGUAGE.bash,
225+
},
226+
],
227+
docsLink: buildDocsUrl("/integrations/hermes"),
228+
},
193229
{
194230
id: "bedrock",
195231
title: "Bedrock",

0 commit comments

Comments
 (0)