> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.agnes-ai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# HermesAgents Integration Guide

> HermesAgents Model Configuration Guide

# HermesAgents Model Configuration Guide

## 1. Overview

This document explains how to configure a custom model provider in HermesAgents. After the configuration is complete, HermesAgents will send model requests to the specified API endpoint and use the selected model to complete Agent tasks.

## 2. Prerequisites

<Note>
  Before you start, make sure you have the following:

  1. HermesAgents installed on your device.
  2. A valid API Key.
  3. The API service endpoint.
  4. The model name you want to use.
  5. A working terminal or command-line environment.
</Note>

## 3. Open Terminal

Open a terminal or command-line tool on your local device.

macOS or Linux users can use Terminal.

Windows users can use Command Prompt, PowerShell, or the terminal inside their development environment.

## 4. Configuration Command Format

The HermesAgents configuration command usually follows this format:

```bash theme={null}
hermes config set <configuration_key> <value>
```

Please note that `set` should be placed before the configuration key.

## 5. Configure the Model Provider

Run the following command:

```bash theme={null}
hermes config set model.provider custom
```

This command tells HermesAgents to use a custom model provider instead of the default built-in provider.

## 6. Configure the API Base URL

Run the following command:

```bash theme={null}
hermes config set model.base_url https://apihub.agnes-ai.com/v1
```

This command sets the HermesAgents model request endpoint to the Agnes AI API Gateway.

Usually, the API Base URL only needs to end with `/v1`. You do not need to manually add `/chat/completions`.

Recommended:

<span class="field-row"><code>[https://apihub.agnes-ai.com/v1](https://apihub.agnes-ai.com/v1)</code></span>

Usually not recommended:

<span class="field-row"><code>[https://apihub.agnes-ai.com/v1/chat/completions](https://apihub.agnes-ai.com/v1/chat/completions)</code></span>

Only use the full API path if HermesAgents explicitly requires a complete endpoint URL.

## 7. Configure the API Key

Run the following command:

```bash theme={null}
hermes config set model.api_key YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API Key.

Example:

```bash theme={null}
hermes config set model.api_key sk-xxxxxxxxxxxxxxxx
```

In most cases, you do not need to manually add the `Bearer` prefix unless HermesAgents explicitly requires a full Authorization header.

If you prefer to configure the API Key through an environment-variable-style setting, you can also use:

```bash theme={null}
hermes config set OPENAI_API_KEY YOUR_API_KEY
```

However, for a custom model provider setup, it is recommended to use:

```bash theme={null}
hermes config set model.api_key YOUR_API_KEY
```

## 8. Configure the Model Name

Run the following command:

```bash theme={null}
hermes config set model.default agnes-2.0-flash
```

Please use the complete model ID provided by the platform.

Model IDs are usually case-sensitive. It is recommended to copy the model name directly from the platform.

## 9. Full Configuration Example

<span class="field-kv"><span class="field-key">Model Provider:</span> <code>custom</code></span>
<span class="field-kv"><span class="field-key">API Base URL:</span> <code>[https://apihub.agnes-ai.com/v1](https://apihub.agnes-ai.com/v1)</code></span>
<span class="field-kv"><span class="field-key">API Key:</span> <code>YOUR\_API\_KEY</code></span>
<span class="field-kv"><span class="field-key">Model Name:</span> <code>agnes-2.0-flash</code></span>

## 10. Full Command Example

```bash theme={null}
hermes config set model.provider custom
hermes config set model.base_url https://apihub.agnes-ai.com/v1
hermes config set model.api_key YOUR_API_KEY
hermes config set model.default agnes-2.0-flash
```

## 11. Verify the Configuration

After completing the configuration, you can run a HermesAgents task or start a test session.

If the configuration is correct, HermesAgents should be able to call the specified API endpoint and return model responses successfully.

## 12. Troubleshooting

### 1. Authentication Failed

Check whether your API Key is valid.

You can reset the API Key by running:

```bash theme={null}
hermes config set model.api_key YOUR_API_KEY
```

Also make sure your account has sufficient balance or credits.

### 2. API Request Failed

Check whether the API Base URL is correct:

<span class="field-row"><code>[https://apihub.agnes-ai.com/v1](https://apihub.agnes-ai.com/v1)</code></span>

Usually, you do not need to manually add `/chat/completions`.

Correct example:

<span class="field-row"><code>[https://apihub.agnes-ai.com/v1](https://apihub.agnes-ai.com/v1)</code></span>

Usually not recommended:

<span class="field-row"><code>[https://apihub.agnes-ai.com/v1/chat/completions](https://apihub.agnes-ai.com/v1/chat/completions)</code></span>

Only use the full API path if HermesAgents explicitly requires a complete endpoint URL.

### 3. Model Provider Not Recognized

Make sure the model provider has been set to:

```bash theme={null}
hermes config set model.provider custom
```

### 4. Model Not Found

Check whether the model name is correct.

It is recommended to run the following command again:

```bash theme={null}
hermes config set model.default agnes-2.0-flash
```

Model IDs are usually case-sensitive. It is recommended to copy the model name directly from the platform.

### 5. Network Error

Make sure your device can access the API endpoint.

If the request fails, check your firewall, proxy, or VPN settings.

## 13. Notes

HermesAgents uses a configuration style similar to OpenAI-compatible APIs.

For custom model providers, the API Base URL usually ends with `/v1`.

Recommended format:

<span class="field-row"><code>[https://apihub.agnes-ai.com/v1](https://apihub.agnes-ai.com/v1)</code></span>

The API Key is recommended to be configured separately through `model.api_key`.

The model provider should be set to:

```text theme={null}
custom
```

This ensures that HermesAgents uses the custom API endpoint instead of the default model provider.