Skip to main content

​
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, fallback models for resilience, and pricing for cost tracking.

​
Quick Example

agents/models/heavy_thinking.ts
import { defineModel } from '@standardagents/builder';

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 supports two model providers: OpenAI (direct) and OpenRouter (access to multiple providers).

​
OpenAI

defineModel({
  name: 'gpt-4o',
  provider: 'openai',
  model: 'gpt-4o',
  inputPrice: 2.5,
  outputPrice: 10,
});
API Key: Set OPENAI_API_KEY environment variable

​
OpenRouter

OpenRouter provides access to models from multiple providers (OpenAI, Anthropic, Google, Meta, etc.) through a single API: 
defineModel({
  name: 'openrouter-claude',
  provider: 'openrouter',
  model: 'anthropic/claude-sonnet-4.5',
  includedProviders: ['anthropic'],  // Optional: only use specific providers
});
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

​
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
defineModel({
  name: 'fallback-cheap',
  provider: 'openai',
  model: 'gpt-4o-mini',
  inputPrice: 0.15,
  outputPrice: 0.60,
});

// agents/models/primary.ts
defineModel({
  name: 'primary-model',
  provider: 'openai',
  model: 'gpt-4o',
  fallbacks: ['fallback-cheap'],  // References the model defined above
  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
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

ModelInput PriceOutput 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: 
// Primary: Fast and cheap
defineModel({
  name: 'budget-primary',
  provider: 'openai',
  model: 'gpt-4o-mini',
  fallbacks: ['openrouter-haiku'],
  inputPrice: 0.15,
  outputPrice: 0.60,
});

​
Multi-Provider Resilience

Fallbacks across providers for maximum uptime: 
defineModel({
  name: 'resilient-model',
  provider: 'openai',
  model: 'gpt-4o',
  fallbacks: ['openrouter-claude', 'openrouter-gpt'],
});

​
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

Prompts

Learn how to use models in prompts

Getting Started

Set up your first agent

Examples

See model configurations in action