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
• 🌊 Streaming Flow Execution - Real-time token streaming with event broadcasting
• 🎨 Template System - 22+ starter templates with instant instantiation
• 🎯 Error Handling Service - User-friendly error messages for all API errors (NEW!)
• 🛠️ 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
• 🌐 MCP Server - Model Context Protocol integration for Claude Desktop and IDEs
• 🎯 Extensible - Build custom agents and patterns with ease
• 🆕 Component Validation - Runtime validation by instantiation (v0.8.0)
• 🏢 Services System - Enterprise service management with dependency injection (v0.7.0)
• 🧪 Code Generation - AI-powered code generation with validation pipelines (v0.8.0)

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();

Real-Time Streaming Flow Execution 🌊

NEW! Stream agent execution with token-by-token LLM responses, progress tracking, and event broadcasting:

use ClaudeAgents\Services\ServiceManager;
use ClaudeAgents\Services\ServiceType;

// Get the streaming executor
$executor = ServiceManager::getInstance()->get(ServiceType::FLOW_EXECUTOR);

// Stream execution with real-time events
foreach ($executor->executeWithStreaming($agent, "Calculate 15 * 23") as $event) {
    match ($event['type']) {
        'token' => print($event['data']['token']),              // Token-by-token streaming
        'progress' => printf("%.1f%%\n", $event['data']['progress_percent']), // Progress updates
        'tool_start' => print("🔧 {$event['data']['tool']}\n"), // Tool execution
        'end' => print("✅ Done!\n"),
        default => null
    };
}

Features:

• 🎯 Token-by-token LLM responses
• 📊 Real-time progress tracking
• 🔧 Tool execution events
• 📡 SSE support for web apps
• 🎪 Multiple listener broadcasting
• ⚡ Generator-based streaming

📚 Complete Streaming Documentation | Event Reference | Examples

Error Handling Service

Convert technical API errors into user-friendly messages. Inspired by Langflow's error handling approach:

use ClaudeAgents\Services\ServiceManager;
use ClaudeAgents\Services\ServiceType;

// Get the service
$errorService = ServiceManager::getInstance()->get(ServiceType::ERROR_HANDLING);

try {
    $result = $agent->run('Your task');
} catch (\Throwable $e) {
    // Convert to user-friendly message
    echo $errorService->convertToUserFriendly($e);
    // Output: "Rate limit exceeded. Please wait before retrying."
    
    // Get detailed error info for logging
    $details = $errorService->getErrorDetails($e);
    $logger->error('Agent failed', $details);
}

Error Pattern Coverage:

• Rate limits → "Rate limit exceeded. Please wait before retrying."
• Auth errors → "Authentication failed. Please check your API key."
• Timeouts → "Request timed out. Please try again."
• Connection → "Connection error. Check your network."
• 9 default patterns + custom pattern support

Features:

• 🎯 User-friendly messages for all Claude API errors
• 🔄 Smart retry logic with exponential backoff
• 📊 Detailed error context for debugging
• ⚙️ Configurable patterns (defaults + custom)
• 🏢 Service layer integration
• 🛠️ Safe tool execution helpers

📚 Error Handling Documentation | Tutorial | Examples

Template/Starter Project System

The framework includes a comprehensive template system with 22+ ready-to-use agent configurations:

Quick Start

use ClaudeAgents\Templates\TemplateManager;

// Search templates
$templates = TemplateManager::search(
    query: 'chatbot',
    tags: ['conversation'],
    fields: ['name', 'description']
);

// Instantiate from template
$agent = TemplateManager::instantiate('rag-agent', [
    'api_key' => getenv('ANTHROPIC_API_KEY'),
    'model' => 'claude-sonnet-4-5'
]);

// Run the agent
$result = $agent->run('What is RAG?');

Available Templates (22+)

Basic Agents (5): Basic Agent, ReAct, Chain-of-Thought, Reflex, Model-Based
Advanced Agents (5): Reflection, Plan-Execute, Tree-of-Thoughts, MAKER, Adaptive
Specialized (5): Hierarchical, Coordinator, Dialog, Intent Classifier, Monitoring
RAG & Knowledge (3): RAG Agent, Memory Chatbot, Knowledge Manager
Workflows (2): Sequential Tasks, Debate System
Production (2): Production Agent, Async Batch Processor

