README

A comprehensive PHP SDK for building AI conversational agents with support for multiple LLM providers (OpenAI, Anthropic, Google), tools, streaming, and human-in-the-loop workflows.

Features

Multiple LLM Providers: OpenAI (GPT-4), Anthropic (Claude), Google (Gemini)
Tool System: Define and execute custom tools with automatic validation
Streaming: Real-time token streaming for responsive UIs
Middleware Pipeline: Logging, retry, rate limiting, caching
Memory Management: Conversation and sliding window memory
Human-in-the-Loop: Approval workflows for sensitive operations
Framework Integration: Laravel and Symfony support

Requirements

PHP 8.0 or higher
Composer
Guzzle HTTP client

Installation

composer require agentphp/sdk

Quick Start

use AgentPHP\Core\AgentBuilder;

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withSystemPrompt('You are a helpful assistant.')
    ->build();

$response = $agent->chat('Hello, how are you?');
echo $response->getContent();

Standalone Usage (Legacy PHP)
Laravel Integration
Symfony Integration
Providers
System Prompts
Tools
Streaming
Middleware
Human-in-the-Loop
Error Handling

Standalone Usage (Legacy PHP)

Basic Chat

<?php

require 'vendor/autoload.php';

use AgentPHP\Core\AgentBuilder;

// Create an agent with OpenAI
$agent = AgentBuilder::create()
    ->withOpenAI('your-openai-api-key', 'gpt-4')
    ->withSystemPrompt('You are a helpful assistant.')
    ->withName('MyAgent')
    ->build();

// Simple chat
$response = $agent->chat('What is the capital of France?');
echo $response->getContent(); // "The capital of France is Paris."

// Get usage information
$usage = $response->getUsage();
echo "Tokens used: " . $usage->getTotalTokens();

Conversation Memory

use AgentPHP\Core\AgentBuilder;

// With conversation memory (default)
$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withConversationMemory()
    ->build();

// The agent remembers previous messages
$agent->chat('My name is John');
$response = $agent->chat('What is my name?');
echo $response->getContent(); // "Your name is John."

// With sliding window memory (limits context size)
$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withSlidingWindowMemory(4000) // Max 4000 tokens
    ->build();

Configuration Options

use AgentPHP\Core\AgentBuilder;
use AgentPHP\Core\AgentConfig;

// Using AgentBuilder (recommended)
$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key', 'gpt-4')
    ->withName('MyAssistant')
    ->withSystemPrompt('You are a coding expert.')
    ->withTemperature(0.7)
    ->withMaxTokens(2000)
    ->withMaxIterations(10)
    ->withTimeout(30)
    ->withStreaming(false)
    ->build();

// Using AgentConfig directly
$config = AgentConfig::fromArray([
    'name' => 'MyAssistant',
    'system_prompt' => 'You are a coding expert.',
    'temperature' => 0.7,
    'max_tokens' => 2000,
    'max_iterations' => 10,
    'timeout' => 30,
    'streaming' => false,
]);

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withConfig($config)
    ->build();

Complete Standalone Example

<?php

require 'vendor/autoload.php';

use AgentPHP\Core\AgentBuilder;
use AgentPHP\Tools\AbstractTool;
use AgentPHP\Tools\ToolSchemaBuilder;

// Define a custom tool
class WeatherTool extends AbstractTool
{
    protected string $name = 'get_weather';
    protected string $description = 'Get the current weather for a location';

    public function getParameters(): array
    {
        return ToolSchemaBuilder::create()
            ->addString('location', 'City name', required: true)
            ->build();
    }

    protected function handle(array $arguments)
    {
        $location = $arguments['location'];
        // Simulate weather API
        return [
            'temperature' => 22,
            'condition' => 'sunny'
        ];
    }
}

// Create agent with tools and middleware
$agent = AgentBuilder::create()
    ->withOpenAI(getenv('OPENAI_API_KEY'), 'gpt-4')
    ->withSystemPrompt('You are a helpful assistant with weather capabilities.')
    ->withTool(new WeatherTool())
    ->withRetry(3, 1000, 2.0)
    ->withConversationMemory()
    ->build();

// Chat
$response = $agent->chat('What is the weather in Paris?');
echo $response->getContent();

Laravel Integration

Installation

composer require agentphp/sdk

The service provider is auto-discovered. For manual registration:

// config/app.php
'providers' => [
    AgentPHP\Framework\Laravel\AgentServiceProvider::class,
],

'aliases' => [
    'Agent' => AgentPHP\Framework\Laravel\Facades\Agent::class,
],

Publish Configuration

php artisan vendor:publish --tag=agent-config

Configuration

