> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Configuration

> Configure AI providers and models for your agents

## Overview

AgentUse supports multiple AI providers. You need to authenticate with at least one provider to run agents.

## Supported Providers

<CardGroup cols={2}>
  <Card title="Anthropic">
    Claude models (Opus, Sonnet, Haiku)
    Supports OAuth and API keys
  </Card>

  <Card title="OpenAI">
    GPT models including GPT-5, GPT-4, GPT-4o
    Supports OAuth and API keys
  </Card>

  <Card title="OpenRouter">
    Access to 100+ models via unified API
    API key authentication
  </Card>

  <Card title="OpenCode Go">
    Low-cost open coding models curated by OpenCode
    API key authentication
  </Card>

  <Card title="Amazon Bedrock">
    Claude, Llama, Mistral, Nova and more via AWS
    AWS SigV4 or Bearer token
  </Card>

  <Card title="Custom / Local">
    Any OpenAI-compatible endpoint: Ollama, LM Studio, vLLM, llama.cpp, etc.
  </Card>
</CardGroup>

## Authentication Methods

### 1. Interactive Login (Recommended)

The simplest way to authenticate:

```bash theme={"system"}
# Interactive menu
agentuse provider login

# Or login to specific provider
agentuse provider login anthropic
agentuse provider login openai
agentuse provider login openrouter
agentuse provider login opencode-go
```

### 2. Environment Variables

Set API keys as environment variables:

```bash theme={"system"}
# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export OPENAI_API_KEY="sk-proj-..."
export OPENROUTER_API_KEY="sk-or-v1-..."
export OPENCODE_GO_API_KEY="..."
```

### 3. Configuration File

Create a `.env` file in your project:

```bash theme={"system"}
# .env
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-proj-...
OPENROUTER_API_KEY=sk-or-v1-...
OPENCODE_GO_API_KEY=...
```

### Advanced Environment Variable Configuration

AgentUse supports flexible environment variable patterns for multiple API keys:

```bash theme={"system"}
# Using environment suffixes for different keys
export ANTHROPIC_API_KEY_DEV=sk-ant-api03-dev-key
export ANTHROPIC_API_KEY_PROD=sk-ant-api03-prod-key
export OPENAI_API_KEY_PERSONAL=sk-proj-personal-key
export OPENCODE_GO_API_KEY_TEAM=opencode-go-team-key

# Then specify in model string
agentuse run agent.md --model anthropic:claude-sonnet-5:dev
agentuse run agent.md --model openai:gpt-5.5:OPENAI_API_KEY_PERSONAL
agentuse run agent.md --model opencode-go:kimi-k2.7-code:OPENCODE_GO_API_KEY_TEAM
```

<Warning>
  Never commit `.env` files to version control! Add to `.gitignore`:

  ```
  .env
  .env.local
  .env.*.local
  ```
</Warning>

## OpenCode Go

OpenCode Go provides curated open coding models through a low-cost OpenCode subscription. AgentUse treats it as a built-in provider and automatically routes each model to the correct OpenCode Go API shape.

```bash theme={"system"}
agentuse provider login opencode-go
agentuse run agent.agentuse -m opencode-go:kimi-k2.7-code
agentuse run agent.agentuse -m opencode-go:minimax-m3
agentuse run agent.agentuse -m opencode-go:qwen3.7-plus
```

Or configure it with an environment variable:

```bash theme={"system"}
export OPENCODE_GO_API_KEY="..."
```

<Note>
  OpenCode Go publishes its live model list at `https://opencode.ai/zen/go/v1/models`, so `opencode-go:` model IDs are passed through rather than validated against AgentUse's static model registry.
</Note>

## Amazon Bedrock

Bedrock authenticates with standard AWS credentials rather than `agentuse provider login`. Three modes are supported (in priority order):

**1. Static IAM access keys (SigV4)**

