/ 
Langertha-0.305
River stage one • 1 direct dependent • 1 total dependent
/ Langertha::Role::Tools

NAME

Langertha::Role::Tools - Role for MCP tool calling support

VERSION

version 0.305

SYNOPSIS

use IO::Async::Loop;
use Net::Async::MCP;
use Future::AsyncAwait;

my $loop = IO::Async::Loop->new;

# Set up an MCP server with tools
my $mcp = Net::Async::MCP->new(server => $my_mcp_server);
$loop->add($mcp);
await $mcp->initialize;

# Create engine with MCP servers (native tool calling)
my $engine = Langertha::Engine::Anthropic->new(
    api_key     => $ENV{ANTHROPIC_API_KEY},
    model       => 'claude-sonnet-4-6',
    mcp_servers => [$mcp],
);

my $response = await $engine->chat_with_tools_f(
    'Use the available tools to answer my question'
);

# Hermes tool calling (for APIs without native tool support)
my $engine = Langertha::Engine::AKI->new(
    api_key     => $ENV{AKI_API_KEY},
    mcp_servers => [$mcp],
);

DESCRIPTION

This role adds MCP (Model Context Protocol) tool calling support to Langertha engines. It provides the "chat_with_tools_f" method which implements the full async tool-calling loop:

1. Gather available tools from all configured MCP servers
2. Send a chat request with tool definitions to the LLM
3. If the LLM returns tool calls, execute them via MCP
4. Feed tool results back to the LLM and repeat
5. When the LLM returns final text, return it

Engines must provide implementations for five methods that handle engine-specific tool format conversion: format_tools, response_tool_calls, extract_tool_call, format_tool_results, and response_text_content. Native API engines (OpenAI, Anthropic, Gemini, etc.) implement these directly. Engines without native tool support compose Langertha::Role::HermesTools which provides implementations using XML tags.

mcp_servers

mcp_servers => [$mcp1, $mcp2]

ArrayRef of Net::Async::MCP instances to use as tool providers. Defaults to an empty ArrayRef. At least one server must be configured before calling "chat_with_tools_f".

tool_max_iterations

tool_max_iterations => 20

Maximum number of tool-calling round trips before aborting with an error. Defaults to 10. Increase for complex multi-step tool workflows.

build_tool_chat_request

my $request = $self->build_tool_chat_request($conversation, $formatted_tools);

Builds an HTTP request for a tool-calling chat turn. The default implementation passes tools as an API parameter via chat_request. Overridden by Langertha::Role::HermesTools to inject tools into the system prompt instead.

chat_with_tools_f

my $response = await $engine->chat_with_tools_f(@messages);

Async tool-calling chat loop. Accepts the same message arguments as "simple_chat" in Langertha::Role::Chat. Gathers tools from all "mcp_servers", sends the request, executes any tool calls returned by the LLM, and repeats until the LLM returns a final text response or "tool_max_iterations" is exceeded. Returns a Future that resolves to the final text response.

SEE ALSO

SUPPORT

Issues

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

CONTRIBUTING

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

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudss.us/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

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