/ 
Langertha-0.503
/ Langertha::ServerToolCall

NAME

Langertha::ServerToolCall - Record of one tool call the provider executed itself

VERSION

version 0.503

SYNOPSIS

my $response = await $engine->chat_f(
    messages => [ { role => 'user', content => 'Current Perl release?' } ],
    tools    => [ { type => 'web_search' } ],
);

for my $call ( @{ $response->server_tool_calls // [] } ) {
    say $call->type, ' ', $call->id, ' ', $call->status // '';
    my $item = $call->data;    # the provider's item, verbatim
}

DESCRIPTION

A server-side tool call is one the provider ran itself during the request -- a web search, a file search, a remote MCP call. The client has nothing to do for it, so it is kept apart from Langertha::ToolCall, which means "a call the client must act on": these records land on "server_tool_calls" in Langertha::Response, never on "tool_calls" in Langertha::Response, and chat_with_tools_f never executes them (ADR 0003 Update k206, ADR 0030).

The record is deliberately thin: the wire item type, its id and status, and the item itself verbatim under "data". Inputs and results are not normalized across providers.

type

The wire item type, for example web_search_call, file_search_call or mcp_call. Required.

id

The provider's item id. Empty when the item carried none.

status

The item status (for example completed), when the provider sent one. Test with has_status.

data

The provider's item, verbatim.

from_responses

my $call = Langertha::ServerToolCall->from_responses($output_item);

Builds a record from one Responses output[] item, or returns undef when the item is not a server-side call.

extract

my @calls = Langertha::ServerToolCall->extract( responses => $data );

Returns every server-side call item of a decoded response, in wire order. Pinned to the wire like "extract" in Langertha::ToolCall. Only responses is supported; other wires croak.

to_hash

Returns { type, id, status?, data }.

TO_JSON

Delegates to "to_hash", for JSON encoders with convert_blessed.

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.