// config/agent.php
return [
    'default' => env('AGENT_PROVIDER', 'openai'),

    'name' => env('AGENT_NAME', 'AgentPHP'),
    'system_prompt' => env('AGENT_SYSTEM_PROMPT', 'You are a helpful assistant.'),

    'providers' => [
        'openai' => [
            'api_key' => env('OPENAI_API_KEY'),
            'model' => env('OPENAI_MODEL', 'gpt-4'),
            'timeout' => 30,
        ],
        'anthropic' => [
            'api_key' => env('ANTHROPIC_API_KEY'),
            'model' => env('ANTHROPIC_MODEL', 'claude-3-sonnet-20240229'),
        ],
        'google' => [
            'api_key' => env('GOOGLE_API_KEY'),
            'model' => env('GOOGLE_MODEL', 'gemini-pro'),
        ],
    ],

    'memory' => [
        'driver' => 'conversation', // or 'sliding_window'
        'max_tokens' => 4000,
    ],

    'middleware' => [
        'logging' => ['enabled' => true, 'level' => 'debug'],
        'retry' => ['enabled' => true, 'max_retries' => 3],
        'rate_limit' => ['enabled' => false, 'max_requests' => 60],
    ],

    'human_loop' => [
        'enabled' => false,
        'timeout' => 300,
    ],

    'tools' => [
        // \App\Tools\SearchTool::class,
    ],
];

Environment Variables

AGENT_PROVIDER=openai
AGENT_NAME=MyAgent
OPENAI_API_KEY=your-openai-api-key
OPENAI_MODEL=gpt-4

Using the Facade

use AgentPHP\Framework\Laravel\Facades\Agent;

// Simple chat
$response = Agent::chat('Hello!');
echo $response->getContent();

// With streaming
$stream = Agent::chatStream('Tell me a story');
foreach ($stream->getChunks() as $chunk) {
    echo $chunk->getContent();
}

// Get conversation history
$history = Agent::getHistory();

// Reset conversation
Agent::reset();

Using Dependency Injection

use AgentPHP\Core\Agent;

class ChatController extends Controller
{
    public function __construct(
        private Agent $agent
    ) {}

    public function chat(Request $request)
    {
        $response = $this->agent->chat($request->input('message'));

        return response()->json([
            'message' => $response->getContent(),
            'usage' => $response->getUsage()->toArray(),
        ]);
    }
}

Using AgentBuilder in Laravel

use AgentPHP\Core\AgentBuilder;

class CustomAgentController extends Controller
{
    public function chat(Request $request)
    {
        // Create a custom agent instance
        $agent = AgentBuilder::create()
            ->withOpenAI(config('agent.providers.openai.api_key'))
            ->withSystemPrompt('You are a customer service agent.')
            ->withTemperature(0.5)
            ->withTool(new SearchTool())
            ->withLogging(app('log'))
            ->build();

        return response()->json([
            'response' => $agent->chat($request->input('message'))->getContent(),
        ]);
    }
}

Registering Tools in Laravel

You can register tools directly on the Agent instance:

use AgentPHP\Core\Agent;

class ChatController extends Controller
{
    public function __construct(
        private Agent $agent
    ) {
        // Register tools directly on the agent
        $this->agent->addTools([
            new \App\Tools\WeatherTool(),
            new \App\Tools\CalculatorTool(),
            new \App\Tools\SearchTool(),
        ]);
    }

    public function chat(Request $request)
    {
        $response = $this->agent->chat($request->input('message'));
        return response()->json(['message' => $response->getContent()]);
    }
}

Or register a single tool:

$this->agent->addTool(new WeatherTool());

Alternatively, you can register tools globally in the ServiceProvider (less recommended):

// In AppServiceProvider
use AgentPHP\Tools\ToolRegistry;

public function boot(ToolRegistry $registry)
{
    $registry->register(new \App\Tools\SearchTool());
}

Laravel Streaming Response

use AgentPHP\Core\Agent;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\StreamedResponse;

public function stream(Request $request): StreamedResponse
{
    $message = $request->input('message');

    return new StreamedResponse(function () use ($message) {
        $agent = app(Agent::class);
        $stream = $agent->chatStream($message);

        foreach ($stream->getChunks() as $chunk) {
            if ($chunk->hasContent()) {
                echo "data: " . json_encode(['content' => $chunk->getContent()]) . "\n\n";
                ob_flush();
                flush();
            }

            if ($chunk->isDone()) {
                break;
            }
        }

        echo "data: [DONE]\n\n";
        ob_flush();
        flush();
    }, 200, [
        'Content-Type' => 'text/event-stream',
        'Cache-Control' => 'no-cache',
        'Connection' => 'keep-alive',
        'X-Accel-Buffering' => 'no',
    ]);
}

Symfony Integration

Installation

composer require agentphp/sdk

Enable the Bundle

// config/bundles.php
return [
    // ...
    AgentPHP\Framework\Symfony\AgentBundle::class => ['all' => true],
];

Configuration

# config/packages/agent.yaml
agent:
    provider: openai
    name: MyAgent
    system_prompt: 'You are a helpful assistant.'

    providers:
        openai:
            api_key: '%env(OPENAI_API_KEY)%'
            model: gpt-4
            timeout: 30
        anthropic:
            api_key: '%env(ANTHROPIC_API_KEY)%'
            model: claude-3-sonnet-20240229
        google:
            api_key: '%env(GOOGLE_API_KEY)%'
            model: gemini-pro

    memory:
        driver: conversation  # or sliding_window
        max_tokens: 4000

    max_iterations: 10
    temperature: 0.7
    max_tokens: ~  # null for provider default
    timeout: 30
    streaming: false

    human_loop:
        enabled: false
        timeout: 300
        auto_approve: false

    middleware:
        logging:
            enabled: true
            level: debug
        retry:
            enabled: true
            max_retries: 3
            delay: 1000
            multiplier: 2.0
        rate_limit:
            enabled: false
            max_requests: 60
            window: 60
        cache:
            enabled: false
            ttl: 3600

    tools: []

