AWS Builder Center
Capability Routing: cómo elegir modelos por capacidad (sin hardcodear el provider)

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)

  1. …
  2. 3
    Capability 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.) es  StrandsModelFactory .
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: true
El 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-reasoning
Esa 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:
  1. el modelo está  enabled ;
  1.  policy.requires ⊆ model.capabilities ;
  1.  cost_class  no supera  max_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:
  1. si la política trae  fallback: [...] , ese orden manda;
  1. 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 Path
from src.models import load_model_registry
from src.policies import load_workflow_catalog
from 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

  1. Saca los model IDs del business logic. Pide capacidades.
  1. Registry declara. Policy requiere. Router decide. Tres roles, cero ambigüedad.
  1. Matching = subset + presupuesto. Si no cabe, error explícito.
  1. Ranking determinista. Mismo input, misma decisión, razón legible.
  1. 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)

  1. …
  2. 3
    Capability Routing: cómo elegir modelos por capacidad (sin hardcodear el provider) This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article