```bash theme={"system"}
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
# Optional, for STS / assumed-role temporary credentials
export AWS_SESSION_TOKEN="..."
```

**2. Bedrock API key (Bearer token)**

```bash theme={"system"}
export AWS_REGION=us-east-1
export AWS_BEARER_TOKEN_BEDROCK="..."
```

**3. AWS SDK credential provider chain** — used automatically when neither of the above is set. Resolves `AWS_PROFILE`, `~/.aws/credentials`, SSO cache, EC2/ECS/EKS instance roles, etc.

```bash theme={"system"}
# Refresh SSO / assume-role credentials for your profile, then run:
export AWS_REGION=eu-west-1
export AWS_PROFILE=my-bedrock-profile
agentuse run agent.agentuse -m bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0
```

Use the full Bedrock model ID (which contains colons) as-is, or an inference profile ARN:

```bash theme={"system"}
agentuse run agent.agentuse -m bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0
agentuse run agent.agentuse -m bedrock:meta.llama3-70b-instruct-v1:0
agentuse run agent.agentuse -m bedrock:arn:aws:bedrock:eu-west-1:123456789012:application-inference-profile/abcd1234
```

<Note>
  Your IAM user/role needs `AmazonBedrockFullAccess` (or an equivalent custom policy) and you must have requested access to the foundation model in the AWS console. The `bedrock:` prefix bypasses the static model registry, so any Bedrock model ID or inference-profile ARN is accepted.
</Note>

## Custom Providers (Local LLMs)

Connect to any OpenAI-compatible endpoint — Ollama, LM Studio, vLLM, llama.cpp, and more.

### Adding a Custom Provider

```bash theme={"system"}
# Ollama (default port 11434)
agentuse provider add ollama --url http://localhost:11434/v1

# LM Studio (default port 1234)
agentuse provider add lmstudio --url http://localhost:1234/v1

# With optional API key
agentuse provider add myserver --url https://my-gpu-server.example.com/v1 --key sk-mykey123
```

### Using Custom Providers

In your agent file:

```yaml theme={"system"}
---
model: ollama:glm-5-flash:q4_K_M
---
```

```yaml theme={"system"}
---
model: lmstudio:qwen/qwen3.5-9b
---
```

Or override at runtime:

```bash theme={"system"}
agentuse run agent.agentuse -m ollama:glm-5-flash:q4_K_M
agentuse run agent.agentuse -m lmstudio:qwen/qwen3.5-9b
```

<Info>
  Custom providers support colons in model names — `ollama:qwen3.5:0.8b` is parsed as provider `ollama`, model `qwen3.5:0.8b`.
</Info>

### Environment Variable Overrides

Custom providers support env var overrides using the uppercased provider name:

```bash theme={"system"}
# Override base URL and API key for a custom provider named "ollama"
export OLLAMA_BASE_URL=http://192.168.1.100:11434/v1
export OLLAMA_API_KEY=sk-optional-key
```

### Managing Custom Providers

```bash theme={"system"}
# List all providers (including custom)
agentuse provider list

# Remove a custom provider
agentuse provider remove ollama
```

<Warning>
  **Local model limitations:**

  * **Quality**: Small models (under 30B parameters) often struggle with complex tool use, multi-step reasoning, and following detailed agent instructions. For best results, use 30B+ parameter models.
  * **Context window**: Ensure your model is loaded with a context size of at least 8192 tokens. AgentUse's system prompts can exceed 4096 tokens.
  * **Tool calling**: Many local models have limited or no native tool/function calling support, which may cause agents with tools to fail or behave unpredictably.
</Warning>

## Managing Credentials

### List Stored Credentials

```bash theme={"system"}
agentuse provider list
```

Output:

