View as MarkdownPlain text for this page Open in ChatGPTQuestions about this page Open in ClaudeQuestions about this page

@standardagents/openai

OpenAI provider package for Standard Agents - direct access to OpenAI models with typed configuration

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.

The provider uses the Responses API for generation and streaming. Rate limit errors preserve Retry-After hints in ProviderError.retryAfter.

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-6.1-sol',
  provider: openai,
  model: 'gpt-6.1-sol',
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 2,
  outputPrice: 10,
});

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

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 providers that support OpenAI Responses requests with 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-6.1-sol',
  provider: openai,
  model: 'gpt-6.1-sol',
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 2,
  outputPrice: 10,
  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 variables
`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 with the native image tool	—

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-6.1-sol-with-tools',
  provider: openai,
  model: 'gpt-6.1-sol',
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 2,
  outputPrice: 10,
  providerTools: ['web_search', 'code_interpreter'],
});

Then reference them in prompts:

import { definePrompt } from '@standardagents/spec';

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

Tool Requirements

Streaming web search logs preserve empty provider values. Null URLs and malformed action fields are omitted.

Some provider tools require thread environment variables.

file_search: requires the vectorStoreId thread environment variable. Its value is your OpenAI Vector Store ID. The tool declares it with the variables array:

variables: [
  { name: 'vectorStoreId', type: 'text', required: true, description: 'OpenAI Vector Store ID' },
]

Model Capabilities

Set capabilities to help the framework understand what the model supports:

export default defineModel({
  name: 'gpt-6.1-sol',
  provider: openai,
  model: 'gpt-6.1-sol',
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 2,
  outputPrice: 10,
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    supportsJsonMode: true,
    supportsStreaming: true,
    maxContextTokens: 1_050_000,
    maxOutputTokens: 128_000,
  },
});

Environment Setup

Set your OpenAI API key as an environment variable:

.dev.vars

OPENAI_API_KEY=sk-...

For a deployed project, set OPENAI_API_KEY in your project's environment settings on the Standard Agents platform.

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-6.1-sol',
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 2,
  outputPrice: 10,
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    supportsJsonMode: true,
    maxContextTokens: 1_050_000,
  },
  providerOptions: {
    service_tier: 'default',
  },
  providerTools: ['web_search', 'code_interpreter'],
});

Budget Model

export default defineModel({
  name: 'fast-response',
  provider: openai,
  model: 'gpt-6-luna',
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 0.1,
  outputPrice: 0.5,
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    maxContextTokens: 1_050_000,
  },
});

Reasoning Model

export default defineModel({
  name: 'deep-reasoning',
  provider: openai,
  model: 'gpt-6.1-sol',
  // Prices change. Check https://developers.openai.com/api/docs/pricing
  // Standard rates apply to prompts up to 272K tokens.
  inputPrice: 2,
  outputPrice: 10,
  capabilities: {
    supportsToolCalls: true,
    reasoningLevels: { 0: 'low', 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