/ 
Langertha-0.201
River stage zero No dependents
/ Langertha::Raider

NAME

Langertha::Raider - Autonomous agent with conversation history and MCP tools

VERSION

version 0.201

SYNOPSIS

use IO::Async::Loop;
use Future::AsyncAwait;
use Net::Async::MCP;
use MCP::Server;
use Langertha::Engine::Anthropic;
use Langertha::Raider;

# Set up MCP server with tools
my $server = MCP::Server->new(name => 'demo', version => '1.0');
$server->tool(
    name => 'list_files',
    description => 'List files in a directory',
    input_schema => {
        type => 'object',
        properties => { path => { type => 'string' } },
        required => ['path'],
    },
    code => sub { $_[0]->text_result(join("\n", glob("$_[1]->{path}/*"))) },
);

my $loop = IO::Async::Loop->new;
my $mcp = Net::Async::MCP->new(server => $server);
$loop->add($mcp);

async sub main {
    await $mcp->initialize;

    my $engine = Langertha::Engine::Anthropic->new(
        api_key     => $ENV{ANTHROPIC_API_KEY},
        mcp_servers => [$mcp],
    );

    my $raider = Langertha::Raider->new(
        engine  => $engine,
        mission => 'You are a code explorer. Investigate files thoroughly.',
    );

    # First raid — uses tools, builds history
    my $r1 = await $raider->raid_f('What files are in the current directory?');
    say $r1;

    # Second raid — has context from first conversation
    my $r2 = await $raider->raid_f('Tell me more about the first file you found.');
    say $r2;

    # Check metrics
    my $m = $raider->metrics;
    say "Raids: $m->{raids}, Tool calls: $m->{tool_calls}, Time: $m->{time_ms}ms";

    # Reset for a fresh conversation
    $raider->clear_history;
}

main()->get;

DESCRIPTION

Langertha::Raider is an autonomous agent that wraps a Langertha engine with MCP tools. It maintains conversation history across multiple interactions (raids), enabling multi-turn conversations where the LLM can reference prior context.

Key features:

  • Conversation history persisted across raids

  • Mission (system prompt) separate from engine's system_prompt

  • Automatic MCP tool calling loop

  • Cumulative metrics tracking

  • Hermes tool calling support (inherited from engine)

  • Mid-raid context injection via inject() and on_iteration

History management: Only user messages and final assistant text responses are persisted in history. Intermediate tool-call messages (assistant tool requests and tool results) are NOT persisted, preventing token bloat across long conversations.

engine

Required. A Langertha engine instance with MCP servers configured. The engine must compose Langertha::Role::Tools.

mission

Optional system prompt for the Raider. This is separate from the engine's own system_prompt — the Raider's mission takes precedence and is prepended to every conversation.

history

ArrayRef of message hashes representing the conversation history. Automatically managed by raid/raid_f. Can be inspected or manually set.

max_iterations

Maximum number of tool-calling round trips per raid. Defaults to 10.

max_context_tokens

Optional. Enables auto-compression when set. When prompt token usage exceeds context_compress_threshold * max_context_tokens, the working history is summarized via LLM before the next raid.

context_compress_threshold

Fraction of max_context_tokens that triggers compression. Defaults to 0.75 (75%).

compression_prompt

System prompt used for history summarization. Customizable. The default instructs the LLM to preserve key facts, decisions, and context.

compression_engine

Optional separate engine for compression (e.g. a cheaper model). Falls back to engine when not set.

session_history

Full chronological archive of ALL messages including tool calls and results. Never auto-compressed. Persists across clear_history and reset. Only cleared manually via $raider->session_history([]).

on_iteration

Optional CodeRef called before each LLM call (iterations 2+). Receives ($raider, $iteration) and returns an arrayref of messages to inject, or undef/empty to skip.

my $raider = Langertha::Raider->new(
    engine => $engine,
    on_iteration => sub {
        my ($raider, $iteration) = @_;
        return ['Check the error log'] if $iteration == 3;
        return;
    },
);

metrics

HashRef of cumulative metrics across all raids:

{
    raids      => 3,       # Number of completed raids
    iterations => 7,       # Total LLM round trips
    tool_calls => 12,      # Total tool invocations
    time_ms    => 4500.2,  # Total wall-clock time in milliseconds
}

langfuse_trace_name

Name for the Langfuse trace created per raid. Defaults to 'raid'.

langfuse_user_id

Optional user ID passed to the Langfuse trace.

langfuse_session_id

Optional session ID passed to the Langfuse trace. Use this to group multiple raids into a single Langfuse session.

langfuse_tags

Optional tags (ArrayRef[Str]) passed to the Langfuse trace.

langfuse_release

Optional release identifier passed to the Langfuse trace.

langfuse_version

Optional version string passed to the Langfuse trace.

langfuse_metadata

Optional metadata HashRef merged into the Langfuse trace metadata (alongside auto-generated fields like mission and history_length).

clear_history

$raider->clear_history;

Clears conversation history and pending injections while preserving metrics.

inject

$raider->inject('Also check the test files');
$raider->inject({ role => 'user', content => 'Focus on .pm files' });

Queues messages to be injected into the conversation at the next iteration. Strings are automatically wrapped as user messages. The Raider drains the queue before each LLM call (iterations 2+).

reset

$raider->reset;

Clears both conversation history and metrics.

compress_history_f

my $summary = await $raider->compress_history_f;

Async. Summarizes the current working history via LLM and replaces it with the summary. Uses compression_engine if set, otherwise falls back to engine. A marker is added to session_history.

compress_history

my $summary = $raider->compress_history;

Synchronous wrapper around compress_history_f.

register_session_history_tool

$raider->register_session_history_tool($mcp_server);

Registers a session_history MCP tool on the given server, allowing the LLM to query its own full session history. Supports query (text filter) and last_n (return last N messages) parameters.

raid

my $response = $raider->raid(@messages);

Synchronous wrapper around raid_f. Sends messages, runs the tool loop, and returns the final text response. Updates history and metrics.

raid_f

my $response = await $raider->raid_f(@messages);

Async tool-calling conversation. Accepts the same message arguments as simple_chat (strings become user messages, hashrefs pass through). Returns a Future resolving 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.