Environment Variables

OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key

Using in Controllers

use AgentPHP\Core\Agent;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;

class ChatController extends AbstractController
{
    public function __construct(
        private Agent $agent
    ) {}

    public function chat(Request $request): JsonResponse
    {
        $message = $request->request->get('message');
        $response = $this->agent->chat($message);

        return $this->json([
            'message' => $response->getContent(),
            'usage' => $response->getUsage()->toArray(),
        ]);
    }
}

Symfony Streaming Response

use AgentPHP\Core\Agent;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\StreamedResponse;

public function stream(Request $request): StreamedResponse
{
    $message = $request->request->get('message');

    return new StreamedResponse(function () use ($message) {
        $stream = $this->agent->chatStream($message);

        foreach ($stream->getChunks() as $chunk) {
            if ($chunk->hasContent()) {
                echo "data: " . json_encode(['content' => $chunk->getContent()]) . "\n\n";
                ob_flush();
                flush();
            }

            if ($chunk->isDone()) {
                break;
            }
        }

        echo "data: [DONE]\n\n";
        ob_flush();
        flush();
    }, 200, [
        'Content-Type' => 'text/event-stream',
        'Cache-Control' => 'no-cache',
        'Connection' => 'keep-alive',
        'X-Accel-Buffering' => 'no',
    ]);
}

Using AgentBuilder in Symfony

use AgentPHP\Core\AgentBuilder;

class CustomAgentService
{
    public function createSpecializedAgent(): Agent
    {
        return AgentBuilder::create()
            ->withAnthropic($_ENV['ANTHROPIC_API_KEY'], 'claude-3-opus-20240229')
            ->withSystemPrompt('You are an expert programmer.')
            ->withTemperature(0.3)
            ->withMaxTokens(4000)
            ->build();
    }
}

Registering Tools as Services

# config/services.yaml
services:
    App\Tools\SearchTool:
        tags: ['agent.tool']

    App\Tools\CalculatorTool:
        tags: ['agent.tool']

Providers

OpenAI

use AgentPHP\Core\AgentBuilder;

$agent = AgentBuilder::create()
    ->withOpenAI(
        apiKey: 'your-api-key',
        model: 'gpt-4',              // or gpt-4-turbo, gpt-3.5-turbo
        baseUrl: null,               // Custom base URL (optional)
        organization: null           // Organization ID (optional)
    )
    ->build();

// Or with ProviderConfig
use AgentPHP\Providers\OpenAIProvider;
use AgentPHP\Providers\ProviderConfig;

$config = new ProviderConfig([
    'api_key' => 'your-api-key',
    'model' => 'gpt-4-turbo',
    'base_url' => 'https://api.openai.com/v1',
    'organization' => 'org-xxx',
    'timeout' => 30,
]);

$provider = new OpenAIProvider($config);
$agent = AgentBuilder::create()
    ->withCustomProvider($provider)
    ->build();

Anthropic (Claude)

use AgentPHP\Core\AgentBuilder;

$agent = AgentBuilder::create()
    ->withAnthropic(
        apiKey: 'your-api-key',
        model: 'claude-3-opus-20240229'  // or claude-3-sonnet, claude-3-haiku
    )
    ->build();

// Available models:
// - claude-3-opus-20240229 (most capable)
// - claude-3-sonnet-20240229 (balanced)
// - claude-3-haiku-20240307 (fastest)

Google (Gemini)

use AgentPHP\Core\AgentBuilder;

$agent = AgentBuilder::create()
    ->withGoogle(
        apiKey: 'your-api-key',
        model: 'gemini-pro'  // or gemini-pro-vision
    )
    ->build();

Custom Provider

use AgentPHP\Contracts\ProviderInterface;
use AgentPHP\Core\AgentBuilder;
use AgentPHP\Core\ChatResponse;

class MyCustomProvider implements ProviderInterface
{
    public function getName(): string
    {
        return 'custom';
    }

    public function chat(array $messages, array $options = []): ChatResponse
    {
        // Your implementation
    }

    public function chatStream(array $messages, callable $callback, array $options = []): ChatResponse
    {
        // Your streaming implementation
    }

    // ... other interface methods
}

$agent = AgentBuilder::create()
    ->withCustomProvider(new MyCustomProvider())
    ->build();

Provider Factory

use AgentPHP\Providers\ProviderFactory;

// Create provider by name
$provider = ProviderFactory::create('openai', [
    'api_key' => 'your-key',
    'model' => 'gpt-4',
]);

