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

# defineModel

> Define LLM model configurations with typed provider options

## Overview

`defineModel` creates a model configuration that can be referenced by prompts and agents. Models use provider factory functions imported from provider packages for typed configuration.

```typescript theme={null}
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,
});
```

## Type Definition

```typescript theme={null}
import type { ProviderFactoryWithOptions, ModelCapabilities } from '@standardagents/spec';
import type { ZodTypeAny, z } from 'zod';

function defineModel<
  N extends string,
  P extends ProviderFactoryWithOptions<ZodTypeAny>
>(options: ModelDefinition<N, P>): ModelDefinition<N, P>;

interface ModelDefinition<
  N extends string = string,
  P extends ProviderFactoryWithOptions<ZodTypeAny> = ProviderFactoryWithOptions<ZodTypeAny>
> {
  name: N;
  provider: P;
  model: string;
  inputPrice?: number;
  outputPrice?: number;
  cachedPrice?: number;
  fallbacks?: string[];
  includedProviders?: string[];
  capabilities?: ModelCapabilities;
  providerOptions?: InferProviderOptions<P>;
  providerTools?: string[];
}

interface ModelCapabilities {
  reasoningLevels?: Record<number, string | null>;
  supportsImages?: boolean;
  supportsToolCalls?: boolean;
  supportsStreaming?: boolean;
  supportsJsonMode?: boolean;
  maxContextTokens?: number;
  maxOutputTokens?: number;
}

// Automatically infers the correct type from the provider's schema
type InferProviderOptions<P> = P extends ProviderFactoryWithOptions<infer S>
  ? S extends ZodTypeAny ? z.input<S> : Record<string, unknown>
  : Record<string, unknown>;
```

## Parameters

**name** `string` *required*

Unique identifier for this model configuration. Used to reference the model in prompts and agents.

**Best Practice:** Name models by use case, not by model ID:

* `heavy-thinking` - Complex reasoning tasks
* `fast-response` - Quick, simple responses
* `code-generation` - Code-focused tasks

**provider** `ProviderFactory` *required*

Provider factory function imported from a provider package.

```typescript theme={null}
import { anthropic } from '@standardagents/anthropic';
import { cerebras } from '@standardagents/cerebras';
import { cloudflare } from '@standardagents/cloudflare';
import { deepinfra } from '@standardagents/deepinfra';
import { google } from '@standardagents/google';
import { groq } from '@standardagents/groq';
import { novita } from '@standardagents/novita';
import { openai } from '@standardagents/openai';
import { openrouter } from '@standardagents/openrouter';
import { xai } from '@standardagents/xai';

provider: anthropic    // Anthropic Claude via @anthropic-ai/sdk
provider: cerebras     // Cerebras Chat Completions API
provider: cloudflare   // Cloudflare Workers AI OpenAI-compatible API
provider: deepinfra    // DeepInfra OpenAI-compatible Chat Completions API
provider: google       // Google Gemini / Imagen via @google/genai
provider: groq         // Groq chat completions via groq-sdk
provider: novita       // Novita OpenAI-compatible Chat Completions API
provider: openai       // Direct OpenAI API
provider: openrouter   // Multi-provider gateway
provider: xai          // xAI Grok chat / image models
```

> [!NOTE]
>
> The provider determines which `providerOptions` are available. TypeScript provides autocompletion based on the provider's schema.

User-defined providers are also provider factories. Put them in `agents/providers/` with `defineProvider`, then import them as a default import:

```typescript theme={null}
import darkbloom from '../providers/darkbloom';

provider: darkbloom
```