Features

• 🔍 Advanced Search - Find templates by name, tags, category, or difficulty
• 📦 Instant Instantiation - Create agents with one line of code
• 💾 Custom Templates - Export your agents as reusable templates
• 🏷️ Smart Organization - 6 categories, 30+ tags, 3 difficulty levels
• 📚 Rich Metadata - Use cases, requirements, setup time, and more

📚 Complete Template Catalog | Template Guide | Creating Templates

Progress Updates (Legacy)

You can also receive progress events via onUpdate():

use ClaudeAgents\Progress\AgentUpdate;

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

MCP Server Integration

The framework includes a full Model Context Protocol (MCP) server that exposes agent capabilities to MCP clients like Claude Desktop, IDEs, and other AI tools.

Quick Start

# 1. Set your API key
export ANTHROPIC_API_KEY=your_api_key_here

# 2. Start the MCP server
php bin/mcp-server

# 3. Add to Claude Desktop config
{
  "mcpServers": {
    "claude-php-agent": {
      "command": "php",
      "args": ["/path/to/claude-php-agent/bin/mcp-server"]
    }
  }
}

Features

• 15 MCP Tools - Agent discovery, execution, visualization, and configuration
• Dual Transport - STDIO for Claude Desktop, SSE for web clients
• Agent Discovery - Search and explore 16+ agent types
• Workflow Visualization - ASCII art diagrams and JSON graphs
• Real-time Execution - Run agents directly through MCP
• Session Management - Isolated per-client sessions with memory

Available Tools

Agent Discovery: search_agents, list_agent_types, get_agent_details, count_agents
Execution: run_agent, get_execution_status
Tool Management: list_tools, search_tools, get_tool_details
Visualization: visualize_workflow, get_agent_graph, export_agent_config
Configuration: update_agent_config, create_agent_instance, validate_agent_config

📚 Full MCP Documentation

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

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);

Streaming Flow Execution 🌊

NEW! Real-time streaming flow execution with comprehensive event management, inspired by Langflow's architecture.

Features

• Token-by-Token Streaming - Real-time LLM responses as they're generated
• Progress Tracking - Detailed execution progress with time estimates
• Event Broadcasting - Multiple subscribers with one-to-many pattern
• SSE Support - Server-Sent Events for web applications
• Queue-Based - Non-blocking event emission with configurable limits
• Langflow Compatible - Compatible event types and patterns

Quick Example

use ClaudeAgents\Services\ServiceManager;
use ClaudeAgents\Services\ServiceType;

// Get streaming executor from ServiceManager
$executor = ServiceManager::getInstance()->get(ServiceType::FLOW_EXECUTOR);

// Stream execution with events
foreach ($executor->executeWithStreaming($agent, "Your task") as $event) {
    match ($event['type']) {
        'token' => print($event['data']['token']),
        'progress' => updateProgressBar($event['data']['progress_percent']),
        'tool_start' => logToolExecution($event['data']['tool']),
        'error' => handleError($event['data']['error']),
        'end' => print("\n✅ Complete!\n"),
        default => null
    };
}

SSE Streaming for Web Apps

// Set SSE headers
header('Content-Type: text/event-stream');
header('Cache-Control: no-cache');

// Stream events to browser
foreach ($executor->streamSSE($agent, $task) as $sseData) {
    echo $sseData;
    flush();
}

JavaScript Client:

const eventSource = new EventSource('/stream?task=' + encodeURIComponent(task));

eventSource.addEventListener('token', (e) => {
    const data = JSON.parse(e.data);
    appendToken(data.data.token);
});

eventSource.addEventListener('progress', (e) => {
    const data = JSON.parse(e.data);
    updateProgressBar(data.data.percent);
});

Multiple Listeners

$eventManager = ServiceManager::getInstance()->get(ServiceType::EVENT_MANAGER);

// Token counter listener
$eventManager->subscribe(function($event) {
    if ($event->isToken()) {
        incrementTokenCount();
    }
});

// Progress logger listener
$eventManager->subscribe(function($event) {
    if ($event->isProgress()) {
        logProgress($event->data['percent']);
    }
});

// Error monitor listener
$eventManager->subscribe(function($event) {
    if ($event->isError()) {
        alertError($event->data['error']);
    }
});

Available Event Types