$provider = ProviderFactory::create('anthropic', [
    'api_key' => 'your-key',
    'model' => 'claude-3-sonnet-20240229',
]);

System Prompts

System prompts define the behavior and personality of your agent.

Basic System Prompt

use AgentPHP\Core\AgentBuilder;

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withSystemPrompt('You are a helpful assistant that speaks formally.')
    ->build();

Detailed System Prompt

$systemPrompt = <<<PROMPT
You are an expert customer service agent for TechCorp.

Your responsibilities:
- Answer questions about our products
- Help troubleshoot technical issues
- Process refund requests when appropriate

Guidelines:
- Always be polite and professional
- If you don't know something, say so
- Never share confidential information
- Escalate to a human agent for complex issues

Available products:
- TechWidget Pro (\$99)
- TechGadget Plus (\$149)
- TechService Premium (monthly subscription)
PROMPT;

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withSystemPrompt($systemPrompt)
    ->build();

Dynamic System Prompts

$userName = 'John';
$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withSystemPrompt("You are helping user: {$userName}")
    ->build();

// Or update at runtime
$agent->setSystemPrompt("New context: User is a premium member.");

Multi-Language Support

$userLanguage = 'es';
$systemPrompt = match($userLanguage) {
    'es' => 'Eres un asistente util. Responde siempre en espanol.',
    'fr' => 'Vous etes un assistant utile. Repondez toujours en francais.',
    default => 'You are a helpful assistant. Always respond in English.',
};

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withSystemPrompt($systemPrompt)
    ->build();

Role-Based System Prompts

function getSystemPromptForRole(string $role): string
{
    return match($role) {
        'developer' => 'You are a senior software developer. Provide code examples and technical explanations.',
        'teacher' => 'You are a patient teacher. Explain concepts simply and use analogies.',
        'analyst' => 'You are a data analyst. Focus on facts, statistics, and data-driven insights.',
        default => 'You are a helpful assistant.',
    };
}

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withSystemPrompt(getSystemPromptForRole('developer'))
    ->build();

Tools

Tools allow your agent to perform actions and access external data.

Creating a Tool

Extend AbstractTool and implement the handle() method:

use AgentPHP\Tools\AbstractTool;
use AgentPHP\Tools\ToolSchemaBuilder;

class WeatherTool extends AbstractTool
{
    protected string $name = 'get_weather';
    protected string $description = 'Get the current weather for a location';

    public function getParameters(): array
    {
        return ToolSchemaBuilder::create()
            ->addString('location', 'The city and country', required: true)
            ->addEnum('unit', 'Temperature unit', ['celsius', 'fahrenheit'], required: false)
            ->build();
    }

    /**
     * Handle the tool execution.
     *
     * @param array $arguments The validated arguments from the LLM
     * @return mixed The result (will be wrapped in ToolResult automatically)
     */
    protected function handle(array $arguments)
    {
        $location = $arguments['location'];
        $unit = $arguments['unit'] ?? 'celsius';

        // Call weather API
        $weather = $this->fetchWeather($location, $unit);

        return [
            'temperature' => $weather['temp'],
            'condition' => $weather['condition'],
            'humidity' => $weather['humidity'],
        ];
    }

    private function fetchWeather(string $location, string $unit): array
    {
        // Your API implementation
        return [
            'temp' => 22,
            'condition' => 'sunny',
            'humidity' => 45,
        ];
    }
}

The AbstractTool base class:

Provides execute(array $arguments): ToolResult which wraps your handle() result
Automatically converts your return value to a ToolResult::success()
Catches exceptions and converts them to ToolResult::failure()
Sets requiresApproval() to false by default (override if needed)

Registering Tools

use AgentPHP\Core\AgentBuilder;

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withTool(new WeatherTool())
    ->withTool(new SearchTool())
    ->withTool(new CalculatorTool())
    ->build();

// Or register multiple at once
$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withTools([
        new WeatherTool(),
        new SearchTool(),
        new CalculatorTool(),
    ])
    ->build();

Tool Schema Builder

use AgentPHP\Tools\ToolSchemaBuilder;

$schema = ToolSchemaBuilder::create()
    // String with validation
    ->addString('email', 'User email address', required: true)

    // Enum (select from options)
    ->addEnum('priority', 'Task priority', ['low', 'medium', 'high'])

    // Integer with range
    ->addInteger('age', 'User age', required: true)

    // Number (float)
    ->addNumber('price', 'Product price')

    // Boolean
    ->addBoolean('active', 'Is active')

    // Array of strings
    ->addArray('tags', 'List of tags', itemType: 'string')

    // Nested object
    ->addObject('address', 'Shipping address', [
        'street' => ['type' => 'string', 'description' => 'Street address'],
        'city' => ['type' => 'string', 'description' => 'City'],
        'zip' => ['type' => 'string', 'description' => 'ZIP code'],
    ])

    ->build();

Tool with Approval Required

For sensitive operations, set $requiresApproval = true:

class DeleteUserTool extends AbstractTool
{
    protected string $name = 'delete_user';
    protected string $description = 'Permanently delete a user account';
    protected bool $requiresApproval = true; // Requires human approval

