Skip to main content
Model Router lets an OpenHands agent choose an LLM profile for each task before the main work starts. This is useful when you have several saved models and want the agent to trade off quality, latency, and cost automatically. Model Router uses saved LLM profiles. The classifier returns a model/profile name, and the backend switches the conversation to the matching saved profile.
Model Router works with OpenHands Agent Profiles. ACP agents such as Claude Code, Codex, and Gemini CLI manage model selection in their own runtime.

​
Create a Model Router

  1. Open Settings > Model Router.
  2. Select Add Model Router.
  3. Choose one of the templates:
    • Add Default Pareto Max Score — prefilled with the default Pareto prompt that favors the highest expected task score.
    • Add Default Pareto Min Cost — prefilled with a placeholder min-cost Pareto prompt.
    • Custom — starts with an empty router form.
  4. Review the classifier model, default model, prompt template, and model table.
  5. Save the router.
If no router is active yet, the first router you create becomes active automatically for new OpenHands conversations.

​
Default Pareto templates

The default Pareto templates use:
  • minimax-m3 as the classifier profile
  • minimax-m3 as the fallback/default profile
  • a model table with the target model names and benchmark score/cost data
  • a direct prompt template that must include {{ instance_text }} and may include {{ model_table }}
The Max Score template is ready to use. The Min Cost template is currently a placeholder so you can edit it while keeping the same model table and profile-generation workflow.

​
Create the target LLM profiles

When you create a default Pareto router, Agent Canvas can create any missing target LLM profiles for you. Leave Create missing LLM profiles for this router checked to reuse your current provider settings for all router models. This copies the active LLM profile’s provider settings and changes only the model identifier and usage id for each router target. It is the quickest way to try a router with an existing LiteLLM proxy or compatible provider configuration.
Make sure your provider or proxy actually serves the target model IDs. The generated profiles reuse credentials and base URL, but they do not verify that every model is available.

​
Custom routers

Choose Custom when you want to write your own router prompt or route between a smaller set of saved profiles. A custom router starts blank and leaves automatic target-profile creation unchecked. Fill in:
  • Classifier model — the saved LLM profile that classifies the task.
  • Default model — the saved LLM profile used if routing fails or no task class matches.
  • Prompt template — the prompt sent to the classifier. It must include {{ instance_text }}.
  • Model table — optional text injected wherever the prompt uses {{ model_table }}.
The classifier should return JSON with a model value that matches a saved LLM profile name. Matching is case-insensitive, so GPT-5.4 and gpt-5.4 resolve to the same profile name.

​
Use the router in a conversation

After a router is active, start a new OpenHands conversation. The agent receives a routing tool and can call it before doing the task. Agent Canvas shows the selected profile in the conversation list and updates the model selector below the chat after a successful switch. You can ask the agent to call the router the same way you would ask it to use any other tool. For example:
You can still switch models manually with the chat model selector or the /model command. See Manage LLM Profiles.