Source: https://docs.sogni.ai/sogni-intelligence/integration-hermes-agent/

# 🪽Hermes Agent Integration

[Hermes Agent](https://hermes-agent.nousresearch.com/) can use Sogni Intelligence through an OpenAI-compatible custom endpoint. Use this when you want Hermes Agent to route prompts to Sogni's Qwen models while keeping Hermes' local agent workflow.

## [#](https://docs.sogni.ai/sogni-intelligence/integration-hermes-agent/#prerequisites)Prerequisites

-   Hermes Agent installed.
-   A Sogni API key from [dashboard.sogni.ai/api-key](https://dashboard.sogni.ai/api-key).
-   A Sogni account with Spark or SOGNI token balance.

## [#](https://docs.sogni.ai/sogni-intelligence/integration-hermes-agent/#interactive-setup)Interactive Setup

Run Hermes' model configuration command:

```
hermes model
```

Choose the custom endpoint/manual URL option, then enter:

| Setting | Value |
| --- | --- |
| Base URL | `https://api.sogni.ai/v1` |
| API key | Your Sogni API key |
| Model | `qwen3.6-35b-a3b-gguf-iq4xs` |

If Hermes asks for a provider type, choose the OpenAI-compatible option.

## [#](https://docs.sogni.ai/sogni-intelligence/integration-hermes-agent/#config-file-setup)Config-File Setup

Hermes also supports direct endpoint overrides in configuration. Use these values if you manage Hermes through a config file:

```
model:
  provider: custom
  base_url: "https://api.sogni.ai/v1"
  api_key: "YOUR_SOGNI_API_KEY"
  default: "qwen3.6-35b-a3b-gguf-iq4xs"
```

Use `GET https://api.sogni.ai/v1/models` for the current model list. Current public model IDs include:

-   `qwen3.6-35b-a3b-gguf-iq4xs`
-   `qwen3.5-35b-a3b-abliterated-gguf-q4km`

## [#](https://docs.sogni.ai/sogni-intelligence/integration-hermes-agent/#recommended-defaults)Recommended Defaults

For coding and agent work, start with:

```
{
  "model": "qwen3.6-35b-a3b-gguf-iq4xs",
  "task_profile": "coding",
  "chat_template_kwargs": {
    "enable_thinking": true
  }
}
```

Hermes may not expose every provider-specific request field in its UI. If it does expose extra body fields and you want a coding-only setup, set `sogni_tools: false` so Sogni does not inject media tools. Leave Sogni tools enabled if you want Hermes to be able to request image, video, or music generation through Sogni.

## [#](https://docs.sogni.ai/sogni-intelligence/integration-hermes-agent/#add-creative-media-tools)Add Creative Media Tools

The endpoint setup above routes Hermes' LLM calls to Sogni. To let Hermes call Sogni image, video and music tools directly, install the public [Sogni Creative Agent Skill](https://docs.sogni.ai/sogni-intelligence/creative-agent-skill/) from Hermes Skills Hub, then install its CLI:

```
hermes skills install skills-sh/sogni-ai/sogni-creative-agent-skill/sogni-creative-agent-skill
npm install -g @sogni-ai/sogni-creative-agent-skill@latest
sogni-agent-hermes doctor
```

Run `/reset` so Hermes loads the new skill. The Skills Hub installs the dedicated, security-scannable instructions and references; the npm package supplies the separate `sogni-agent-hermes` executable.

The skill wraps direct image/video/music generation, hosted `/v1/chat/completions`, durable `/v1/chat/runs`, `/v1/creative-agent/workflows`, replay utilities, persona/memory stores, and the same per-skill creative-agent manifests used by the rest of the Sogni platform. Use the OpenAI-compatible endpoint when Hermes should only choose a model; use the skill when the agent should execute Sogni creative workflows through `sogni-agent-hermes`. For Manus, Claude Code, or another skill-aware runtime, follow the matching setup on the [Creative Agent Skill page](https://docs.sogni.ai/sogni-intelligence/creative-agent-skill/).

## [#](https://docs.sogni.ai/sogni-intelligence/integration-hermes-agent/#cost-control)Cost Control

Hermes uses Sogni for LLM coding/reasoning work today; media tools spend tokens if you leave them enabled.

-   **Pick the billing token.** Pass `token_type: "spark"` (purchased) or `"sogni"` (native) in Hermes' provider extra-body if your version exposes one. Defaults to `auto`.
-   **Vendor models require explicit naming.** OpenAI GPT Image 2, [ByteDance Seedance 2.0](https://www.sogni.ai/models/seedance-2-0) / Fast / Mini, and [Alibaba HappyHorse 1.1](https://www.sogni.ai/models/happyhorse-1-1) require Premium Spark and are never selected by the router on your behalf.
-   **For coding-only setups** that should never spend on media, leave `sogni_tools: false` (above).

For approvals, hard caps, and the durable cost-approval flow, see [Billing & Cost Control](https://docs.sogni.ai/sogni-intelligence/billing-and-cost-control/).

## [#](https://docs.sogni.ai/sogni-intelligence/integration-hermes-agent/#verify)Verify

Ask Hermes:

```
Which model and API base URL are you using?
```

Then try a short coding prompt:

```
Write a TypeScript function that validates an Ethereum address and explain edge cases.
```

## [#](https://docs.sogni.ai/sogni-intelligence/integration-hermes-agent/#troubleshooting)Troubleshooting

| Issue | Fix |
| --- | --- |
| `401 authentication_error` | Confirm the Hermes custom endpoint is using your Sogni API key, not an OpenAI or OpenRouter key. |
| Model not found | Use `qwen3.6-35b-a3b-gguf-iq4xs` or query `/v1/models` for the current list. |
| `402 insufficient_quota` | Add Spark or SOGNI token balance in the Sogni dashboard. |
| Hermes falls back to another provider | Re-run `hermes model` and confirm the custom endpoint is selected. |
| Requests work in curl but not Hermes | Check whether Hermes is overriding `base_url`, `api_key`, or `model` from a different config profile. |

See the [Hermes Agent configuration docs](https://hermes-agent.nousresearch.com/docs/user-guide/configuration/) for the current custom endpoint settings.