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

# Multi-Provider Agent

> Build an agent that uses multiple AI providers with unified budget

Build an agent that uses OpenAI, Anthropic, and other providers while maintaining a single unified budget.

## What You'll Build

An agent that:

* Uses OpenAI for fast, cheap tasks
* Uses Anthropic for complex reasoning
* Falls back between providers on errors
* Tracks spend across all providers in one place
* Never exceeds your budget regardless of which provider handles the call

## Why This Matters

Without unified budgeting:

```
OpenAI account: $47.23 this month
Anthropic account: $89.12 this month
Google account: $23.45 this month
Total: $159.80 (discovered during invoice reconciliation)
```

With Saturn:

```
Saturn balance: $200.00
Spent today: $12.34 (across all providers)
Agent cap: $50/day
Status: Within budget
```

One number. One cap. Multiple providers.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      Your Agent                             │
│                                                             │
│  ┌───────────┐  ┌───────────┐  ┌───────────────────────┐   │
│  │   Fast    │  │  Complex  │  │      Fallback         │   │
│  │   Tasks   │  │  Reasoning│  │       Logic           │   │
│  │  (OpenAI) │  │(Anthropic)│  │   (Any available)     │   │
│  └─────┬─────┘  └─────┬─────┘  └───────────┬───────────┘   │
└────────┼──────────────┼────────────────────┼───────────────┘
         │              │                    │
         ▼              ▼                    ▼
┌─────────────────────────────────────────────────────────────┐
│                        Saturn                               │
│              Unified budget across providers                │
│         $50/day cap applies to ALL calls combined           │
└─────────────────────────────────────────────────────────────┘
         │              │                    │
         ▼              ▼                    ▼
    ┌────────┐    ┌──────────┐        ┌──────────┐
    │ OpenAI │    │Anthropic │        │  Google  │
    └────────┘    └──────────┘        └──────────┘
```

## Step 1: Create Agent with Provider-Agnostic Caps

```typescript theme={null}
import { Saturn } from '@saturn-pay/sdk';

const saturn = new Saturn({
  apiKey: process.env.SATURN_KEY,
});

// Caps apply across ALL providers
await saturn.policies.update(agentId, {
  maxPerCallUsdCents: 100,   // $1.00 per call, any provider
  maxPerDayUsdCents: 5000,   // $50.00 per day, total
});
```

## Step 2: Route by Task Type

```typescript theme={null}
interface Task {
  type: 'quick-classification' | 'deep-analysis' | 'general';
  prompt: string;
}

