Hermes Agent Provider Routing: Choosing Which Model Handles Each Request

provider_routing :
sort : "price" # How to rank providers
only : [ ] # Whitelist: only use these providers
ignore : [ ] # Blacklist: never use these providers
order : [ ] # Explicit provider priority order
require_parameters : false # Only use providers that support all parameters
data_collection : null # Control data collection ("allow" or "deny")

Configuration Reference

Each option in the provider_routing section controls a specific aspect of routing behavior. The table below summarizes all documented options, their values, and their defaults.

Option	Description	Values	Default
sort	Controls how OpenRouter ranks available providers for your request.	"price", "throughput", "latency"	Not specified (aggregator default)
only	Whitelist of provider slugs. When set, only these providers will be used. All others are excluded. Use the lowercase slug shown by OpenRouter for each provider.	List of strings (e.g., ["anthropic", "google"])	Empty list []
ignore	Blacklist of provider names. These providers will never be used, even if they offer the cheapest or fastest option.	List of strings (e.g., ["together", "deepinfra"])	Empty list []
order	Explicit priority order. Providers listed first are preferred. Unlisted providers are used as fallbacks.	List of strings (e.g., ["anthropic", "google", "amazon-bedrock"])	Empty list []
require_parameters	When true, OpenRouter will only route to providers that support all parameters in your request (like temperature, top_p, tools, etc.). This avoids silent parameter drops.	Boolean (true or false)	false
data_collection	Controls whether providers can use your prompts for training.	"allow" or "deny"	null (no preference sent)

How It Works

Provider routing preferences are passed to OpenRouter or Nous Portal on agent chat requests and iteration-limit summaries via the extra_body.provider field. In the OpenAI Python SDK, this is the extra_body argument; in the JSON request, it becomes the top-level provider object. Auxiliary tasks such as compression and title generation are configured independently under auxiliary.<task>.extra_body.

The routing config is read from config.yaml and passed as parameters when creating the AIAgent. The official documentation shows the following mapping:

providers_allowed ← from provider_routing.only
providers_ignored ← from provider_routing.ignore
providers_order ← from provider_routing.order
provider_sort ← from provider_routing.sort
provider_require_parameters ← from provider_routing.require_parameters
provider_data_collection ← from provider_routing.data_collection

In CLI mode, the configuration is loaded at startup. In Gateway mode, it is loaded when the gateway starts.

Requirements and Limitations

• Provider routing only applies when using OpenRouter or Nous Portal as your LLM provider. It has no effect with direct provider connections (e.g., connecting directly to the Anthropic API).
• The only option requires the lowercase slug shown by OpenRouter for each provider. The documentation does not specify where to find these slugs, but they are typically available in the OpenRouter provider list.
• The data_collection option only works if the provider supports it; not all providers honor this preference.
• When no provider_routing section is configured (the default), the aggregator uses its own default routing logic, which generally balances cost and availability automatically.
• Provider routing is distinct from fallback models. Provider routing controls which sub-providers behind OpenRouter or Nous Portal handle your requests. For automatic failover to an entirely different provider when your primary model fails, see Fallback Providers.

Troubleshooting

The official documentation does not list specific failure modes or error messages for provider routing. However, based on the configuration options, the following common issues may arise:

• Provider not found in only list: If you specify a provider slug that does not exist or is misspelled, OpenRouter may return an error or fall back to no providers. Double-check the slug against the OpenRouter provider list.
• Conflicting only and ignore: If a provider appears in both only and ignore, the behavior is undefined. The documentation does not specify which takes precedence, so avoid listing the same provider in both.
• require_parameters blocking all providers: If you set require_parameters: true and no provider supports all your request parameters, OpenRouter may return an error. Consider relaxing this option or adjusting your parameters.
• data_collection not working: Not all providers support the data_collection flag. If you set it to "deny" and the provider ignores it, your prompts may still be used for training. Check the provider's documentation for data collection policies.