    public function getParameters(): array
    {
        return ToolSchemaBuilder::create()
            ->addString('user_id', 'The user ID to delete', required: true)
            ->addString('reason', 'Reason for deletion', required: true)
            ->build();
    }

    protected function handle(array $arguments)
    {
        $userId = $arguments['user_id'];

        // Delete user logic
        $this->userService->delete($userId);

        return [
            'deleted' => true,
            'user_id' => $userId,
        ];
    }
}

Using Tools with Agent

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withSystemPrompt('You can help users check the weather.')
    ->withTool(new WeatherTool())
    ->build();

// The agent will automatically use the tool when appropriate
$response = $agent->chat('What is the weather in Paris?');
echo $response->getContent();
// "The current weather in Paris is 22C and sunny with 45% humidity."

// Check if tools were used
if ($response->hasToolCalls()) {
    foreach ($response->getToolCalls() as $call) {
        echo "Tool used: " . $call->getName();
    }
}

Tool Registry

use AgentPHP\Tools\ToolRegistry;

$registry = new ToolRegistry();

// Register tools
$registry->register(new WeatherTool());
$registry->register(new SearchTool());

// Check if tool exists
if ($registry->has('get_weather')) {
    $tool = $registry->get('get_weather');
}

// Get all tool names
$names = $registry->names(); // ['get_weather', 'search']

// Get tools requiring approval
$sensitiveTools = $registry->getRequiringApproval();

// Filter tools
$readOnlyTools = $registry->filter(fn($tool) => !$tool->requiresApproval());

Manual Tool Execution

use AgentPHP\Tools\ToolExecutor;

$executor = new ToolExecutor($registry);

// Execute a specific tool
$result = $executor->executeByName('get_weather', [
    'location' => 'Tokyo',
    'unit' => 'celsius',
]);

if ($result->isSuccess()) {
    echo $result->getResultAsString();
} else {
    echo "Error: " . $result->getError();
}

Streaming

Streaming allows you to receive tokens in real-time as they are generated. All providers (OpenAI, Anthropic, Google) support streaming.

How Streaming Works

When you call $agent->chatStream(), it returns a StreamInterface object. This object provides methods to iterate over chunks of text as they arrive from the LLM provider, instead of waiting for the complete response.

Legacy PHP - Terminal/CLI Streaming

Complete example for running in terminal:

<?php
// File: cli_stream.php

require 'vendor/autoload.php';

use AgentPHP\Core\AgentBuilder;

// Create agent
$agent = AgentBuilder::create()
    ->withOpenAI(getenv('OPENAI_API_KEY'), 'gpt-4')
    ->withSystemPrompt('You are a helpful assistant.')
    ->build();

echo "Assistant: ";

// Get the stream
$stream = $agent->chatStream('Tell me a short story about a robot');

// Process each chunk as it arrives
foreach ($stream->getChunks() as $chunk) {
    // Check if chunk has text content
    if ($chunk->hasContent()) {
        echo $chunk->getContent();

        // Force output to display immediately
        if (function_exists('ob_flush')) {
            @ob_flush();
        }
        flush();
    }
}

echo "\n\n--- Stream complete ---\n";

Run it:

php cli_stream.php

Legacy PHP - Web Browser SSE Streaming

Complete example for streaming to a web browser using Server-Sent Events (SSE):

Backend (stream.php):

<?php
// File: stream.php

require 'vendor/autoload.php';

use AgentPHP\Core\AgentBuilder;

// Disable output buffering
if (ob_get_level()) {
    ob_end_clean();
}

// Set SSE headers
header('Content-Type: text/event-stream');
header('Cache-Control: no-cache');
header('Connection: keep-alive');
header('X-Accel-Buffering: no'); // Required for nginx

// Get message from request
$message = $_GET['message'] ?? $_POST['message'] ?? 'Hello';

// Create agent
$agent = AgentBuilder::create()
    ->withOpenAI(getenv('OPENAI_API_KEY'), 'gpt-4')
    ->withSystemPrompt('You are a helpful assistant.')
    ->build();

try {
    $stream = $agent->chatStream($message);

    foreach ($stream->getChunks() as $chunk) {
        if ($chunk->hasContent()) {
            // Send SSE data
            echo "data: " . json_encode([
                'type' => 'content',
                'content' => $chunk->getContent()
            ]) . "\n\n";

            flush();
        }

        // Check for errors
        if ($chunk->isError()) {
            echo "data: " . json_encode([
                'type' => 'error',
                'message' => $chunk->getContent()
            ]) . "\n\n";
            flush();
            break;
        }
    }

    // Send completion signal
    echo "data: " . json_encode(['type' => 'done']) . "\n\n";
    flush();

} catch (\Exception $e) {
    echo "data: " . json_encode([
        'type' => 'error',
        'message' => $e->getMessage()
    ]) . "\n\n";
    flush();
}

Frontend (index.html):

