README

A powerful PHP framework for building AI agents with Claude, featuring ReAct loops, tool orchestration, hierarchical agents, and advanced agentic patterns.

Features

🔄 Loop Strategies - ReactLoop, PlanExecuteLoop, ReflectionLoop, and StreamingLoop
🛠️ Tool System - Easy tool definition, registration, and execution
🧠 Memory Management - Persistent state across agent iterations
🏗️ Agent Patterns - ReAct, Plan-Execute, Reflection, Hierarchical, and more
🤖 Adaptive Agent Service - Intelligent agent selection, validation, and auto-adaptation
📊 Output Parsers - JSON, XML, Markdown, CSV, Lists, and Regex with auto-detection
🔗 Chain Composition - Sequential, parallel, and conditional chain execution
⚡ Production Ready - Retry logic, error handling, logging, and monitoring
🚀 Async/Concurrent - AMPHP-powered parallel execution for batch operations
🎯 Extensible - Build custom agents and patterns with ease

Installation

composer require claude-php/agent

Quick Start

<?php

use ClaudeAgents\Agent;
use ClaudeAgents\Tools\Tool;
use ClaudePhp\ClaudePhp;

$client = new ClaudePhp(apiKey: getenv('ANTHROPIC_API_KEY'));

// Create a simple calculator tool
$calculator = Tool::create('calculate')
    ->description('Perform mathematical calculations')
    ->parameter('expression', 'string', 'Math expression to evaluate')
    ->required('expression')
    ->handler(function (array $input): string {
        return (string) eval("return {$input['expression']};");
    });

// Create an agent with the tool
$agent = Agent::create($client)
    ->withTool($calculator)
    ->withSystemPrompt('You are a helpful assistant that can perform calculations.');

// Run the agent
$result = $agent->run('What is 25 * 17 + 100?');

echo $result->getAnswer();

Progress Updates (Streaming UI / Live Status)

While an agent is running, you can receive continuous progress events (iteration output, tool results, and streaming deltas when using StreamingLoop) via onUpdate():

use ClaudeAgents\Progress\AgentUpdate;

$agent = Agent::create($client)
    ->onUpdate(function (AgentUpdate $update): void {
        // Send to WebSocket/SSE, update CLI spinner, etc.
        // $update->getType() and $update->getData() are structured and stable.
    });

Core Concepts

Loop Strategies

The framework provides multiple loop strategies for different types of tasks:

ReactLoop (Default)

The Reason-Act-Observe pattern for general-purpose tasks:

use ClaudeAgents\Loops\ReactLoop;

$agent = Agent::create()
    ->withLoopStrategy(new ReactLoop())
    ->withTools([$searchTool, $calculatorTool])
    ->maxIterations(10);

PlanExecuteLoop

Plan first, then execute systematically for complex multi-step tasks:

use ClaudeAgents\Loops\PlanExecuteLoop;

$loop = new PlanExecuteLoop(allowReplan: true);
$loop->onPlanCreated(function ($steps) {
    echo "Plan: " . count($steps) . " steps\n";
});

$agent = Agent::create()
    ->withLoopStrategy($loop)
    ->withTools($tools);

ReflectionLoop

Generate, reflect, and refine for high-quality outputs:

use ClaudeAgents\Loops\ReflectionLoop;

$loop = new ReflectionLoop(
    maxRefinements: 3,
    qualityThreshold: 8
);

$agent = Agent::create()
    ->withLoopStrategy($loop);

See the Loop Strategies Guide for detailed documentation.

Tools

Tools give Claude the ability to interact with the world:

use ClaudeAgents\Tools\Tool;

// Fluent API for tool creation
$weatherTool = Tool::create('get_weather')
    ->description('Get current weather for a location')
    ->parameter('city', 'string', 'City name')
    ->parameter('units', 'string', 'Temperature units (celsius/fahrenheit)', false)
    ->required('city')
    ->handler(function (array $input): string {
        // Your weather API call here
        return json_encode(['temp' => 72, 'conditions' => 'sunny']);
    });

