NAME

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

VERSION

Version 0.02

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

• prompt - The prompt string to send to Claude

• options - A Claude::Agent::Options object (optional)

• loop - An IO::Async::Loop object (optional, for async integration)

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 $calc = tool(
    'calculate',
    'Perform mathematical calculations',
    { expression => { type => 'string' } },
    sub {
        my ($args) = @_;
        my $result = eval $args->{expression};
        return {
            content => [{ type => 'text', text => "Result: $result" }]
        };
    }
);

Creates an MCP tool definition.

Arguments

• name - Tool name

• description - Tool description

• input_schema - JSON Schema for tool input

• handler - Coderef that handles tool execution

Returns

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

create_sdk_mcp_server

my $server = create_sdk_mcp_server(
    name  => 'my-tools',
    tools => [$calc, $other_tool],
);

Creates an SDK MCP server configuration.

Arguments

• name - Server name

• tools - ArrayRef of tool definitions

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

Returns

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

MESSAGE TYPES

Messages returned from query iteration are instances of:

• Claude::Agent::Message::User - User messages

• Claude::Agent::Message::Assistant - Claude's responses

• Claude::Agent::Message::System - System messages (init, status)

• Claude::Agent::Message::Result - Final result

See Claude::Agent::Message for details.

CONTENT BLOCKS

Assistant messages contain content blocks:

• Claude::Agent::Content::Text - Text content

• Claude::Agent::Content::Thinking - Thinking/reasoning

• Claude::Agent::Content::ToolUse - Tool invocation

• Claude::Agent::Content::ToolResult - Tool result

See Claude::Agent::Content for details.

SEE ALSO

• Claude::Agent::Options - Configuration options

• Claude::Agent::Query - Query iterator

• Claude::Agent::Hook - Hook system

• Claude::Agent::Permission - Permission handling

• Claude::Agent::MCP - MCP server integration

• Claude::Agent::Subagent - Subagent definitions

• Claude::Agent::Client - Persistent session client

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)

cpanm Claude::Agent

perl -MCPAN -e shell
install Claude::Agent