Skip to main content

​
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

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.

​
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: 
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: 
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: 
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:
text
https://apihub.agnes-ai.com/v1
Usually not recommended:
text
https://apihub.agnes-ai.com/v1/chat/completions
Only use the full API path if HermesAgents explicitly requires a complete endpoint URL.

​
7. Configure the API Key

Run the following command: 
hermes config set model.api_key YOUR_API_KEY
Replace YOUR_API_KEY with your actual API Key. Example: 
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: 
hermes config set OPENAI_API_KEY YOUR_API_KEY
However, for a custom model provider setup, it is recommended to use: 
hermes config set model.api_key YOUR_API_KEY

​
8. Configure the Model Name

Run the following command: 
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

text
Model Provider: custom
API Base URL: https://apihub.agnes-ai.com/v1
API Key: YOUR_API_KEY
Model Name: agnes-2.0-flash

​
10. Full Command Example

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: 
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:
text
https://apihub.agnes-ai.com/v1
Usually, you do not need to manually add /chat/completions. Correct example:
text
https://apihub.agnes-ai.com/v1
Usually not recommended:
text
https://apihub.agnes-ai.com/v1/chat/completions
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: 
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: 
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:
text
https://apihub.agnes-ai.com/v1
The API Key is recommended to be configured separately through model.api_key. The model provider should be set to:
text
custom
This ensures that HermesAgents uses the custom API endpoint instead of the default model provider.