Leitfaden — Benutzerdefinierte Modell-Provider

Umfang

Dieses Dokument fasst die Schritte und Kriterien für benutzerdefinierte Modell-Provider mit dem Strands Agents SDK in Shell Sentinel zusammen. Es ergänzt die offizielle Dokumentation als interne Checkliste.

Voraussetzungen

Kenntnis der Hierarchie strands.models.Model (z. B. BedrockModel).
Verständnis von Messages, StreamEvent und ToolSpec.
Python-Client für den proprietären LLM-Dienst.
Deklarative Konfiguration in conf/ und Credentials über Umgebungsvariablen.

Implementierungsablauf

Konfiguration definieren: typisierte ModelConfig mit get_config/update_config.
Client initialisieren: Credentials sicher auflösen, Remote-Client instanziieren, Logging registrieren.
stream(...) implementieren: Eingaben konvertieren, StreamEvent anpassen, Fehler behandeln; bei sync SDK asyncio.to_thread nutzen.
Tools unterstützen: stream in structured_output(...) mit Pydantic-ToolSpec.
Provider registrieren in smart_ai_sys_admin.agent und conf/agent.conf.

Zusätzliche Hinweise

DEBUG-Logging für Troubleshooting.
Neue Parameter in Benutzerhandbüchern dokumentieren, wenn Operatoren betroffen sind.
Keine Tokens oder Endpoints hardcoden.
Smoke-Tests vor TUI-Integration.

Praxisbeispiel: OpenAI Responses API

providers.openai.api unterstützt chat_completions (Standard, /v1/chat/completions) und responses (/v1/responses). max_tokens wird für Chat Completions zu max_completion_tokens oder für Responses zu max_output_tokens; reasoning_effort und reasoning.effort werden ebenfalls an den Endpoint angepasst.

Die Migration behebt einen HTTP 400, wenn gpt-5.6-sol über Chat Completions Function Tools mit aktivem Reasoning erhält. reasoning_effort: "none" verhindert den Fehler nur durch deaktiviertes Reasoning (reasoning_tokens=0). Responses unterstützt Function Tools mit Reasoning medium ohne diese Einschränkung.

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

Die effektive Anfrage nutzt reasoning.effort und max_output_tokens; die reale Konfiguration nutzt 65536. Optionales temperature: 0.3 wird unterstützt, ist aber kein Standardwert. OPENAI_API_KEY kommt aus der Umgebung.

Optionales stateful kann previous_response_id nutzen, aber rekonstruiertes Multi-Turn-reasoningContent behält noch keine vollständige Reasoning-Kontinuität.

Praxisbeispiel: LM Studio

OpenAI-kompatibler lokaler Server (/v1/*); base_url, api_key, model_id konfigurieren.
Start mit lms server start; client_args für Timeouts.
Native REST-API (/api/v0/*) für Metriken und max_context_length.

Praxisbeispiel: Mistral AI (Pfad A+)

ShellMistralModel umschließt Strands MistralModel (offizielles mistralai v2 SDK).
providers.mistral mit Standard reasoning_effort: high und max_tokens: 16184.
make test-mistral ausführen, wenn MISTRAL_API_KEY gesetzt ist.

Praxisbeispiel: Cerebras

cerebras_cloud_sdk mit SSE-Streaming integrieren.
providers.cerebras mit model_id, params, client_args, api_key_env.
ChatChunkResponse in native Events mit metadata für Nutzung und Zeiten.