Skip to main content

​
Overview

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

​
Supported Providers

Anthropic

Claude models (Opus, Sonnet, Haiku) Supports OAuth and API keys

OpenAI

GPT models including GPT-5, GPT-4, GPT-4o Supports OAuth and API keys

OpenRouter

Access to 100+ models via unified API API key authentication

​
Authentication Methods

The simplest way to authenticate: 
# Interactive menu
agentuse auth login

# Or login to specific provider
agentuse auth login anthropic
agentuse auth login openai
agentuse auth login openrouter

​
2. Environment Variables

Set API keys as environment variables: 
# 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-..."

​
3. Configuration File

Create a .env file in your project: 
# .env
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-proj-...
OPENROUTER_API_KEY=sk-or-v1-...

​
Advanced Environment Variable Configuration

AgentUse supports flexible environment variable patterns for multiple API keys: 
# 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

# Then specify in model string
agentuse run agent.md --model anthropic:claude-sonnet-4-5:dev
agentuse run agent.md --model openai:gpt-5.2:OPENAI_API_KEY_PERSONAL
Never commit .env files to version control! Add to .gitignore:
.env
.env.local
.env.*.local

​
Managing Credentials

​
List Stored Credentials

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

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

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

​
Remove Credentials

# Remove specific provider
agentuse auth logout anthropic

# Remove all credentials
agentuse auth logout

​
Rotate API Keys

# Logout and login again
agentuse auth logout openai
agentuse auth login openai

​
Getting API Keys

Get API keys from provider consoles:
Keys are shown only once. Store them securely and never commit to version control.

​
Authentication Priority Order

AgentUse checks authentication sources in this order:
  1. OAuth tokens - Checked first and refreshed automatically
  2. Stored API keys (via agentuse auth login) - Stored in ~/.local/share/agentuse/auth.json
  3. Environment variables - ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_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: 
agentuse run agent.agentuse --model anthropic:claude-haiku-4-5
agentuse run agent.agentuse -m openai:gpt-5-mini

CLI Commands - Model Override

See the complete reference for model override format, environment-specific keys, CI/CD examples, and sub-agent inheritance behavior.

​
Multi-Provider Setup

Use different providers for different agents: 
---
name: fast-agent
model: anthropic:claude-haiku-4-5  # Uses Anthropic
---

---
name: powerful-agent
model: openai:gpt-5  # Uses OpenAI GPT-5
openai:
  reasoningEffort: high    # More thorough reasoning
  textVerbosity: medium    # Balanced response length
---

---
name: specialized-agent
model: openrouter:z-ai/glm-4.7  # Uses OpenRouter
---

​
Provider Options

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

​
OpenAI Provider Options

For OpenAI models (especially GPT-5), you can control reasoning and verbosity: 
---
model: openai:gpt-5
openai:
  reasoningEffort: high  # Options: 'low', 'medium', 'high'
  textVerbosity: low     # Options: 'low', 'medium', 'high'
---
reasoningEffort: Controls computational effort for reasoning
  • low: Faster responses with less thorough reasoning
  • medium: Balanced performance (default)
  • high: More comprehensive reasoning, slower responses
textVerbosity: Controls response length and detail
  • low: Concise, minimal prose
  • medium: Balanced detail (default)
  • high: Verbose, detailed explanations
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

​
Troubleshooting

  • Verify API key is correct
  • Check key hasn’t expired
  • Ensure key has required permissions
  • Try logging out and back in
  • Check your API tier and limits
  • Implement exponential backoff
  • Consider upgrading your plan
  • Use different keys for different projects

​
CI/CD Authentication

For automated environments:

​
GitHub Actions

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 }}

​
Docker

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}
CMD ["agentuse", "run", "agent.agentuse"]

​
Next Steps

Quick Start

Start using your authenticated providers

Creating Agents

Build agents with your providers