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: OpenAI Responses API

providers.openai.api admite chat_completions (predeterminado, /v1/chat/completions) y responses (/v1/responses). max_tokens se normaliza a max_completion_tokens para Chat Completions o a max_output_tokens para Responses; reasoning_effort y reasoning.effort también se adaptan al endpoint.

El error HTTP 400 que motivó la migración aparece cuando gpt-5.6-sol recibe function tools y razonamiento activo en Chat Completions. Usar reasoning_effort: "none" evita el error porque desactiva el razonamiento y deja reasoning_tokens=0. Responses permite function tools con esfuerzo medium sin esa degradación.

{
  "model_id": "gpt-5.6-sol",
  "api": "responses",
  "params": {"reasoning_effort": "medium", "max_tokens": 32768}
}

El request efectivo usa reasoning.effort y max_output_tokens; la configuración real usa 65536. temperature: 0.3 está aceptado como opción, pero no es el valor predeterminado. Exporta OPENAI_API_KEY desde el entorno.

stateful es opcional y puede usar previous_response_id, pero existe una limitación multi-turno: reasoningContent no mantiene aún continuidad completa al reconstruir el historial. El modelo razona en cada turno, pero pierde parte del contexto de razonamiento entre turnos.

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: Mistral AI (Camino A+)

• ShellMistralModel envuelve MistralModel de Strands (SDK mistralai v2).
• Configura providers.mistral con reasoning_effort: high y max_tokens: 16184 por defecto.
• Ejecuta make test-mistral con MISTRAL_API_KEY disponible.

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