Add Hermes Agent integration page

cookbook/_routes.json

@@ -493,5 +493,10 @@
     "notebook": "example_data_migration-jp.ipynb",
     "docsPath": null,
     "isGuide": true
+  },
+  {
+    "notebook": "integration_hermes.ipynb",
+    "docsPath": "integrations/frameworks/hermes",
+    "isGuide": false
   }
 ]

cookbook/integration_hermes.ipynb

@@ -0,0 +1,233 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "vscode": {
+          "languageId": "raw"
+        }
+      },
+      "source": [
+        "<!-- NOTEBOOK_METADATA source: \"⚠️ Jupyter Notebook\" title: \"Integrate Langfuse with Hermes Agent\" sidebarTitle: \"Hermes Agent\" logo: \"/images/integrations/hermes_icon.png\" description: \"Trace and debug Hermes Agent conversations, LLM calls, and tool usage with Langfuse observability.\" category: \"Integrations\" -->\n",
+        "\n",
+        "# Integrate Langfuse with Hermes Agent\n",
+        "\n",
+        "This notebook shows how to integrate **Langfuse** with **Hermes Agent** to trace, debug, and evaluate your agent's conversations, LLM calls, and tool usage.\n",
+        "\n",
+        "> **What is Hermes Agent?** [Hermes Agent](https://github.com/NousResearch/hermes-agent) is a self-improving AI agent built by [Nous Research](https://nousresearch.com). It features a built-in learning loop, persistent memory, autonomous skill creation, and support for any LLM provider. Hermes ships a bundled Langfuse observability plugin that traces every conversation turn, LLM request, and tool call.\n",
+        "\n",
+        "> **What is Langfuse?** [Langfuse](https://langfuse.com) is an open-source LLM engineering platform that helps teams trace, debug, and evaluate their LLM applications."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "vscode": {
+          "languageId": "raw"
+        }
+      },
+      "source": [
+        "<!-- STEPS_START -->\n",
+        "## Step 1: Install Dependencies"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "%pip install hermes-agent langfuse -U"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "vscode": {
+          "languageId": "raw"
+        }
+      },
+      "source": [
+        "## Step 2: Set Up Environment Variables\n",
+        "\n",
+        "Get your Langfuse keys from the project settings in [Langfuse Cloud](https://langfuse.com/cloud) or set up [self-hosting](https://langfuse.com/self-hosting)."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import os\n",
+        "\n",
+        "# Get keys for your project from the project settings page: https://langfuse.com/cloud\n",
+        "os.environ[\"LANGFUSE_PUBLIC_KEY\"] = \"pk-lf-...\"\n",
+        "os.environ[\"LANGFUSE_SECRET_KEY\"] = \"sk-lf-...\"\n",
+        "os.environ[\"LANGFUSE_BASE_URL\"] = \"https://cloud.langfuse.com\" # 🇪🇺 EU region (API host)\n",
+        "# os.environ[\"LANGFUSE_BASE_URL\"] = \"https://us.cloud.langfuse.com\" # 🇺🇸 US region (API host)\n",
+        "\n",
+        "# The Hermes Langfuse plugin reads HERMES_LANGFUSE_PUBLIC_KEY / HERMES_LANGFUSE_SECRET_KEY /\n",
+        "# HERMES_LANGFUSE_BASE_URL and falls back to the standard LANGFUSE_* vars above.\n",
+        "# For production use, set these in ~/.hermes/.env or via `hermes tools`."
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "vscode": {
+          "languageId": "raw"
+        }
+      },
+      "source": [
+        "With the environment variables set, initialize the Langfuse client. `get_client()` picks up the env vars above and returns a client bound to your project.\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "from langfuse import get_client\n",
+        "\n",
+        "langfuse = get_client()\n",
+        "\n",
+        "# Verify connection\n",
+        "if langfuse.auth_check():\n",
+        "    print(\"Langfuse client is authenticated and ready!\")\n",
+        "else:\n",
+        "    print(\"Authentication failed. Please check your credentials and host.\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "vscode": {
+          "languageId": "raw"
+        }
+      },
+      "source": [
+        "## Step 3: Enable the Langfuse Plugin\n",
+        "\n",
+        "Hermes ships a bundled Langfuse observability plugin under `plugins/observability/langfuse`. It is **opt-in** — enable it via the CLI or by editing your config file.\n",
+        "\n",
+        "The plugin hooks into Hermes lifecycle events (`pre_api_request`, `post_api_request`, `pre_tool_call`, `post_tool_call`) to automatically capture traces for every conversation turn."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Enable the Langfuse plugin (run this in your terminal, not in a notebook)\n",
+        "# hermes plugins enable observability/langfuse\n",
+        "\n",
+        "# Or use the interactive tool configurator:\n",
+        "# hermes tools  # → select \"Langfuse Observability\"\n",
+        "\n",
+        "# Verify it is enabled:\n",
+        "# hermes plugins list  # observability/langfuse should show \"enabled\""
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "vscode": {
+          "languageId": "raw"
+        }
+      },
+      "source": [
+        "## Step 4: Run Hermes and Generate a Trace\n",
+        "\n",
+        "With the plugin enabled and credentials set, every Hermes conversation turn is automatically traced to Langfuse. Each trace captures:\n",
+        "\n",
+        "- **Conversation turns** as the root span (\"Hermes turn\")\n",
+        "- **LLM calls** as generation observations with model, usage, cost, and latency\n",
+        "- **Tool calls** as tool observations with input arguments and results\n",
+        "- **Token usage and cost** broken down by input, output, cache, and reasoning tokens\n",
+        "\n",
+        "You can start a conversation from the CLI:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Start an interactive conversation (traces are sent automatically)\n",
+        "# hermes chat -q \"What is the weather in San Francisco?\"\n",
+        "\n",
+        "# Or start a full interactive session:\n",
+        "# hermes"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "vscode": {
+          "languageId": "raw"
+        }
+      },
+      "source": [
+        "### Optional: Tune Tracing Behavior\n",
+        "\n",
+        "The Hermes Langfuse plugin supports several optional environment variables:\n",
+        "\n",
+        "| Variable | Description | Default |\n",
+        "|---|---|---|\n",
+        "| `HERMES_LANGFUSE_ENV` | Environment tag (e.g. `production`, `staging`) | — |\n",
+        "| `HERMES_LANGFUSE_RELEASE` | Release/version tag | — |\n",
+        "| `HERMES_LANGFUSE_SAMPLE_RATE` | Sampling rate `0.0`–`1.0` | `1.0` |\n",
+        "| `HERMES_LANGFUSE_MAX_CHARS` | Max characters per traced field | `12000` |\n",
+        "| `HERMES_LANGFUSE_DEBUG` | Verbose plugin logging (`true`/`false`) | `false` |\n",
+        "\n",
+        "Set these in `~/.hermes/.env` or export them in your shell before starting Hermes."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "vscode": {
+          "languageId": "raw"
+        }
+      },
+      "source": [
+        "## Step 5: View Traces in Langfuse\n",
+        "\n",
+        "After running the example, open [Langfuse Cloud](https://langfuse.com/cloud) to see the full trace including prompts, completions, tool calls, token usage, and latency.\n",
+        "\n",
+        "![Example Hermes Agent trace in Langfuse](https://langfuse.com/images/cookbook/integration-hermes/hermes-example-trace.png)\n",
+        "\n",
+        "[Example trace in Langfuse](TODO: paste a public example trace URL from your Langfuse Cloud project)\n",
+        "\n",
+        "<!-- STEPS_END -->"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "vscode": {
+          "languageId": "raw"
+        }
+      },
+      "source": [
+        "<!-- MARKDOWN_COMPONENT name: \"LearnMore\" path: \"@/components-mdx/integration-learn-more.mdx\" -->"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}