AgentUse - AI Agents as Simple as Markdown

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, GPT-3.5 API key authentication

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

Anthropic supports OAuth login for both Claude Max and Console users - no API key needed!

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-3-sonnet:dev
agentuse run agent.md --model openai:gpt-4: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-3-5-sonnet-20241022
  🎫 openai (api) → Use as: openai:gpt-4-turbo

Environment variables:
  🌍 openrouter (OPENROUTER_API_KEY) → Use as: openrouter:qwen/qwen-2.5-72b-instruct

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

OAuth Authentication (Anthropic)

Both Claude Max and Console users can use OAuth for seamless authentication:

Run OAuth Login

agentuse auth login anthropic

Select from:

Claude Pro/Max Plan (OAuth) - For claude.ai users
Anthropic Console (OAuth) - For console.anthropic.com users
Manual API Key - Traditional API key method

Authorization URL

Copy the authorization URL shown in terminal and visit in your browser

Authorize

Copy Code

Copy the authorization code from the browser

Paste Code

Paste the code in terminal - you’re authenticated!

OAuth Benefits

No API key management required
Automatic token refresh
Secure PKCE authentication flow
Works with both Claude Max and Console accounts
Tokens stored securely in ~/.local/share/agentuse/auth.json with restricted permissions

API Key Authentication

Getting API Keys

Anthropic
OpenAI
OpenRouter

Go to console.anthropic.com
Navigate to API Keys
Click Create Key
Name your key (e.g., “AgentUse”)
Copy the key (starts with sk-ant-api03-)

Keys are shown only once. Store them securely!

Authentication Priority Order

AgentUse checks authentication sources in this order:

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

Security Best Practices

Use OAuth When Possible

OAuth is more secure than API keys as tokens can be revoked and rotated automatically. AgentUse uses PKCE flow for enhanced security.

Secure File Storage

Stored credentials in ~/.local/share/agentuse/auth.json are automatically set to user read/write only (0600 permissions).

Rotate Keys Regularly

Change API keys every 90 days or immediately if compromised.

Limit Key Permissions

Create keys with minimal required permissions.

Use Environment Variables

Never hardcode keys in your agent files or code.

Monitor Usage

Regularly check API usage to detect unusual activity.

Runtime Model Override

You can override the model specified in an agent file at runtime using the --model flag. This is especially useful for:

Testing: Compare how different models handle the same task
Cost Optimization: Use cheaper models during development
Environment-Specific Deployment: Different models for dev/staging/prod
Quick Experimentation: Try new models without editing files

Basic Usage

# Original agent uses claude-3-5-sonnet
agentuse run agent.agentuse --model anthropic:claude-3-5-haiku-latest

# Switch to OpenAI for comparison
agentuse run agent.agentuse --model openai:gpt-4o

# Use a faster model for development
agentuse run agent.agentuse -m openai:gpt-5-mini

Environment-Specific Keys

Combine model override with environment suffixes:

# Development environment
agentuse run agent.agentuse --model openai:gpt-4o:dev
# Uses OPENAI_API_KEY_DEV

# Production environment
agentuse run agent.agentuse --model openai:gpt-5:prod
# Uses OPENAI_API_KEY_PROD

# Personal projects
agentuse run agent.agentuse --model anthropic:claude-3-5-sonnet:ANTHROPIC_API_KEY_PERSONAL
# Uses specific environment variable

CI/CD Examples

# GitHub Actions - different models per environment
- name: Run agent (Development)
  run: agentuse run agent.agentuse --model anthropic:claude-3-5-haiku-latest
  if: github.ref != 'refs/heads/main'

- name: Run agent (Production)
  run: agentuse run agent.agentuse --model anthropic:claude-3-5-sonnet-20241022
  if: github.ref == 'refs/heads/main'

# Shell script for model comparison
for model in "anthropic:claude-3-5-haiku-latest" "openai:gpt-4o" "openai:gpt-5-mini"; do
  echo "Testing with $model"
  agentuse run benchmark.agentuse --model "$model" > "results_${model//:/\_}.txt"
