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

# Models

> Configure LLM models with provider factories, capabilities, and pricing tracking

## What are Models?

Models in Standard Agents define the LLM configurations that your agents and prompts use for AI responses. Each model configuration specifies which provider to use, the specific model ID, capabilities, fallback models for resilience, and optional pricing for cost tracking.

## Quick Example

```typescript agents/models/heavy_thinking.ts theme={null}
import { defineModel } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

export default defineModel({
  name: 'heavy-thinking',
  provider: openai,
  model: 'gpt-5.4',
  inputPrice: 2.5,
  outputPrice: 10,
});
```

Reference in a prompt:

```typescript agents/prompts/my_prompt.ts theme={null}
import { definePrompt } from '@standardagents/builder';

export default definePrompt({
  name: 'my_prompt',
  model: 'heavy-thinking',  // Type-safe reference
  prompt: 'You are a helpful assistant...',
});
```

## Naming Models

<Tip>
  **Best Practice:** Name your models based on their **use case**, not the underlying model ID.
</Tip>

This approach provides several benefits:

* **Swap models easily** - Change the underlying model without updating prompts
* **Clear intent** - Team members understand what each model is for
* **Environment flexibility** - Use different models in dev vs production

**Good model names:**

* `heavy-thinking` - Complex reasoning tasks
* `fast-response` - Quick, simple responses
* `code-generation` - Code-focused tasks
* `eval` - Evaluation and scoring
* `budget` - Cost-conscious general use
* `creative-writing` - Creative content generation

**Avoid:**

* `gpt-5.4` - Ties the name to a specific model
* `claude-sonnet` - Same issue, hard to swap later
* `model-1` - No indication of purpose

## Model Providers

Standard Agents uses **provider factory functions** imported from provider packages. This enables typed `providerOptions`, runtime validation, and local provider definitions.

### OpenAI

```typescript theme={null}
import { defineModel } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

export default defineModel({
  name: 'gpt-5.4',
  provider: openai,
  model: 'gpt-5.4',
  inputPrice: 2.5,
  outputPrice: 10,
  providerOptions: {
    service_tier: 'default',
  },
});
```

**API Key:** Set `OPENAI_API_KEY` environment variable

**Package:** `@standardagents/openai`

### User-Defined Providers

Use `defineProvider` when another API is compatible with a base provider but needs its own endpoint, API key, icon, model list, or pricing behavior.

```typescript agents/providers/darkbloom.ts theme={null}
import { defineProvider, providerEnv } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

export default defineProvider({
  name: 'darkbloom',
  label: 'Darkbloom',
  baseProvider: openai,
  config: {
    apiKey: providerEnv('DARKBLOOM_API_KEY', { valueType: 'secret' }),
    baseUrl: providerEnv('DARKBLOOM_BASE_URL', {
      valueType: 'url',
      default: 'https://api.darkbloom.dev/v1',
    }),
  },
});
```

```typescript agents/models/darkbloom_chat.ts theme={null}
import { defineModel } from '@standardagents/spec';
import darkbloom from '../providers/darkbloom';

export default defineModel({
  name: 'darkbloom_chat',
  provider: darkbloom,
  model: 'darkbloom-chat',
});
```

Sub-providers inherit the base provider's `providerOptions` type. They can override any provider method with `overrides`; call `next()` inside an override to compose with the base provider, or return your own value to replace it.

### Anthropic

Anthropic's Claude models are available through a dedicated provider package built on the official `@anthropic-ai/sdk`:

```typescript theme={null}
import { defineModel } from '@standardagents/spec';
import { anthropic } from '@standardagents/anthropic';

export default defineModel({
  name: 'claude-opus',
  provider: anthropic,
  model: 'claude-opus-4-8',
  inputPrice: 5,
  outputPrice: 25,
  providerOptions: {
    cacheSystemPrompt: true,
  },
});
```

**API Key:** Set `ANTHROPIC_API_KEY` environment variable

<Note>
  **Known Anthropic pricing fallback:** Standard Agents derives the exact request cost for documented Claude models from the API's token usage buckets (including prompt-cache reads and writes), so `inputPrice` and `outputPrice` are optional for known Claude models. Set them yourself only for custom or unlisted model IDs.
</Note>

**Package:** `@standardagents/anthropic`

### Cerebras

