
Capability Routing: cómo elegir modelos por capacidad (sin hardcodear el provider)
Tu agente no debería saber si detrás hay Ollama, OpenAI o Anthropic; debería pedir tool-use y structured-output, y dejar que el router se encargue del resto.
Series: LLM Portability (4 articles)
- …
- 3Capability Routing: cómo elegir modelos por capacidad (sin hardcodear el provider) This article
Hay una línea de código que envejece más rápido que cualquier dependencia:
model = "gpt-4o-mini"O peor:
if provider == "openai": ...elif provider == "ollama": ...Cada lanzamiento de modelo la vuelve un poco más falsa, cada experimento de latencia te empuja a tocarla, y cada "vamos a probar Claude" termina en un PR que no debería existir.
Yo también empecé así, hasta que me cansé de tocar el agent loop cada vez que quería comparar un profile.
La salida no fue otro wrapper HTTP, sino un Capability Router: una capa determinista que elige el modelo a partir de lo que el workflow necesita, no de cómo se llama el vendor.
El agent loop no elige modelos
Si usas Strands , la invocación ya está abstraída. Providers intercambiables, mismo agent loop, mismos tools.
Eso resuelve cómo hablar con el modelo, pero no resuelve cuál modelo debería correr este workflow.
En el lab, la separación es deliberada:
- el router decide el profile y la cadena de fallback;
- el WorkflowRunner recorre esa cadena;
- el AgentFactory solo ejecuta con el profile que le pasan;
- el único módulo que importa SDKs de providers (
OpenAIModel,OllamaModel, etc.) esStrandsModelFactory.
Cuando
run.py arranca incident_analysis , el runner pide una RoutingDecision antes de invocar al agente; después, el agente no opina sobre OpenAI vs Ollama, porque recibe un profile ya elegido y sigue. Si pasas --profile , el registry se reduce a ese profile, pero la decisión sigue pasando por el router.Si quieres el mapa completo de capas encima del adapter, está en este artículo . Aquí me quedo en la pieza que falta cuando ya puedes swappear… pero todavía eliges el modelo a mano.
Capacidades: el vocabulario común
Antes de enrutar, necesitas un idioma compartido entre workflows y modelos.
En el lab, las capacidades relevantes son pocas a propósito:
Capability | Qué significa en la práctica |
|---|---|
text | puede generar texto |
tool-use | puede invocar tools del agent loop |
structured-output | puede cumplir un contrato tipado |
reasoning | declarado para perfiles de razonamiento más profundo |
long-context | declarado para ventanas largas |
No inventes una taxonomía de marketing: declara solo lo que tu app realmente discrimina.
Y sé honesto: declarado ≠ evaluado. Si pones
tool-use en el registry, es porque lo verificaste. Si no, el router te va a mandar tráfico a un mentiroso bien tipado.El registry: dónde viven los profiles
Los models viven en YAML. Sin secretos. Con versión. Con
enabled para apagar sin borrar:models: fast-general: provider: mock model_id: mock-fast capabilities: - text - tool-use - structured-output latency_class: low cost_class: low enabled: true
deep-reasoning: provider: mock model_id: mock-deep capabilities: - text - reasoning - tool-use - structured-output - long-context latency_class: high cost_class: high enabled: trueEl workflow, por su lado, no pide
mock-fast . Pide capacidades:workflows: incident_analysis: requires: - tool-use - structured-output optimize_for: reliability max_cost_class: high fallback: - fast-general - deep-reasoningEsa asimetría es el punto: un lado declara qué puede, el otro declara qué necesita, y el router hace el match.
Matching: subset, no vibes
La regla de compatibilidad es aburrida a propósito:
- el modelo está
enabled;
-
policy.requires ⊆ model.capabilities;
-
cost_classno superamax_cost_class.
Si un profile solo tiene
text y el workflow pide tool-use + structured-output , queda fuera, sin "tal vez funciona".
En código, eso termina en algo así:
compatible = [ model for model in registry.enabled_models() if policy.requires.issubset(model.capabilities) and cost_ok(model, policy.max_cost_class)]Si la lista queda vacía, el lab lanza
NoCompatibleModelError ; prefiero un error claro a las 10am que un modelo incapaz a las 3am.Ranking: determinista o no lo llames router
Una vez que tienes los candidatos que pasan el filtro, falta ordenarlos, y acá tomé una decisión de diseño que me ha ahorrado dolores: no uso un LLM para elegir otro LLM.
El ranking es determinista:
- si la política trae
fallback: [...], ese orden manda;
- lo que quede se ordena por
optimize_for(latency,cost,reliability).
Para
incident_analysis en la config de ejemplo, el resultado es estable:- selected:
fast-general
- fallbacks:
deep-reasoning
Los tests lo clavan: misma entrada, misma decisión, que es exactamente lo que quieres cuando estás debuggeando un on-call y no una ruleta.

