README

An autonomous agent framework for PHP 8.2+. Implements the Plan → Execute → Reflect loop with LLM-powered planning, workflow-based execution, and adaptive reflection. Built on NexusAI and NexusAI Workflows.

Features

• Autonomous agent loop — Plan → Execute → Reflect with configurable strategies
• 3 planning strategies — ReAct, Chain-of-Thought, Plan-and-Execute — all LLM-powered with static fallbacks
• WorkflowRunner integration — each plan step executes as a workflow via StepMapper + WorkflowExecutor
• LLM Reflection — dynamic decision-making: Continue, Finish, Replan, Retry, AskUser, Abort
• AgentBuilder — fluent chainable API with auto-wiring of components
• Multi-agent orchestration — OrchestratorAgent, AgentTeam, Handoff, MessageBus
• Memory system — Working, Episodic, and Semantic memory with MemoryManager
• Middleware pipeline — BudgetGuard, MemoryInjection, Planning middleware
• Budget & step limits — configurable guardrails to prevent runaway agents
• Observability — 6 typed Event DTOs (AgentStarted, AgentStep, AgentReflection, AgentCompleted, AgentFailed, AgentToolCall)
• FakeAgent — deterministic test doubles with assertion helpers

Installation

composer require token27/nexus-ai-agents

Quick Start

Using AgentBuilder (recommended)

use Token27\NexusAI\Agents\AgentBuilder;
use Token27\NexusAI\Agents\Enum\PlanningStrategy;

$agent = AgentBuilder::named('researcher')
    ->withDescription('AI research assistant')
    ->withProvider('openai', 'gpt-4o')
    ->withStrategy(PlanningStrategy::ReAct)
    ->withDriver($driver)
    ->withWorkflowRunner($runner)
    ->withBudget(1.00)
    ->withMaxSteps(20)
    ->build();

$result = $agent->run('What are the latest trends in PHP?');

echo $result->output;       // Final answer
echo $result->totalSteps;   // Steps executed
echo $result->totalCost;    // Cost in USD

Minimal (no LLM, static planning)

$agent = AgentBuilder::named('simple')
    ->withStrategy(PlanningStrategy::ChainOfThought)
    ->build();

$result = $agent->run('Analyze this problem');

Architecture

AgentBuilder::named('agent')
    ->withDriver($driver)           ← LLM for planning + reflection
    ->withWorkflowRunner($runner)   ← Workflow engine for execution
    ->build()

Agent::run(input)
    ├── Planner::plan(input, ctx)          ← LLM generates Plan with steps
    │   └── ReAct | CoT | PlanAndExecute
    │
    ├── WorkflowExecutor::execute(step)    ← Each step runs as a workflow
    │   └── StepMapper → WorkflowBuilder → WorkflowRunner
    │
    └── LLMReflector::reflect(ctx, output) ← LLM evaluates results
        └── Continue | Finish | Replan | Retry | Abort

Documentation

Full documentation is available in the docs/ directory:

• Getting Started
• Agent Loop
• Planning Strategies
• Execution
• Reflection
• AgentBuilder
• Multi-Agent
• Memory
• Middleware
• Observability
• Testing

Requirements

• PHP 8.2 or higher
• token27/nexus-ai ^1.0
• token27/nexus-ai-workflows ^1.0

License

MIT. Please see LICENSE for more information.