Cerebras exposes an OpenAI-compatible Chat Completions API with a dedicated provider package:

```typescript theme={null}
import { defineModel } from '@standardagents/spec';
import { cerebras } from '@standardagents/cerebras';

export default defineModel({
  name: 'fast-cerebras',
  provider: cerebras,
  model: 'llama3.1-8b',
  inputPrice: 0.1,
  outputPrice: 0.1,
  providerOptions: {
    service_tier: 'default',
  },
});
```

**API Key:** Set `CEREBRAS_API_KEY` environment variable

<Note>
  **Known Cerebras pricing fallback:** Standard Agents can derive request cost for documented Cerebras models when the API response includes token usage but no explicit dollar cost. For custom or private Cerebras models, keep setting `inputPrice` and `outputPrice` yourself.
</Note>

**Package:** `@standardagents/cerebras`

### Google Gemini / Imagen

Google's dedicated provider uses the official `@google/genai` SDK for Gemini text generation and Imagen image generation/editing:

```typescript theme={null}
import { defineModel } from '@standardagents/spec';
import { google } from '@standardagents/google';

export default defineModel({
  name: 'gemini-fast',
  provider: google,
  model: 'gemini-2.5-flash',
  providerOptions: {
    responseModalities: ['TEXT'],
  },
});
```

**API Key:** Set `GOOGLE_API_KEY` environment variable

**Package:** `@standardagents/google`

### Groq

Groq exposes low-latency chat completions through the official `groq-sdk`:

```typescript theme={null}
import { defineModel } from '@standardagents/spec';
import { groq } from '@standardagents/groq';

export default defineModel({
  name: 'groq-fast',
  provider: groq,
  model: 'llama-3.1-8b-instant',
  providerOptions: {
    reasoning_format: 'parsed',
  },
});
```

**API Key:** Set `GROQ_API_KEY` environment variable

**Package:** `@standardagents/groq`

### Novita AI

Novita AI exposes an OpenAI-compatible Chat Completions API with live model catalog pricing:

```typescript theme={null}
import { defineModel } from '@standardagents/spec';
import { novita } from '@standardagents/novita';

export default defineModel({
  name: 'novita-reasoning',
  provider: novita,
  model: 'deepseek/deepseek-v3.2',
  providerOptions: {
    seed: 42,
  },
});
```

**API Key:** Set `NOVITA_API_KEY` environment variable

<Note>
  **No pricing required for catalog models:** Novita's provider reads model prices from `/openai/v1/models`, including cache-read prices when available, and attaches provider-owned `usage.pricing` / `usage.cost` values. For custom or private Novita models, set `inputPrice`, `outputPrice`, and `cachedPrice` yourself.
</Note>

**Package:** `@standardagents/novita`

### Cloudflare Workers AI

Cloudflare Workers AI exposes an OpenAI-compatible Chat Completions endpoint scoped to your Cloudflare account:

```typescript theme={null}
import { defineModel } from '@standardagents/spec';
import { cloudflare } from '@standardagents/cloudflare';

export default defineModel({
  name: 'workers-fast',
  provider: cloudflare,
  model: '@cf/meta/llama-3.1-8b-instruct',
  inputPrice: 0.1,
  outputPrice: 0.1,
  providerOptions: {
    seed: 42,
  },
});
```

**Environment:** Set both `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`

**Package:** `@standardagents/cloudflare`

### OpenRouter

OpenRouter provides access to models from multiple providers (OpenAI, Anthropic, Google, Meta, etc.) through a single API:

```typescript theme={null}
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'claude-sonnet',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
  providerOptions: {
    provider: {
      zdr: true,  // Zero Data Retention
      only: ['anthropic'],
    },
  },
});
```

<Note>
  **No pricing required:** OpenRouter models automatically fetch pricing data from the OpenRouter API at runtime. You do not need to specify `inputPrice` or `outputPrice` for OpenRouter models.
</Note>

**Model ID format:** `provider/model-name`

**Example models:**

* `openai/gpt-5.4`
* `anthropic/claude-sonnet-4`
* `google/gemini-2.0-flash-exp`
* `meta-llama/llama-3.3-70b-instruct`

**API Key:** Set `OPENROUTER_API_KEY` environment variable

**Package:** `@standardagents/openrouter`

### xAI

xAI uses the official `@ai-sdk/xai` provider for Grok chat and image models:

```typescript theme={null}
import { defineModel } from '@standardagents/spec';
import { xai } from '@standardagents/xai';

export default defineModel({
  name: 'grok-default',
  provider: xai,
  model: 'grok-4-0709',
  providerOptions: {
    reasoningEffort: 'high',
  },
});
```

**API Key:** Set `XAI_API_KEY` environment variable

**Package:** `@standardagents/xai`

## Provider Options

Each provider has typed options that are validated at build time and runtime:

### OpenAI Provider Options

```typescript theme={null}
providerOptions: {
  service_tier: 'auto' | 'default' | 'flex',
  user: 'user-123',
  seed: 42,
  frequency_penalty: 0.5,
  presence_penalty: 0.5,
  logprobs: true,
  top_logprobs: 5,
  store: true,
  metadata: { key: 'value' },
}
```

### OpenRouter Provider Options

```typescript theme={null}
providerOptions: {
  provider: {
    order: ['anthropic', 'openai'],
    allow_fallbacks: true,
    zdr: true,
    only: ['anthropic'],
    ignore: ['azure'],
    sort: 'price' | 'throughput' | 'latency',
    max_price: {
      prompt: 1,
      completion: 5,
    },
    quantizations: ['fp16', 'bf16'],
  },
}
```

### Cerebras Provider Options

```typescript theme={null}
providerOptions: {
  service_tier: 'priority' | 'default' | 'auto' | 'flex',
  reasoning_effort: 'none' | 'low' | 'medium' | 'high',
  clear_thinking: false,
  user: 'user-123',
  seed: 42,
  logprobs: true,
  top_logprobs: 5,
}
```

### Google Provider Options

```typescript theme={null}
providerOptions: {
  responseModalities: ['TEXT', 'IMAGE'],
  candidateCount: 1,
  cachedContent: 'cachedContents/...',
  thinkingConfig: {
    thinkingBudget: 1024,
  },
  imageConfig: {
    aspectRatio: '1:1',
  },
}
```

### Groq Provider Options

```typescript theme={null}
providerOptions: {
  reasoning_format: 'parsed',
  reasoning_effort: 'high',
  citation_options: 'enabled',
  service_tier: 'auto',
  search_settings: {
    include_domains: ['example.com'],
  },
}
```

### Cloudflare Provider Options

```typescript theme={null}
providerOptions: {
  baseUrl: 'https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/ai/v1',
  seed: 42,
  user: 'user-123',
  logprobs: true,
  top_logprobs: 5,
  frequency_penalty: 0.5,
  presence_penalty: 0.5,
}
```

### xAI Provider Options

```typescript theme={null}
providerOptions: {
  reasoningEffort: 'high',
  logprobs: true,
  topLogprobs: 5,
  searchParameters: {
    mode: 'auto',
    returnCitations: true,
  },
  aspect_ratio: '16:9',
  quality: 'high',
}
```

See the [Anthropic](/providers/anthropic), [Baseten](/providers/baseten), [Cloudflare Workers AI](/providers/cloudflare), [Cerebras](/providers/cerebras), [Google](/providers/google), [Groq](/providers/groq), [Novita AI](/providers/novita), [OpenAI](/providers/openai), [OpenRouter](/providers/openrouter), and [xAI](/providers/xai) documentation for complete options.

## Model Capabilities

Set capabilities to help the framework understand what features the model supports:

```typescript theme={null}
export default defineModel({
  name: 'gpt-5.4',
  provider: openai,
  model: 'gpt-5.4',
  inputPrice: 2.5,
  outputPrice: 10,
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    supportsJsonMode: true,
    supportsStreaming: true,
    maxContextTokens: 128000,
    maxOutputTokens: 16384,
    reasoningLevels: { 0: null, 33: 'low', 66: 'medium', 100: 'high' },
  },
});
```

| Capability          | Type                             | Description                                               |
| ------------------- | -------------------------------- | --------------------------------------------------------- |
| `supportsImages`    | `boolean`                        | Model can process image inputs                            |
| `supportsToolCalls` | `boolean`                        | Model supports function/tool calling                      |
| `supportsJsonMode`  | `boolean`                        | Model supports structured JSON output                     |
| `supportsStreaming` | `boolean`                        | Model supports streaming responses                        |
| `maxContextTokens`  | `number`                         | Maximum context window size                               |
| `maxOutputTokens`   | `number`                         | Maximum output tokens                                     |
| `reasoningLevels`   | `Record<number, string \| null>` | Mapping of 0-100 scale to model-specific reasoning levels |

## Provider Tools

Some providers offer built-in tools. Enable the provider-defined tool names on
the model with `providerTools`:

```typescript theme={null}
import { openai } from '@standardagents/openai';

export default defineModel({
  name: 'gpt-5.4-with-tools',
  provider: openai,
  model: 'gpt-5.4',
  inputPrice: 2.5,
  outputPrice: 10,
  providerTools: ['web_search', 'code_interpreter'],
});
```

**OpenAI Provider Tools:**

* `web_search` - Search the web with citations
* `file_search` - Search uploaded files (requires `vectorStoreId` tenv)
* `code_interpreter` - Execute Python code
* `image_generation` - Generate images with GPT-image-1

**OpenRouter Provider Tools:**

* `web_search` - Search the web through OpenRouter server tools
* `web_fetch` - Fetch and extract URL content through OpenRouter
* `datetime` - Resolve the current date and time through OpenRouter
* `image_generation` - Generate images through OpenRouter server tools

Provider packages translate these names into their native request format and
execute them through the provider API. AgentBuilder discovers and selects the
tools, but does not execute provider tools locally. Completed calls are recorded
through the generic provider-tool log path.

## Fallback Models

Fallback models provide resilience when the primary model is unavailable or fails. The system automatically retries with fallback models for:

* Network errors
* Rate limits (429)
* Server errors (5xx)
* Authentication errors (401)

Fallbacks reference other models you've defined with `defineModel` by their `name`:

```typescript theme={null}
// agents/models/fallback_cheap.ts
import { openai } from '@standardagents/openai';

export default defineModel({
  name: 'fallback-cheap',
  provider: openai,
  model: 'gpt-5.4-mini',
  inputPrice: 0.15,
  outputPrice: 0.60,
});

// agents/models/primary.ts
export default defineModel({
  name: 'primary-model',
  provider: openai,
  model: 'gpt-5.4',
  fallbacks: ['fallback-cheap'],
  inputPrice: 2.5,
  outputPrice: 10,
});
```

### Retry Sequence

When a request fails:

1. **Primary model** (attempt 1) → Failed? Retry...
2. **Primary model** (attempt 2) → Failed? Try fallback...
3. **Fallback 1** (attempt 1) → Failed? Retry...
4. **Fallback 1** (attempt 2) → Failed? Try next fallback...
5. **Fallback 2** (attempt 1) → Failed? Retry...
6. **Fallback 2** (attempt 2) → Failed? Throw error

<Tip>
  Configure fallbacks for production deployments to ensure high availability. Choose fallback models from different providers to avoid provider-specific outages.
</Tip>

## Pricing Configuration

Configure pricing to track token costs across your application:

```typescript theme={null}
defineModel({
  name: 'gpt-5.4',
  provider: openai,
  model: 'gpt-5.4',
  inputPrice: 2.5,    // $2.50 per 1M input tokens
  outputPrice: 10,    // $10 per 1M output tokens
  cachedPrice: 1.25,  // $1.25 per 1M cached tokens (if provider supports)
});
```

**Pricing units:** All prices are in USD per 1 million tokens

### Current Pricing Examples

| Model       | Input Price | Output Price |
| ----------- | ----------- | ------------ |
| GPT-4o      | \$2.50      | \$10.00      |
| GPT-4o-mini | \$0.15      | \$0.60       |
| o1-mini     | \$1.10      | \$4.40       |

<Note>
  Prices shown may change. Check provider websites for current pricing. OpenRouter models fetch pricing automatically.
</Note>

## Type Safety

After defining models, Standard Agents generates the `StandardAgents.Models` type:

```typescript theme={null}
// Auto-generated
declare namespace StandardAgents {
  type Models = 'gpt-5.4' | 'claude-sonnet' | 'gemini-pro' | /* ... */;
}
```

This enables type-safe model references in prompts:

```typescript theme={null}
definePrompt({
  name: 'my_prompt',
  model: 'gpt-5.4',  // TypeScript validates this
  // model: 'typo',  // ❌ Error: not a valid model
  // ...
});
```

## Common Patterns

### Cost-Optimized Chain

Use cheaper models with expensive fallbacks:

```typescript theme={null}
import { openai } from '@standardagents/openai';

defineModel({
  name: 'budget-primary',
  provider: openai,
  model: 'gpt-5.4-mini',
  fallbacks: ['claude-haiku'],
  inputPrice: 0.15,
  outputPrice: 0.60,
});
```

### Multi-Provider Resilience

Fallbacks across providers for maximum uptime:

```typescript theme={null}
import { openai } from '@standardagents/openai';
import { openrouter } from '@standardagents/openrouter';

// Primary OpenAI model
defineModel({
  name: 'resilient-model',
  provider: openai,
  model: 'gpt-5.4',
  fallbacks: ['openrouter-claude', 'openrouter-gpt'],
});

// Fallback via OpenRouter
defineModel({
  name: 'openrouter-claude',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
});
```

## Environment Setup

Configure provider API keys as environment variables:

```bash .dev.vars theme={null}
# Cloudflare Workers AI
CLOUDFLARE_API_TOKEN=...
CLOUDFLARE_ACCOUNT_ID=...

# Cerebras
CEREBRAS_API_KEY=...

# Google
GOOGLE_API_KEY=...

# Groq
GROQ_API_KEY=...

# Novita AI
NOVITA_API_KEY=...

# Baseten Model APIs
BASETEN_API_KEY=...

# OpenAI (direct)
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# OpenRouter (access to multiple providers)
OPENROUTER_API_KEY=sk-or-...

# xAI
XAI_API_KEY=...

# User-defined OpenAI-compatible provider
DARKBLOOM_API_KEY=...
# DARKBLOOM_BASE_URL=https://api.darkbloom.dev/v1
```

For hosted projects, configure production provider keys through the Standard
Agents platform environment settings. For self-managed Worker deployments, use
Cloudflare secrets:

```bash theme={null}
wrangler secret put CLOUDFLARE_API_TOKEN
wrangler secret put CLOUDFLARE_ACCOUNT_ID
wrangler secret put CEREBRAS_API_KEY
wrangler secret put GOOGLE_API_KEY
wrangler secret put GROQ_API_KEY
wrangler secret put NOVITA_API_KEY
wrangler secret put BASETEN_API_KEY
wrangler secret put OPENAI_API_KEY
wrangler secret put ANTHROPIC_API_KEY
wrangler secret put OPENROUTER_API_KEY
wrangler secret put XAI_API_KEY
```

## File Organization

Models are auto-discovered from the `agents/models/` directory:

```
agents/
└── models/
    ├── heavy_thinking.ts   # export default defineModel({...})
    ├── fast_response.ts    # export default defineModel({...})
    └── budget.ts           # export default defineModel({...})
```

**Requirements:**

* Use snake\_case for file names: `heavy_thinking.ts`, `fast_response.ts`
* One model per file
* Default export required

## Next Steps

<CardGroup cols={2}>
  <Card title="Model API Reference" icon="code" href="/api-reference/define/model">
    Complete defineModel specification
  </Card>

  <Card title="Baseten Provider" icon="server" href="/providers/baseten">
    Baseten Model APIs
  </Card>

  <Card title="Cloudflare Provider" icon="cloud" href="/providers/cloudflare">
    Workers AI chat completions
  </Card>

  <Card title="Cerebras Provider" icon="zap" href="/providers/cerebras">
    OpenAI-compatible chat completions
  </Card>

  <Card title="Google Provider" icon="sparkles" href="/providers/google">
    Gemini and Imagen
  </Card>

  <Card title="Groq Provider" icon="rocket" href="/providers/groq">
    Groq chat completions
  </Card>

  <Card title="Novita Provider" icon="zap" href="/providers/novita">
    OpenAI-compatible Novita models
  </Card>

  <Card title="OpenAI Provider" icon="brain" href="/providers/openai">
    OpenAI-specific configuration
  </Card>

  <Card title="OpenRouter Provider" icon="route" href="/providers/openrouter">
    Multi-provider gateway
  </Card>

  <Card title="xAI Provider" icon="cpu" href="/providers/xai">
    Grok chat and image models
  </Card>

  <Card title="Prompts" icon="message" href="/core-concepts/prompts">
    Learn how to use models in prompts
  </Card>
</CardGroup>