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

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

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.

El ejemplo actual usa GPT-6.1 Sol. Este modelo requiere Responses para function tools y admite razonamiento medium; none no está soportado. La solución anterior de GPT-5.6 no se aplica a GPT-6.1 Sol.

{
  "model_id": "gpt-6.1-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. 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

Caso práctico: Mistral AI (Camino A+)

Para Mistral Large 4, configura provider: "mistral", providers.mistral.model_id: "mistral-large-4" y reasoning_effort: "high"; conserva max_tokens: 16184 y MISTRAL_API_KEY en el entorno. El razonamiento de Mistral Large 4 no admite none. Ejecuta las pruebas reales de la TUI con RUN_E2E=1 SHELL_SENTINEL_E2E_PROVIDERS=mistral-large-4 make test-e2e-live.

Caso práctico: Google Gemini

Prompt caching

Límite de turnos por instrucción

Caso práctico: Cerebras

Referencias externas