← Back to documentation / Custom providers (EN)

Guide — Custom model providers

Scope

This document summarises the steps and criteria for implementing custom model providers with the Strands Agents SDK inside Shell Sentinel. It serves as an internal checklist and complements the official documentation.

Prerequisites

Implementation flow

  1. Define configuration: create a typed ModelConfig and expose get_config/update_config.
  2. Initialise the client: resolve credentials securely, instantiate the remote client and register logging.
  3. Implement stream(...): convert inputs, adapt to StreamEvent, handle errors; use asyncio.to_thread for sync SDKs.
  4. Support tools: reuse stream in structured_output(...) with Pydantic ToolSpec conversion.
  5. Register the provider in smart_ai_sys_admin.agent and conf/agent.conf.

Additional considerations

Practical case: OpenAI Responses API

providers.openai.api accepts chat_completions (default, /v1/chat/completions) and responses (/v1/responses). max_tokens is normalized to max_completion_tokens for Chat Completions or max_output_tokens for Responses; reasoning_effort and reasoning.effort are normalized for the selected endpoint too.

The migration addresses an HTTP 400 when gpt-5.6-sol receives function tools and active reasoning through Chat Completions. reasoning_effort: "none" avoids the error only by disabling reasoning (reasoning_tokens=0). Responses supports function tools with medium reasoning without that degradation.

The current example uses GPT-6.1 Sol. This model requires Responses for function tools and supports medium reasoning; none is not supported. The GPT-5.6 workaround above does not apply to GPT-6.1 Sol. 

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

The effective request uses reasoning.effort and max_output_tokens; the real configuration uses 65536. Export OPENAI_API_KEY from the environment.

Optional stateful mode can use previous_response_id, but reconstructed multi-turn reasoningContent does not yet retain full reasoning continuity.

Practical case: LM Studio

Practical case: Mistral AI (Path A+)

For Mistral Large 4, set provider: "mistral", providers.mistral.model_id: "mistral-large-4" and reasoning_effort: "high"; keep max_tokens: 16184 and MISTRAL_API_KEY in the environment. Mistral Large 4 reasoning does not support none. Run the live TUI checks with RUN_E2E=1 SHELL_SENTINEL_E2E_PROVIDERS=mistral-large-4 make test-e2e-live.

Practical case: Google Gemini

Prompt caching

Turn limit per instruction

Practical case: Cerebras

External references