Hyperterse — Agentic server framework.

Hyperterse resolves model providers per agent from model.provider, model.model, and model.options.

Provider matrix

Provider value	Backend
`gemini`, `google_ai_studio`	Gemini via Google AI Studio
`vertex`, `vertex_ai`	Gemini via Vertex AI
`openai_compatible`, `openai`	OpenAI-compatible `/chat/completions` endpoint

When an agent loads, Hyperterse normalizes provider values (lowercased; - becomes _).

Option keys and env behavior

Key	Used by	Behavior / fallback
`api_key`	Gemini, Vertex, OpenAI-compatible	Inline key value. Supports `{{ env.VAR_NAME }}` substitution. If unset, Hyperterse falls back to each provider’s default env var.
`base_url`	OpenAI-compatible	Base URL; defaults to `https://api.openai.com/v1` when unset.
`project`	Vertex	Vertex project id; fallback `GOOGLE_CLOUD_PROJECT`.
`location`	Vertex	Vertex location; fallback `GOOGLE_CLOUD_LOCATION`, then `GOOGLE_CLOUD_REGION`.

Model option string values support {{ env.VAR_NAME }} substitution when the agent model is initialized.

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

Other popular providers

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.

Provider	Status
OpenAI Platform	Direct
OpenRouter	Direct
Together AI	Direct
Groq	Direct
Fireworks AI	Direct
DeepSeek	Direct
Mistral	Direct
Perplexity	Direct
xAI	Direct
LiteLLM gateway	Direct
Azure OpenAI	Indirect
Anthropic	Indirect
Gemini / Vertex	Indirect

OpenAI compatibility

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

Accepted provider identifiers

After normalization (lowercase, with - converted to _), Hyperterse 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

OpenRouter with a free model

model:
  provider: openai_compatible
  model: openai/gpt-oss-20b:free
  options:
    base_url: https://openrouter.ai/api/v1
    api_key: '{{ env.OPENROUTER_API_KEY }}'

Recommended patterns

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.

​Provider matrix

​Option keys and env behavior

​Gemini (Google AI Studio)

​Vertex AI

​OpenAI-compatible

​Other popular providers

​OpenAI compatibility

​Accepted provider identifiers

​Required protocol contract

​Direct vs indirect usage

​Production-safe examples

​Gemini with env-managed key

​Vertex with explicit project/location

​OpenAI-compatible with custom gateway

​OpenRouter with a free model

​Recommended patterns

Provider matrix

Option keys and env behavior

Gemini (Google AI Studio)

Vertex AI

OpenAI-compatible

Other popular providers

OpenAI compatibility

Accepted provider identifiers

Required protocol contract

Direct vs indirect usage

Production-safe examples

Gemini with env-managed key

Vertex with explicit project/location

OpenAI-compatible with custom gateway

OpenRouter with a free model

Recommended patterns