See [defineProvider](https://docs.standardagents.ai/api-reference/define/provider.md) for custom endpoints, API keys, icons, and model discovery overrides.

**model** `string` *required*

The specific model identifier sent to the provider API.

**OpenAI examples:**

* `gpt-4o`
* `gpt-4o-mini`
* `o1-mini`

**Cerebras examples:**

* `llama3.1-8b`
* `qwen-3-235b-a22b-instruct-2507`
* `gpt-oss-120b`

**Cloudflare Workers AI examples:**

* `@cf/meta/llama-3.1-8b-instruct`
* `@cf/openai/gpt-oss-120b`
* `@cf/qwen/qwen3-30b-a3b-fp8`

**OpenRouter format:** `provider/model-name`

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

**Google examples:**

* `gemini-2.5-pro`
* `gemini-2.5-flash`
* `imagen-4.0-generate-001`

**Groq examples:**

* `llama-3.1-8b-instant`
* `openai/gpt-oss-120b`
* `qwen/qwen3-32b`

**Novita AI examples:**

* `zai-org/glm-5.2`
* `deepseek/deepseek-v3.2`
* `moonshotai/kimi-k2.7-code`

**xAI examples:**

* `grok-4-0709`
* `grok-code-fast-1`
* `grok-imagine-image`

**inputPrice** `number`

Price per 1 million input tokens in USD. Typically required for direct providers like OpenAI and Cerebras.

OpenRouter models fetch pricing automatically from the API.

**outputPrice** `number`

Price per 1 million output tokens in USD. Typically required for direct providers like OpenAI and Cerebras.

**cachedPrice** `number`

Price per 1 million cached tokens in USD (if provider supports caching).

**fallbacks** `string[]`

Array of model names to try if the primary model fails. Must reference other models defined with `defineModel`.

Fallbacks are tried for:

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

**includedProviders** `string[]`

**OpenRouter only.** Only use specific providers for this model.

```typescript theme={null}
includedProviders: ['anthropic']  // Only route to Anthropic
```

**capabilities** `ModelCapabilities`

Model capability flags for framework behavior. See [Capabilities](#capabilities) section.

**providerOptions** `InferProviderOptions\<P\>`

Provider-specific options. Type is inferred from the provider's schema.
Native effort values are valid here. A prompt's `reasoning.level` replaces a native effort value. Other options remain. Without a level, options apply as provided.

See [Provider Options](#provider-options) section for available options per provider.

**providerTools** `string[]`

Enable built-in provider tools by provider-defined name. Available tools depend on the provider and model.

```typescript theme={null}
providerTools: ['web_search', 'code_interpreter']
```

Provider packages translate these names into their native request format and
execute them through the provider API. Standard Agents Builder discovers and selects the
tools, but does not execute provider tools locally.

## Provider Options

### OpenAI

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

defineModel({
  name: 'gpt-4o',
  provider: openai,
  model: 'gpt-4o',
  providerOptions: {
    service_tier: 'auto' | 'default' | 'flex',
    user: 'user-123',
    seed: 42,
    frequency_penalty: 0.5,  // -2.0 to 2.0
    presence_penalty: 0.5,   // -2.0 to 2.0
    logprobs: true,
    top_logprobs: 5,         // 0-20
    store: true,
    metadata: { key: 'value' },
  },
});
```

### OpenRouter

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

defineModel({
  name: 'claude-sonnet',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
  providerTools: ['web_search', 'web_fetch', 'datetime', 'image_generation'],
  providerOptions: {
    provider: {
      order: ['anthropic', 'openai'],
      allow_fallbacks: true,
      require_parameters: true,
      data_collection: 'allow' | 'deny',
      zdr: true,
      only: ['anthropic'],
      ignore: ['azure'],
      sort: 'price' | 'throughput' | 'latency',
      max_price: {
        prompt: 1,
        completion: 5,
        request: 0.01,
        image: 0.05,
      },
      quantizations: ['fp16', 'bf16'],
      preferred_min_throughput: 100,
      preferred_max_latency: 1,
    },
    serverTools: {
      web_search: { max_results: 5 },
      web_fetch: { max_content_tokens: 50000 },
      datetime: { timezone: 'America/New_York' },
      image_generation: { quality: 'high' },
    },
  },
});
```

### Cerebras

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

defineModel({
  name: 'cerebras-fast',
  provider: cerebras,
  model: 'llama3.1-8b',
  inputPrice: 0.1,
  outputPrice: 0.1,
  providerOptions: {
    service_tier: 'default',
    reasoning_effort: 'high',
    clear_thinking: false,
    user: 'user-123',
    seed: 42,
  },
});
```

### Cloudflare Workers AI

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

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

## Capabilities

```typescript theme={null}
capabilities: {
  // Reasoning support (0-100 scale → model values)
  reasoningLevels: {
    0: null,      // No reasoning
    33: 'low',    // Low effort
    66: 'medium', // Medium effort
    100: 'high',  // High effort
  },

  // Feature support
  supportsImages: true,      // Can process image inputs
  supportsToolCalls: true,   // Supports function calling
  supportsStreaming: true,   // Supports streaming responses
  supportsJsonMode: true,    // Supports structured JSON output

  // Token limits
  maxContextTokens: 128000,  // Max context window
  maxOutputTokens: 16384,    // Max output tokens
}
```

## Return Value

Returns the same `ModelDefinition` object passed in, enabling the build system to register it.

## Examples

### OpenAI Model

```typescript theme={null}
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,
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    supportsJsonMode: true,
    maxContextTokens: 128000,
  },
  providerOptions: {
    service_tier: 'default',
  },
});
```

### OpenRouter Model

```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',
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    maxContextTokens: 200000,
  },
  providerOptions: {
    provider: {
      zdr: true,
      only: ['anthropic'],
    },
  },
});
```

> [!NOTE]
>
> OpenRouter models automatically fetch pricing from the OpenRouter API. You do not need to specify `inputPrice` or `outputPrice`.

### With Fallbacks

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

// Define fallback model first
export const fallbackCheap = defineModel({
  name: 'fallback-cheap',
  provider: openai,
  model: 'gpt-4o-mini',
  inputPrice: 0.15,
  outputPrice: 0.60,
});

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

### With Provider Tools

```typescript theme={null}
import { defineModel } from '@standardagents/spec';
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', 'file_search'],
});
```

### Reasoning Model

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

export default defineModel({
  name: 'deep-reasoning',
  provider: openai,
  model: 'o1',
  inputPrice: 15,
  outputPrice: 60,
  capabilities: {
    supportsToolCalls: true,
    reasoningLevels: {
      0: null,
      33: 'low',
      66: 'medium',
      100: 'high',
    },
  },
});
```

## File Location

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

```
agents/
└── models/
    ├── heavy_thinking.ts
    ├── fast_response.ts
    └── budget.ts
```

**Requirements:**

* Use snake\_case for file names
* One model per file
* Default export required

## Generated Types

After running the build, `StandardAgents.Models` type is generated:

```typescript theme={null}
declare namespace StandardAgents {
  type Models = 'heavy-thinking' | 'fast-response' | 'budget';
}
```

This enables type-safe model references in prompts.

## Runtime Validation

`defineModel` performs runtime validation:

* `name` is required and must be a non-empty string
* `provider` must be a valid ProviderFactory function
* `model` is required
* Pricing values must be non-negative if provided
* `providerOptions` are validated against the provider's schema

```typescript theme={null}
// This will throw at runtime:
defineModel({
  name: 'my-model',
  provider: 'openai',  // Error: Must be a ProviderFactory, not a string
  model: 'gpt-4o',
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.