/ 
Langertha-0.503
/ Langertha::Role::ServerTools

NAME

Langertha::Role::ServerTools - Role for an engine whose wire accepts provider-native server-side tools

VERSION

version 0.503

SYNOPSIS

my $engine = Langertha::Engine::OpenAIResponses->new(
    api_key      => $ENV{OPENAI_API_KEY},
    model        => 'gpt-5.6-luna',
    server_tools => [ { type => 'web_search' } ],   # sent on every request
);

say 'server tools ok' if $engine->supports('server_tools');

DESCRIPTION

Marks an engine whose wire takes provider-native server-side tool entries in tools -- tools the provider runs itself, such as web_search -- and contributes the server_tools capability flag (ADR 0002). The flag says that the wire accepts them, not which types a given model honors.

The role holds the per-engine default list ("server_tools") and the "_server_tool_wire_check" hook. The wire envelope that consumes the engine (Langertha::Role::ResponsesCompatible) appends the defaults to every request, so simple_chat, chat_f and chat_with_tools_f all send them. It does not require Langertha::Role::Tools.

Server-side calls come back on "server_tool_calls" in Langertha::Response; see Langertha::ServerTool and ADR 0030.

server_tools

server_tools => [ { type => 'web_search' }, $server_tool_object ]

Server-side tools sent with every chat request of this engine, after any tools of the request itself. Each entry is a Langertha::ServerTool or a provider-native hash that "from_hash" in Langertha::ServerTool recognises for the engine's wire; anything else (a bare string such as 'web_search', a function tool, a type Langertha does not list) croaks when the request is built. Wrap an unlisted type as Langertha::ServerTool->new( wire => ..., spec => ..., unlisted => 1 ).

The request wins. A default is left out when the request's own tools already carry a server tool of the same kind: the same type, and for mcp the same server_label as well. So a per-request { type => 'web_search', search_context_size => 'high' } replaces a default web_search instead of sending it twice. The kind is the type only, not the tool's target: a request file_search over other vector_store_ids also replaces a default file_search, so pass both stores in the request when both should be searched.

Defaults to an empty ArrayRef.

_server_tool_wire_check

my $spec = $engine->_server_tool_wire_check($server_tool);

Engine hook, called once per Langertha::ServerTool while a request is built. Returns the native hash to send; may croak or rewrite it where the provider diverges from the shared wire. The default returns the tool's native hash unchanged. It runs after "to" in Langertha::ServerTool, which already refuses a remote mcp tool without require_approval => 'never'.

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.