LiteAgents SDK: routing por turno, instalación y migración

Corregir un fallo de inicio de sesión no es una tarea uniforme. Diagnosticar la causa, proponer una corrección defensiva, comprobar pruebas y explicar un pull request requieren trabajos diferentes. Utilizar el mismo modelo grande para todo puede desperdiciar dinero. Encargarlo todo al más barato puede salir peor si después hacen falta más intentos o correcciones humanas.

LiteAgents SDK incorpora la selección de modelos al entorno de ejecución del agente. Esta guía responde a las preguntas de implementación: qué significa «por turno», qué paquete instalar, cómo escribir un router, qué hace realmente el fallback de Jev y qué cambia al migrar desde el Claude Agent SDK.

Revisión de fuentes: 25 de septiembre de 2026. Las observaciones sobre código corresponden al commit 539a6e2 de BerriAI/liteagents. Los ejemplos se han contrastado con las fuentes; no son un benchmark con proveedores en vivo ni una afirmación de que Wavect haya desplegado este SDK para un cliente.

¿Qué es LiteAgents SDK y qué papel desempeña LiteLLM?

LiteAgents es el SDK en Python de BerriAI para ejecutar agentes con diferentes proveedores mediante una interfaz query() familiar. La página de producto de LiteLLM presenta la idea central: elegir el modelo según el trabajo, en lugar de vincular permanentemente el agente a uno solo.

El anuncio de lanzamiento ilustra una corrección de login con Claude Opus 4.8 para planificar, GPT-5.4 mini para implementar y escribir pruebas, y Claude Sonnet 4.6 para describir el PR. Son roles ilustrativos, no una clasificación respaldada por benchmarks ni una promesa de que un único prompt produzca exactamente esa secuencia.

El README revisado del SDK documenta modelos fijos, routers propios, selección de niveles con Jev, un cliente con estado, adaptadores de herramientas MCP y un modo fusion separado. LiteLLM proporciona la capa de acceso a modelos. LiteAgents añade la conversación y el bucle de herramientas.

Esta guía trata la integración de un SDK concreto. Para elegir infraestructura, consulta nuestra comparación de gateways y routers de LLM. Para el modelo de decisión, consulta el análisis técnico de Jev. Son decisiones arquitectónicas distintas.

¿LiteAgents cambia de modelo después de cada herramienta?

No automáticamente con el router Jev revisado. Un turno de usuario y una ronda de llamada al modelo son unidades distintas. La implementación del cliente incrementa su contador de turnos con cada agent.query(prompt). Esa consulta puede necesitar varias respuestas del modelo y resultados de herramientas.

La implementación del bucle de herramientas consulta al router antes de cada ronda de llamada al modelo. Sin embargo, el router Jev almacena el modelo elegido por context.turn. Las siguientes rondas de ese turno reutilizan la selección. Un router propio puede inspeccionar el historial actual y actuar de otra forma; la ruta Jev incorporada no vuelve a clasificar cada resultado de herramienta.

Distingue también el contexto conservado del contexto usado para decidir la ruta. El adaptador Jev envía el prompt actual y las descripciones de niveles, no la conversación completa. «Haz la siguiente parte» aporta por tanto menos información al clasificador que una descripción autónoma de la tarea. Crea un router por cliente: no compartas sin comprobar su caché por número de turno entre sesiones independientes.

¿Cómo instalar el paquete LiteAgents correcto?

Verifica la identidad del repositorio antes de copiar el comando de instalación. Los metadatos revisados de BerriAI declaran Python 3.10 o posterior y la versión 0.1.0. En la fecha de revisión, la entrada pública de PyPI llamada liteagents mostraba otro proyecto, versión 0.0.2, de enero de 2025. Compartir nombre no significa compartir software.

Para esta revisión, la opción inequívoca es un entorno limpio y un commit explícito del repositorio. Estos comandos requieren Git y una shell de tipo POSIX. Fijar el commit identifica el código instalado; no demuestra su seguridad ni la de sus dependencias.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install \
  "liteagents @ git+https://github.com/BerriAI/liteagents.git@539a6e2a9669433ffa9034ae262718e30c4f80b6"
python -c "from liteagents import LiteAgentOptions, LiteAgentClient; print('SDK imports OK')"

La documentación de pip sobre instalación desde VCS explica las referencias directas a commits completos. Revisa el canal de publicación del proveedor al adoptar el SDK y fija y revisa también las dependencias transitivas. No reutilices sin comprobar un entorno de producción que contenga un paquete ajeno con el mismo nombre.