Flow Lifecycle: flow.started, flow.completed, flow.failed
Token Streaming: token.received, token.chunk
Iterations: iteration.started, iteration.completed, iteration.failed
Tools: tool.started, tool.completed, tool.failed
Progress: progress.update, step.started, step.completed
Errors: error, warning, info

Documentation

• 📚 Complete Guide - Architecture, usage, and best practices
• 📖 Event Reference - All 25+ event types documented
• 🎯 Streaming Patterns - Advanced patterns and SSE implementation
• 💡 Examples - 4 comprehensive working examples

Architecture

The system adapts Python's async patterns to PHP:

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 110+ complete working examples including:

Core Examples (70+ files):

• 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

🆕 Tutorial Examples (42 files in examples/tutorials/):

• Component validation patterns (7 examples)
• Services system usage (7 examples)
• MCP server integration (7 examples)
• Code generation workflows (7 examples)
• Production deployment patterns (7 examples)
• Testing strategies (7 examples)

🌊 Streaming Flow Execution (4 examples in examples/Execution/):

• basic-streaming.php - Token streaming with event handling
• progress-tracking.php - Real-time progress monitoring
• multiple-listeners.php - Event broadcasting pattern
• sse-server.php - Complete SSE endpoint with HTML client

💡 All examples are fully runnable: php examples/Execution/basic-streaming.php

Documentation

🎓 Getting Started

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

• 📚 Getting Started Tutorials - Complete beginner-friendly series
  • Tutorial 0: Introduction to Agentic AI
  • Tutorial 1: Your First Agent
  • Tutorial 2: ReAct Loop Basics
  • Tutorial 3: Multi-Tool Agent
  • Tutorial 4: Production-Ready Patterns
  • Tutorial 5: Advanced Patterns

🆕 New Features Tutorials (v0.7.0 - v0.9.0)

Master the latest framework capabilities:

• 🌊 Streaming Flow Execution - Real-time streaming with event management (NEW!)
• 🔍 Component Validation - Runtime validation by instantiation (45min)
• 🏢 Services System - Enterprise service management (50min)
• 🌐 MCP Server Integration - Connect to Claude Desktop (55min)
• 🧪 Code Generation - AI-powered code generation (50min)
• 🚀 Production Patterns - Production deployment (60min)
• ✅ Testing Strategies - Comprehensive testing (55min)

💡 46 runnable examples included - Each feature comes with working code samples!

📖 Complete Documentation

• Quick Start Guide - Get started in 5 minutes
• 🌊 Streaming Flow Execution - Real-time streaming guide
  • Event Reference - All event types
  • Streaming Patterns - SSE & patterns
• 🎯 Error Handling Service - User-friendly error messages (NEW!)
  • Tutorial - Complete 6-part tutorial
• Documentation Index - Complete guide to all features
• All Tutorials - 17+ comprehensive tutorials with examples
• Loop Strategies - Understanding agent loops
• Agent Selection Guide - Choose the right pattern
• Best Practices Guide - Production-ready patterns
• MCP Server Integration - Claude Desktop connectivity
• Component Validation - Runtime validation guide
• Services System - Enterprise service management
• Examples - 79+ working code examples + 55 tutorial 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.

What's New

v1.3.0 (Latest)

• ✨ Error Handling Service - User-friendly error messages for all API errors (HIGH PRIORITY)
  • 9 default error patterns for common API errors
  • Custom pattern support with override capability
  • Full service layer integration
  • Comprehensive retry logic and tool helpers
• 📚 New tutorial: Complete 6-part Error Handling tutorial
• 📝 9 new examples with real API testing
• 🔧 Deprecated old ErrorHandler with migration guide

v0.8.0

• ✨ Component Validation Service - Runtime validation by instantiation
• ✨ Code Generation Agent - AI-powered code generation with validation
• 📚 New tutorials: Component Validation, Code Generation, Production Patterns, Testing Strategies
• 📝 42 new tutorial examples in examples/tutorials/

v0.7.0

• ✨ Services System - Enterprise service management with dependency injection
• ✨ MCP Server - Model Context Protocol integration for Claude Desktop
• 📚 New tutorials: Services System, MCP Server Integration
• 🔧 Enhanced observability and monitoring

See CHANGELOG.md for complete version history.

Acknowledgments

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