/ 
Claude-Agent-0.10
/ Claude::Agent

NAME

Claude::Agent - Perl SDK for the Claude Agent SDK

VERSION

Version 0.10

SYNOPSIS

use Claude::Agent qw(query tool create_sdk_mcp_server);
use Claude::Agent::Options;

# Simple query
my $options = Claude::Agent::Options->new(
    allowed_tools   => ['Read', 'Glob', 'Grep'],
    permission_mode => 'bypassPermissions',
);

my $iter = query(
    prompt  => "Find all TODO comments in the codebase",
    options => $options,
);

while (my $msg = $iter->next) {
    if ($msg->isa('Claude::Agent::Message::Result')) {
        print $msg->result, "\n";
        last;
    }
}

# Async iteration with IO::Async
use IO::Async::Loop;
use Future::AsyncAwait;

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

async sub run_agent {
    my ($loop) = @_;

    # Pass the loop for proper async integration
    my $iter = query(
        prompt  => "Analyze this codebase",
        options => Claude::Agent::Options->new(
            allowed_tools => ['Read', 'Glob', 'Grep'],
        ),
        loop => $loop,
    );

    while (my $msg = await $iter->next_async) {
        if ($msg->isa('Claude::Agent::Message::Result')) {
            print $msg->result, "\n";
            last;
        }
    }
}

run_agent($loop)->get;

DESCRIPTION

Claude::Agent is a Perl SDK for the Claude Agent SDK, providing programmatic access to Claude's agentic capabilities. It allows you to build AI agents that can read files, run commands, search the web, edit code, and more.

The SDK communicates with the Claude CLI and provides:

  • Streaming message iteration (blocking and async)

  • Tool permission management

  • Hook system for intercepting tool calls

  • MCP (Model Context Protocol) server integration

  • Subagent support for parallel task execution

  • Session management (resume, fork)

  • Structured output support

EXPORTED FUNCTIONS

query

my $iter = query(
    prompt  => $prompt,
    options => $options,
    loop    => $loop,      # optional, for async integration
);

Creates a new query and returns an iterator for streaming messages.

Arguments

Returns

A Claude::Agent::Query object that can be iterated to receive messages.

Note: For proper async behavior, pass your application's IO::Async::Loop. This allows multiple queries to share the same event loop.

tool

my $calculator = tool(
    'calculate',
    'Perform basic arithmetic calculations',
    {
        type       => 'object',
        properties => {
            a => {
                type        => 'number',
                description => 'First operand',
            },
            b => {
                type        => 'number',
                description => 'Second operand',
            },
            operation => {
                type        => 'string',
                enum        => ['add', 'subtract', 'multiply', 'divide'],
                description => 'The arithmetic operation to perform',
            },
        },
        required => ['a', 'b', 'operation'],
    },
    sub {
        my ($args) = @_;
        my ($a, $b, $op) = @{$args}{qw(a b operation)};

        my $result = $op eq 'add'      ? $a + $b
                   : $op eq 'subtract' ? $a - $b
                   : $op eq 'multiply' ? $a * $b
                   : $op eq 'divide'   ? ($b != 0 ? $a / $b : 'Error: division by zero')
                   :                     'Error: unknown operation';

        return {
            content => [{ type => 'text', text => "Result: $result" }]
        };
    }
);

Creates an MCP tool definition for use with SDK MCP servers. The handler executes locally in your Perl process when Claude calls the tool.

Arguments

  • name - Tool name (will be prefixed with mcp__<server>__)

  • description - Description of what the tool does

  • input_schema - JSON Schema defining the tool's input parameters

  • handler - Coderef that executes the tool logic

Handler Signature

sub handler {
    my ($args) = @_;

    # $args is a hashref of input parameters

    # Return a result hashref:
    return {
        content => [
            { type => 'text', text => 'Result text' },
        ],
        is_error => 0,  # Optional, default false
    };
}

Returns

A Claude::Agent::MCP::ToolDefinition object.

create_sdk_mcp_server

my $server = create_sdk_mcp_server(
    name    => 'utils',
    tools   => [$greeter],
    version => '1.0.0',
);

# Use in options
my $options = Claude::Agent::Options->new(
    mcp_servers   => { utils => $server },
    allowed_tools => ['mcp__utils__greet'],
);

Creates an SDK MCP server that runs tool handlers locally in your Perl process. When Claude calls a tool from this server, the SDK intercepts the request, executes your handler, and returns the result.

This is the recommended way to extend Claude with custom tools that need access to your application's state or APIs.

Arguments

  • name - Server name (used in tool naming: mcp__<name>__<tool>)

  • tools - ArrayRef of Claude::Agent::MCP::ToolDefinition objects

  • version - Server version (default: '1.0.0')

Returns

A Claude::Agent::MCP::Server object.

How It Works

The SDK creates a Unix socket and spawns a lightweight MCP server process. The CLI connects to this server via stdio. When a tool is called:

1. CLI sends the tool request to the MCP server process 2. MCP server forwards the request to your Perl process via the socket 3. Your handler executes and returns a result 4. Result flows back through the socket to the CLI

This architecture allows your handlers to access your application's state, database connections, and other resources.

MESSAGE TYPES

Messages returned from query iteration are instances of:

See Claude::Agent::Message for details.

CONTENT BLOCKS

Assistant messages contain content blocks:

See Claude::Agent::Content for details.

SEE ALSO

AUTHOR

LNATION, <email at lnation.org>

BUGS

Please report any bugs or feature requests to the GitHub issue tracker at https://github.com/lnation/Claude-Agent/issues.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Claude::Agent

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)