Auggyv0.5.0
PublishedDocs / Runtime

Model provider

Configure the model provider Auggy's kernel calls each turn.

What it configures

Every turn, the kernel calls one configured model provider. The configuration resolves the provider adapter, the model, token limits, and provider-specific options such as routing and cost metadata.

Why the config key is engine

The config resolves a provider adapter package and a model client, not just a model id, then exposes one model-client interface to the kernel. That resolved unit is the engine.

Provider families

Anthropic

Hosted Claude models

Use the native Anthropic adapter for hosted Claude development and production turns.

agent.yaml

engine:
  provider: anthropic
  model: claude-sonnet-4-6

Credential: ANTHROPIC_API_KEY

OpenAI

Hosted OpenAI models

Use the OpenAI adapter with the same kernel and typed-tool contract.

agent.yaml

engine:
  provider: openai
  model: gpt-5.4-mini

Credential: OPENAI_API_KEY

OpenRouter

Routed model access

Use OpenRouter when the selected model should run through its provider-routing service.

agent.yaml

engine:
  provider: openrouter
  model: anthropic/claude-sonnet-4-6

Credential: OPENROUTER_API_KEY

Ollama

Local or remote models

Use a local Ollama runtime for development and private experiments, or configure a remote compatible host.

agent.yaml

engine:
  provider: ollama
  model: llama3.2

Credential: No key required locally

Minimal configuration

Choose the provider during auggy create. After scaffolding, agent.yaml is the source of truth for the provider and model while .env supplies hosted provider credentials.

agent.yamlyaml
engine:
  provider: anthropic
  model: claude-sonnet-4-6
  maxContextTokens: 200000
  maxTokens: 4096
Hosted provider key.env
ANTHROPIC_API_KEY=sk-ant-...

Model-provider fields

FieldApplies toUse
providerAll providersRequired. One of anthropic, openai, openrouter, or ollama.
modelAll providersRequired. Provider-specific model identifier.
maxContextTokensAll providersMaximum context window Auggy should plan around.
maxTokensAll providersMaximum output tokens per turn; OpenAI and OpenRouter receive it as max_completion_tokens.
baseURLAnthropic, OpenAI, OllamaOptional proxy, gateway, or remote Ollama base URL. OpenRouter is hardcoded to OpenRouter.
reasoningEffortOpenAI, OpenRouterOptional reasoning setting: none, minimal, low, medium, high, or xhigh. Unsupported models may reject it upstream.
providerRoutingOpenRouter onlyProvider allow/deny, sort, and max_price routing hints forwarded to OpenRouter.
costOverrideHosted pricing/cost estimationOverride USD-per-million-token rates for unknown models or custom pricing.
keepAliveOllama onlyHow long Ollama keeps the model loaded after a request.
optionsOllama onlyNative Ollama generation options such as temperature, top_k, top_p, seed, repeat_penalty, or mirostat.

No API keys in YAML

Provider API keys stay in .env or provider-owned secret stores. agent.yaml selects the provider and model; it does not store ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, or OLLAMA_API_KEY.

Provider-specific configuration

OpenRouter routingyaml
engine:
  provider: openrouter
  model: anthropic/claude-sonnet-4-6
  maxContextTokens: 200000
  maxTokens: 4096
  reasoningEffort: medium
  providerRouting:
    only: [Anthropic]
    ignore: [SomeProvider]
    sort: price
    max_price:
      prompt: 3
      completion: 15
Ollama local optionsyaml
engine:
  provider: ollama
  model: llama3.2
  baseURL: http://localhost:11434
  maxContextTokens: 8192
  maxTokens: 1024
  keepAlive: 5m
  options:
    temperature: 0.2
    top_p: 0.9
    seed: 42

Resolution and validation

  1. agent.yamlSelects the provider, model, token limits, and provider-specific options.
  2. .envSupplies the credential required by the selected hosted provider.
  3. CLIValidates field shapes and rejects provider-specific options on incompatible providers.
  4. RuntimeLoads the provider adapter and exposes one model-client interface to the kernel.
  5. ProviderPerforms final model-name and option validation when a request is made.

Run auggy doctor after changing engine configuration. It catches local configuration and credential problems; a provider can still reject an unknown model or unsupported option at request time.

Common failures

SymptomCheck
Missing credentialSet the key for the selected provider in .env and restart the runtime.
Unknown modelUse a model identifier accepted by that provider; model availability changes independently of Auggy.
Context overflowSet maxContextTokens to the real model window and keep maxTokens within provider limits.
Rejected reasoning optionRemove reasoningEffort or choose a model that supports the requested setting.
OpenRouter routing failureCheck provider names, allow/deny lists, and max_price values.
Ollama connection failureStart Ollama, confirm baseURL, and verify the model is installed.

Cost and limits

  • Hosted model providers bill through their provider or routing service.
  • maxContextTokens guides context allocation; maxTokens limits requested output. Neither is a provider billing cap.
  • Memory extraction can use model calls in addition to user-facing turns when enabled.
  • Use the budgets augment as a runtime guardrail, but keep provider-side billing alerts and quotas in place.
  • Pin exact Auggy versions and model choices for production work until 1.0.0.

Related

Run an agentCreate a local Auggy agent and complete the first model turn.agent.yamlConfigure identity, engine, and enabled augment order for an agent project.