STATEK
Model Providers

STATEK Model Providers

Model providers are the LLM transport layer.

They decide where STATEK sends prompts, chat history, and formal tool definitions. They do not change the core STATEK model: agents execute Python, jobs persist state, tools are Python callables, and dbzero-backed objects are normal durable application objects.

Provider configuration answers three questions:

  • which API credentials should STATEK use?
  • which provider should a job route through?
  • which model string should be sent upstream?

Supported Provider Adapters

STATEK includes built-in provider keys for many OpenAI-compatible chat-completions APIs:

  • OPENAI
  • OPENROUTER
  • GROQ
  • MISTRAL, MISTRALAI, MISTRAL_AI
  • DEEPSEEK, DEEP_SEEK
  • XAI, X_AI, GROK
  • TOGETHER, TOGETHERAI, TOGETHER_AI
  • FIREWORKS, FIREWORKSAI, FIREWORKS_AI
  • CEREBRAS
  • PERPLEXITY
  • SAMBANOVA, SAMBA_NOVA
  • NVIDIA, NVIDIA_NIM, NIM
  • NEBIUS
  • COHERE
  • MOONSHOT, MOONSHOTAI, MOONSHOT_AI, KIMI
  • DASHSCOPE, DASH_SCOPE, ALIBABA, ALIBABA_CLOUD, QWEN
  • CLOUDFLARE, CLOUDFLARE_WORKERS_AI, WORKERS_AI
  • CLOUDFLARE_AI_GATEWAY, AI_GATEWAY
  • GITHUB, GITHUB_MODELS
  • BEDROCK, AMAZON_BEDROCK, AWS_BEDROCK
  • MICROSOFT_FOUNDRY, MS_FOUNDRY, AZURE_FOUNDRY
  • AZURE_OPENAI, AZURE_OPEN_AI
  • GEMINI_ENTERPRISE, GOOGLE_GEMINI_ENTERPRISE, GOOGLE_OPENAI
  • OLLAMA
  • LMSTUDIO, LM_STUDIO
  • VLLM
  • SGLANG
  • LLAMA_CPP, LLAMACPP, LLAMA_CPP_PYTHON

STATEK also includes separate adapters for APIs that do not use the OpenAI chat-completions shape:

  • VERTEXAI: Vertex AI Gemini GenerateContent
  • CLAUDEAI: Anthropic Messages-style requests

The provider factory also accepts these aliases:

  • VERTEX_AI, GOOGLE_VERTEXAI, GOOGLE for the Vertex AI adapter
  • CLAUDE_AI, CLAUDE, ANTHROPIC for the Claude adapter

This is adapter support, not a guarantee that every account, endpoint, model, region, or feature works with no additional setup. Provider-specific credentials and endpoint details still have to match the provider you use.

If your provider is not built in, register it with add_provider(...). See Custom Providers.

Provider Credentials

STATEK loads provider settings from environment variables named by provider:

{PROVIDER}_API_URL=...
{PROVIDER}_API_KEY=...

Examples:

OPENROUTER_API_URL=https://openrouter.ai/api/v1
OPENROUTER_API_KEY=...
 
OPENAI_API_URL=https://api.openai.com/v1
OPENAI_API_KEY=...
 
VERTEXAI_API_URL=https://aiplatform.googleapis.com/v1
VERTEXAI_API_KEY=...
 
CLAUDEAI_API_URL=https://api.anthropic.com/v1/messages
CLAUDEAI_API_KEY=...

Provider settings are created when both API URL and API key are present.

Optional provider fields use the same prefix:

OPENAI_RESPONSE_FORMAT_FILE=./response-format.json
CLAUDEAI_USE_PROMPT_CACHING=true

RESPONSE_FORMAT_FILE points to a JSON response-format schema. USE_PROMPT_CACHING is used by Claude-style provider code when prompt caching is enabled.

Default Provider

default_llm_api_provider defaults to OPENROUTER.

You can override it in Python:

from statek.settings import StatekSettings
 
settings = StatekSettings(default_llm_api_provider="OPENAI")

or through your application settings flow. The default provider is only a fallback. Job and model metadata can override it.

Provider Selection Order

Provider selection is resolved in this order:

  1. A provider embedded in the MODEL string wins.
  2. Frozen job metadata PROVIDER wins over the loop/default provider.
  3. An explicit loop provider is used only when job metadata has no provider.
  4. default_llm_api_provider is the final fallback.

For example:

# MODEL: openrouter/openai/gpt-5-mini
# PROVIDER: OPENAI

The embedded openrouter provider wins over PROVIDER: OPENAI.

This matters because JobDef metadata is frozen. If an agent's metadata changes later, existing jobs keep the provider and model configuration captured when their job definition was created.

