Skip to content

Improve model-routing discoverability and task-oriented examples #2387

Open

Description

@danbarr

Reader need

"I want a stronger planning model, cheaper agents for smaller tasks, and a way to check which model actually ran."

Current gap

user-docs/features/sessions/model-routing.md already owns the necessary behavior and configuration. It is linked from Capabilities and partway through Choose models and providers, but has no direct entry point from the Use Mecatl index, customization guide, or delegation workflow. Its first example combines aliases, auxiliary slots, categories, and the Jev classifier before a reader completes a small task.

Proposed work

Improve the existing routing page rather than create a competing guide. Add task-oriented entry points for a planning model, routing delegated work by task complexity, and verifying the actual model. Start with the smallest useful configuration; introduce classifier backend choices when the automatic-routing scenario needs them. Make links from relevant client/delegation and operator entry points describe the outcome.

Reader framing

Lead with the desired outcome and configured model policy. A reader should be able to describe a task normally while eligible delegation uses operator defaults and automatic routing. Present explicit model or category selection as an optional control for tasks that need it, rather than something users must specify in every prompt.

Distinguish the model's choice of delegation mechanism from the router's selection of a model for an eligible delegated call. Neither guarantees that every task will be delegated or that every configured category will be used. Show how to inspect what actually ran and how an unavailable or unsuitable route is handled.

Acceptance criteria

  • A reader can reach routing from Use Mecatl and delegated-work guidance without knowing the feature name.
  • At least one minimal configuration-to-task-to-verification example precedes the comprehensive configuration treatment.
  • Session model selection, plan-mode model selection, auxiliary slots, and delegated routing are distinguished without duplicating their full contracts.
  • The example explains configuration ownership, provider setup prerequisites, and when an operator must make the change on a remote server.
  • The reader can verify the actual delegated provider/model and recognize a fallback; a classifier candidate is not presented as proof of execution.
  • The main worked example starts with an ordinary task prompt after policy setup, then verifies the actual selection; users do not need to name a model or category for each task.
  • Explicit model/category overrides are clearly optional and explain their effect on automatic routing; do not imply that explicit choices still exercise the classifier.
  • Delegation-mode selection and model routing are distinguished, with no promise that the agent always chooses a particular mode or model.
  • Existing routing URLs and canonical ownership are preserved.

Tracking

Part of #2386. Follow the parent issue's shared ownership and validation criteria.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions