--- title: "Understand model routing and the stable application contract" description: "Model routing keeps one application contract across an approved set of external model routes through six control layers." lang: en status: public-preview lastUpdated: 2026-08-31 url: https://dev.duale.ai/en/docs/model-routing --- ## AI-generated summary Model routing keeps one application contract across approved external model routes, using contextual route choice while the application validates terminal results and owns business acceptance. - Six control layers move a task from approved deployment through route choice to application validation. - A route's declared feature list is operator-written; Duale AI validates responses against the application's schema. - Three lifecycles—request, model configuration, and business process—change independently and each needs an owner. - Wrong feature claims can spend provider calls and time until the deadline ends the task. Summaries were generated by AI. Generative AI is experimental. --- Use model routing to keep one application contract across an approved set of external model routes. First define the hard deployment and tenant boundary. The application can then add contextual preferences without naming a provider or model. [Integrate model routing in an application](https://dev.duale.ai/en/docs/model-routing/application-integration.md) shows the request fields, terminal-result checks, and failure path that keep this contract independent of one provider. The effective model pool contains the enabled routes from the selected tenant configuration that the task runtime has applied. The endpoint and API token select the task boundary; a routing policy only influences choices inside the pool. [Routing contract and limits](https://dev.duale.ai/en/docs/model-routing/contract-and-limits.md) owns the hard boundary, soft preferences, attempt variability, and pool-change rule. [Control model changes](https://dev.duale.ai/en/docs/model-routing/control-model-changes.md) gives the evaluation and rollback sequence for a material pool change. ## Six layers decide the route Model routing moves a task through six control layers. The organization sets the approved boundary, model pool, and agent tools before the request arrives. The request adds the task, output contract, deadline, and preferences. Duale AI then chooses routes and makes attempts. The application validates the terminal result and decides how the business process can use it. Route choice is contextual; result acceptance stays with the application. ```mermaid flowchart LR accTitle: Model routing control boundaries accDescr { The organization defines the deployment, tenant, model pool, and agent tools. The application sends a task, an output contract, a deadline, and routing preferences. Duale AI uses routes from the effective pool. The application validates the terminal result before the business process uses it. } Boundary[Approved deployment and tenant] Pool[Enabled model routes] Agent[Agent tools and permissions] Request[Task, output contract, and routing preferences] Choice[Contextual route choice and attempts] Control[Application validation and business controls] Boundary --> Pool Pool --> Choice Agent --> Choice Request --> Choice Choice --> Control ``` The diagram and table use the same six layers: | Layer | Purpose | Main rule | | ---------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | Approved deployment and tenant | Set the physical data boundary and the logical identity and configuration boundary | Include every external path; a tenant is not physical or regional isolation | | Enabled model routes | Define the provider routes available to the tenant | Treat every enabled route as potentially selectable | | Agent tools and permissions | Define the tools the agent can call | A request cannot add a tool allowlist | | Task, output contract, and routing preferences | Describe the work, deadline, required result, and contextual preferences | A routing preference is not a command to use one route | | Contextual route choice and attempts | Select eligible routes and seek a valid result within the task deadline | Do not assume sequential attempts or an attempt against every enabled route | | Application validation and business controls | Validate the terminal result and decide whether the business process can use it | Keep acceptance and irreversible actions outside routing | Use [Model routing architecture patterns](https://dev.duale.ai/en/docs/model-routing/architecture-patterns.md) when a customer, region, provider, or evaluation boundary needs a separate tenant or deployment. This design provides provider portability, contextual selection, and more fallback options. Model routing controls which external model answers a completion; it does not control document storage, tool destinations, telemetry, or regional hosting. [Plan the deployment](https://dev.duale.ai/en/docs/model-routing/plan-deployment.md) covers those paths. ## Know what a route claims, and what a wrong claim costs Each route in the pool carries a declared feature list, and an operator writes that list. A model identifier adds no feature by itself. Duale AI validates the route document but does not probe the configured endpoint, so a route can claim a feature that its endpoint or model does not honor. [Plan the deployment and model portfolio](https://dev.duale.ai/en/docs/model-routing/plan-deployment.md) states what saving a route does check. A wrong claim does not corrupt your result. Duale AI validates every answer against the response schema your application sent, whichever route ran it, so your application receives a matching result or an error. It never receives a wrong shape. The declaration and adapter path decide how your response schema reaches the provider: | Route condition | What happens | | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | The route declares native structured output and the endpoint honors it | The schema travels in the provider's structured-output field. The provider enforces the sanitized schema. | | The adapter has no native response-schema path | Duale AI adds the schema to the model instructions. The provider does not enforce it. | | The route declares native structured output but the endpoint does not honor it | The provider call can fail. Local validation rejects a wrong-shaped answer, so the task can spend more attempts. | One pool can contain routes that use either valid schema path for the same request. The third row is a configuration error to find during route evaluation, not a supported fallback path. The cost is less visible. A wrong claim can spend provider calls, time, and money until another attempt succeeds or the deadline ends the task. It can look like poor model quality rather than a configuration error. [Routing contract and limits](https://dev.duale.ai/en/docs/model-routing/contract-and-limits.md) states what the routing contract does and does not promise about those attempts. A claim does not decide which routes stay in the pool either. Image support is the exception: a request whose tool results carry images narrows the pool to routes that can carry at least one image. When no route can, every route stays and every image is dropped. [Provider capability and compatibility](https://dev.duale.ai/en/docs/model-routing/provider-capabilities.md) lists what each provider type accepts and how an operator declares it. ## Keep three lifecycles separate Model routing joins three lifecycles that can change independently. A stable request interface can therefore hide a model change that affects the business result. Assign an owner, acceptance evidence, and a stop action to each lifecycle: - **Request lifecycle:** one task is submitted, routed, completed, stopped, or failed. The application owns its deadline, terminal result validation, and failure path. - **Model and configuration lifecycle:** a route is evaluated, approved, enabled, observed, disabled, and retired. The authorized configuration owner controls tenant-owned fields. Preset and provider owners can control other effective fields. - **Business-process lifecycle:** a workflow is designed, accepted, monitored, changed, and withdrawn. Its owner remains accountable for the outcome even when the application code does not change. Require technical checks and business acceptance for each material change. [Ownership and approvals](https://dev.duale.ai/en/docs/model-routing/ownership-and-approvals.md) maps those decisions to customer-held records. [Operate model routing and manage risk](https://dev.duale.ai/en/docs/model-routing/operations-and-risk.md) shows how to observe the resulting business, route, and control health. ## Related content - [Integrate model routing in an application](https://dev.duale.ai/en/docs/model-routing/application-integration.md) - [Provider capability and compatibility](https://dev.duale.ai/en/docs/model-routing/provider-capabilities.md) - [Operate model routing and manage risk](https://dev.duale.ai/en/docs/model-routing/operations-and-risk.md) - [Runtime security and pricing for production agents](https://dev.duale.ai/en/product.md) - [Ownership and approvals for routing decisions](https://dev.duale.ai/en/docs/model-routing/ownership-and-approvals.md) - [One runtime path for production agents by operating role](https://dev.duale.ai/en/solutions.md) --- ## Sitemap See the full [Markdown sitemap](https://dev.duale.ai/sitemap.md) for all pages.