# Hermes Agent

Hermes Agent is a terminal agent from Nous Research. The [Liquid Inference plugin](https://github.com/architect-xyz/hermes-liquid-inference) adds the exchange as a model provider. It is also in the [Hermes Agent plugin catalog](https://hermes-agent.nousresearch.com/docs/plugins/liquid-inference-provider). The plugin holds the exchange URL and the request headers. The buyer key stays in the environment.

Steps 1 to 5 use the plugin. To set each value yourself, see [Manual configuration](#manual-configuration).

## Start with the Liquid CLI

The [Liquid CLI](https://inference.ai.exchange/docs/cli.md) can start Hermes Agent with the exchange as its provider. Set Hermes Agent up one time first.

```bash
curl -fsSL https://inference.ai.exchange/cli/install.sh | bash
liquid login
liquid connect hermes-agent   # prints the setup below with your model filled in
liquid hermes
```

## Before you start

- A workspace with a balance and a `spend` key. See [API keys](https://inference.ai.exchange/docs/keys.md).
- macOS or Linux, with `git` and `curl`.
- On Linux, the `libatomic` library, before step 1. The install command cannot ask for a `sudo` password. The package is `libatomic1` on Debian and Ubuntu, and `libatomic` on Fedora and RHEL.
- A model with a context window of 64,000 tokens or more. Hermes Agent refuses a smaller model.
- Hermes Agent 0.21.6. This setup is tested with that release.

## 1. Install Hermes Agent

```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/818c13be1dc4fd28987e1e881a9408224afd4535/scripts/install.sh | bash -s -- --commit 818c13be1dc4fd28987e1e881a9408224afd4535 --skip-setup
export PATH="$HOME/.local/bin:$PATH"
```

The script comes from the commit of the [Hermes Agent 0.21.6 release](https://github.com/NousResearch/hermes-agent/releases/tag/v0.21.6). It downloads its own Python and Node, and it places `hermes` in `~/.local/bin`. The second command adds that directory to `PATH`. `--skip-setup` omits the setup questions.

## 2. Export the buyer key

Use the same shell for each command below.

```bash
export LIQUID_API_KEY=sk-liquid-...
```

| Setting           | Why it is set                                         |
| ----------------- | ----------------------------------------------------- |
| `LIQUID_API_KEY`  | The buyer key that Hermes Agent reads from the shell. |
| `LIQUID_BASE_URL` | The exchange URL, with `/v1`.                         |

`LIQUID_API_KEY` is the buyer key. `LIQUID_BASE_URL` is the exchange URL, with `/v1`. Set it only if the command shows it. To keep a setting between shells, put the line without `export` in `~/.hermes/.env`. Keep that file private.

## 3. Install the plugin and select the model

```bash
hermes plugins install architect-xyz/hermes-liquid-inference --ref a7ce8ae3d46253b51c70922c734e3a71ee6bad37 --enable &&
hermes config set model.provider liquid &&
hermes config set model.default "liquid.auto"
```

The first command installs one commit of the plugin into `~/.hermes/plugins`. `--ref` fixes the commit, and `--enable` turns the plugin on. The other commands each change one setting in `~/.hermes/config.yaml`: `model.provider` selects the plugin, and `model.default` is the model for new sessions.

The plugin sends these headers with each model request, including the requests for a session title, compression and vision:

| Header             | Value          | Purpose                                 |
| ------------------ | -------------- | --------------------------------------- |
| `X-Title`          | `Hermes Agent` | Identifies Hermes Agent on the receipt. |
| `x-liquid-cap-usd` | `1.00`         | Limits the charge for each request.     |

Hermes Agent reads the model list from the exchange but not a context window. For a model it does not know, such as `liquid.auto`, it uses 256,000 tokens. To change this, set `model.context_length`. Do not put the key in the configuration file or in a header.

## 4. Check it works

```bash
hermes -z "Reply with the word ready"
```

The answer must contain `ready`. Open **Credits → Receipts** to check the charge and the Hermes Agent client label.

## 5. Start a session

```bash
hermes
```

To use another model, change `model.default`, or type `/model` in a session. Use an exact model, a router model or a preset. See [Connect an app](https://inference.ai.exchange/docs/connect-overview.md).

## Reasoning effort

Task requests use `medium` unless you set a reasoning effort. The plugin sends the level that you select, for example `/reasoning high` in a session or:

```bash
hermes config set agent.reasoning_effort high
```

The plugin sends none for `none` or when reasoning is off. The exchange sends a request with a reasoning effort only to an offer that accepts one. Otherwise it refuses with `400 unsupported_parameter` and no charge, and Hermes Agent sends the request again without it.

## The session title request

Each session sends one more request for a title, with the same headers and cap. It asks for a JSON schema format. If no offer accepts it, the exchange refuses with `400 unsupported_parameter` and no charge, and Hermes Agent sends it again without the format. To stop the title request:

```bash
hermes config set auxiliary.title_generation.enabled false
```

## Control the cost

To set a different cap for each request:

```bash
hermes config set model.default_headers.x-liquid-cap-usd 0.25
```

A header in `model.default_headers` replaces the plugin header of the same name. Do not set `X-Title` there, or the receipt has no client label.

One task can send several requests, so the request cap does not limit the total charge. Set a spend limit on the key. See [API keys](https://inference.ai.exchange/docs/keys.md). For other rules, use a preset. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md).

## Troubleshooting

| Symptom                                               | Cause and fix                                                                   |
| ----------------------------------------------------- | ------------------------------------------------------------------------------- |
| `hermes` is absent from `PATH`.                       | Add `~/.local/bin` to `PATH`.                                                   |
| `Unknown provider 'liquid'`                           | The plugin is not installed. Run the first command of step 3 again.             |
| The install command says that the release is too old. | Update Hermes Agent to 0.21.6 or later.                                         |
| The context window is below the limit.                | Select a model with 64,000 tokens or more.                                      |
| A command waits and prints nothing.                   | Check `LIQUID_BASE_URL`. Hermes Agent waits a long time when it cannot connect. |
| `401`                                                 | Check that `LIQUID_API_KEY` is set, valid and not expired.                      |
| `403`                                                 | Check the key `spend` scope, address restriction and preset rules.              |
| `402`                                                 | Add credit, or check the spend limit of the key.                                |
| `cap_exceeds_buyer_cap`                               | Increase the request cap or select a cheaper model.                             |
| The model is absent.                                  | Check the live offers and presets. Set `model.default` to an exact name.        |

See [Errors](https://inference.ai.exchange/docs/errors.md).

## Manual configuration

Use the custom OpenAI-compatible endpoint, with no plugin. Do steps 1 and 2, then run these commands in place of step 3.

```bash
hermes config set model.provider custom &&
hermes config set model.base_url "https://router.inference.ai.exchange/v1" &&
hermes config set model.key_env LIQUID_API_KEY &&
hermes config set model.default "liquid.auto" &&
hermes config set model.context_length 128000 &&
hermes config set model.default_headers.X-Title "Hermes Agent" &&
hermes config set model.default_headers.x-liquid-cap-usd 1.00
```

- `model.key_env` names the variable that holds the key. Write `LIQUID_API_KEY` without `$`.
- `model.context_length` is the context window of your model. Change it with `model.default`.
- Set headers in `model.default_headers`. `extra_headers` on a named provider is not sent with the session title request.

### Reasoning effort with a custom endpoint

Hermes Agent sends `reasoning_effort: medium` with each task request and `none` with the title request. If no offer accepts it, the exchange refuses with `400 unsupported_parameter` and no charge, and Hermes Agent sends the request again without it. To prevent the refused requests:

```bash
hermes config set model_overrides.custom._default.supports_reasoning false &&
hermes config set auxiliary.title_generation.enabled false
```

### Troubleshooting a custom endpoint

| Symptom                                | Cause and fix                                               |
| -------------------------------------- | ----------------------------------------------------------- |
| A command waits and prints nothing.    | Check `model.base_url`.                                     |
| The context window is below the limit. | Set `model.context_length` to the real window of the model. |