@standardagents/openai - AgentBuilder

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.

Connection Config Slots

The OpenAI factory exposes connection-level config slots that defineProvider sub-providers can override:

Slot	Type	Default
`apiKey`	`secret`	`OPENAI_API_KEY`
`baseUrl`	`url`	`https://api.openai.com/v1`
`timeout`	`number`	`30000`

Use this for OpenAI-compatible providers that share request/response behavior but use a different endpoint and credential:

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

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

Option	Type	Description
`service_tier`	`'auto' \| 'default' \| 'flex'`	Service tier for request processing
`user`	`string`	User identifier for abuse monitoring
`seed`	`number`	Seed for deterministic outputs (beta)
`frequency_penalty`	`number`	Reduces repetition (-2.0 to 2.0)
`presence_penalty`	`number`	Encourages new topics (-2.0 to 2.0)
`logprobs`	`boolean`	Return log probabilities
`top_logprobs`	`number`	Most likely tokens to return (0-20)
`store`	`boolean`	Store completion for future reference
`metadata`	`Record<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:

Tool	Description	Required `tenvs`
`web_search`	Search the web for up-to-date information with citations	`userLocation` (optional)
`file_search`	Search uploaded files using vector embeddings	`vectorStoreId` (required)
`code_interpreter`	Execute Python in a sandboxed container	`containerId` (optional)
`image_generation`	Generate 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 and are recorded through Standard Agents’ generic provider-tool log path.

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

​Overview

Key Features

​Installation

​Quick Start

​Provider Factory

​Connection Config Slots

​Provider Options

​Available Options

​Type Safety

​Provider Tools

​Using Provider Tools

​Tool Requirements

​Model Capabilities

​Environment Setup

​Example Configurations

​High-Performance Model

​Budget Model

​Reasoning Model

​Exports

​Next Steps

Models

OpenRouter

Tools

defineModel API

Overview

Installation

Quick Start

Provider Factory

Connection Config Slots

Provider Options

Available Options

Type Safety

Provider Tools

Using Provider Tools

Tool Requirements

Model Capabilities

Environment Setup

Example Configurations

High-Performance Model

Budget Model

Reasoning Model

Exports

Next Steps