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.

Das aktuelle Beispiel verwendet GPT-6.1 Sol. Dieses Modell benötigt Responses für Function Tools und unterstützt Reasoning medium; none wird nicht unterstützt. Der obige GPT-5.6-Workaround gilt nicht für GPT-6.1 Sol.

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

Für Mistral Large 4 setze provider: "mistral", providers.mistral.model_id: "mistral-large-4" und reasoning_effort: "high"; behalte max_tokens: 16184 bei und hinterlege MISTRAL_API_KEY in der Umgebung. Mistral Large 4 Reasoning unterstützt none nicht. Starte die Live-TUI-Tests mit RUN_E2E=1 SHELL_SENTINEL_E2E_PROVIDERS=mistral-large-4 make test-e2e-live.

Praxisbeispiel: Google Gemini

Strands' GeminiModel (Extra gemini, offizielles google-genai-SDK) wird direkt genutzt; kein eigener Wrapper.
providers.gemini mit model_id (gemini-3.8-flash), params (max_tokens wird zu max_output_tokens) und client_args konfigurieren.
Schlüssel aus api_key_env (GEMINI_API_KEY, dann GOOGLE_API_KEY); api_key im JSON wird abgelehnt. client_args.vertexai: true nutzt Google-Cloud-Anmeldedaten.
Thoughts kommen als reasoningContent (show_thinking); cached_content_token_count wird auf cacheReadInputTokens abgebildet. Kein CacheConfig, daher startet der Block cache deaktiviert.
Die Live-e2e-Registry enthält eine Zeile gemini: make test-e2e-live deckt sie ab, sobald GEMINI_API_KEY gesetzt ist.

Prompt-Caching

Optionaler Block cache pro Provider (enabled, strategy, ttl, system_prompt_ttl, tools_ttl, cache_key), abgebildet auf Strands' CacheConfig.
Bedrock: standardmäßig enabled: true + strategy: "auto"; Cache-Points nur bei Claude-Modell-IDs.
OpenAI und Mistral: standardmäßig enabled: true; es wird nur ein stabiler prompt_cache_key aus Konfigurationspfad und model_id gesendet (cache_key: false deaktiviert ihn).
LM Studio ist standardmäßig deaktiviert; Ollama, Cerebras und Gemini ignorieren den Block mit einer Warnung im Log. /status zeigt gecachte gegenüber gesamten Eingabe-Tokens des letzten Turns.

Turn-Limit pro Anweisung

agent.max_turns (Standard 25, null/0 deaktiviert) wird als positive Ganzzahl validiert und von AgentRuntime.invoke als limits={"turns": N} an den Strands-Agenten übergeben.
Beim Erreichen des Limits liefert Strands stop_reason == "limit_turns", statt weiter zu rekursieren; die Runtime hängt die lokalisierte Warnung agent.invoke.turn_limit an den Modelltext an und protokolliert ein WARNING. Keine providerspezifische Arbeit nötig.

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.
Für strukturierte Ausgaben eine ToolSpec erzeugen und tool_call.function.arguments parsen.