@wavespec/adapter-openai-responses

OpenAI Responses API adapter for Agent Harness.

Overview

This adapter provides integration with the OpenAI Responses API (released March 2025), enabling comprehensive testing of text generation, function calling, built-in tools, streaming, and multi-turn conversations.

Features

• Text Generation: Support for GPT-4o, GPT-4.1, o3-mini, and other models
• Multi-turn Conversations: Automatic conversation continuity via previous_response_id
• Function Calling: Custom tools with JSON schema validation
• Built-in Tools: Web search, file search, code interpreter
• Structured Outputs: JSON schema-based response formatting
• Streaming: AsyncGenerator-based streaming responses
• Error Handling: Comprehensive error translation with CoachingError
• State Management: Automatic conversation state tracking
• Record/Replay: VCR cassette support for deterministic testing

Installation

npm install @wavespec/adapter-openai-responses openai

Requirements

• Node.js 18+
• OpenAI API key
• @wavespec/types >= 0.1.0
• @wavespec/kit >= 0.1.0

Basic Usage

import { OpenAIResponsesAdapter } from "@wavespec/adapter-openai-responses";

// Initialize adapter
const adapter = new OpenAIResponsesAdapter();

// Connect with configuration
await adapter.connect({
  type: "openai-responses",
  apiKey: process.env.OPENAI_API_KEY,
  model: "gpt-4o"
}, context);

// Create a response
const result = await adapter.run({
  operation: "call",
  params: {
    input: "What is the capital of France?"
  }
}, context);

console.log(result.output_text); // "The capital of France is Paris."

Operations

call - Create Response

Create a new response from the OpenAI API.

const result = await adapter.run({
  operation: "call",
  params: {
    input: "Hello, world!",
    model: "gpt-4o",  // optional, uses config default
    max_tokens: 1000,
    temperature: 0.7
  }
}, context);

get - Retrieve Response

Retrieve a previously created response by ID.

const result = await adapter.run({
  operation: "get",
  params: {
    response_id: "resp_abc123"
  }
}, context);

Configuration

Required

• type: Must be "openai-responses"
• apiKey: Your OpenAI API key

Optional

• model: Default model for responses (e.g., "gpt-4o")
• organization: Organization ID for multi-org accounts
• project: Project ID for usage tracking
• baseURL: Custom API endpoint
• timeout: Request timeout in milliseconds
• maxRetries: Maximum retry attempts
• persistState: Auto-inject previous_response_id (default: true)

Multi-turn Conversations

Enable automatic conversation continuity:

await adapter.connect({
  type: "openai-responses",
  apiKey: process.env.OPENAI_API_KEY,
  persistState: true  // default
}, context);

// First message
await adapter.run({
  operation: "call",
  params: { input: "My name is Alice." }
}, context);

// Second message - automatically includes previous_response_id
const result = await adapter.run({
  operation: "call",
  params: { input: "What's my name?" }
}, context);

console.log(result.output_text); // "Your name is Alice."

Function Calling

Define custom tools:

const result = await adapter.run({
  operation: "call",
  params: {
    input: "What's the weather in Paris?",
    tools: [
      {
        type: "function",
        function: {
          name: "get_weather",
          description: "Get current weather for a location",
          parameters: {
            type: "object",
            properties: {
              location: { type: "string" }
            },
            required: ["location"]
          }
        }
      }
    ]
  }
}, context);

Built-in Tools

Use OpenAI's integrated tools:

const result = await adapter.run({
  operation: "call",
  params: {
    input: "Search for recent news about AI",
    tools: [
      { type: "web_search" }
    ]
  }
}, context);

Streaming

Stream responses as they're generated:

const stream = adapter.stream({
  operation: "call",
  params: {
    input: "Write a short story"
  }
}, context);

for await (const chunk of stream) {
  process.stdout.write(chunk.content);
}

Structured Outputs

Get JSON-formatted responses:

const result = await adapter.run({
  operation: "call",
  params: {
    input: "List three primary colors",
    response_format: {
      type: "json_schema",
      json_schema: {
        name: "colors",
        schema: {
          type: "object",
          properties: {
            colors: {
              type: "array",
              items: { type: "string" }
            }
          },
          required: ["colors"]
        }
      }
    }
  }
}, context);

Templates

Explore the templates/ directory for example test specifications:

• basic.yaml - Simple text generation
• init.yaml - Initial setup and configuration
• metadata.yaml - Comprehensive feature examples
• tutorial.yaml - Step-by-step guide

Testing

npm test

Error Handling

All errors are translated to CoachingError with actionable guidance:

try {
  await adapter.run(spec, context);
} catch (error) {
  if (error instanceof CoachingError) {
    console.error(error.code);    // ERROR_API_AUTH
    console.error(error.message); // Authentication failed
    console.error(error.hint);    // Invalid API key provided
    console.error(error.fix);     // Check your OPENAI_API_KEY
  }
}

Architecture

• OpenAIResponsesAdapter: Main adapter class implementing Adapter interface
• OpenAIClient: OpenAI SDK wrapper with connection management
• OpenAIClientManager: Singleton client manager for connection pooling
• OpenAIRequestExtractor: VCR support for record/replay testing
• ResponseNormalizer: Standardizes OpenAI responses to Agent Harness format

Development

# Build the adapter
npm run build

# Run type checking
npm run type-check

# Run linting
npm run lint

License

MIT

Links

• Agent Harness Documentation
• OpenAI API Reference
• OpenAI Responses API Guide

Contributing

This adapter is part of the OpenAI Adapters package. See the main repository for contribution guidelines.