Agent Patterns

Basic ReAct Agent

use ClaudeAgents\Agents\ReactAgent;

$agent = new ReactAgent($client, [
    'tools' => [$tool1, $tool2],
    'max_iterations' => 10,
    'system' => 'You are a helpful assistant.',
]);

$result = $agent->run('Complete this task...');

Hierarchical Agent (Master-Worker)

use ClaudeAgents\Agents\HierarchicalAgent;
use ClaudeAgents\Agents\WorkerAgent;

$master = new HierarchicalAgent($client);

$master->registerWorker('researcher', new WorkerAgent($client, [
    'specialty' => 'research and information gathering',
]));

$master->registerWorker('writer', new WorkerAgent($client, [
    'specialty' => 'writing and content creation',
]));

$result = $master->run('Research PHP 8 features and write a summary');

Reflection Agent

use ClaudeAgents\Agents\ReflectionAgent;

$agent = new ReflectionAgent($client, [
    'max_refinements' => 3,
    'quality_threshold' => 8,
]);

$result = $agent->run('Write a function to validate email addresses');
// Agent will generate, reflect, and refine until quality threshold is met

Memory & State

use ClaudeAgents\Memory\Memory;
use ClaudeAgents\Memory\FileMemory;

// In-memory state
$memory = new Memory();
$memory->set('user_preference', 'dark_mode');

// Persistent file-based memory
$memory = new FileMemory('/path/to/state.json');

$agent = Agent::create()
    ->withMemory($memory)
    ->run('Remember my preferences...');

Production Features

use ClaudeAgents\Agent;
use ClaudeAgents\Tools\ToolResult;
use Psr\Log\LoggerInterface;

$agent = Agent::create($client)
    ->withLogger($psrLogger)
    ->withRetry(maxAttempts: 3, delayMs: 1000) // ms
    ->onError(function (Throwable $e, int $attempt) {
        // Handle errors
    })
    ->onToolExecution(function (string $tool, array $input, ToolResult $result) {
        // Monitor tool usage
    })
    ->onUpdate(function (\ClaudeAgents\Progress\AgentUpdate $update) {
        // Unified progress updates (iterations, tools, streaming deltas, start/end)
    });

MAKER Agent (Massively Decomposed Agentic Processes)

⚡ NEW: Solve million-step tasks with near-zero error rates!

use ClaudeAgents\Agents\MakerAgent;

// Based on: "Solving a Million-Step LLM Task with Zero Errors"
// https://arxiv.org/html/2511.09030v1

$maker = new MakerAgent($client, [
    'voting_k' => 3,                    // First-to-ahead-by-3 voting
    'enable_red_flagging' => true,      // Detect unreliable responses
    'max_decomposition_depth' => 10,    // Extreme decomposition
]);

// Can reliably handle tasks requiring millions of steps
$result = $maker->run('Solve this complex multi-step problem...');

// Track detailed execution statistics
$stats = $result->getMetadata()['execution_stats'];
echo "Steps: {$stats['total_steps']}\n";
echo "Votes: {$stats['votes_cast']}\n";
echo "Error Rate: " . $result->getMetadata()['error_rate'] . "\n";

Key Features:

✓ Extreme task decomposition into atomic subtasks
✓ Multi-agent voting for error correction at each step
✓ Red-flagging to detect and retry unreliable responses
✓ Scales to organization-level tasks (millions of steps)
✓ Sub-linear cost scaling with proper decomposition

Paper Results: Successfully solved 20-disk Towers of Hanoi (1,048,575 moves) with ZERO errors!

See MakerAgent Documentation for detailed documentation.

Adaptive Agent Service

🎯 NEW: Intelligent agent selection with automatic validation and adaptation!

use ClaudeAgents\Agents\AdaptiveAgentService;

// Create service that automatically selects the best agent
$service = new AdaptiveAgentService($client, [
    'max_attempts' => 3,              // Try up to 3 times
    'quality_threshold' => 7.0,       // Require 7/10 quality
    'enable_reframing' => true,       // Reframe on failure
]);