Ante ImportError: cannot import name 'LiteAgentOptions', comprueba python -m pip show liteagents, el intérprete activo y si un archivo local liteagents.py está ocultando el paquete. Un error de importación no demuestra que la clave del proveedor sea incorrecta.

¿Cómo enrutar modelos sin Jev?

Implementa un método asíncrono route(context) que devuelva un identificador de modelo aprobado. Si la aplicación ya conoce la etapa del trabajo, no necesita un servicio de clasificación. También ofrece una referencia útil antes de introducir routing probabilístico.

Configura LITEAGENTS_REASONING_MODEL, LITEAGENTS_FAST_MODEL y LITEAGENTS_BALANCED_MODEL con identificadores que incluyan el proveedor y estén disponibles para tu cuenta. Configura por separado las credenciales de cada proveedor seleccionado. Las etiquetas representan roles de la aplicación, no capacidades garantizadas.

Este ejemplo completo de Python conserva una conversación durante tres turnos explícitos. Solo redacta texto: no conecta un repositorio, una shell, un ejecutor de pruebas ni una herramienta para publicar en GitHub. Los tiempos de espera y límites de salida acotan peticiones individuales; un trabajo de producción necesita además un plazo total y un techo de gasto.

import asyncio
import os
from dataclasses import dataclass

from liteagents import (
    AssistantMessage, LiteAgentClient, LiteAgentOptions,
    TextBlock, TurnContext,
)