<!DOCTYPE html>
<html>
<head>
    <title>Chat Streaming</title>
    <style>
        #chat { max-width: 600px; margin: 20px auto; }
        #response {
            min-height: 200px;
            border: 1px solid #ccc;
            padding: 15px;
            white-space: pre-wrap;
            font-family: sans-serif;
        }
        #message { width: 80%; padding: 10px; }
        button { padding: 10px 20px; }
    </style>
</head>
<body>
    <div id="chat">
        <h2>Chat with AI</h2>
        <input type="text" id="message" placeholder="Type your message...">
        <button onclick="sendMessage()">Send</button>
        <h3>Response:</h3>
        <div id="response"></div>
    </div>

    <script>
    let eventSource = null;

    function sendMessage() {
        const message = document.getElementById('message').value;
        const responseDiv = document.getElementById('response');

        // Clear previous response
        responseDiv.textContent = '';

        // Close existing connection
        if (eventSource) {
            eventSource.close();
        }

        // Create new SSE connection
        eventSource = new EventSource('stream.php?message=' + encodeURIComponent(message));

        eventSource.onmessage = function(event) {
            const data = JSON.parse(event.data);

            if (data.type === 'content') {
                responseDiv.textContent += data.content;
            } else if (data.type === 'done') {
                eventSource.close();
                console.log('Stream complete');
            } else if (data.type === 'error') {
                responseDiv.textContent += '\n\nError: ' + data.message;
                eventSource.close();
            }
        };

        eventSource.onerror = function() {
            eventSource.close();
            console.log('Connection closed');
        };
    }
    </script>
</body>
</html>

Legacy PHP - AJAX POST Streaming

For POST requests with the Fetch API:

Backend (api_stream.php):

<?php
// File: api_stream.php

require 'vendor/autoload.php';

use AgentPHP\Core\AgentBuilder;

// Handle CORS if needed
header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Headers: Content-Type');

if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    exit(0);
}

// Disable output buffering
while (ob_get_level()) {
    ob_end_clean();
}

// Set SSE headers
header('Content-Type: text/event-stream');
header('Cache-Control: no-cache');
header('Connection: keep-alive');
header('X-Accel-Buffering: no');

// Get JSON body
$input = json_decode(file_get_contents('php://input'), true);
$message = $input['message'] ?? 'Hello';

$agent = AgentBuilder::create()
    ->withOpenAI(getenv('OPENAI_API_KEY'), 'gpt-4')
    ->build();

$stream = $agent->chatStream($message);

foreach ($stream->getChunks() as $chunk) {
    if ($chunk->hasContent()) {
        echo "data: " . json_encode(['content' => $chunk->getContent()]) . "\n\n";
        flush();
    }
}

echo "data: [DONE]\n\n";
flush();

Frontend JavaScript (Fetch API):

async function streamChat(message) {
    const responseDiv = document.getElementById('response');
    responseDiv.textContent = '';

    const response = await fetch('api_stream.php', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ message: message })
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const text = decoder.decode(value);
        const lines = text.split('\n');

        for (const line of lines) {
            if (line.startsWith('data: ')) {
                const data = line.substring(6).trim();

                if (data === '[DONE]') {
                    console.log('Stream complete');
                    return;
                }

                try {
                    const parsed = JSON.parse(data);
                    if (parsed.content) {
                        responseDiv.textContent += parsed.content;
                    }
                } catch (e) {
                    // Skip invalid JSON
                }
            }
        }
    }
}

StreamChunk Methods

Each chunk in the stream provides these methods:

foreach ($stream->getChunks() as $chunk) {
    // Get text content
    $text = $chunk->getContent();
    $text = $chunk->getText();  // Alias

    // Check what type of chunk this is
    $chunk->hasContent();       // Has text content?
    $chunk->isContent();        // Is a content chunk?
    $chunk->isDone();           // Is the final chunk?
    $chunk->isError();          // Is an error chunk?
    $chunk->isFinal();          // Is done, stop, or error?

    // For tool calls during streaming
    $chunk->hasToolCall();      // Has complete tool call?
    $chunk->hasToolCallDelta(); // Has partial tool call data?
    $chunk->getToolCall();      // Get ToolCall object
    $chunk->getToolCallDelta(); // Get partial tool call array

    // Metadata
    $chunk->getType();          // 'content', 'tool_call', 'done', 'error', etc.
    $chunk->getIndex();         // Chunk index number
    $chunk->getFinishReason();  // 'stop', 'length', 'tool_calls', etc.
    $chunk->getModel();         // Model name (usually in first/last chunk)
    $chunk->getUsage();         // Usage stats (usually in last chunk)
}

Getting the Complete Response After Streaming

$stream = $agent->chatStream('Tell me about PHP');
$fullText = '';

// Collect all chunks
foreach ($stream->getChunks() as $chunk) {
    if ($chunk->hasContent()) {
        $content = $chunk->getContent();
        echo $content;  // Stream to output
        $fullText .= $content;  // Collect for later
    }
}

// After streaming, you have the complete text
echo "\n\nComplete response length: " . strlen($fullText) . " characters\n";

Streaming with Different Providers

All providers use the same streaming interface:

// OpenAI
$agent = AgentBuilder::create()
    ->withOpenAI(getenv('OPENAI_API_KEY'), 'gpt-4')
    ->build();

