OpenResponses Dart Client

• Features
• Why choose this client?
• Quickstart
• Configuration
• Usage
• Error Handling
• Examples
• API Coverage
• Official Documentation
• Sponsor
• License

Use OpenResponsesClient.fromEnvironment() for OpenAI-style defaults, or provide OpenResponsesConfig directly when you target another provider. This keeps provider switching explicit and easy to test.

import 'package:open_responses/open_responses.dart';

Future<void> main() async {
  final client = OpenResponsesClient(
    config: OpenResponsesConfig(
      baseUrl: 'http://localhost:11434/v1',
      timeout: const Duration(minutes: 5),
      retryPolicy: RetryPolicy(
        maxRetries: 3,
        initialDelay: Duration(seconds: 1),
      ),
    ),
  );

  client.close();
}

Environment variables:

• OPENAI_API_KEY
• OPENAI_BASE_URL

Use explicit configuration on web builds where runtime environment variables are not available.

The CreateResponseRequest.text(...) helper keeps simple requests short, while the full request type remains available for advanced configurations. response.outputText is the fastest path for text-first integrations.

import 'package:open_responses/open_responses.dart';

Future<void> main() async {
  final client = OpenResponsesClient(
    config: OpenResponsesConfig(
      baseUrl: 'https://api.openai.com/v1',
      authProvider: BearerTokenProvider('YOUR_API_KEY'),
    ),
  );

  try {
    final response = await client.responses.create(
      CreateResponseRequest.text(
        model: 'gpt-4o',
        input: 'Summarize why provider portability matters.',
      ),
    );

    print(response.outputText);
  } finally {
    client.close();
  }
}

→ Full example

Streaming works through a runner helper or manual event iteration. That makes it easy to bind partial text updates to a CLI, server-sent event bridge, or Flutter state notifier.

import 'dart:io';

import 'package:open_responses/open_responses.dart';

Future<void> main() async {
  final client = OpenResponsesClient.fromEnvironment();

  try {
    final runner = client.responses.stream(
      CreateResponseRequest.text(
        model: 'gpt-4o',
        input: 'Write a short note about Flutter desktop.',
      ),
    )..onTextDelta(stdout.write);

    await runner.finalResponse;
  } finally {
    client.close();
  }
}

→ Full example

Tool calling is declared in the request, which keeps the provider-neutral contract intact. This is useful when you want one agent loop that can run against hosted or local providers.

import 'package:open_responses/open_responses.dart';

Future<void> main() async {
  final client = OpenResponsesClient.fromEnvironment();

  try {
    final response = await client.responses.create(
      CreateResponseRequest(
        model: 'gpt-4o',
        input: const ResponseTextInput('What is the weather in Berlin?'),
        tools: [
          FunctionTool(
            name: 'get_weather',
            description: 'Get the current weather',
            parameters: const {
              'type': 'object',
              'properties': {
                'location': {'type': 'string'},
              },
              'required': ['location'],
            },
          ),
        ],
      ),
    );

    print(response.functionCalls.length);
  } finally {
    client.close();
  }
}

→ Full example

OpenResponses keeps follow-up turns provider-neutral through previousResponseId. That is the main portability feature when you need stateful assistants without rewriting request history handling for each backend.

import 'package:open_responses/open_responses.dart';

Future<void> main() async {
  final client = OpenResponsesClient.fromEnvironment();

  try {
    final first = await client.responses.create(
      CreateResponseRequest.text(
        model: 'gpt-4o',
        input: 'My name is Alice.',
      ),
    );

    final second = await client.responses.create(
      CreateResponseRequest(
        model: 'gpt-4o',
        input: const ResponseTextInput('What is my name?'),
        previousResponseId: first.id,
      ),
    );

    print(second.outputText);
  } finally {
    client.close();
  }
}

→ Full example

Structured output uses the same response surface and adds a JSON schema under text.format. That keeps extraction workflows consistent even when you swap providers behind the same Dart code.

import 'package:open_responses/open_responses.dart';

Future<void> main() async {
  final client = OpenResponsesClient.fromEnvironment();

  try {
    final response = await client.responses.create(
      CreateResponseRequest(
        model: 'gpt-4o',
        input: const ResponseTextInput('List three fruits and their colors.'),
        text: TextConfig(
          format: JsonSchemaFormat(
            name: 'fruits',
            schema: const {
              'type': 'object',
              'properties': {
                'fruits': {
                  'type': 'array',
                  'items': {
                    'type': 'object',
                    'properties': {
                      'name': {'type': 'string'},
                      'color': {'type': 'string'},
                    },
                    'required': ['name', 'color'],
                  },
                },
              },
              'required': ['fruits'],
            },
          ),
        ),
      ),
    );

    print(response.outputText);
  } finally {
    client.close();
  }
}

→ Full example

The provider switch happens in OpenResponsesConfig, not in the request body. That keeps your higher-level application logic independent from the underlying deployment target.

import 'package:open_responses/open_responses.dart';

Future<void> main() async {
  final client = OpenResponsesClient(
    config: const OpenResponsesConfig(
      baseUrl: 'http://localhost:11434/v1',
    ),
  );

  try {
    final response = await client.responses.create(
      CreateResponseRequest.text(
        model: 'llama3.2',
        input: 'Explain what hot reload means.',
      ),
    );

    print(response.outputText);
  } finally {
    client.close();
  }
}

→ Full example

open_responses throws typed exceptions so provider differences do not collapse into raw HTTP status handling. Catch ApiException first, then fall back to OpenResponsesException for transport or client-side failures.

import 'dart:io';

import 'package:open_responses/open_responses.dart';

Future<void> main() async {
  final client = OpenResponsesClient.fromEnvironment();

  try {
    await client.responses.create(
      CreateResponseRequest.text(
        model: 'gpt-4o',
        input: 'Ping',
      ),
    );
  } on RateLimitException catch (error) {
    stderr.writeln('Retry after: ${error.retryAfter}');
  } on ApiException catch (error) {
    stderr.writeln('Provider API error ${error.statusCode}: ${error.message}');
  } on OpenResponsesException catch (error) {
    stderr.writeln('OpenResponses client error: $error');
  } finally {
    client.close();
  }
}

→ Full example