Models

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

agents/models/heavy_thinking.ts

import { defineModel } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

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

Reference in a prompt:

agents/prompts/my_prompt.ts

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

Best Practice: Name your models based on their use case, not the underlying model ID.

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-4o - 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 and runtime validation.

OpenAI

import { defineModel } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

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

API Key: Set OPENAI_API_KEY environment variable Package: @standardagents/openai

OpenRouter

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

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'],
    },
  },
});

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.

Model ID format: provider/model-name Example models:

openai/gpt-4o
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

Provider Options

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

OpenAI Provider Options

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

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'],
  },
}

See the OpenAI and OpenRouter documentation for complete options.

Model Capabilities

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

export default defineModel({
  name: 'gpt-4o',
  provider: openai,
  model: 'gpt-4o',
  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 them with providerTools:

import { openai } from '@standardagents/openai';

export default defineModel({
  name: 'gpt-4o-with-tools',
  provider: openai,
  model: 'gpt-4o',
  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

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:

// agents/models/fallback_cheap.ts
import { openai } from '@standardagents/openai';

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

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

Retry Sequence

When a request fails:

Primary model (attempt 1) → Failed? Retry…
Primary model (attempt 2) → Failed? Try fallback…
Fallback 1 (attempt 1) → Failed? Retry…
Fallback 1 (attempt 2) → Failed? Try next fallback…
Fallback 2 (attempt 1) → Failed? Retry…
Fallback 2 (attempt 2) → Failed? Throw error

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

Pricing Configuration

Configure pricing to track token costs across your application:

defineModel({
  name: 'gpt-4o',
  provider: openai,
  model: 'gpt-4o',
  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

Prices shown may change. Check provider websites for current pricing. OpenRouter models fetch pricing automatically.

Type Safety

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

// Auto-generated
declare namespace StandardAgents {
  type Models = 'gpt-4o' | 'claude-sonnet' | 'gemini-pro' | /* ... */;
}

This enables type-safe model references in prompts:

definePrompt({
  name: 'my_prompt',
  model: 'gpt-4o',  // TypeScript validates this
  // model: 'typo',  // ❌ Error: not a valid model
  // ...
});

Common Patterns

Cost-Optimized Chain

Use cheaper models with expensive fallbacks:

import { openai } from '@standardagents/openai';

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

Multi-Provider Resilience

Fallbacks across providers for maximum uptime:

import { openai } from '@standardagents/openai';
import { openrouter } from '@standardagents/openrouter';

// Primary OpenAI model
defineModel({
  name: 'resilient-model',
  provider: openai,
  model: 'gpt-4o',
  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:

.dev.vars

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

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

For Cloudflare Workers, add to wrangler.jsonc:

wrangler.jsonc

{
  "vars": {
    "OPENAI_API_KEY": "...",
    "OPENROUTER_API_KEY": "..."
  }
}

Or use Cloudflare secrets for production:

wrangler secret put OPENAI_API_KEY
wrangler secret put OPENROUTER_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

Model API Reference

Complete defineModel specification

OpenAI Provider

OpenAI-specific configuration

OpenRouter Provider

Multi-provider gateway

Prompts

Learn how to use models in prompts

Getting Started

Core Concepts

User Interfaces

Providers

What are Models?

Quick Example

Naming Models

Model Providers

OpenAI

OpenRouter

Provider Options

OpenAI Provider Options

OpenRouter Provider Options

Model Capabilities

Provider Tools

Fallback Models

Retry Sequence

Pricing Configuration

Current Pricing Examples

Type Safety

Common Patterns

Cost-Optimized Chain

Multi-Provider Resilience

Environment Setup

File Organization

Next Steps

Model API Reference

OpenAI Provider

OpenRouter Provider

Prompts

Getting Started

Core Concepts

User Interfaces

Providers

​What are Models?

​Quick Example

​Naming Models

​Model Providers

​OpenAI

​OpenRouter

​Provider Options

​OpenAI Provider Options

​OpenRouter Provider Options

​Model Capabilities

​Provider Tools

​Fallback Models

​Retry Sequence

​Pricing Configuration

​Current Pricing Examples

​Type Safety

​Common Patterns

​Cost-Optimized Chain

​Multi-Provider Resilience

​Environment Setup

​File Organization

​Next Steps

Model API Reference

OpenAI Provider

OpenRouter Provider

Prompts

What are Models?

Quick Example

Naming Models

Model Providers

OpenAI

OpenRouter

Provider Options

OpenAI Provider Options

OpenRouter Provider Options

Model Capabilities

Provider Tools

Fallback Models

Retry Sequence

Pricing Configuration

Current Pricing Examples

Type Safety

Common Patterns

Cost-Optimized Chain

Multi-Provider Resilience

Environment Setup

File Organization

Next Steps