```
📁 Credentials stored in: ~/.local/share/agentuse/auth.json

Stored credentials:
  🔑 anthropic (oauth) → Use as: anthropic:claude-sonnet-5
  🎫 openai (api) → Use as: openai:gpt-5.5

Environment variables:
  🌍 openrouter (OPENROUTER_API_KEY) → Use as: openrouter:z-ai/glm-5.2

Custom Providers:
  🔌 ollama → http://localhost:11434/v1
  🔌 lmstudio → http://localhost:1234/v1
```

### Remove Credentials

```bash theme={"system"}
# Remove specific provider
agentuse provider logout anthropic

# Remove a custom provider
agentuse provider remove ollama
```

### Rotate API Keys

```bash theme={"system"}
# Logout and login again
agentuse provider logout openai
agentuse provider login openai
```

## Getting API Keys

Get API keys from provider consoles:

* **Anthropic**: [console.anthropic.com](https://console.anthropic.com) → API Keys → Create Key (starts with `sk-ant-api03-`)
* **OpenAI**: [platform.openai.com](https://platform.openai.com) → API Keys → Create new secret key (starts with `sk-proj-`)
* **OpenRouter**: [openrouter.ai](https://openrouter.ai) → Keys → Create Key (starts with `sk-or-v1-`)
* **OpenCode Go**: [opencode.ai/auth](https://opencode.ai/auth) → Subscribe to Go → Copy API key

<Warning>
  Keys are shown only once. Store them securely and never commit to version control.
</Warning>

## Authentication Priority Order

AgentUse checks authentication sources in this order:

1. **OAuth tokens** - Checked first and refreshed automatically
2. **Stored API keys** (via `agentuse provider login`) - Stored in `~/.local/share/agentuse/auth.json`
3. **Environment variables** - `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `OPENCODE_GO_API_KEY`
4. **Custom environment variables** - Using suffix patterns (e.g., `ANTHROPIC_API_KEY_DEV`) or full variable names

## Runtime Model Override

Override the model at runtime using the `--model` flag:

```bash theme={"system"}
agentuse run agent.agentuse --model anthropic:claude-haiku-4-5
agentuse run agent.agentuse -m openai:gpt-5.4-mini
agentuse run agent.agentuse -m opencode-go:kimi-k2.7-code
```

<Card title="CLI Commands - Model Override" icon="terminal" href="/reference/cli-commands#model-override">
  See the complete reference for model override format, environment-specific keys, CI/CD examples, and sub-agent inheritance behavior.
</Card>

## Multi-Provider Setup

Use different providers for different agents:

```markdown theme={"system"}
---
name: fast-agent
model: anthropic:claude-haiku-4-5  # Uses Anthropic
---
```

```markdown theme={"system"}
---
name: powerful-agent
model: openai:gpt-5.5  # Uses OpenAI GPT-5
openai:
  reasoningEffort: high    # More thorough reasoning
  textVerbosity: medium    # Balanced response length
---
```

```markdown theme={"system"}
---
name: specialized-agent
model: openrouter:z-ai/glm-5.2  # Uses OpenRouter
---
```

```markdown theme={"system"}
---
name: open-coding-agent
model: opencode-go:kimi-k2.7-code  # Uses OpenCode Go
---
```

```markdown theme={"system"}
---
name: local-agent
model: ollama:glm-5-flash:q4_K_M  # Uses local Ollama
---
```

## Provider Options

Configure provider-specific settings for fine-tuned model behavior:

### OpenAI Provider Options

For OpenAI models (especially GPT-5), you can control thinking effort and verbosity:

```yaml theme={"system"}
---
model: openai:gpt-5.5
openai:
  reasoningEffort: high      # Options: 'none', 'minimal', 'low', 'medium', 'high', 'xhigh'
  reasoningSummary: auto     # Options: 'auto', 'detailed' — surface reasoning in the session trace
  textVerbosity: low         # Options: 'low', 'medium', 'high'
  promptCacheRetention: 24h  # Optional: extended prompt caching on supported models
---
```

<Info>
  **reasoningEffort**: Controls thinking effort for reasoning

  * `none`: Disable reasoning when the selected model supports it
  * `minimal`: Use the lightest reasoning mode
  * `low`: Faster responses with less thorough reasoning
  * `medium`: Balanced performance (default)
  * `high`: More comprehensive reasoning, slower responses
  * `xhigh`: Maximum reasoning for models that support it

  **reasoningSummary**: Streams a natural-language summary of the model's reasoning so it appears inline in the session trace (`auto` or `detailed`). On reasoning-capable models this **defaults to `auto`** — the reasoning tokens are billed whether or not you ask for the summary, so surfacing it is near-free. Non-reasoning models (e.g. `gpt-4o`) omit it automatically.

  **textVerbosity**: Controls response length and detail

  * `low`: Concise, minimal prose
  * `medium`: Balanced detail (default)
  * `high`: Verbose, detailed explanations

  **prompt caching**: AgentUse automatically sends a stable OpenAI `promptCacheKey` per agent so repeated runs with the same prompt prefix are easier for OpenAI to route to cache. You usually do not need to configure this. Set `promptCacheRetention: 24h` only when you want extended retention and the selected OpenAI model supports it.
</Info>

<Note>
  If you omit `reasoningEffort`, `textVerbosity`, or `promptCacheRetention`, AgentUse leaves those fields unset and uses the OpenAI/AI SDK defaults. Reasoning effort is typically `medium` on reasoning models. `none`, `xhigh`, and `24h` retention are model-specific OpenAI options; if a model does not support a selected option, OpenAI will reject the request. Whether a reasoning summary actually streams also depends on the effort level and task complexity.
</Note>

### Anthropic Provider Options

For Claude models, you can enable extended thinking so the model's reasoning streams into the session trace:

```yaml theme={"system"}
---
model: anthropic:claude-opus-4-8
anthropic:
  thinking:
    budgetTokens: 4096  # Minimum 1024
---
```

<Warning>
  Extended thinking is **off by default** — an explicit opt-in. Enabling it generates new thinking tokens billed at **output rates**, a real cost increase that scales with the budget (unlike OpenAI's `reasoningSummary`, where the reasoning is billed either way). AgentUse automatically raises `max_tokens` above the budget so Anthropic's `max_tokens > budget` constraint is met and there's headroom for the answer.
</Warning>

These options help you optimize for:

* **Speed vs Quality**: Lower reasoning effort for faster responses
* **Conciseness vs Detail**: Lower verbosity for more direct answers
* **Cost Optimization**: Lower settings reduce token usage
* **Reasoning visibility**: `reasoningSummary` (OpenAI) and `thinking` (Anthropic) surface the model's "why" inline in the session view

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed">
    * Verify API key is correct
    * Check key hasn't expired
    * Ensure key has required permissions
    * Try logging out and back in
  </Accordion>

  <Accordion title="Rate limiting">
    * Check your API tier and limits
    * Implement exponential backoff
    * Consider upgrading your plan
    * Use different keys for different projects
  </Accordion>
</AccordionGroup>

## CI/CD Authentication

For automated environments:

### GitHub Actions

```yaml theme={"system"}
name: Run Agent
on: [push]
jobs:
  agent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: pnpm install -g agentuse
      - run: agentuse run my-agent.agentuse
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          OPENCODE_GO_API_KEY: ${{ secrets.OPENCODE_GO_API_KEY }}
```

### Docker

```dockerfile theme={"system"}
FROM node:20
RUN npm install -g pnpm && pnpm install -g agentuse
ENV ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
ENV OPENAI_API_KEY=${OPENAI_API_KEY}
ENV OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
ENV OPENCODE_GO_API_KEY=${OPENCODE_GO_API_KEY}
CMD ["agentuse", "run", "agent.agentuse"]
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Start using your authenticated providers
  </Card>

  <Card title="Creating Agents" icon="file-pen" href="/guides/creating-agents">
    Build agents with your providers
  </Card>
</CardGroup>