From f7d89b663ad95d19291e62bf2266533f2252c4ee Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Thu, 25 Jun 2026 19:19:23 +0000 Subject: [PATCH 1/5] Add Custom routers documentation page Add a standalone Custom routers page under Inference & providers covering complexity-based and rule-based routing, creating routers in settings or as YAML files, selecting them from the model picker, and team-synced routers for Enterprise admins. Cross-reference the page from Model choice, the sidebar, and the Admin Panel Models section. Co-Authored-By: Oz --- .../inference/custom-routers.mdx | 124 ++++++++++++++++++ .../agent-platform/inference/model-choice.mdx | 8 +- .../team-management/admin-panel.mdx | 2 + src/sidebar.ts | 1 + 4 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 src/content/docs/agent-platform/inference/custom-routers.mdx diff --git a/src/content/docs/agent-platform/inference/custom-routers.mdx b/src/content/docs/agent-platform/inference/custom-routers.mdx new file mode 100644 index 00000000..ce9839c9 --- /dev/null +++ b/src/content/docs/agent-platform/inference/custom-routers.mdx @@ -0,0 +1,124 @@ +--- +title: Custom routers +description: >- + Define a custom router that automatically picks the right model for each task, + based on task complexity or rules you write, and use it from the model picker. +--- + +Custom routers let you define your own router that automatically picks the right model for each task. Instead of committing to a single model up front, you set the routing logic once, and Warp resolves a concrete model each time you send a prompt, based on either task complexity or rules you write. + +## Key features + +* **Complexity-based routing** - Warp classifies each task's difficulty and routes to the model you mapped to that level. +* **Rule-based routing** - Write natural-language rules that describe when to use each model. +* **Your models, your choice** - Route to any concrete model you have access to, across providers. +* **Built in the app or as a file** - Create a router in settings, or author it as a YAML file that Warp picks up automatically. +* **Team-synced routers** - Admins can publish a router to an entire team (Enterprise). + +## How it works + +A custom router appears in the [model picker](/agent-platform/inference/model-choice/#how-to-change-models) as its own entry, alongside Warp's built-in Auto models and individual models. You select it like any other model. + +When you send a prompt, the router resolves to a single concrete model and runs the task on it, the same end-to-end experience as Warp's built-in Auto models. You can always see which model actually ran. + +Warp chooses a model when you start a conversation and keeps using it for the rest of that conversation. Very short, trivial prompts (like a quick "hello") don't lock in the choice. + +:::note +A router always resolves to concrete models that you choose. It can't route to an Auto model or to another router. +::: + +## Routing types + +A router uses one of two routing types. You choose the type when you create the router. + +### Complexity-based routing + +Warp classifies each task as easy, medium, or hard and routes to the model you assigned to that level. You also set a default model, which Warp uses for any level you leave unset or when it can't determine complexity. + +Use complexity-based routing to put cheaper models on simple work and stronger models on hard work, without describing tasks yourself. + +### Rule-based routing + +Rule-based routing routes each task using rules you write. Each rule pairs a classification prompt (a natural-language description of when to use a model, such as "debugging or fixing failing tests") with the model to use when that rule matches. + +* Warp evaluates rules from top to bottom, and the first rule that matches wins. Rules higher in the list take precedence over those below. +* If no rule matches, Warp uses the required default model. + +## Create a router in Warp + +1. Open **Settings** > **Agents** > **Warp Agent** and find the **Custom Routers** section. +2. Click **Add router** and enter a name. +3. Under **Routing type**, choose **Complexity-based** or **Rule-based**. +4. Configure the routing: + * **Complexity-based** - Select a **Default** model, then assign models to **Easy**, **Medium**, and **Hard**. + * **Rule-based** - Select a **Default model**, then click **Add rule** for each rule, write a **Classification prompt** describing when to use the model, and select the model. Rules are matched top to bottom, so order them by precedence. +5. Click **Save**. + +Your router now appears in the model picker. Saving also writes a file you can reopen with **Open file**, edit, or remove with **Delete**. + +## Author a router as a file + +Custom routers are stored as YAML files in `~/.warp/custom_model_routers/`, with one router per file. Warp loads every file in that directory and reloads automatically when you add, edit, or remove one, with no restart required. Routers you create in settings are saved here too. + +Routing targets use the same `model_id` values listed on the [Model choice](/agent-platform/inference/model-choice/) page. Every target must be a concrete model. + +A complexity router uses `type: complexity`. `default` is required and is used for any bucket you omit: + +```yaml title="~/.warp/custom_model_routers/cost-saver.yaml" +name: Cost saver +type: complexity +default: claude-4-5-sonnet +routing: + easy: claude-4-5-haiku + medium: claude-4-5-sonnet + hard: claude-4-7-opus-high +``` + +A rule-based router uses `type: prompt`. `default` is the required catch-all used when no rule matches, and `routing` is the ordered list of rules: + +```yaml title="~/.warp/custom_model_routers/by-task.yaml" +name: By task +type: prompt +default: claude-4-5-sonnet +routing: + - description: debugging or fixing failing tests + model: claude-4-7-opus-high + - description: writing documentation or comments + model: gpt-5-5-low + - description: simple one-line edits or renames + model: claude-4-5-haiku +``` + +If a file can't be parsed, Warp shows a non-blocking error identifying the file and skips it; your other routers keep working. + +## Use a router + +1. In the prompt input, open the model picker by clicking the current model name. +2. Choose your router from the list. + +Your selection persists for future prompts, like any model choice. Each time the router runs, Warp shows the concrete model it resolved to. + +## Team-synced routers + +Team admins can create routers that are shared with the whole team, so everyone can use the same routing strategy. Team-synced routers are an Enterprise feature, and only admins can create or edit them. + +To create one, an admin: + +1. Opens the [Admin Panel](https://app.warp.dev/admin/) and goes to **Models**. +2. Finds the **Custom Routers** section and clicks **New router**. +3. Chooses **Complexity-based** or **Rule-based**, sets the models or rules, and clicks **Create**. + +Team-synced routers appear in the model picker for every team member, who can select them like any other router. + +## Credits and model availability + +A custom router resolves to a concrete model, so credit usage matches whichever model the router selects for each task. See [Credits](/support-and-community/plans-and-billing/credits/) for how credits are consumed. + +If a router targets a model you don't have access to or that's disabled for your organization, Warp falls back to the router's default model. If no usable model remains, Warp falls back to a built-in default and tells you. + +## Related resources + +* [Model choice](/agent-platform/inference/model-choice/) — Supported models and `model_id` values, including Warp's built-in Auto models. +* [Bring Your Own API Key](/agent-platform/inference/bring-your-own-api-key/) — Use your own OpenAI, Anthropic, or Google API keys. +* [Custom inference endpoint](/agent-platform/inference/custom-inference-endpoint/) — Route Warp through any OpenAI-compatible endpoint. +* [Admin Panel for teams](/enterprise/team-management/admin-panel/) — Manage team-wide settings, including team-synced routers. diff --git a/src/content/docs/agent-platform/inference/model-choice.mdx b/src/content/docs/agent-platform/inference/model-choice.mdx index 86640939..3ebeadf9 100644 --- a/src/content/docs/agent-platform/inference/model-choice.mdx +++ b/src/content/docs/agent-platform/inference/model-choice.mdx @@ -7,7 +7,7 @@ description: >- auto-select the best model). --- -Warp lets you choose from a curated set of large language models to power your agents, or let Warp auto-select the best model for each task. Models from OpenAI, Anthropic, Google, and open source providers are available, with configurable reasoning levels and per-profile defaults. +Warp lets you choose from a curated set of large language models to power your agents, or let Warp auto-select the best model for each task. Models from OpenAI, Anthropic, Google, and open source providers are available, with configurable reasoning levels and per-profile defaults. You can also define [custom routers](/agent-platform/inference/custom-routers/) that pick a model for each task using your own logic. ## Available models @@ -124,6 +124,12 @@ You can use the model picker in your prompt input to quickly switch between mode To change models, click the displayed model name (for example, _Claude Sonnet 4.5_) to open a dropdown with all supported options. Your selection will automatically persist for future prompts. +### Custom routers + +Beyond the built-in Auto models, you can define your own custom routers that automatically pick a concrete model for each task, based on task complexity or rules you write. Custom routers appear in the model picker alongside Auto and individual models. + +See [Custom routers](/agent-platform/inference/custom-routers/) to create one. + ### Model fallback Warp uses a model fallback system to ensure uninterrupted service if your selected model becomes temporarily unavailable due to provider outages or capacity issues. diff --git a/src/content/docs/enterprise/team-management/admin-panel.mdx b/src/content/docs/enterprise/team-management/admin-panel.mdx index 41c6dfe7..2af958a0 100644 --- a/src/content/docs/enterprise/team-management/admin-panel.mdx +++ b/src/content/docs/enterprise/team-management/admin-panel.mdx @@ -215,6 +215,8 @@ When enabled, agents understand your code patterns, architecture, and convention Control which LLM models are available to your team and how inference is routed. From the **Models** page, admins can enable or disable individual models and configure [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) routing through AWS Bedrock. +From the **Models** page, admins can also create team-synced [custom routers](/agent-platform/inference/custom-routers/) that route each task to a model based on complexity or rules. Team-synced routers appear in the model picker for every team member. + **Models with provider-specific data retention requirements** Some models require data retention from the model provider and are therefore not available under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr). For Enterprise teams, these models are **disabled by default**. A workspace admin must explicitly enable them before team members can use them. diff --git a/src/sidebar.ts b/src/sidebar.ts index 758c6273..4cfca791 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -302,6 +302,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ collapsed: true, items: [ { slug: 'agent-platform/inference/model-choice', label: 'Model choice' }, + { slug: 'agent-platform/inference/custom-routers', label: 'Custom routers' }, 'agent-platform/inference/bring-your-own-api-key', { slug: 'agent-platform/inference/custom-inference-endpoint', label: 'Custom inference endpoint' }, { slug: 'agent-platform/inference/grok-subscription', label: 'SuperGrok subscription' }, From f93875480e45df39c7fdd7f9b6f3cd151b89f5b1 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Thu, 25 Jun 2026 19:23:02 +0000 Subject: [PATCH 2/5] Polish Custom routers page wording Tighten the intro, sharpen Key features labels, smooth a few sentences, and remove minor redundancy. Co-Authored-By: Oz --- .../agent-platform/inference/custom-routers.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/content/docs/agent-platform/inference/custom-routers.mdx b/src/content/docs/agent-platform/inference/custom-routers.mdx index ce9839c9..8a2a8cb4 100644 --- a/src/content/docs/agent-platform/inference/custom-routers.mdx +++ b/src/content/docs/agent-platform/inference/custom-routers.mdx @@ -5,21 +5,21 @@ description: >- based on task complexity or rules you write, and use it from the model picker. --- -Custom routers let you define your own router that automatically picks the right model for each task. Instead of committing to a single model up front, you set the routing logic once, and Warp resolves a concrete model each time you send a prompt, based on either task complexity or rules you write. +Custom routers automatically pick the right model for each task, using routing logic you define. Instead of committing to a single model up front, you set the logic once, and Warp resolves a concrete model each time you send a prompt, based on either task complexity or rules you write. ## Key features * **Complexity-based routing** - Warp classifies each task's difficulty and routes to the model you mapped to that level. * **Rule-based routing** - Write natural-language rules that describe when to use each model. -* **Your models, your choice** - Route to any concrete model you have access to, across providers. -* **Built in the app or as a file** - Create a router in settings, or author it as a YAML file that Warp picks up automatically. -* **Team-synced routers** - Admins can publish a router to an entire team (Enterprise). +* **Any supported model** - Route to any concrete model you have access to, across providers. +* **Settings or file** - Create a router in settings, or author it as a YAML file that Warp loads automatically. +* **Team-synced routers** - Admins can share a router with an entire team (Enterprise). ## How it works A custom router appears in the [model picker](/agent-platform/inference/model-choice/#how-to-change-models) as its own entry, alongside Warp's built-in Auto models and individual models. You select it like any other model. -When you send a prompt, the router resolves to a single concrete model and runs the task on it, the same end-to-end experience as Warp's built-in Auto models. You can always see which model actually ran. +When you send a prompt, the router resolves to a single concrete model and runs the task on it, just like Warp's built-in Auto models. You can always see which model actually ran. Warp chooses a model when you start a conversation and keeps using it for the rest of that conversation. Very short, trivial prompts (like a quick "hello") don't lock in the choice. @@ -35,7 +35,7 @@ A router uses one of two routing types. You choose the type when you create the Warp classifies each task as easy, medium, or hard and routes to the model you assigned to that level. You also set a default model, which Warp uses for any level you leave unset or when it can't determine complexity. -Use complexity-based routing to put cheaper models on simple work and stronger models on hard work, without describing tasks yourself. +Use complexity-based routing to put lower-cost models on simple work and more capable models on harder tasks, without describing tasks yourself. ### Rule-based routing @@ -54,7 +54,7 @@ Rule-based routing routes each task using rules you write. Each rule pairs a cla * **Rule-based** - Select a **Default model**, then click **Add rule** for each rule, write a **Classification prompt** describing when to use the model, and select the model. Rules are matched top to bottom, so order them by precedence. 5. Click **Save**. -Your router now appears in the model picker. Saving also writes a file you can reopen with **Open file**, edit, or remove with **Delete**. +Your router now appears in the model picker. Saving also writes a file: use **Open file** to edit it directly, or **Delete** to remove the router. ## Author a router as a file @@ -96,7 +96,7 @@ If a file can't be parsed, Warp shows a non-blocking error identifying the file 1. In the prompt input, open the model picker by clicking the current model name. 2. Choose your router from the list. -Your selection persists for future prompts, like any model choice. Each time the router runs, Warp shows the concrete model it resolved to. +Your selection persists for future prompts, like any other model choice. ## Team-synced routers From f0a12b399d77438349a4bfd154b0d8a61e6e5c2d Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Thu, 25 Jun 2026 19:36:23 +0000 Subject: [PATCH 3/5] Clarify custom routers and BYO inference Document that router targets must be Warp-supported models (custom inference endpoint models can't be targets) and that, like Auto models, custom routers consume Warp credits and don't use your BYOK keys. Co-Authored-By: Oz --- src/content/docs/agent-platform/inference/custom-routers.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/agent-platform/inference/custom-routers.mdx b/src/content/docs/agent-platform/inference/custom-routers.mdx index 8a2a8cb4..465c54dc 100644 --- a/src/content/docs/agent-platform/inference/custom-routers.mdx +++ b/src/content/docs/agent-platform/inference/custom-routers.mdx @@ -60,7 +60,7 @@ Your router now appears in the model picker. Saving also writes a file: use **Op Custom routers are stored as YAML files in `~/.warp/custom_model_routers/`, with one router per file. Warp loads every file in that directory and reloads automatically when you add, edit, or remove one, with no restart required. Routers you create in settings are saved here too. -Routing targets use the same `model_id` values listed on the [Model choice](/agent-platform/inference/model-choice/) page. Every target must be a concrete model. +Routing targets use the same `model_id` values listed on the [Model choice](/agent-platform/inference/model-choice/) page. Every target must be a concrete, Warp-supported model. You can't route to an Auto model, another router, or a model from a [custom inference endpoint](/agent-platform/inference/custom-inference-endpoint/). A complexity router uses `type: complexity`. `default` is required and is used for any bucket you omit: @@ -114,6 +114,8 @@ Team-synced routers appear in the model picker for every team member, who can se A custom router resolves to a concrete model, so credit usage matches whichever model the router selects for each task. See [Credits](/support-and-community/plans-and-billing/credits/) for how credits are consumed. +Like Warp's built-in Auto models, custom routers consume Warp credits and don't draw on your own provider keys, even if you've configured [Bring Your Own API Key (BYOK)](/agent-platform/inference/bring-your-own-api-key/). To run a model on your own key, select that model directly instead of a router. + If a router targets a model you don't have access to or that's disabled for your organization, Warp falls back to the router's default model. If no usable model remains, Warp falls back to a built-in default and tells you. ## Related resources From 385091611d4303cf1438e7113013e6636550ca4c Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Thu, 25 Jun 2026 20:20:54 +0000 Subject: [PATCH 4/5] Use newer models in custom router examples Update the example routers to current models (Claude Opus 4.8, Claude Sonnet 4.6) and add Claude Opus 4.8 to the Model choice table. Co-Authored-By: Oz --- .../docs/agent-platform/inference/custom-routers.mdx | 10 +++++----- .../docs/agent-platform/inference/model-choice.mdx | 5 ++++- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/src/content/docs/agent-platform/inference/custom-routers.mdx b/src/content/docs/agent-platform/inference/custom-routers.mdx index 465c54dc..91c70ac5 100644 --- a/src/content/docs/agent-platform/inference/custom-routers.mdx +++ b/src/content/docs/agent-platform/inference/custom-routers.mdx @@ -67,11 +67,11 @@ A complexity router uses `type: complexity`. `default` is required and is used f ```yaml title="~/.warp/custom_model_routers/cost-saver.yaml" name: Cost saver type: complexity -default: claude-4-5-sonnet +default: claude-4-6-sonnet-high routing: easy: claude-4-5-haiku - medium: claude-4-5-sonnet - hard: claude-4-7-opus-high + medium: claude-4-6-sonnet-high + hard: claude-4-8-opus-high ``` A rule-based router uses `type: prompt`. `default` is the required catch-all used when no rule matches, and `routing` is the ordered list of rules: @@ -79,10 +79,10 @@ A rule-based router uses `type: prompt`. `default` is the required catch-all use ```yaml title="~/.warp/custom_model_routers/by-task.yaml" name: By task type: prompt -default: claude-4-5-sonnet +default: claude-4-6-sonnet-high routing: - description: debugging or fixing failing tests - model: claude-4-7-opus-high + model: claude-4-8-opus-high - description: writing documentation or comments model: gpt-5-5-low - description: simple one-line edits or renames diff --git a/src/content/docs/agent-platform/inference/model-choice.mdx b/src/content/docs/agent-platform/inference/model-choice.mdx index 3ebeadf9..f5b8fffc 100644 --- a/src/content/docs/agent-platform/inference/model-choice.mdx +++ b/src/content/docs/agent-platform/inference/model-choice.mdx @@ -57,6 +57,9 @@ All Auto models perform well across all agent workflows and are ideal if you pre | Model | `model_id` | Variant | | --- | --- | --- | +| Claude Opus 4.8 | `claude-4-8-opus-xhigh` | Default effort | +| Claude Opus 4.8 | `claude-4-8-opus-high` | High effort | +| Claude Opus 4.8 | `claude-4-8-opus-max` | Max effort | | Claude Opus 4.7 | `claude-4-7-opus-xhigh` | Default effort | | Claude Opus 4.7 | `claude-4-7-opus-high` | High effort | | Claude Opus 4.7 | `claude-4-7-opus-max` | Max effort | @@ -122,7 +125,7 @@ You can use the model picker in your prompt input to quickly switch between mode
Model selector in Warp's input.
-To change models, click the displayed model name (for example, _Claude Sonnet 4.5_) to open a dropdown with all supported options. Your selection will automatically persist for future prompts. +To change models, click the displayed model name (for example, _Claude Sonnet 4.6_) to open a dropdown with all supported options. Your selection will automatically persist for future prompts. ### Custom routers From 599d4ede40bb19b39d168ed63f64d6eec5ebe02e Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Thu, 25 Jun 2026 20:42:32 +0000 Subject: [PATCH 5/5] Link router examples to the available models list Point the model_id reference to the Model choice #available-models section so readers can quickly find valid model IDs. Co-Authored-By: Oz --- src/content/docs/agent-platform/inference/custom-routers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/agent-platform/inference/custom-routers.mdx b/src/content/docs/agent-platform/inference/custom-routers.mdx index 91c70ac5..0d208ab9 100644 --- a/src/content/docs/agent-platform/inference/custom-routers.mdx +++ b/src/content/docs/agent-platform/inference/custom-routers.mdx @@ -60,7 +60,7 @@ Your router now appears in the model picker. Saving also writes a file: use **Op Custom routers are stored as YAML files in `~/.warp/custom_model_routers/`, with one router per file. Warp loads every file in that directory and reloads automatically when you add, edit, or remove one, with no restart required. Routers you create in settings are saved here too. -Routing targets use the same `model_id` values listed on the [Model choice](/agent-platform/inference/model-choice/) page. Every target must be a concrete, Warp-supported model. You can't route to an Auto model, another router, or a model from a [custom inference endpoint](/agent-platform/inference/custom-inference-endpoint/). +Routing targets use the same `model_id` values listed on the [Model choice](/agent-platform/inference/model-choice/#available-models) page. Every target must be a concrete, Warp-supported model. You can't route to an Auto model, another router, or a model from a [custom inference endpoint](/agent-platform/inference/custom-inference-endpoint/). A complexity router uses `type: complexity`. `default` is required and is used for any bucket you omit: