Engines & Providers

February 23, 2026 · View on GitHub

ProbeAgent supports multiple AI providers and execution engines. This document covers provider configuration, model selection, and multi-provider strategies.

TL;DR

// Auto-detect provider from environment
const agent = new ProbeAgent({ path: './src' });

// Explicit provider
const agent = new ProbeAgent({
  path: './src',
  provider: 'anthropic',
  model: 'claude-sonnet-4-6'
});

Supported Providers

API-Based Providers

Provider	Environment Variable	Default Model
Anthropic	`ANTHROPIC_API_KEY`	`claude-sonnet-4-6`
OpenAI	`OPENAI_API_KEY`	`gpt-5.2`
Google	`GOOGLE_GENERATIVE_AI_API_KEY`	`gemini-2.5-flash`
AWS Bedrock	AWS credentials	`anthropic.claude-sonnet-4-6`

CLI-Based Providers

Provider	Requirement	Description
Claude Code	`claude` CLI installed	Uses Claude Code's built-in access
Codex	`codex` CLI installed	Uses Codex CLI

Provider Configuration

Anthropic Claude

export ANTHROPIC_API_KEY=sk-ant-...

const agent = new ProbeAgent({
  path: './src',
  provider: 'anthropic',
  model: 'claude-sonnet-4-6'  // Optional
});

Available Models:

claude-sonnet-4-6 (default)
claude-opus-4-20250514
claude-3-haiku-20240307

OpenAI

export OPENAI_API_KEY=sk-...

const agent = new ProbeAgent({
  path: './src',
  provider: 'openai',
  model: 'gpt-5.2'  // Optional
});

Available Models:

gpt-5.2 (default)
gpt-5.2-mini
gpt-4-turbo

Google Gemini

export GOOGLE_GENERATIVE_AI_API_KEY=...

const agent = new ProbeAgent({
  path: './src',
  provider: 'google',
  model: 'gemini-2.5-flash'  // Optional
});

Available Models:

gemini-2.5-flash (default)
gemini-1.5-pro
gemini-1.5-flash

AWS Bedrock

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1
# Optional: export AWS_SESSION_TOKEN=...

const agent = new ProbeAgent({
  path: './src',
  provider: 'bedrock',
  model: 'anthropic.claude-sonnet-4-6'  // Optional
});

Claude Code (CLI)

Requires claude CLI to be installed and authenticated:

# Verify installation
which claude
claude --version

const agent = new ProbeAgent({
  path: './src',
  provider: 'claude-code'
});

Codex (CLI)

Requires codex CLI to be installed:

which codex

const agent = new ProbeAgent({
  path: './src',
  provider: 'codex'
});

Auto-Detection

If no provider is specified, ProbeAgent auto-detects based on available credentials:

Priority Order:

Claude Code CLI (if claude command exists)
Codex CLI (if codex command exists)
Anthropic (if ANTHROPIC_API_KEY set)
OpenAI (if OPENAI_API_KEY set)
Google (if GOOGLE_GENERATIVE_AI_API_KEY set)
Bedrock (if AWS credentials set)

// Auto-detect best available provider
const agent = new ProbeAgent({ path: './src' });
await agent.initialize();

console.log(`Using: ${agent.clientApiProvider}`);
console.log(`Model: ${agent.model}`);

Custom API Endpoints

Override default API endpoints for self-hosted or proxy setups:

# Generic endpoint (applies to all)
export LLM_BASE_URL=https://your-proxy.com

# Provider-specific (overrides generic)
export ANTHROPIC_API_URL=https://your-anthropic-proxy.com
export OPENAI_API_URL=https://your-openai-proxy.com
export GOOGLE_API_URL=https://your-google-proxy.com

Retry Configuration

Configure automatic retry for transient failures:

const agent = new ProbeAgent({
  path: './src',
  retry: {
    maxRetries: 3,           // Number of retry attempts
    initialDelay: 1000,      // First retry delay (ms)
    maxDelay: 30000,         // Maximum delay (ms)
    backoffFactor: 2,        // Exponential backoff multiplier
    jitter: true             // Add random jitter
  }
});

Retryable Errors:

