@ank1015/agents-provider-openai

OpenAI Responses API runtime adapter for the @ank1015/agents packages.

This package turns normalized LLMRequest<"openai"> objects into OpenAI Responses API streaming calls and translates OpenAI stream events back into normalized assistant events and messages. It also re-exports @ank1015/agents-provider-openai-spec so consumers can import the provider id, config schema, model catalog, and OpenAI-specific types from one package.

Install

pnpm add @ank1015/agents-provider-openai

What This Package Provides

• OpenAIProviderAdapter, a provider adapter for direct OpenAI API calls.
• createOpenAIProviderAdapter helper for app wiring.
• createOpenAIProviderAdapterFactory for transport/container integration.
• OpenAIResponsesClient and OpenAIProviderAdapterDeps test/injection types.
• Re-exports from @ank1015/agents-provider-openai-spec, including OPENAI_PROVIDER, OPENAI_MODELS, and config/model types.

Import Paths

import {
  OPENAI_PROVIDER,
  createOpenAIProviderAdapter,
} from '@ank1015/agents-provider-openai';

import { OpenAIProviderAdapter } from '@ank1015/agents-provider-openai/adapter';

The root import is the normal application entrypoint. The ./adapter subpath exposes the runtime adapter APIs without making internal mapping helpers public.

Basic Usage

import { createAdapterTransport } from '@ank1015/agents-core/transport';
import {
  OPENAI_PROVIDER,
  createOpenAIProviderAdapter,
} from '@ank1015/agents-provider-openai';

const openai = createOpenAIProviderAdapter({
  provider: OPENAI_PROVIDER,
  apiKey: {
    type: 'env',
    name: 'OPENAI_API_KEY',
  },
});

const transport = createAdapterTransport([openai]);

const stream = transport.stream({
  provider: OPENAI_PROVIDER,
  modelId: 'gpt-5.6-terra',
  messages: [
    {
      role: 'user',
      id: 'user_1',
      timestamp: Date.now(),
      content: [{ type: 'text', content: 'Write a short haiku about types.' }],
    },
  ],
});

for await (const event of stream) {
  if (event.type === 'text_delta') {
    process.stdout.write(event.delta);
  }
}

const message = await stream.result();

Configuration

The adapter accepts OpenAIProviderConfig from the spec package:

import { createOpenAIProviderAdapter } from '@ank1015/agents-provider-openai';

const adapter = createOpenAIProviderAdapter({
  provider: 'openai',
  apiKey: {
    type: 'env',
    name: 'OPENAI_API_KEY',
  },
  baseUrl: 'https://api.openai.com/v1',
  headers: {
    'x-app': 'agents',
  },
  organization: 'org_123',
  project: 'proj_123',
});

apiKey is a secret reference. The adapter resolves environment references from process.env, or uses a direct value reference when the key comes from another secret source:

createOpenAIProviderAdapter({
  provider: 'openai',
  apiKey: {
    type: 'value',
    value: openAIKey,
  },
});

Request Mapping

The adapter maps the normalized request shape into OpenAI Responses API streaming parameters:

• instructions becomes OpenAI instructions.
• Text and image user content becomes OpenAI response input content.
• Tool result messages become function or custom tool call output items.
• Prior OpenAI-native assistant responses are reused when available.
• Normalized assistant text, thinking, and tool calls are converted back into OpenAI response input history.
• Function tools become OpenAI function tools with JSON Schema parameters.
• strict is preserved when a function tool sets it to true or false.
• Custom grammar tools become OpenAI custom tools.

providerOptions are forwarded to OpenAI after the generic fields owned by the adapter are removed. The adapter does not default max_output_tokens; callers can set it through providerOptions. GPT-5.6 callers can also select max reasoning effort, Pro mode, persisted reasoning context, and request-wide prompt-cache options.

Streaming Behavior

adapter.stream(request) returns an AssistantMessageEventStreamSource<"openai">.

The stream may emit:

• start
• text_start, text_delta, text_end
• thinking_start, thinking_delta, thinking_end
• toolcall_start, toolcall_delta, toolcall_end
• done
• error
• aborted

Successful messages include the OpenAI native response, normalized assistant content, usage, cost estimates from the static model catalog, duration, and mapped stop reason. Cache reads and GPT-5.6 cache writes are reported and priced separately. For GPT-5.6 and GPT-5.5, the adapter selects whole-request long-context rates when total input exceeds 272K tokens. Failed or aborted messages preserve any normalized content that was produced before the stream ended.

Testing And Injection

The adapter accepts dependency overrides for unit tests and custom runtime containers:

import { OpenAIProviderAdapter } from '@ank1015/agents-provider-openai/adapter';

const adapter = new OpenAIProviderAdapter(config, {
  client: fakeOpenAIClient,
  createMessageId: () => 'msg_test',
  now: () => 1_700_000_000_000,
  resolveModel: (modelId) => modelRegistry.get('openai', modelId),
});

If no client override is provided, the adapter creates an openai SDK client from the provider config.

Versioning

This package is currently 0.1.1. Until 1.0.0, adapter APIs and event mapping behavior may evolve as the surrounding agent runtime settles.