done

When overriding to a different provider, provider-specific options (like OpenAI’s reasoningEffort) from the original agent file will be ignored.

Sub-Agent Model Inheritance

When using the --model flag with agents that have sub-agents:

Complete Override: The model override applies to the parent AND all sub-agents
Uniform Execution: All agents in the hierarchy will use the same model
Authentication: Ensures consistent authentication across all agents

# Parent agent configured with claude-sonnet-4-0
# Sub-agents configured with various models
agentuse run orchestrator.agentuse --model openai:gpt-5-mini

# Result: ALL agents (parent + sub-agents) use gpt-5-mini

This behavior ensures:

Consistent performance across the entire agent hierarchy
Simplified testing with different model configurations
Cost control when switching between expensive and cheap models
No authentication conflicts between parent and sub-agents

Multi-Provider Setup

Use different providers for different agents:

---
name: fast-agent
model: anthropic:claude-3-5-haiku-20241022  # 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:qwen/qwen-2.5-coder-32b-instruct  # 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

Authentication failed

Verify API key is correct
Check key hasn’t expired
Ensure key has required permissions
Try logging out and back in

Rate limiting

Check your API tier and limits
Implement exponential backoff
Consider upgrading your plan
Use different keys for different projects

OAuth issues

Clear browser cookies
Try a different browser
Ensure you’re using the correct OAuth mode (Max vs Console)
Check that your Claude subscription is active (for Max mode)
Verify you have console access (for Console mode)
Try manual API key authentication as fallback

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"]

Getting Started

Guides

Reference

Model Configuration

Overview

Supported Providers

Anthropic

OpenAI

OpenRouter

Authentication Methods

2. Environment Variables

3. Configuration File

Advanced Environment Variable Configuration

Managing Credentials

List Stored Credentials

Remove Credentials

Rotate API Keys

OAuth Authentication (Anthropic)

OAuth Benefits

API Key Authentication

Getting API Keys

Authentication Priority Order

Security Best Practices

Runtime Model Override

Basic Usage

Environment-Specific Keys

CI/CD Examples

Sub-Agent Model Inheritance

Multi-Provider Setup

Provider Options

OpenAI Provider Options

Troubleshooting

CI/CD Authentication

GitHub Actions

Docker

Next Steps

Quick Start

Creating Agents

Getting Started

Guides

Reference

​Overview

​Supported Providers

Anthropic

OpenAI

OpenRouter

​Authentication Methods

​1. Interactive Login (Recommended)

​2. Environment Variables

​3. Configuration File

​Advanced Environment Variable Configuration

​Managing Credentials

​List Stored Credentials

​Remove Credentials

​Rotate API Keys

​OAuth Authentication (Anthropic)

​OAuth Benefits

​API Key Authentication

​Getting API Keys

​Authentication Priority Order

​Security Best Practices

​Runtime Model Override

​Basic Usage

​Environment-Specific Keys

​CI/CD Examples

​Sub-Agent Model Inheritance

​Multi-Provider Setup

​Provider Options

​OpenAI Provider Options

​Troubleshooting

​CI/CD Authentication

​GitHub Actions

​Docker

​Next Steps

Quick Start

Creating Agents

Overview

Supported Providers

Authentication Methods

1. Interactive Login (Recommended)

2. Environment Variables

3. Configuration File

Advanced Environment Variable Configuration

Managing Credentials

List Stored Credentials

Remove Credentials

Rotate API Keys

OAuth Authentication (Anthropic)

OAuth Benefits

API Key Authentication

Getting API Keys

Authentication Priority Order

Security Best Practices

Runtime Model Override

Basic Usage

Environment-Specific Keys

CI/CD Examples

Sub-Agent Model Inheritance

Multi-Provider Setup

Provider Options

OpenAI Provider Options

Troubleshooting

CI/CD Authentication

GitHub Actions

Docker

Next Steps