Skip to main content
Enabled when OPENAI_API_KEY is set in your environment.

​
Overview

The @standardagents/openai package provides the OpenAI provider factory for Standard Agents. It enables direct access to OpenAI models with typed providerOptions and built-in provider tools.

Key Features

  • Direct OpenAI API access with automatic client management
  • Typed providerOptions with TypeScript autocompletion
  • Built-in provider tools (web search, file search, code interpreter, image generation)
  • Model capability detection and icon support

​
Installation

npm
npm install @standardagents/openai
pnpm
pnpm add @standardagents/openai
yarn
yarn add @standardagents/openai

​
Quick Start

agents/models/gpt_5_4.ts
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.00,
  outputPrice: 8.00,
});

​
Provider Factory

The openai export is a provider factory function that creates OpenAI provider instances: 
import { openai } from '@standardagents/openai';

// The factory is used by defineModel internally
defineModel({
  name: 'my-model',
  provider: openai,  // Pass the factory, not a string
  model: 'gpt-5.4',
});
Unlike the legacy string-based provider: 'openai', the new API uses an imported factory function. This enables typed providerOptions and runtime validation.

​
Provider Options

The openai factory includes a typed schema for provider-specific options: 
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.00,
  outputPrice: 8.00,
  providerOptions: {
    service_tier: 'default',  // TypeScript knows this is valid
    user: 'user-123',
    seed: 42,
  },
});

​
Available Options

OptionTypeDescription
service_tier'auto' | 'default' | 'flex'Service tier for request processing
userstringUser identifier for abuse monitoring
seednumberSeed for deterministic outputs (beta)
frequency_penaltynumberReduces repetition (-2.0 to 2.0)
presence_penaltynumberEncourages new topics (-2.0 to 2.0)
logprobsbooleanReturn log probabilities
top_logprobsnumberMost likely tokens to return (0-20)
storebooleanStore completion for future reference
metadataRecord<string, string>Metadata for stored completions

​
Type Safety

The providerOptions type is automatically inferred from the provider: 
import { openai } from '@standardagents/openai';
import type { OpenAIProviderOptions } from '@standardagents/openai';

// TypeScript enforces the correct shape
const options: OpenAIProviderOptions = {
  service_tier: 'default',
  frequency_penalty: 0.5,
  // seed: 'invalid', // Error: Type 'string' is not assignable to type 'number'
};

​
Provider Tools

OpenAI provides built-in tools that execute on OpenAI’s servers and can be used alongside your custom tools:
ToolDescriptionRequired tenvs
web_searchSearch the web for up-to-date information with citationsuserLocation (optional)
file_searchSearch uploaded files using vector embeddingsvectorStoreId (required)
code_interpreterExecute Python in a sandboxed containercontainerId (optional)
image_generationGenerate images via gpt-image-1—
All current GPT-5.4 models (gpt-5.4, gpt-5.4-mini, gpt-5.4-nano) support these built-in tools. See OpenAI’s tool documentation for the current per-model compatibility matrix.

​
Using Provider Tools

Enable provider tools in your model definition: 
import { defineModel } from '@standardagents/spec';
import { openai } from '@standardagents/openai';

export default defineModel({
  name: 'gpt-5.4-with-tools',
  provider: openai,
  model: 'gpt-5.4',
  inputPrice: 2.00,
  outputPrice: 8.00,
  providerTools: ['web_search', 'code_interpreter'],
});
Then reference them in prompts: 
import { definePrompt } from '@standardagents/spec';

export default definePrompt({
  name: 'research-assistant',
  model: 'gpt-5.4-with-tools',
  prompt: 'You are a research assistant with web search capabilities.',
  tools: ['web_search'],  // Provider tool
});

​
Tool Requirements

Some provider tools require thread environment variables (tenvs): file_search: 
// Requires vectorStoreId tenv
tenvs: z.object({
  vectorStoreId: z.string().describe('OpenAI Vector Store ID'),
})
Provider tools are executed by OpenAI’s servers, not locally. Results come back in the API response.

​
Model Capabilities

Set capabilities to help the framework understand what the model supports: 
export default defineModel({
  name: 'gpt-5.4',
  provider: openai,
  model: 'gpt-5.4',
  inputPrice: 2.00,
  outputPrice: 8.00,
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    supportsJsonMode: true,
    supportsStreaming: true,
    maxContextTokens: 1_000_000,
    maxOutputTokens: 32_768,
  },
});

​
Environment Setup

Set your OpenAI API key as an environment variable:
.dev.vars
OPENAI_API_KEY=sk-...
For Cloudflare Workers: 
wrangler secret put OPENAI_API_KEY

​
Example Configurations

​
High-Performance Model

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

export default defineModel({
  name: 'heavy-thinking',
  provider: openai,
  model: 'gpt-5.4',
  inputPrice: 2.00,
  outputPrice: 8.00,
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    supportsJsonMode: true,
    maxContextTokens: 1_000_000,
  },
  providerOptions: {
    service_tier: 'default',
  },
  providerTools: ['web_search', 'code_interpreter'],
});

​
Budget Model

export default defineModel({
  name: 'fast-response',
  provider: openai,
  model: 'gpt-5.4-mini',
  inputPrice: 0.40,
  outputPrice: 1.60,
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    maxContextTokens: 1_000_000,
  },
});

​
Reasoning Model

export default defineModel({
  name: 'deep-reasoning',
  provider: openai,
  model: 'gpt-5.4',
  inputPrice: 2.00,
  outputPrice: 8.00,
  capabilities: {
    supportsToolCalls: true,
    reasoningLevels: { 0: null, 33: 'low', 66: 'medium', 100: 'high' },
  },
  providerTools: ['web_search', 'code_interpreter'],
});

​
Exports

import {
  // Provider factory
  openai,

  // Provider options schema (Zod)
  openaiProviderOptions,

  // Provider class (advanced usage)
  OpenAIProvider,
} from '@standardagents/openai';

import type {
  // TypeScript types
  OpenAIProviderOptions,
} from '@standardagents/openai';

​
Next Steps

Models

Learn about model configuration

OpenRouter

Access multiple providers via OpenRouter

Tools

Create custom tools

defineModel API

Complete API reference