Guía — Proveedores de modelo personalizados

Alcance

Este documento resume los pasos y criterios para implementar proveedores de modelo personalizados en el SDK de Strands Agents dentro de Shell Sentinel. Sirve como checklist interno y complemento de la documentación oficial.

Requisitos previos

• Conocer la jerarquía strands.models.Model (revisa ejemplos como BedrockModel).
• Comprender los tipos Messages, StreamEvent y ToolSpec.
• Cliente Python para el servicio LLM propietario (sincrónico o asíncrono).
• Configuración declarativa en conf/ y credenciales vía variables de entorno.

Flujo de implementación

1. Definir configuración: crea una ModelConfig tipada con los parámetros admitidos y expón get_config/update_config.
2. Inicializar el cliente: resuelve credenciales desde el entorno seguro, instancia el cliente remoto y registra logging (smart_ai_sys_admin.agent).
3. Implementar stream(...):
   • Convierte messages, tool_specs y system_prompt al formato que espera el servicio externo.
   • Adapta la respuesta al protocolo StreamEvent (eventos messageStart, contentBlockDelta, messageStop, etc.).
   • Gestiona errores de ventana de contexto, timeouts y autenticación con trazas útiles.
   • Si el SDK es sincrónico, usa asyncio.to_thread para no bloquear el event loop.
4. Soportar herramientas: reutiliza stream en structured_output(...), convierte modelos Pydantic a ToolSpec y valida la respuesta.
5. Registrar el proveedor: expón la clase dentro de smart_ai_sys_admin.agent y añade la configuración correspondiente en conf/agent.conf.

Consideraciones adicionales

• Usa logging con nivel DEBUG para facilitar el troubleshooting.
• Documenta cualquier nuevo parámetro en los manuales de usuario cuando afecte al operario.
• No hardcodees tokens ni endpoints; emplea variables de entorno y archivos en conf/.
• Prepara pruebas de humo o scripts manuales antes de integrar el proveedor en la TUI.

Caso práctico: LM Studio

• Servidor local compatible con la API de OpenAI (/v1/*); configura base_url, api_key y model_id.
• Arranca con lms server start; ajusta client_args para controlar timeouts.
• La REST API nativa (/api/v0/*) expone métricas; úsala para telemetría y cálculo de límites (max_context_length).

Caso práctico: Cerebras

• Integra cerebras_cloud_sdk dentro de un modelo personalizado con streaming SSE.
• Configura model_id, params, client_args y api_key_env en providers.cerebras.
• Convierte ChatChunkResponse en eventos nativos, exponiendo metadata con uso y tiempos.
• Para salidas estructuradas, genera un ToolSpec y parsea tool_call.function.arguments.

Referencias externas

• Documentación oficial: Strands Agents
• Código de ejemplo (BedrockModel): Repositorio oficial