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, runtime validation, and local provider definitions.

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

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.

agents/providers/darkbloom.ts

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

agents/models/darkbloom_chat.ts

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:

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

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.

Package: @standardagents/anthropic

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

Novita AI

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

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

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.

Package: @standardagents/novita

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 Anthropic, Baseten, Cloudflare Workers AI, Cerebras, Google, Groq, Novita AI, 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 the provider-defined tool names on the model 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

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:

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

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

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

Model API Reference

Complete defineModel specification

Baseten Provider

Baseten Model APIs

Cloudflare Provider

Workers AI chat completions

Cerebras Provider

OpenAI-compatible chat completions

Google Provider

Gemini and Imagen

Groq Provider

Groq chat completions

Novita Provider

OpenAI-compatible Novita models

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

​What are Models?

​Quick Example

​Naming Models

​Model Providers

​OpenAI

​User-Defined Providers

​Anthropic

​Cerebras

​Google Gemini / Imagen

​Groq

​Novita AI

​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

Baseten Provider

Cloudflare Provider

Cerebras Provider

Google Provider

Groq Provider

Novita Provider

OpenAI Provider

OpenRouter Provider

xAI Provider

Prompts

What are Models?

Quick Example

Naming Models

Model Providers

OpenAI

User-Defined Providers

Anthropic

Cerebras

Google Gemini / Imagen

Groq

Novita AI

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