Models - AgentBuilder

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-5.4',
  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-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 and runtime validation.

OpenAI

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

Cerebras

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

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

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.

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:

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:

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

Cloudflare Workers AI

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

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:

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-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:

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

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

Cerebras Provider Options

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

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

Groq Provider Options

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

Cloudflare Provider Options

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

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

See the Cloudflare Workers AI, Cerebras, Google, Groq, OpenAI, OpenRouter, and xAI documentation for complete options.

Model Capabilities

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

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 them with providerTools:

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

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-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:

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-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

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-5.4' | 'claude-sonnet' | 'gemini-pro' | /* ... */;
}

This enables type-safe model references in prompts:

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:

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:

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:

.dev.vars

# Cerebras
CEREBRAS_API_KEY=...

# 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": {
    "CEREBRAS_API_KEY": "...",
    "OPENAI_API_KEY": "...",
    "OPENROUTER_API_KEY": "..."
  }
}

Or use Cloudflare secrets for production:

wrangler secret put CLOUDFLARE_API_TOKEN
wrangler secret put CEREBRAS_API_KEY
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

Cloudflare Provider

Workers AI chat completions

Cerebras Provider

OpenAI-compatible chat completions

Google Provider

Gemini and Imagen

Groq Provider

Groq chat completions

OpenAI Provider

OpenAI-specific configuration

OpenRouter Provider

Multi-provider gateway

xAI Provider

Grok chat and image models

Prompts

Learn how to use models in prompts

Getting Started

Core Concepts

User Interfaces

Providers

Documentation Index

​What are Models?

​Quick Example

​Naming Models

​Model Providers

​OpenAI

​Cerebras

​Google Gemini / Imagen

​Groq

​Cloudflare Workers AI

​OpenRouter

​xAI

​Provider Options

​OpenAI Provider Options

​OpenRouter Provider Options

​Cerebras Provider Options

​Google Provider Options

​Groq Provider Options

​Cloudflare Provider Options

​xAI 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

Cloudflare Provider

Cerebras Provider

Google Provider

Groq Provider

OpenAI Provider

OpenRouter Provider

xAI Provider

Prompts

What are Models?

Quick Example

Naming Models

Model Providers

OpenAI

Cerebras

Google Gemini / Imagen

Groq

Cloudflare Workers AI

OpenRouter

xAI

Provider Options

OpenAI Provider Options

OpenRouter Provider Options

Cerebras Provider Options

Google Provider Options

Groq Provider Options

Cloudflare Provider Options

xAI 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