Rate limiting (429)
Server errors (500, 502, 503, 504)
Timeout errors
Connection errors (ECONNRESET, ETIMEDOUT, ENOTFOUND)
API overload errors

Fallback Configuration

Configure automatic fallback to alternative providers:

Strategy: Any Available

Try any available provider on failure:

const agent = new ProbeAgent({
  path: './src',
  provider: 'anthropic',
  fallback: {
    strategy: 'any'
  }
});

Strategy: Same Model

Try the same model on different providers:

const agent = new ProbeAgent({
  path: './src',
  provider: 'anthropic',
  fallback: {
    strategy: 'same-model',
    models: ['claude-sonnet-4-6']
  }
});

Strategy: Same Provider

Try different models on the same provider:

const agent = new ProbeAgent({
  path: './src',
  provider: 'anthropic',
  fallback: {
    strategy: 'same-provider',
    models: ['claude-sonnet-4-6', 'claude-3-haiku-20240307']
  }
});

Strategy: Custom

Define exact fallback sequence:

const agent = new ProbeAgent({
  path: './src',
  fallback: {
    strategy: 'custom',
    providers: [
      { provider: 'anthropic', model: 'claude-sonnet-4-6' },
      { provider: 'openai', model: 'gpt-5.2' },
      { provider: 'google', model: 'gemini-2.5-flash' }
    ],
    stopOnSuccess: true,
    maxTotalAttempts: 10
  }
});

Fallback Options

Option	Type	Default	Description
`strategy`	string	-	`'any'`, `'same-model'`, `'same-provider'`, `'custom'`
`models`	string[]	-	Models for same-provider/same-model
`providers`	ProviderConfig[]	-	Custom provider list
`stopOnSuccess`	boolean	true	Stop after first success
`continueOnNonRetryableError`	boolean	false	Try fallback on non-retryable errors
`maxTotalAttempts`	number	10	Max total attempts across all providers
`debug`	boolean	false	Enable debug logging

Combined Retry + Fallback

Use both for maximum resilience:

const agent = new ProbeAgent({
  path: './src',
  provider: 'anthropic',
  retry: {
    maxRetries: 3,
    initialDelay: 1000,
    backoffFactor: 2
  },
  fallback: {
    strategy: 'any',
    stopOnSuccess: true
  }
});

Execution Order:

Try primary provider
Retry up to maxRetries on transient errors
On persistent failure, try next fallback provider
Repeat retry logic for each fallback
Fail if all providers exhausted

Timeout Configuration

const agent = new ProbeAgent({
  path: './src',
  requestTimeout: 120000,       // Per-request timeout (ms)
  maxOperationTimeout: 300000   // Total operation timeout (ms)
});

Environment Variable:

ENGINE_ACTIVITY_TIMEOUT=180000  # 3 minutes (range: 5s - 10min)

Engine Statistics

Access retry and fallback statistics:

// After operations
const usage = agent.getTokenUsage();
console.log('Provider:', agent.clientApiProvider);
console.log('Model:', agent.model);
console.log('Total tokens:', usage.total.total);

Provider Comparison

Feature	Anthropic	OpenAI	Google	Bedrock
Streaming	✓	✓	✓	✓
Tool Use	✓	✓	✓	✓
Vision	✓	✓	✓	✓
Caching	✓	✓	Varies	✓
Max Context	200K	128K	1M+	200K

Best Practices

1. Use Fallback for Production

const agent = new ProbeAgent({
  provider: 'anthropic',
  retry: { maxRetries: 3 },
  fallback: { strategy: 'any' }
});

2. Match Model to Task

// Complex analysis: use capable model
const analyzerAgent = new ProbeAgent({
  provider: 'anthropic',
  model: 'claude-sonnet-4-6'
});

// Simple queries: use fast model
const queryAgent = new ProbeAgent({
  provider: 'anthropic',
  model: 'claude-3-haiku-20240307'
});

3. Monitor Provider Usage

agent.events.on('toolCall', (event) => {
  if (event.name === 'ai_request') {
    console.log(`Provider: ${agent.clientApiProvider}`);
  }
});

Retry & Fallback - Detailed retry/fallback guide
API Reference - Full configuration options
Troubleshooting - Provider issues