Model Strings

STATEK parses model strings in these shapes:

model
model_family/model
provider/model_family/model

Examples:

# MODEL: gpt-5-mini
# PROVIDER: OPENAI
# MODEL: openai/gpt-5-mini
# PROVIDER: OPENROUTER
# MODEL: openrouter/openai/gpt-5-mini

For OpenRouter, when a model family is present, STATEK sends model_family/model upstream. For providers that do not require a model family, STATEK sends the model component.

Inline Python metadata uses the same strings:

agent = Agent(
    role="analyst",
    _system_prompt=system_prompt,
    _tools=[],
    _metadata={"MODEL": "openrouter/openai/gpt-5-mini"},
)

In larger applications, model and provider metadata usually live in prompt .md files:

# MODEL: openrouter/openai/gpt-5-mini
# CHAT_STYLE: DIRECT
 
# System Prompt
Analyze the Python objects in context.

OpenAI-Compatible APIs

The OpenAI-compatible adapters use a chat-completions request shape.

The request includes:

  • model
  • messages
  • optional formal tools
  • optional response_format
  • optional temperature
  • optional reasoning

Tool calls use the OpenAI function format. STATEK parses those provider tool calls into internal call specs and then executes the corresponding Python tools.

The default OpenAI-compatible implementation also accepts extra provider kwargs. Registered custom providers can use this to pass provider-specific payload fields without forking STATEK.

Vertex AI Gemini

The Vertex AI adapter builds Gemini GenerateContent requests.

It uses:

  • contents
  • optional systemInstruction
  • optional Gemini function declarations for tools
  • optional generationConfig

The adapter supports URL construction from project, location, and optional publisher kwargs, or a URL that already contains the full model resource. Authentication is sent either as a bearer token or, when configured with auth="api_key", as x-goog-api-key.

Keep Vertex setup explicit in application configuration because project, region, endpoint, and authentication mode are deployment-specific.

Claude and Anthropic-Style APIs

The Claude adapter builds Anthropic Messages API requests.

It uses:

  • model
  • messages
  • max_tokens
  • optional top-level system
  • optional Anthropic-style tools
  • optional temperature
  • optional thinking

Tool calls use tool_use and tool_result blocks. STATEK normalizes those into internal call specs.

When prompt caching is enabled, the Claude adapter adds cache-control blocks and the Anthropic beta header used by that implementation.

Tool Call Differences

Providers do not use identical tool-call JSON.

STATEK normalizes these shapes:

  • OpenAI/OpenRouter: function tool calls
  • Claude: tool_use and tool_result
  • Vertex AI: functionCall and functionResponse

Your application tools are still Python callables. Provider-specific tool JSON is an adapter concern.

Not every model supports tool calling, response formats, reasoning, or the same context limits. Choose models that support the features your agent needs. When a model can write Python but does not support reliable formal tool calling, Chat Styles explains how MARKDOWN can still let it submit executable Python blocks inside a durable STATEK job.

Usage and Cost

STATEK records usage per job where provider data is available:

  • bytes sent
  • bytes received
  • input tokens
  • output tokens
  • cached input tokens
  • provider-reported cost, when the provider response includes it

STATEK can also calculate cost from model pricing files loaded through STATEK_MODEL_INFO_DIR.

See STATEK Metering for pricing table format, job.usage fields, calculated versus provider-reported cost, and the difference between provider billing tokens and byte-based harness limits.

Practical Setup

A minimal OpenRouter setup:

STATEK_PROMPT_FILES_DIR=./prompts
 
OPENROUTER_API_URL=https://openrouter.ai/api/v1
OPENROUTER_API_KEY=...

Prompt metadata:

# MODEL: openai/gpt-5-mini
 
# System Prompt
You write Python against the objects available in context.

A minimal OpenAI-compatible setup:

OPENAI_API_URL=https://api.openai.com/v1
OPENAI_API_KEY=...

Prompt metadata:

# MODEL: gpt-5-mini
# PROVIDER: OPENAI
 
# System Prompt
You write Python against the objects available in context.

Caveats

Provider setup does not decide what Python code an agent can run. That is controlled by STATEK restricted mode, your application context, tools, permissions, process isolation, and deployment environment.

Do not place provider keys in agent-accessible Python locals. Keep credentials in settings, environment variables, or managed secret systems used by trusted application code.

⚠️

Provider configuration does not provide tenant isolation, data-residency guarantees, secrets management, process isolation, or side-effect safety. Treat provider credentials as production secrets and keep privileged adapters out of agent-visible context. See Security for credential boundaries.

Where to go next

Read Custom Providers for provider registration, Chat Styles for tool-call compatibility, Configuration for environment variables, and API Reference for provider settings types.

Harness PoliciesMetering