// Anthropic
$agent = AgentBuilder::create()
    ->withAnthropic(getenv('ANTHROPIC_API_KEY'), 'claude-3-sonnet-20240229')
    ->build();

// Google
$agent = AgentBuilder::create()
    ->withGoogle(getenv('GOOGLE_API_KEY'), 'gemini-pro')
    ->build();

// Same streaming code works for all providers
$stream = $agent->chatStream('Hello!');
foreach ($stream->getChunks() as $chunk) {
    echo $chunk->getContent();
}

Error Handling in Streams

try {
    $stream = $agent->chatStream('Tell me a story');

    foreach ($stream->getChunks() as $chunk) {
        if ($chunk->isError()) {
            throw new \Exception('Stream error: ' . $chunk->getContent());
        }

        echo $chunk->getContent();
    }
} catch (\AgentPHP\Exceptions\ProviderException $e) {
    echo "Provider error: " . $e->getMessage();
} catch (\AgentPHP\Exceptions\RateLimitException $e) {
    echo "Rate limited. Retry after: " . $e->getRetryAfter() . " seconds";
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Nginx Configuration for SSE

If using nginx, add this to your location block:

location /stream.php {
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 3600s;

    # If using FastCGI
    fastcgi_buffering off;
    fastcgi_keep_conn on;
}

Apache Configuration for SSE

For Apache with mod_php, streaming should work out of the box. If using PHP-FPM:

<Location /stream.php>
    SetEnv no-gzip 1
    SetEnv proxy-nokeepalive 1
</Location>

Middleware

Middleware allows you to intercept and modify requests/responses.

Built-in Middleware

Logging Middleware

use AgentPHP\Core\AgentBuilder;
use Psr\Log\LoggerInterface;

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withLogging($logger, 'info')  // PSR-3 logger
    ->build();

// Or with Laravel
$agent = AgentBuilder::create()
    ->withOpenAI(config('agent.providers.openai.api_key'))
    ->withLogging(app('log'), 'debug')
    ->build();

Retry Middleware

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withRetry(
        maxRetries: 3,        // Number of retry attempts
        delay: 1000,          // Initial delay in milliseconds
        multiplier: 2.0       // Exponential backoff multiplier
    )
    ->build();

Rate Limit Middleware

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withRateLimit(
        maxRequests: 60,      // Maximum requests
        window: 60            // Time window in seconds
    )
    ->build();

Timeout Middleware

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withTimeout(30)  // 30 seconds timeout
    ->build();

Combining Middleware

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withLogging($logger)
    ->withRetry(3, 1000, 2.0)
    ->withRateLimit(60, 60)
    ->withTimeout(30)
    ->build();

Custom Middleware

use AgentPHP\Contracts\MiddlewareInterface;
use AgentPHP\Core\ChatRequest;
use AgentPHP\Core\ChatResponse;

class MetricsMiddleware implements MiddlewareInterface
{
    public function __construct(
        private MetricsService $metrics
    ) {}

    public function process(ChatRequest $request, callable $next): ChatResponse
    {
        $startTime = microtime(true);

        try {
            // Call next middleware/handler
            $response = $next($request);

            // Record success metrics
            $duration = microtime(true) - $startTime;
            $this->metrics->record('chat.success', $duration);
            $this->metrics->increment('chat.tokens', $response->getUsage()->getTotalTokens());

            return $response;

        } catch (\Exception $e) {
            // Record error metrics
            $this->metrics->increment('chat.errors');
            throw $e;
        }
    }
}

// Use the middleware
$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withMiddleware(new MetricsMiddleware($metricsService))
    ->build();

Authentication Middleware

class AuthenticationMiddleware implements MiddlewareInterface
{
    public function process(ChatRequest $request, callable $next): ChatResponse
    {
        // Check if user is authenticated
        if (!$this->auth->check()) {
            throw new UnauthorizedException('User must be authenticated');
        }

        // Check rate limits for user
        $userId = $this->auth->id();
        if ($this->rateLimiter->tooManyAttempts($userId, 100)) {
            throw new RateLimitException('Too many requests');
        }

        $this->rateLimiter->hit($userId);

        return $next($request);
    }
}

Content Filter Middleware

class ContentFilterMiddleware implements MiddlewareInterface
{
    private array $blockedWords = ['spam', 'inappropriate'];

    public function process(ChatRequest $request, callable $next): ChatResponse
    {
        // Filter input
        $messages = $request->getMessages();
        foreach ($messages as $message) {
            if ($this->containsBlockedContent($message['content'] ?? '')) {
                throw new ContentPolicyException('Message contains blocked content');
            }
        }

        $response = $next($request);

        // Filter output
        $content = $response->getContent();
        if ($this->containsBlockedContent($content)) {
            throw new ContentPolicyException('Response contains blocked content');
        }

        return $response;
    }

    private function containsBlockedContent(string $text): bool
    {
        foreach ($this->blockedWords as $word) {
            if (stripos($text, $word) !== false) {
                return true;
            }
        }
        return false;
    }
}

Human-in-the-Loop

Enable approval workflows for sensitive operations.

Basic Setup

use AgentPHP\Core\AgentBuilder;
use AgentPHP\HumanLoop\ApprovalHandler;

$approvalHandler = ApprovalHandler::create();

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withHumanApproval($approvalHandler)
    ->withTool(new DeleteUserTool())  // requiresApproval() returns true
    ->build();

Custom Approval Handler

use AgentPHP\Contracts\HumanLoopInterface;
use AgentPHP\Tools\ToolCall;

class SlackApprovalHandler implements HumanLoopInterface
{
    public function requestApproval(ToolCall $call): bool
    {
        // Send Slack notification
        $this->slack->send([
            'channel' => '#approvals',
            'text' => "Approval needed for: {$call->getName()}",
            'data' => $call->getArguments(),
        ]);

        // Wait for response (implement your logic)
        return $this->waitForApproval($call->getId());
    }

    public function onApproved(ToolCall $call): void
    {
        $this->slack->send([
            'channel' => '#approvals',
            'text' => "Approved: {$call->getName()}",
        ]);
    }

    public function onDenied(ToolCall $call, string $reason): void
    {
        $this->slack->send([
            'channel' => '#approvals',
            'text' => "Denied: {$call->getName()} - {$reason}",
        ]);
    }
}

Auto-Approval for Development

$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->withAutoApproval()  // Skip approval in development
    ->build();

// Or skip approval for specific tools
$agent = AgentBuilder::create()
    ->withOpenAI('your-api-key')
    ->skipApproval()  // Skip all approvals
    ->build();

Error Handling

use AgentPHP\Exceptions\AgentException;
use AgentPHP\Exceptions\ProviderException;
use AgentPHP\Exceptions\RateLimitException;
use AgentPHP\Exceptions\TimeoutException;
use AgentPHP\Exceptions\ToolException;
use AgentPHP\Exceptions\ValidationException;

try {
    $response = $agent->chat('Hello');
} catch (RateLimitException $e) {
    // Handle rate limiting
    $retryAfter = $e->getRetryAfter();
    sleep($retryAfter);

} catch (TimeoutException $e) {
    // Handle timeout
    echo "Request timed out after {$e->getTimeout()} seconds";

} catch (ToolException $e) {
    // Handle tool errors
    echo "Tool '{$e->getToolName()}' failed: {$e->getMessage()}";

} catch (ValidationException $e) {
    // Handle validation errors
    foreach ($e->getErrors() as $field => $error) {
        echo "{$field}: {$error}";
    }

} catch (ProviderException $e) {
    // Handle provider-specific errors
    echo "Provider error: {$e->getMessage()}";

} catch (AgentException $e) {
    // Handle all other agent errors
    echo "Agent error: {$e->getMessage()}";
}

Development

Setup

# Clone the repository
git clone https://github.com/agentphp/sdk.git
cd sdk

# Install dependencies
composer install

# Run tests
composer test

# Run code style check
composer cs:check

# Run static analysis
composer analyse

Testing

# Run all tests
composer test

# Run unit tests only
composer test:unit

# Run integration tests only
composer test:integration

# Run tests with coverage
composer test:coverage

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

The MIT License (MIT). Please see License File for more information.

Security

If you discover any security-related issues, please email security@agentphp.dev instead of using the issue tracker.

agentphp / sdk

Maintainers

Details

README

Features

Requirements

Installation

Quick Start

Table of Contents

Standalone Usage (Legacy PHP)

Basic Chat

Conversation Memory

Configuration Options

Complete Standalone Example

Laravel Integration

Installation

Publish Configuration

Configuration

Environment Variables

Using the Facade

Using Dependency Injection

Using AgentBuilder in Laravel

Registering Tools in Laravel

Laravel Streaming Response

Symfony Integration

Installation

Enable the Bundle

Configuration

Environment Variables

Using in Controllers

Symfony Streaming Response

Using AgentBuilder in Symfony

Registering Tools as Services

Providers

OpenAI

Anthropic (Claude)

Google (Gemini)

Custom Provider

Provider Factory

System Prompts

Basic System Prompt

Detailed System Prompt

Dynamic System Prompts

Multi-Language Support

Role-Based System Prompts

Tools

Creating a Tool

Registering Tools

Tool Schema Builder

Tool with Approval Required

Using Tools with Agent

Tool Registry

Manual Tool Execution

Streaming

How Streaming Works

Legacy PHP - Terminal/CLI Streaming

Legacy PHP - Web Browser SSE Streaming

Legacy PHP - AJAX POST Streaming

StreamChunk Methods

Getting the Complete Response After Streaming

Streaming with Different Providers

Error Handling in Streams

Nginx Configuration for SSE

Apache Configuration for SSE

Middleware

Built-in Middleware

Logging Middleware

Retry Middleware

Rate Limit Middleware

Timeout Middleware

Combining Middleware

Custom Middleware

Authentication Middleware

Content Filter Middleware

Human-in-the-Loop

Basic Setup

Custom Approval Handler

Auto-Approval for Development

Error Handling

Development