# Model provider

Canonical: https://auggy.dev/docs/engines
Status: Published
Package: auggy 0.5.0

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.

> **Note: 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.

Credential: `ANTHROPIC_API_KEY`

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

### OpenAI

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

Credential: `OPENAI_API_KEY`

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

### OpenRouter

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

Credential: `OPENROUTER_API_KEY`

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

### Ollama

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

Credential: `No key required locally`

```yaml
engine:
  provider: ollama
  model: llama3.2
```

## 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.yaml**

```yaml
engine:
  provider: anthropic
  model: claude-sonnet-4-6
  maxContextTokens: 200000
  maxTokens: 4096
```

**Hosted provider key**

```env
ANTHROPIC_API_KEY=sk-ant-...
```

## Model-provider fields

| Field | Applies to | Use |
| --- | --- | --- |
| provider | All providers | Required. One of anthropic, openai, openrouter, or ollama. |
| model | All providers | Required. Provider-specific model identifier. |
| maxContextTokens | All providers | Maximum context window **Auggy** should plan around. |
| maxTokens | All providers | Maximum output tokens per turn; OpenAI and OpenRouter receive it as `max_completion_tokens`. |
| baseURL | Anthropic, OpenAI, Ollama | Optional proxy, gateway, or remote Ollama base URL. OpenRouter is hardcoded to OpenRouter. |
| reasoningEffort | OpenAI, OpenRouter | Optional reasoning setting: none, minimal, low, medium, high, or xhigh. Unsupported models may reject it upstream. |
| providerRouting | OpenRouter only | Provider allow/deny, sort, and `max_price` routing hints forwarded to OpenRouter. |
| costOverride | Hosted pricing/cost estimation | Override USD-per-million-token rates for unknown models or custom pricing. |
| keepAlive | Ollama only | How long Ollama keeps the model loaded after a request. |
| options | Ollama only | Native Ollama generation options such as temperature, `top_k`, `top_p`, seed, `repeat_penalty`, or mirostat. |

> **Warning: 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 routing**

```yaml
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 options**

```yaml
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.yaml: Selects the provider, model, token limits, and provider-specific options.
2. .env: Supplies the credential required by the selected hosted provider.
3. CLI: Validates field shapes and rejects provider-specific options on incompatible providers.
4. Runtime: Loads the provider adapter and exposes one model-client interface to the kernel.
5. Provider: Performs 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

| Symptom | Check |
| --- | --- |
| Missing credential | Set the key for the selected provider in .env and restart the runtime. |
| Unknown model | Use a model identifier accepted by that provider; model availability changes independently of **Auggy**. |
| Context overflow | Set maxContextTokens to the real model window and keep maxTokens within provider limits. |
| Rejected reasoning option | Remove reasoningEffort or choose a model that supports the requested setting. |
| OpenRouter routing failure | Check provider names, allow/deny lists, and `max_price` values. |
| Ollama connection failure | Start 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 agent](https://auggy.dev/docs/quickstart/markdown)
- [agent.yaml](https://auggy.dev/docs/agent-yaml/markdown)