A powerful PHP framework for building AI agents with Claude, featuring ReAct loops, tool orchestration, hierarchical agents, and advanced agentic patterns.
- π 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)
composer require claude-php/agent<?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();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
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
The framework includes a comprehensive template system with 22+ ready-to-use agent configurations:
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?');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
- π 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
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.
});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.
# 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"]
}
}
}- 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
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
The framework provides multiple loop strategies for different types of tasks:
The Reason-Act-Observe pattern for general-purpose tasks:
use ClaudeAgents\Loops\ReactLoop;
$agent = Agent::create()
->withLoopStrategy(new ReactLoop())
->withTools([$searchTool, $calculatorTool])
->maxIterations(10);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);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 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']);
});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...');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');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 metuse 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...');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)
});β‘ 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.
π― 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.
| 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 |
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);NEW! Real-time streaming flow execution with comprehensive event management, inspired by Langflow's architecture.
- 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
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
};
}// 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);
});$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']);
}
});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
- π 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
The system adapts Python's async patterns to PHP:
| Python (Langflow) | PHP (claude-php-agent) |
|---|---|
async/await |
Generator/yield |
asyncio.Queue |
SplQueue |
| Async subscribers | Iterator pattern |
async for |
foreach with Generator |
The framework leverages AMPHP for true asynchronous and concurrent execution:
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";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);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.
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.
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 handlingprogress-tracking.php- Real-time progress monitoringmultiple-listeners.php- Event broadcasting patternsse-server.php- Complete SSE endpoint with HTML client
π‘ All examples are fully runnable:
php examples/Execution/basic-streaming.php
New to AI agents? Start with our comprehensive tutorial series:
- π Getting Started Tutorials - Complete beginner-friendly series
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!
- 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
- PHP 8.1, 8.2, or 8.3
- Composer
- claude-php/claude-php-sdk
composer require claude-php/agentFor detailed setup instructions, see QUICKSTART.md.
We welcome contributions! Please see:
- CONTRIBUTING.md - Contribution guidelines
- SECURITY.md - Security policy
- CHANGELOG.md - Version history
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: docs/
MIT License - see LICENSE for details.
- β¨ 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
- β¨ 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/
- β¨ 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.
Built with β€οΈ using Claude PHP SDK and inspired by the latest research in AI agents and LLM orchestration.