def required(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise RuntimeError(f"Set {name} to an approved provider/model ID")
    return value


@dataclass(frozen=True)
class StageRouter:
    models: tuple[str, ...]

    async def route(self, context: TurnContext) -> str:
        index = context.turn - 1
        if not 0 <= index < len(self.models):
            raise RuntimeError("No approved model for this workflow stage")
        return self.models[index]


async def main() -> None:
    router = StageRouter(models=(
        required("LITEAGENTS_REASONING_MODEL"),
        required("LITEAGENTS_FAST_MODEL"),
        required("LITEAGENTS_BALANCED_MODEL"),
    ))
    options = LiteAgentOptions(
        model_router=router,
        system="Draft suggestions only. Never claim a tool or test was run.",
        max_tokens=1200,
        max_turns=4,
        model_kwargs={"timeout": 45, "num_retries": 0},
    )
    prompts = (
        "A login handler calls password.strip() before checking for None. "
        "Explain the failure and propose a defensive fix.",
        "Draft unit-test cases for that fix. Do not execute anything.",
        "Draft a PR description. Separate proposed changes from verified results.",
    )
    async with LiteAgentClient(options=options) as agent:
        for prompt in prompts:
            last = None
            async for event in agent.query(prompt):
                if isinstance(event, AssistantMessage):
                    last = event
                    print(f"model={event.model} stop={event.stop_reason}")
                    for block in event.content:
                        if isinstance(block, TextBlock):
                            print(block.text)
            if last is None or last.stop_reason not in {
                "end_turn", "stop", "stop_sequence",
            }:
                raise RuntimeError("Incomplete stage; do not continue automatically")


if __name__ == "__main__":
    asyncio.run(main())

El router y el cliente siguen la interfaz documentada para routers propios. El ejemplo determinístico falla deliberadamente ante una cuarta etapa inesperada, en lugar de elegir un modelo silenciosamente. Tampoco continúa tras una respuesta incompleta. Usa clientes separados para trabajos independientes; no ejecutes consultas simultáneas sobre el mismo cliente con estado.

¿Cómo elige Jev un nivel en el routing automático?

JevAgent proporciona el envoltorio sencillo. Usa JevModelRouter dentro de LiteAgentOptions para combinar routing con otras opciones. Define los niveles candidatos y un modelo de fallback. En el adaptador revisado, la clasificación utiliza nombres y descripciones de niveles; la petición no contiene precios actualizados ni puntuaciones de calidad medidas. «El más adecuado» es el objetivo, no una prueba de coste globalmente óptimo.

El siguiente fragmento es una referencia de configuración, no una integración Jev verificada en vivo. Lee explícitamente TYPESAFE_API_KEY para que una configuración ausente falle al inicio, en lugar de seleccionar silenciosamente el fallback.

import os
from liteagents import JevModelRouter, JevTier, LiteAgentOptions

router = JevModelRouter(
    tiers=(
        JevTier(name="FAST", model=os.environ["LITEAGENTS_FAST_MODEL"],
                description="Bounded edits and test-case drafting"),
        JevTier(name="BALANCED", model=os.environ["LITEAGENTS_BALANCED_MODEL"],
                description="Routine implementation and explanations"),
        JevTier(name="REASONING", model=os.environ["LITEAGENTS_REASONING_MODEL"],
                description="Ambiguous diagnosis and architecture"),
    ),
    fallback_model=os.environ["LITEAGENTS_REASONING_MODEL"],
    api_key=os.environ["TYPESAFE_API_KEY"],
    timeout=5.0,
)
options = LiteAgentOptions(model_router=router, max_tokens=1200, max_turns=4)

Comprueba el contrato del endpoint antes de depender de esta ruta. El adaptador revisado llama a /v1/classify y califica su contrato HTTP de ilustrativo o «best-effort». La referencia pública de modelos de TypeSafe documenta POST /v1/systemone. La diferencia exige una prueba de compatibilidad real o corregir el adaptador; no demuestra que sea imposible que exista un endpoint no documentado.

Hasta superar esa comprobación, utiliza el router determinístico o un adaptador propio probado contra la API documentada. No inventes umbrales de confianza para el adaptador incorporado: consume un nombre de nivel y no expone la distribución de probabilidades del clasificador.

¿Por qué LiteAgents siempre usa el modelo de fallback?

Una respuesta completa no demuestra que el routing automático haya funcionado. En la implementación Jev revisada, una clave ausente, un error HTTP gestionado, JSON inválido o un nivel desconocido pueden activar fallback_model. La aplicación puede seguir respondiendo mientras desaparece el ahorro esperado.

Comprueba credenciales, compatibilidad del endpoint, formato de respuesta y nombres exactos de los niveles. Un adaptador instrumentado debería registrar si la ruta se clasificó, se impuso por política o se eligió tras un error. Registra la ruta solicitada junto a AssistantMessage.model y el uso. El mismo modelo puede ser una selección legítima o un fallback; su nombre no distingue ambos casos.

No interpretes fallback como gestión universal de excepciones. Por ejemplo, el código revisado espera JSON con un campo tier; también debes probar tipos inesperados en el nivel superior. El fallback del clasificador tampoco equivale a failover del proveedor: tras elegir el modelo todavía pueden fallar las credenciales, los límites de uso o la generación. LiteLLM documenta el failover de proveedores por separado.

El modelo de fallback debe respetar los mismos límites de proveedores y datos aprobados. «Usar el modelo seguro» no es una decisión de autorización y no debe saltarse restricciones de región, cliente o confidencialidad.

¿LiteAgents sustituye directamente al Claude Agent SDK?

Una interfaz familiar no implica un entorno de ejecución equivalente. Cambiar imports puede ser sencillo. Herramientas, permisos, persistencia y supuestos de ejecución requieren pruebas de migración independientes. La descripción de Anthropic del Agent SDK presenta un entorno basado en Claude Code con herramientas, permisos, sesiones y hooks incorporados.

Las opciones y el cliente revisados de LiteAgents definen el límite de su API local. La documentación de MCP asigna a la aplicación el transporte, la autenticación y la duración de la sesión. El adaptador no es un sistema de permisos. Mantén abiertas las sesiones MCP inicializadas durante el uso y expón solo herramientas de una lista permitida explícita.

Un gateway LiteLLM puede gestionar selección de despliegues y fiabilidad debajo del agente. La documentación de LiteLLM Router describe esa capa. Instalar el SDK de agentes no despliega automáticamente un gateway ni activa controles de gasto para toda la organización.

¿Cómo implementar «corrige el login, añade pruebas y abre un PR»?

Haz explícitas las etapas. Primero diagnostica el fallo con un ejemplo reproducible y acceso de solo lectura al repositorio. Después, una etapa de implementación genera un parche acotado en una rama aislada. Una herramienta de pruebas separada debe ejecutar las comprobaciones reales y devolver su código de salida y resultados. Una etapa de revisión evalúa el diff y la evidencia antes de que la herramienta de publicación cree un PR en borrador.

La política puede asignar un modelo de razonamiento al diagnóstico, uno pequeño a una modificación concreta y uno equilibrado a la explicación. Esa distribución es una hipótesis para evaluar, no una receta universal. Un fallo de autenticación puede ser sensible para la seguridad aunque el cambio de código parezca pequeño.

Conserva la evidencia de ejecución fuera de la prosa del modelo. Guarda identificador de commit, archivos modificados, comando de pruebas, código de salida e identificador del PR como resultados de herramientas. No aceptes «las pruebas pasaron» de un modelo sin herramienta de pruebas. Separa las autorizaciones de merge y despliegue del permiso para redactar un PR.

Para una implementación real, utiliza espacios de trabajo nuevos, tokens de repositorio limitados, restricciones de rutas de escritura y una clave de idempotencia para crear el PR. Son controles recomendados de la aplicación, no funciones demostradas por el ejemplo que solo redacta texto.

¿En qué se diferencia fusion del routing de modelos?

El routing decide qué modelo atiende una llamada. Fusion permite que un agente principal delegue una subtarea en un asistente con historial propio. La documentación de fusion del SDK describe su configuración mediante FusionOptions. Los historiales separados pueden apoyar trabajos distintos; no demuestran por sí solos una reducción de coste.

Evalúa fusion por separado del cambio secuencial. Cuenta entradas y salidas de ambos agentes, esperas, investigaciones duplicadas y verificación. Conservar el historial del cliente tampoco crea una caché portable entre proveedores: un nuevo proveedor puede recibir la conversación sin heredar los tokens cacheados del anterior. Mide el uso real de caché en lugar de suponer un traspaso gratuito.

El crecimiento del historial puede eliminar el ahorro de un modelo pequeño. Usa evidencia pertinente y resúmenes explícitos, pero conserva la información necesaria para reproducir el fallo. El routing entre proveedores también amplía el conjunto de sistemas que pueden recibir prompts o código. Aprueba ese flujo de datos antes de habilitar un nivel.

¿El routing por turno reduce realmente el coste de los agentes?

Solo si el trabajo aceptado resulta más barato con la calidad y latencia necesarias. Una respuesta individual más económica no basta. Incluye clasificación, generación, reintentos, herramientas, infraestructura y corrección humana atribuible dentro de la ventana de evaluación.

Coste por tarea aceptada = coste atribuible total de todos los intentos / número de tareas aceptadas

En este ejemplo inventado, el gasto cae un 25 %, pero el coste por tarea aceptada sube un 20 %. Además queda más trabajo sin terminar. El denominador correcto cambia la decisión.

Compara cuatro candidatos sobre las mismas tareas reservadas para evaluación: el modelo fijo actual, uno fijo más barato, un router determinístico por etapas y el router automático. Mantén herramientas, criterios de aceptación y presupuestos máximos comparables. Informa sobre calidad, tiempo de corrección, frecuencia de fallback y latencia total p50/p95, no solo coste medio por token. Nuestra guía de coste por acción de agente amplía el modelo de cálculo.

¿Qué debe demostrar un piloto de LiteAgents antes de producción?

Empieza con trabajo reversible y una lista corta de modelos permitidos. Observa primero las rutas propuestas mientras la configuración conocida completa las tareas. Después prueba la ejecución realmente enrutada sobre copias aisladas. Así evalúas el routing sin convertir el primer experimento en permiso para modificar producción.

Presta especial atención a max_turns. En el bucle de herramientas revisado, alcanzar ese límite durante el uso de herramientas no genera una respuesta final. Sigue la última respuesta del asistente y trata stop_reason="tool_use" como trabajo incompleto. Recibir un flujo de mensajes no equivale automáticamente a un resultado empresarial satisfactorio.

¿Cuándo merece la pena evaluar LiteAgents?

LiteAgents resulta interesante cuando necesitas flexibilidad entre proveedores y tus tareas tienen requisitos de modelos realmente distintos. Aporta menos cuando un único modelo económico ya cumple, o cuando migrar eliminaría controles del entorno de ejecución sin reemplazarlos.

La progresión útil es concreta: verificar el paquete, reproducir el comportamiento con modelo fijo, introducir etapas explícitas y añadir clasificación automática solo después de validar contrato y economía. Una animación convincente de routing no sustituye una prueba de aceptación de producción.

Los servicios de ingeniería de IA de Wavect apoyan la integración y evaluación. El caso Twinsoft AI aporta contexto de entrega relacionado, no una afirmación de despliegue de LiteAgents. Utiliza la lista de QA previa al lanzamiento para definir la aceptación o comenta un piloto de agentes con routing centrado en un flujo real y su rendimiento actual.