> ## 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.

# @standardagents/openai

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

> [!NOTE]
>
> **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.

Rate limit errors preserve `Retry-After` hints in `ProviderError.retryAfter`.

> [card] 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

```bash npm theme={null}
npm install @standardagents/openai
```

```bash pnpm theme={null}
pnpm add @standardagents/openai
```

```bash yarn theme={null}
yarn add @standardagents/openai
```

## Quick Start

```typescript agents/models/gpt_5_4.ts theme={null}
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:

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

> [!NOTE]
>
> 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:

```typescript agents/providers/darkbloom.ts theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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` | — |

> [!NOTE]
>
> 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](https://platform.openai.com/docs/guides/tools) for the current per-model compatibility matrix.

### Using Provider Tools

Enable provider tools in your model definition:

```typescript theme={null}
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:

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

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

Some provider tools require thread environment variables (tenvs):

**file\_search:**

```typescript theme={null}
// Requires vectorStoreId tenv
tenvs: z.object({
  vectorStoreId: z.string().describe('OpenAI Vector Store ID'),
})
```

> [!NOTE]
>
> 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:

```typescript theme={null}
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:

```bash .dev.vars theme={null}
OPENAI_API_KEY=sk-...
```

For Cloudflare Workers:

```bash theme={null}
wrangler secret put OPENAI_API_KEY
```

## Example Configurations

### High-Performance Model

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

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

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

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

> [card] [Models](https://docs.standardagents.ai/core-concepts/models.md)
>
> Learn about model configuration

> [card] [OpenRouter](https://docs.standardagents.ai/providers/openrouter.md)
>
> Access multiple providers via OpenRouter

> [card] [Tools](https://docs.standardagents.ai/core-concepts/tools.md)
>
> Create custom tools

> [card] [defineModel API](https://docs.standardagents.ai/api-reference/define/model.md)
>
> Complete API reference


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