Skip to content
zidane
SDK reference

zidane/providers/openai

The OpenAI provider on the Responses API, with API keys or ChatGPT (Codex) OAuth credentials.

import { … } from 'zidane/providers/openai'src/providers/openai.ts

Use openai() for OpenAI models on the Responses API. Pass a platform key as apiKey. With no key, it runs on OPENAI_CODEX_API_KEY, then on the stored Codex OAuth sign-in. It does not run on OPENAI_API_KEY. The agent's session id is sent as prompt_cache_key, so a conversation keeps hitting the same prompt cache. For the Chat Completions API, use openaiCompat(). See Providers.

TypeScript
import { createAgent } from 'zidane'
import { openai } from 'zidane/providers/openai'

const agent = createAgent({ provider: openai({ defaultModel: 'gpt-6-astra' }) })
const stats = await agent.run({ prompt: 'Summarize README.md in three bullets.' })
console.log(stats.turns)

Functions#

classifyOpenAIErrorFunction#

Classify an OpenAI Codex error. pi-ai surfaces errors either as thrown Errors (wrapping event.error.errorMessage) or via stream event types.

The retryable hint is set on a transient failure — pattern-matched against message since pi-ai strips structured fields on plain-Error throws. Set behavior.retry.maxAttempts: 1 to disable the loop-level retry.

TypeScript
function classifyOpenAIError(err: unknown): ClassifiedError | null

Parameters

Parameters
NameTypeDescription
errunknown

Error thrown by pi-ai or the HTTP layer.

Returns

ClassifiedError | null

src/providers/openai.ts:475

mapCodexStopReasonFunction#

Map pi-ai's StopReason to the zidane TurnFinishReason union — the same native-stop-reason fidelity anthropic's mapStopReason / openai-compat's mapOAIFinishReason provide. length (max-token truncation) maps to 'length', not to a clean stop. hasToolCalls is the fallback for messages whose stop reason is missing or doesn't carry the tool-call signal.

TypeScript
function mapCodexStopReason(
  stopReason: string | undefined,
  hasToolCalls: boolean,
): TurnFinishReason

Parameters

Parameters
NameTypeDescription
stopReasonstring | undefined

pi-ai stop reason, when present.

hasToolCallsboolean

Whether the turn contains tool calls.

src/providers/openai.ts:372

openaiFunction#

Creates the OpenAI provider on the Responses API. Picks the backend per request from the credential: a Codex OAuth token streams through the ChatGPT Codex backend, a platform API key (sk-…) through the standard Responses API. A run reads params.apiKey, then OPENAI_CODEX_API_KEY, then the stored OAuth credentials. OPENAI_API_KEY is read only by the exact token count (countTokens) and by the decisions helper, together with params.apiKey and OPENAI_CODEX_API_KEY.

TypeScript
function openai(params?: OpenAIParams): Provider

Parameters

Parameters
NameTypeDescription
params?OpenAIParams

API key or OAuth credentials, account id, default model, transport and extra headers.

Returns

Provider

Example

Example
import { createAgent } from 'zidane'
import { openai } from 'zidane/providers/openai'

const agent = createAgent({
  provider: openai({ apiKey: process.env.OPENAI_API_KEY }),
})
await agent.run({ prompt: 'Say hello.' })

src/providers/openai.ts:618

toPiMessagesFunction#

Converts session messages to pi-ai messages for the Responses wire, pairing tool calls with their results.

TypeScript
function toPiMessages(messages: SessionMessage[], modelId: string): Message[]

Parameters

Parameters
NameTypeDescription
messagesSessionMessage[]

Session messages to convert.

modelIdstring

Model id stamped on converted assistant messages.

Returns

Message[]

src/providers/openai.ts:281

Interfaces#

OpenAIParamsInterface#

Options for openai: an API key or ChatGPT OAuth credentials, plus model and request settings.

TypeScript
interface OpenAIParams extends OAuthParams

Properties

OpenAIParams properties
NameTypeDefaultDescription
access?from OAuthParamsstring

OAuth access token supplied at runtime. Used together with refresh and expires to refresh without a credentials file.

account?from OAuthParamsstring

Run on ONE stored account of the provider instead of its active one: the credential's stable id (ProviderCredential.id, see chat/credentials). Resolved to the slot holding it on every token read and refresh, so promoting another account mid-session never moves this provider to it. The provider's env key is ignored while pinned (it is the active credential's, not this account's). A missing account fails the call with pinnedAccountMissingError — never a silent fallback to another account.

accountId?string

ChatGPT account id sent with runtime OAuth credentials. Normally derived from the access token.

apiKey?from OAuthParamsstring

Static API key or OAuth access token sent as is, bypassing credential lookup and refresh.

defaultModel?string'gpt-6-astra'

Model used when a request does not set one.

expires?from OAuthParamsnumber

Expiry of access as a Unix timestamp in milliseconds.

extraHeaders?Record<string, string>

Extra HTTP headers merged into every request (the streaming Responses call and the token-count endpoint). Use for routing/attribution headers a proxy in front of the OpenAI Codex endpoint consumes. Merged with provider defaults; pi-ai lets these override defaults, so avoid authorization / content-type unless you intend to replace them.

refresh?from OAuthParamsstring

OAuth refresh token supplied at runtime.

transport?'auto' | 'sse' | 'websocket'

Transport for the Codex backend: sse, websocket or auto. Ignored for platform API keys.

src/providers/openai.ts:64