Read the live capability surface
Start with the official models directory at implementation time. Confirm availability, supported inputs and outputs, tool support, context limits, and current pricing for your account and region. Do not infer a capability from a family name.
Keep documentation links near configuration so the next maintainer can re-check the decision rather than trusting an old comment.
Evaluate the workload, not the leaderboard
Build a representative set from real tasks and failure modes. Score correctness, instruction following, evidence quality, latency, and total cost. For media or voice workloads, include quality and delivery constraints specific to that modality.
A routing policy may use different models for interactive speed, deep analysis, media, or fallback. Keep it understandable; routing complexity becomes another system to test.
- Pin a tested identifier for production.
- Review aliases before relying on automatic migration.
- Define fallback behavior before an outage.
Make replacement routine
Store the model identifier, timeouts, reasoning controls, and feature flags in validated configuration. Capture an evaluation baseline and a rollback value with each change.
Re-run the same cases when the catalog or application changes. Promote only after quality gates pass, then monitor drift in latency, errors, and task success.