La decisión tiene que explicarse sola
El router no devuelve solo un string con el model id. Devuelve una
RoutingDecision :class RoutingDecision(BaseModel): selected: ModelProfile fallbacks: list[ModelProfile] reason: str workflow: str candidates_considered: list[str]La
reason se ve más o menos así:Selected 'fast-general' for workflow 'incident_analysis' (optimize_for=reliability, requires=['structured-output', 'tool-use'], max_cost_class=high). Fallback chain: ['deep-reasoning'].
Eso va a logs, así que cuando algo falla no tienes que preguntar "quién eligió este modelo", porque ya está escrito.
El runner toma
decision.chain y le pasa cada profile al AgentFactory para ejecutar, sin reabrir el debate de selección.Demo local: lo mínimo para creerlo
Con el registry y el workflow de ejemplo:
python -c "from pathlib import Pathfrom src.models import load_model_registryfrom src.policies import load_workflow_catalogfrom src.router import CapabilityRouter
root = Path('.')registry = load_model_registry(root / 'config' / 'models.yaml')policy = load_workflow_catalog(root / 'config' / 'workflows.yaml').get('incident_analysis')decision = CapabilityRouter().route(registry, policy)print(decision.selected.name)print([m.name for m in decision.fallbacks])print(decision.reason)"Salida esperada:
fast-general['deep-reasoning']Selected 'fast-general' for workflow 'incident_analysis' ...Si metes un registry con un solo modelo
text-only y la misma policy, no obtienes un soft-fail creativo, sino un NoCompatibleModelError .Eso es el contrato del router: elige en voz alta, o falla en voz alta.
Lo que este router no es
No es un policy engine completo; aquí usamos políticas lo justo para filtrar y rankear, mientras que el diseño fino de budgets, prioridades y cadenas de fallback merece su propio espacio y no quiero mezclarlo con la mecánica del match.
No es un load balancer mágico. No mira GPUs. No predice tokens. En fase local, la honestidad gana a la sofisticación.
No reemplaza evaluación. Enrutar bien no prueba que el juicio del modelo sea portable. Solo prueba que elegiste un candidato compatible antes de invocarlo.
Lo que quiero que te lleves
- Saca los model IDs del business logic. Pide capacidades.
- Registry declara. Policy requiere. Router decide. Tres roles, cero ambigüedad.
- Matching = subset + presupuesto. Si no cabe, error explícito.
- Ranking determinista. Mismo input, misma decisión, razón legible.
- El runner consume
RoutingDecision. El agent loop no elige providers.
Cuando el próximo modelo salga el martes, no reescribes el agente; actualizas el registry, o ni eso, porque a veces basta con cambiar qué profile está
enabled y en qué orden de fallback entra.Si ya estás eligiendo modelos dentro del agent loop, prueba esto: busca un
gpt- , un claude- o un llama en tu business logic. Cada match es una deuda de portabilidad esperando el próximo launch.Series: LLM Portability (4 articles)
- …
- 3Capability Routing: cómo elegir modelos por capacidad (sin hardcodear el provider) This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article