// Register various agents with their profiles
$service->registerAgent('react', $reactAgent, [
    'type' => 'react',
    'complexity_level' => 'medium',
    'quality' => 'standard',
]);

$service->registerAgent('reflection', $reflectionAgent, [
    'type' => 'reflection',
    'complexity_level' => 'medium',
    'quality' => 'high',
]);

// Service automatically:
// 1. Analyzes the task
// 2. Selects the best agent
// 3. Validates the result
// 4. Retries with different agents if needed
$result = $service->run('Your task here');

echo "Agent used: {$result->getMetadata()['final_agent']}\n";
echo "Quality: {$result->getMetadata()['final_quality']}/10\n";

Key Features:

✓ Intelligent agent selection based on task analysis
✓ Automatic quality validation and scoring
✓ Adaptive retry with different agents on failure
✓ Request reframing for better results
✓ Performance tracking and learning

See docs/adaptive-agent-service.md for detailed documentation.

Agent Patterns Reference

Pattern	Use Case	Scalability	Example
ReAct	General-purpose autonomous tasks	~100 steps	Research, calculations, data processing
Plan-Execute	Complex multi-step tasks	~1K steps	Project planning, workflows
Reflection	Quality-critical outputs	~500 steps	Code generation, writing
Hierarchical	Multi-domain tasks	~5K steps	Business analysis, reports
Chain-of-Thought	Complex reasoning	~500 steps	Math problems, logic puzzles
Tree-of-Thoughts	Exploration tasks	~1K steps	Creative writing, optimization
MAKER/MDAP	Million-step tasks, zero errors	Millions+	Long sequences, organization-level tasks
Monitoring	System monitoring, anomaly detection	Real-time	Server metrics, performance tracking
Scheduler	Task scheduling, cron jobs	Continuous	Automated workflows, batch processing
Alert	Intelligent alerting, notifications	Real-time	System alerts, incident management
Reflex	Rule-based responses	Instant	FAQs, simple automation
Model-Based	State-aware decision making	~500 steps	Planning, simulation
Utility-Based	Optimization, trade-offs	~100 steps	Resource allocation, decision support
Learning	Adaptive behavior, feedback loops	Continuous	Personalization, strategy evolution
Collaboration	Multi-agent coordination (AutoGen)	~5K steps	Team workflows, complex research
TaskPrioritization	Goal-driven task management (BabyAGI)	~1K steps	Project breakdown, execution
Coordinator	Agent orchestration, load balancing	~10K steps	Distributed systems, agent networks
Dialog	Conversational AI, context tracking	Continuous	Customer service, assistants
IntentClassifier	Intent recognition, entity extraction	Instant	Command routing, NLU
EnvironmentSimulator	What-if analysis, prediction	~100 steps	Testing, planning
SolutionDiscriminator	Solution evaluation, voting	~50 steps	Quality assurance, selection
MemoryManager	Knowledge management, retrieval	Continuous	Shared memory, context
AdaptiveAgentService	Meta-agent selection & validation	Varies	Auto-optimization, quality assurance

Configuration

use ClaudeAgents\Config\AgentConfig;

$config = new AgentConfig([
    'model' => 'claude-sonnet-4-5',
    'max_tokens' => 4096,
    'max_iterations' => 10,
    'temperature' => 0.7,
    'timeout' => 30.0,
    'retry' => [
        'max_attempts' => 3,
        'delay_ms' => 1000,
        'multiplier' => 2,
    ],
]);

$agent = Agent::create()->withConfig($config);

Async & Concurrent Execution

The framework leverages AMPHP for true asynchronous and concurrent execution:

Batch Processing

Process multiple agent tasks concurrently:

use ClaudeAgents\Async\BatchProcessor;

$processor = BatchProcessor::create($agent);

$processor->addMany([
    'task1' => 'Summarize this document...',
    'task2' => 'Analyze this data...',
    'task3' => 'Generate a report...',
]);

// Execute with concurrency of 5
$results = $processor->run(concurrency: 5);

