/ 
Langertha-0.503
/ Langertha::Engine::OpenAIResponses

NAME

Langertha::Engine::OpenAIResponses - OpenAI Responses API (reasoning models like gpt-5.5-pro)

VERSION

version 0.503

SYNOPSIS

use Langertha::Engine::OpenAIResponses;

my $engine = Langertha::Engine::OpenAIResponses->new(
    api_key => $ENV{OPENAI_API_KEY},
    model   => 'gpt-5.5-pro',   # reasoning-only model
);

my $response = $engine->simple_chat('Hello');
print $response;

DESCRIPTION

Provides access to OpenAI's Responses API endpoint (POST /v1/responses) for reasoning-only models like gpt-5.5-pro, o3-pro, and future -pro SKUs that are not available on the Chat Completions endpoint (/v1/chat/completions).

Unlike Langertha::Engine::OpenAI which calls /v1/chat/completions, this engine speaks the Open-Responses wire envelope: input instead of messages, top-level instructions, flat tool objects, and an output[] array with type discriminators. That envelope lives in Langertha::Role::ResponsesCompatible (parallel to Langertha::Role::OpenAICompatible); this engine is a thin shell that inherits OpenAI's Bearer auth, API key and model list from Langertha::Engine::OpenAI, composes the Responses envelope on top, and opts out of streaming.

This engine returns a Langertha::Response that is shape-compatible with the chat path, so existing consumers (including Goldmine's complete method) work without modification. Reasoning tokens are normalized to completion_tokens_details.reasoning_tokens for cost lookup compatibility.

Structured output

Structured output goes under text.format (a flat json_schema, not the Chat-Completions nested shape); the Responses API has no response_format param. See "_responses_format_kwargs" in Langertha::Role::ResponsesCompatible.

Server-side tools

OpenAI's hosted tools (web_search, file_search, code_interpreter, image_generation, remote mcp, ...) are supported: this engine composes Langertha::Role::ServerTools, so supports('server_tools') is true. Pass them per request in tools (native hashes or Langertha::ServerTool objects, mixed freely with function tools), or once on the engine:

my $engine = Langertha::Engine::OpenAIResponses->new(
    api_key      => $ENV{OPENAI_API_KEY},
    model        => 'gpt-5.6-luna',
    server_tools => [ { type => 'web_search' } ],
);
my $r = $engine->simple_chat('What is the current stable Perl 5 release?');
say $_->{url} for @{ $r->citations // [] };

The provider runs them within the request. What it did lands on "server_tool_calls" in Langertha::Response, the url_citation annotations of the answer on "citations" in Langertha::Response; neither ever reaches "tool_calls" in Langertha::Response, so chat_with_tools_f executes only function calls and echoes the server items back unchanged on the next turn. The search sources of a web_search_call (request them with include => ['web_search_call.action.sources']) stay on that call's data.

A remote mcp tool must say require_approval => 'never': OpenAI's default is always, which answers with an mcp_approval_request the client has to confirm, and Langertha has no approval flow yet. Anything else croaks before the request is sent (checked by "to" in Langertha::ServerTool).

Function call output shape

The Responses API emits function_call as a top-level output[] item (real reasoning models) or nested inside a message item (older fixtures); chat_response and "extract" in Langertha::ToolCall walk both. Streaming is not supported — Langertha::Role::ResponsesCompatible can stream the envelope, but this engine opts out (see below).

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.