Skip to main content
Hyperterse resolves model providers per agent from model.provider, model.model, and model.options.

​
Provider matrix

Provider valueRuntime target
gemini, google_ai_studioGemini via Google AI Studio
vertex, vertex_aiGemini via Vertex AI
openai_compatible, openaiOpenAI-compatible /chat/completions endpoint
Provider values are normalized at runtime (lowercased; - converted to _).

​
Option keys and env behavior

KeyUsed byBehavior / fallback
api_keyGemini, Vertex, OpenAI-compatibleInline key value. Supports {{ env.VAR_NAME }} substitution. If unset, runtime falls back to provider default env var.
base_urlOpenAI-compatibleBase URL; defaults to https://api.openai.com/v1 when unset.
projectVertexVertex project id; fallback GOOGLE_CLOUD_PROJECT.
locationVertexVertex location; fallback GOOGLE_CLOUD_LOCATION, then GOOGLE_CLOUD_REGION.
Model option string values support {{ env.VAR_NAME }} substitution at runtime model initialization.

​
Gemini (Google AI Studio)

model:
  provider: gemini
  model: gemini-2.5-flash
Supported auth options:
  • api_key (inline or {{ env.VAR_NAME }} substitution)
  • fallback env: GOOGLE_API_KEY (recommended)

​
Vertex AI

model:
  provider: vertex_ai
  model: gemini-2.5-pro
  options:
    project: my-gcp-project
    location: us-central1
Resolution behavior:
  • project option or env GOOGLE_CLOUD_PROJECT
  • location option or env GOOGLE_CLOUD_LOCATION, fallback GOOGLE_CLOUD_REGION
  • optional api_key support, fallback GOOGLE_API_KEY

​
OpenAI-compatible

model:
  provider: openai_compatible
  model: gpt-4o-mini
  options:
    base_url: https://api.openai.com/v1
    api_key: '{{ env.OPENAI_API_KEY }}'
Resolution behavior:
  • base_url defaults to https://api.openai.com/v1
  • key from api_key, fallback OPENAI_API_KEY
Direct means you can use openai_compatible with that provider’s OpenAI-compatible endpoint directly. Indirect means you should put a compatibility gateway in front first.
For production, run a quick smoke test with your exact model and one tool call before rollout.
ProviderStatus
OpenAI PlatformDirect
OpenRouterDirect
Together AIDirect
GroqDirect
Fireworks AIDirect
DeepSeekDirect
MistralDirect
PerplexityDirect
xAIDirect
LiteLLM gatewayDirect
Azure OpenAIIndirect
AnthropicIndirect
Gemini / VertexIndirect

​
OpenAI compatibility

openai_compatible is defined by protocol behavior, not by vendor name.

​
Accepted provider identifiers

After normalization (lowercase, with - converted to _), runtime accepts:
  • openai_compatible (canonical)
  • openai (alias)

​
Required protocol contract

For direct integration, the target endpoint must support:
  • POST {base_url}/chat/completions
  • Authorization: Bearer <token>
  • OpenAI-compatible request/response payloads
  • OpenAI-compatible tool-call payloads when tools are enabled

​
Direct vs indirect usage

Use openai_compatible directly only when the contract above is satisfied. Use a compatibility gateway when any of these differ:
  • endpoint path
  • auth mechanism (for example non-Bearer or required custom headers)
  • payload/response/tool-call schema

​
Production-safe examples

​
Gemini with env-managed key

model:
  provider: gemini
  model: gemini-2.5-flash

​
Vertex with explicit project/location

model:
  provider: vertex_ai
  model: gemini-2.5-pro
  options:
    project: my-gcp-project
    location: us-central1

​
OpenAI-compatible with custom gateway

model:
  provider: openai_compatible
  model: gpt-4o-mini
  options:
    base_url: https://my-gateway.example.com/v1
  • Keep secrets in provider default env vars (OPENAI_API_KEY, GOOGLE_API_KEY) instead of inline literals.
  • Pin model values deliberately per agent role (cheap vs reasoning-heavy).
  • Add one agent per workflow role rather than reusing a single all-purpose prompt.
Avoid committing inline api_key values to source control. Prefer provider default env vars and managed secret injection in deployment.
For full agent shape, see Agent configuration reference and Quickstart.