# @standardagents/openai

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

> **Info:**
>
> For direct access, set `OPENAI_API_KEY` in your environment. Standard Agents Builder can use hosted routing through `STANDARD_AGENTS_API_KEY` when the provider key is absent. Hosted access depends on platform 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

```bash npm
npm install @standardagents/openai
```

```bash pnpm
pnpm add @standardagents/openai
```

```bash yarn
yarn add @standardagents/openai
```

## Quick Start

```typescript 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:

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

> **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 providers that support OpenAI Responses requests with a different endpoint and credential:

```typescript 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:

```typescript
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:

```typescript
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               | —                          |

> **Note:**
>
> The package exposes all four tool definitions for GPT-6 model IDs. Upstream availability depends on the selected model. 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
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:

```typescript
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:

```typescript
variables: [
  { name: 'vectorStoreId', type: 'text', required: true, description: '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
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:

```bash .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

```typescript
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

```typescript
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

```typescript
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

```typescript
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](/docs/core-concepts/models)

  Learn about model configuration

* [OpenRouter](/docs/providers/openrouter)

  Access multiple providers via OpenRouter

- [Tools](/docs/core-concepts/tools)

  Create custom tools

* [defineModel API](/docs/api-reference/define/model)

  Complete API reference