// Get statistics
$stats = $processor->getStats();
echo "Success rate: " . ($stats['success_rate'] * 100) . "%\n";

Parallel Tool Execution

Execute multiple tool calls simultaneously:

use ClaudeAgents\Async\ParallelToolExecutor;

$executor = new ParallelToolExecutor($tools);

$calls = [
    ['tool' => 'get_weather', 'input' => ['city' => 'London']],
    ['tool' => 'get_time', 'input' => ['timezone' => 'UTC']],
    ['tool' => 'calculate', 'input' => ['expression' => '42 * 8']],
];

// All execute in parallel!
$results = $executor->execute($calls);

Promise-Based Workflows

Use promises for async operations:

use ClaudeAgents\Async\Promise;

$promises = $processor->runAsync();

// Do other work...

// Wait for all to complete
$results = Promise::all($promises);

See the examples directory for complete async/concurrent examples.

Output Parsers

Transform unstructured LLM responses into structured data:

use ClaudeAgents\Parsers\ParserFactory;
use ClaudeAgents\Chains\LLMChain;

$factory = ParserFactory::create();

// JSON with schema validation
$jsonParser = $factory->json([
    'type' => 'object',
    'required' => ['sentiment', 'confidence']
]);

// Auto-detect and parse
$result = $factory->autoParse($llmResponse);

// Use with chains
$chain = LLMChain::create($client)
    ->withPromptTemplate($template)
    ->withOutputParser(fn($text) => $jsonParser->parse($text));

Available Parsers:

JsonParser - Extract and validate JSON
ListParser - Parse bullet/numbered lists
RegexParser - Pattern-based extraction
XmlParser - Parse XML/HTML
MarkdownParser - Extract structured markdown
CsvParser - Parse CSV/TSV data
ParserFactory - Auto-detection and convenience methods

See Parsers Documentation for complete guide.

Examples

See the examples directory for 70+ complete working examples including:

Basic ReAct agents and multi-tool usage
Hierarchical agent systems (master-worker pattern)
Reflection agents for self-improvement
Production-ready agent setups with error handling
Adaptive agent service with intelligent selection
Async/concurrent execution with AMPHP
MAKER framework for million-step reliable tasks
Output parsers for structured data extraction
Chain composition patterns
And many more!

Documentation

🎓 Getting Started

New to AI agents? Start with our comprehensive tutorial series:

📚 Getting Started Tutorials - Complete beginner-friendly series

📖 Complete Documentation

Quick Start Guide - Get started in 5 minutes
Documentation Index - Complete guide to all features
Loop Strategies - Understanding agent loops
Agent Selection Guide - Choose the right pattern
Best Practices Guide - Production-ready patterns
Examples - 70+ working code examples

Requirements

PHP 8.1, 8.2, or 8.3
Composer
claude-php/claude-php-sdk

Installation

composer require claude-php/agent

For detailed setup instructions, see QUICKSTART.md.

Contributing

We welcome contributions! Please see:

CONTRIBUTING.md - Contribution guidelines
SECURITY.md - Security policy
CHANGELOG.md - Version history

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/

License

MIT License - see LICENSE for details.

Acknowledgments

Built with ❤️ using Claude PHP SDK and inspired by the latest research in AI agents and LLM orchestration.

claude-php / agent

Maintainers

Details

README

Features

Installation

Quick Start

Progress Updates (Streaming UI / Live Status)

Core Concepts

Loop Strategies

ReactLoop (Default)

PlanExecuteLoop

ReflectionLoop

Tools

Agent Patterns

Basic ReAct Agent

Hierarchical Agent (Master-Worker)

Reflection Agent

Memory & State

Production Features

MAKER Agent (Massively Decomposed Agentic Processes)

Adaptive Agent Service

Agent Patterns Reference

Configuration

Async & Concurrent Execution

Batch Processing

Parallel Tool Execution

Promise-Based Workflows

Output Parsers

Examples

Documentation

🎓 Getting Started

📖 Complete Documentation

Requirements

Installation

Contributing

Support

License

Acknowledgments