@standardagents/openrouter

Enabled when OPENROUTER_API_KEY is set in your environment.

Overview

The @standardagents/openrouter package provides the OpenRouter provider factory for Standard Agents. OpenRouter is a multi-provider gateway that routes requests to various LLM providers (OpenAI, Anthropic, Google, Meta, and more) through a single API.

Key Features

Access to 200+ models from multiple providers
Automatic pricing data fetched from OpenRouter API
Typed providerOptions for routing configuration
Provider selection, fallbacks, and price limits
Zero Data Retention (ZDR) endpoints
Provider-executed OpenRouter server tools

Installation

npm

npm install @standardagents/openrouter

pnpm

pnpm add @standardagents/openrouter

yarn

yarn add @standardagents/openrouter

Quick Start

agents/models/claude_sonnet.ts

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

export default defineModel({
  name: 'claude-sonnet',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
});

OpenRouter models automatically fetch pricing from the OpenRouter API. You do not need to specify inputPrice or outputPrice.

Provider Factory

The openrouter export is a provider factory function:

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

defineModel({
  name: 'my-model',
  provider: openrouter,  // Pass the factory, not a string
  model: 'anthropic/claude-sonnet-4',
});

Model ID Format

OpenRouter uses a provider/model-name format for model IDs:

Provider	Example Model ID
OpenAI	`openai/gpt-5.4`
Anthropic	`anthropic/claude-sonnet-4.5`
Google	`google/gemini-2.5-pro`
Meta	`meta-llama/llama-3.3-70b-instruct`
Mistral	`mistralai/mistral-large`
xAI	`x-ai/grok-4`

Browse all available models at openrouter.ai/models.

Provider Options

The openrouter factory includes a typed schema for routing configuration:

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

export default defineModel({
  name: 'claude-secure',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
  providerOptions: {
    provider: {
      zdr: true,  // Zero Data Retention
      only: ['anthropic'],  // Only route to Anthropic
      max_price: {
        prompt: 5,  // Max $5 per million input tokens
        completion: 25,  // Max $25 per million output tokens
      },
    },
  },
});

Routing Options

All routing options are nested under the provider key:

Option	Type	Description
`order`	`string[]`	Provider slugs to try in order
`allow_fallbacks`	`boolean`	Allow fallback to other providers (default: true)
`require_parameters`	`boolean`	Only use providers that support all request parameters
`data_collection`	`'allow' \| 'deny'`	Control data storage policies
`zdr`	`boolean`	Restrict to Zero Data Retention endpoints
`only`	`string[]`	Restrict to these providers only
`ignore`	`string[]`	Skip these providers
`sort`	`string \| object`	Sort by price, throughput, or latency
`max_price`	`object`	Maximum price constraints
`quantizations`	`string[]`	Allowed quantization levels
`preferred_min_throughput`	`number \| object`	Minimum throughput preference
`preferred_max_latency`	`number \| object`	Maximum latency preference

Server Tool Options

OpenRouter server tools are provider-executed tools. Enable the tool names with providerTools, select them from prompts like normal tools, and pass optional OpenRouter parameters through providerOptions.serverTools:

export default defineModel({
  name: 'openrouter-research',
  provider: openrouter,
  model: 'openai/gpt-5.4',
  providerTools: ['web_search', 'web_fetch', 'datetime', 'image_generation'],
  providerOptions: {
    serverTools: {
      web_search: { max_results: 5 },
      web_fetch: { max_content_tokens: 50000 },
      datetime: { timezone: 'America/New_York' },
      image_generation: { quality: 'high' },
    },
  },
});

serverTools configures native OpenRouter tool parameters only. It is stripped from the request body after the provider converts selected tools into openrouter:* tool definitions.

Price Limits

Set hard limits on pricing (request fails if no provider meets threshold):

providerOptions: {
  provider: {
    max_price: {
      prompt: 1,        // Max $1 per million input tokens
      completion: 5,    // Max $5 per million output tokens
      request: 0.01,    // Max $0.01 per request
      image: 0.05,      // Max $0.05 per image
    },
  },
}

Provider Selection

Control which providers handle your requests:

// Only use specific providers
providerOptions: {
  provider: {
    only: ['anthropic', 'openai'],
  },
}

// Prefer certain providers in order
providerOptions: {
  provider: {
    order: ['anthropic', 'openai', 'google'],
    allow_fallbacks: true,
  },
}

// Exclude specific providers
providerOptions: {
  provider: {
    ignore: ['azure'],
  },
}

Sorting

Sort available providers by different criteria:

// Sort by price (cheapest first)
providerOptions: {
  provider: {
    sort: 'price',
  },
}

// Sort by throughput (fastest first)
providerOptions: {
  provider: {
    sort: 'throughput',
  },
}

// Advanced sorting with partition
providerOptions: {
  provider: {
    sort: {
      by: 'latency',
      partition: 'model',
    },
  },
}

Zero Data Retention (ZDR)

For sensitive data, restrict to ZDR endpoints:

providerOptions: {
  provider: {
    zdr: true,  // Only use providers with Zero Data Retention
  },
}

Performance Preferences

Set soft preferences for throughput and latency:

providerOptions: {
  provider: {
    // Simple: apply to p50 percentile
    preferred_min_throughput: 100,  // 100 tokens/sec minimum
    preferred_max_latency: 1,       // 1 second max latency

    // Advanced: specify percentiles
    preferred_min_throughput: {
      p50: 100,
      p90: 50,
    },
    preferred_max_latency: {
      p50: 0.5,
      p99: 2,
    },
  },
}

Type Safety

The providerOptions type is automatically inferred:

import { openrouter } from '@standardagents/openrouter';
import type { OpenRouterProviderOptions } from '@standardagents/openrouter';

const options: OpenRouterProviderOptions = {
  provider: {
    zdr: true,
    only: ['anthropic'],
    // invalid: true,  // Error: Object literal may only specify known properties
  },
};

Model Capabilities

Set capabilities for proper framework behavior:

export default defineModel({
  name: 'claude-sonnet',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    supportsStreaming: true,
    maxContextTokens: 200000,
  },
});

Environment Setup

Set your OpenRouter API key:

.dev.vars

OPENROUTER_API_KEY=sk-or-...

For Cloudflare Workers:

wrangler secret put OPENROUTER_API_KEY

Example Configurations

Budget-Conscious Model

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

export default defineModel({
  name: 'budget-llm',
  provider: openrouter,
  model: 'meta-llama/llama-3.3-70b-instruct',
  providerOptions: {
    provider: {
      sort: 'price',
      max_price: {
        prompt: 0.5,
        completion: 1,
      },
    },
  },
});

High-Security Configuration

export default defineModel({
  name: 'secure-claude',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
  providerOptions: {
    provider: {
      zdr: true,
      only: ['anthropic'],
      data_collection: 'deny',
    },
  },
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    maxContextTokens: 200000,
  },
});

Multi-Provider Fallback

export default defineModel({
  name: 'resilient-model',
  provider: openrouter,
  model: 'openai/gpt-5.4',
  providerOptions: {
    provider: {
      order: ['openai', 'azure', 'anthropic'],
      allow_fallbacks: true,
    },
  },
});

Performance-Optimized

export default defineModel({
  name: 'fast-model',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
  providerOptions: {
    provider: {
      sort: 'throughput',
      preferred_min_throughput: 100,
      preferred_max_latency: 0.5,
    },
  },
});

Tool Calling

OpenRouter tool calls are sent with strict function schemas. The provider normalizes object schemas for OpenAI-backed endpoints by listing every object property in required, while AgentBuilder still validates the returned tool arguments against the original tool Zod schema before execution. When tools are present, tool_choice: "auto" is omitted because OpenRouter treats that as the default. This keeps endpoints that support tools but do not advertise the separate tool_choice parameter eligible for routing.

Provider-Executed Server Tools

The OpenRouter provider exposes these built-in server tools through getTools():

Tool	Native OpenRouter type	Description
`web_search`	`openrouter:web_search`	Search the web server-side
`web_fetch`	`openrouter:web_fetch`	Fetch and extract URL content server-side
`datetime`	`openrouter:datetime`	Resolve current date/time server-side
`image_generation`	`openrouter:image_generation`	Generate images server-side

AgentBuilder marks these tools as provider-executed. The OpenRouter provider translates them to native openrouter:* tools for both Chat Completions and Responses requests, and records completed server tool usage through the generic provider-tool log path.

Generation Metadata

OpenRouter provides additional metadata about request routing that can be fetched after completion:

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

const metadata = await fetchGenerationMetadata(generationId, apiKey);
// Returns: provider used, tokens, latency, etc.

Exports

import {
  // Provider factory
  openrouter,

  // Provider options schema (Zod)
  openrouterProviderOptions,

  // Provider class (advanced usage)
  OpenRouterProvider,

  // Metadata utilities
  fetchGenerationMetadata,
} from '@standardagents/openrouter';

import type {
  // TypeScript types
  OpenRouterProviderOptions,
  OpenRouterConfig,
  GenerationMetadata,
} from '@standardagents/openrouter';

Next Steps

Models

Learn about model configuration

OpenAI Provider

Direct OpenAI API access

Prompts

Configure prompts with models

defineModel API

Complete API reference

Documentation Index

​Overview

Key Features

​Installation

​Quick Start

​Provider Factory

​Model ID Format

​Provider Options

​Routing Options

​Server Tool Options

​Price Limits

​Provider Selection

​Sorting

​Zero Data Retention (ZDR)

​Performance Preferences

​Type Safety

​Model Capabilities

​Environment Setup

​Example Configurations

​Budget-Conscious Model

​High-Security Configuration

​Multi-Provider Fallback

​Performance-Optimized

​Tool Calling

​Provider-Executed Server Tools

​Generation Metadata

​Exports

​Next Steps

Models

OpenAI Provider

Prompts

defineModel API

Overview

Installation

Quick Start

Provider Factory

Model ID Format

Provider Options

Routing Options

Server Tool Options

Price Limits

Provider Selection

Sorting

Zero Data Retention (ZDR)

Performance Preferences

Type Safety

Model Capabilities

Environment Setup

Example Configurations

Budget-Conscious Model

High-Security Configuration

Multi-Provider Fallback

Performance-Optimized

Tool Calling

Provider-Executed Server Tools

Generation Metadata

Exports

Next Steps