async function processTask(task: Task) {
  if (task.type === 'quick-classification') {
    // Fast, cheap model for simple tasks
    return await saturn.reason({
      prompt: task.prompt,
      provider: 'openai',
      model: 'gpt-4o-mini',
    });
  }

  if (task.type === 'deep-analysis') {
    // Powerful model for complex reasoning
    return await saturn.reason({
      prompt: task.prompt,
      provider: 'anthropic',
      model: 'claude-sonnet-4-20250514',
    });
  }

  // Default: let Saturn choose
  return await saturn.reason({ prompt: task.prompt });
}
```

## Step 3: Implement Fallback with Budget Awareness

```typescript theme={null}
async function reliableReason(prompt: string) {
  const providers = ['anthropic', 'openai', 'google'];

  for (const provider of providers) {
    try {
      const result = await saturn.reason({ prompt, provider });

      console.log(
        `Success via ${provider}: $${(result.metadata.chargedUsdCents / 100).toFixed(2)}`
      );

      return result;

    } catch (err) {
      if (err.code === 'BUDGET_EXCEEDED') {
        // Don't try other providers - budget is budget
        console.log('Budget exhausted. Stopping.');
        throw err;
      }

      if (err.code === 'PROVIDER_UNAVAILABLE') {
        console.log(`${provider} unavailable, trying next...`);
        continue;
      }

      throw err;
    }
  }

  throw new Error('All providers failed');
}
```

<Warning>
  Always check for `BUDGET_EXCEEDED` before falling back. Budget applies across all providers — trying another provider won't help if you're out of budget.
</Warning>

## Step 4: Track Cross-Provider Spend

```typescript theme={null}
async function runWorkload(tasks: Task[]) {
  let totalCost = 0;
  const providerCosts: Record<string, number> = {};

  for (const task of tasks) {
    try {
      const result = await processTask(task);
      const cost = result.metadata.chargedUsdCents;
      const provider = result.metadata.provider;

      totalCost += cost;
      providerCosts[provider] = (providerCosts[provider] || 0) + cost;

    } catch (err) {
      if (err.code === 'BUDGET_EXCEEDED') {
        console.log('Daily budget reached. Partial results available.');
        break;
      }
      throw err;
    }
  }

  // Summary
  console.log(`Total: $${(totalCost / 100).toFixed(2)}`);
  console.log('By provider:');
  for (const [provider, cost] of Object.entries(providerCosts)) {
    console.log(`  ${provider}: $${(cost / 100).toFixed(2)}`);
  }
}
```

## The Fallback Storm Scenario

Without unified budgeting:

```
Primary (OpenAI) fails → Retry with Anthropic
Anthropic fails → Retry with Google
Google fails → Back to OpenAI
Loop continues...
Each "retry" costs money
No unified cap across providers
Wake up to $500 bill across 3 accounts
```

With Saturn:

```
Primary (OpenAI) fails → $0.15
Retry with Anthropic → $0.20
Retry with Google → $0.10
Loop continues...
After $50 total: BUDGET_EXCEEDED
All providers stopped
Damage: $50 (your cap)
```

## Risk Comparison

| Risk               | Without Saturn              | With Saturn         |
| ------------------ | --------------------------- | ------------------- |
| Fallback storm     | Unbounded across providers  | Single cap for all  |
| Provider A outage  | Traffic shifts, costs spike | Same budget applies |
| Cost comparison    | Reconcile 3 invoices        | One dashboard       |
| Budget enforcement | Per-provider, manual        | Automatic, unified  |

## Production Checklist

<Steps>
  <Step title="Set unified caps">
    Per-call and daily caps apply across all providers.
  </Step>

  <Step title="Handle BUDGET_EXCEEDED in fallback">
    Don't retry with another provider if budget is exhausted.
  </Step>

  <Step title="Log provider metadata">
    Track `metadata.provider` for cost analysis.
  </Step>

  <Step title="Implement circuit breaker">
    Stop retrying after N consecutive failures.
  </Step>
</Steps>

## Complete Example

```typescript theme={null}
import { Saturn } from '@saturn-pay/sdk';

const saturn = new Saturn({ apiKey: process.env.SATURN_KEY });

async function analyzeDocuments(docs: string[]) {
  const results = [];
  const costs = { total: 0, byProvider: {} };

  for (const doc of docs) {
    try {
      // Quick classification with fast model
      const classification = await saturn.reason({
        prompt: `Classify this document type: ${doc.slice(0, 500)}`,
        provider: 'openai',
        model: 'gpt-4o-mini',
      });
      costs.total += classification.metadata.chargedUsdCents;

      // Deep analysis with powerful model
      const analysis = await saturn.reason({
        prompt: `Analyze in detail: ${doc}`,
        provider: 'anthropic',
        model: 'claude-sonnet-4-20250514',
      });
      costs.total += analysis.metadata.chargedUsdCents;

      results.push({
        type: classification.data.content,
        analysis: analysis.data.content,
      });

    } catch (err) {
      if (err.code === 'BUDGET_EXCEEDED') {
        console.log(`Processed ${results.length}/${docs.length} docs before budget`);
        break;
      }
      throw err;
    }
  }

  return { results, costs };
}
```

## Extend This

<CardGroup cols={2}>
  <Card title="Cost-Aware Routing">
    Check remaining budget, route to cheaper provider when low.
  </Card>

  <Card title="Provider Preferences">
    Weight by cost/latency/quality based on task type.
  </Card>

  <Card title="Spend Alerts">
    Notify when 80% of daily cap consumed.
  </Card>

  <Card title="Provider Analytics">
    Compare cost/quality across providers over time.
  </Card>
</CardGroup>