> ## Documentation Index
> Fetch the complete documentation index at: https://docs.standardagentbuilder.com/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

<Info>
  **Enabled when** `OPENAI_API_KEY` is set in your environment.
</Info>

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

<Card title="Key Features" icon="brain">
  * 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
</Card>

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

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

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

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.
</Note>

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

<CardGroup cols={2}>
  <Card title="Models" icon="cube" href="/core-concepts/models">
    Learn about model configuration
  </Card>

  <Card title="OpenRouter" icon="route" href="/providers/openrouter">
    Access multiple providers via OpenRouter
  </Card>

  <Card title="Tools" icon="wrench" href="/core-concepts/tools">
    Create custom tools
  </Card>

  <Card title="defineModel API" icon="code" href="/api-reference/define/model">
    Complete API reference
  </Card>
</CardGroup>