PHPackages                             helgesverre/pagent - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. helgesverre/pagent

ActiveLibrary[Testing & Quality](/categories/testing)

helgesverre/pagent
==================

A Pest-inspired LLM Agent Framework for PHP with multi-provider support, automatic tool calling, safety guards, and multi-agent orchestration

v1.0.0(5mo ago)00MITPHPPHP ^8.3CI passing

Since Dec 3Pushed 4mo agoCompare

[ Source](https://github.com/HelgeSverre/pagent)[ Packagist](https://packagist.org/packages/helgesverre/pagent)[ Docs](https://github.com/helgesverre/pagent)[ RSS](/packages/helgesverre-pagent/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (19)Versions (2)Used By (0)

Pagent 🩸
========

[](#pagent-)

**A Pest-inspired LLM Agent Framework for PHP**

Build intelligent agents with automatic tool calling, multi-provider support, safety guards, and multi-agent orchestration—all with a clean, fluent API.

[![Latest Version](https://camo.githubusercontent.com/bbb37175eadebbefca30bb796620fa1560de34e2473bb36155cfd7918c66c93b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f68656c67657376657272652f706167656e742e7376673f7374796c653d666c61742d73717561726526763d31373335323537363030)](https://packagist.org/packages/helgesverre/pagent)[![Tests](https://camo.githubusercontent.com/14c53a54009bebaa5b8d3f191ed2963a4adaec823eaa0bcc6467f3e108dd76e5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f68656c67657376657272652f706167656e742f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d73717561726526763d31373335323537363030)](https://github.com/helgesverre/pagent/actions)[![Total Downloads](https://camo.githubusercontent.com/77640035abbd7eb012e88eb4220aee5773e3adc68efb47df4831f8a0607679bf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f68656c67657376657272652f706167656e742e7376673f7374796c653d666c61742d73717561726526763d31373335323537363030)](https://packagist.org/packages/helgesverre/pagent)[![PHP Version](https://camo.githubusercontent.com/7e7660ee8cd4ff3bc19c92c25b849db72b95260a3b383892393bdb3b69cb604f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f68656c67657376657272652f706167656e742e7376673f7374796c653d666c61742d73717561726526763d31373335323537363030)](https://packagist.org/packages/helgesverre/pagent)[![License](https://camo.githubusercontent.com/a9d4c15992d7b7d058dd03c9c70204b0a5d5546f553fc442dafcfa4136c9438d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f48656c67655376657272652f706167656e743f7374796c653d666c61742d73717561726526763d31373335323537363030)](https://github.com/HelgeSverre/pagent/blob/main/LICENSE)

---

Why Pagent?
-----------

[](#why-pagent)

- **🧪 Pest-Inspired API** - Fluent, expressive syntax that feels natural
- **🌊 Real-Time Streaming** - SSE streaming for ChatGPT-like experiences
- **💾 Memory & Persistence** - SQLite, File, and custom storage adapters
- **🔧 Automatic Tool Calling** - JSON schema generation from PHP functions
- **🤖 Multi-Provider** - Anthropic Claude, OpenAI GPT, Ollama (local), Mock (for testing)
- **🛡️ Safety Guards** - PII detection, content filtering, prompt injection prevention
- **📊 Evaluation Framework** - Test datasets with automated metrics and reports
- **🔄 Multi-Agent Orchestration** - Pipeline, handoff, and delegation patterns
- **📡 Observability & Tracing** - OpenTelemetry instrumentation with Jaeger, Zipkin, OTLP support
- **⚡ Production Ready** - 630+ tests, PHPStan level 9, PHP 8.3+ type safety

---

Installation
------------

[](#installation)

```
composer require helgesverre/pagent
```

**Requirements:**

- PHP 8.3 or higher
- Composer 2.x

Quick Start
-----------

[](#quick-start)

```
// Configure an agent
agent('assistant')
    ->provider('anthropic')
    ->system('You are a helpful assistant')
    ->temperature(0.7);

// Use the agent
$response = agent('assistant')->prompt('Hello!');
echo $response->content;

// Or stream responses in real-time
agent('assistant')->streamTo('Tell me a story', function ($chunk) {
    if ($chunk->isText()) {
        echo $chunk->content;
        flush();
    }
});

// Persist conversations across sessions
agent('support')
    ->memory('sqlite', ['path' => 'storage/conversations.db'])
    ->sessionId('user-123')
    ->contextWindow(100000)
    ->prompt('Hello');
```

**📖 Explore:** [Streaming Guide](docs/streaming.md) | [Memory & Persistence](docs/memory-persistence.md)

Providers
---------

[](#providers)

### Mock Provider (for testing)

[](#mock-provider-for-testing)

```
$mock = mock([
    'Hello' => 'Hi there!',
    'How are you?' => 'I am doing great!'
]);

$response = $mock->prompt('Hello');
echo $response->content; // "Hi there!"
```

### Anthropic (Claude)

[](#anthropic-claude)

```
export ANTHROPIC_API_KEY="your-key"
```

```
$claude = anthropic();
$response = $claude->prompt('Hello!', [
    'model' => 'claude-3-sonnet-20240229',
    'max_tokens' => 100
]);
```

### OpenAI (GPT)

[](#openai-gpt)

```
export OPENAI_API_KEY="your-key"
```

```
$gpt = openai();
$response = $gpt->prompt('Hello!', [
    'model' => 'gpt-4',
    'temperature' => 0.8
]);
```

### Ollama (Local LLMs)

[](#ollama-local-llms)

Run models locally with complete privacy and zero API costs:

```
# Install Ollama and pull models
ollama pull qwen3:8b
ollama pull gpt-oss:20b
ollama serve
```

```
$ollama = ollama();
$response = $ollama->prompt('Hello!', [
    'model' => 'qwen3:8b',
    'temperature' => 0.7
]);
```

**Benefits:**

- 🔒 Complete privacy - all data stays local
- 💰 Zero API costs
- ⚡ Low latency
- 🛠️ Full tool calling support (qwen3, llama3.1, mistral)
- 📡 NDJSON streaming

**📖 Full Guide:** [Ollama Integration](docs/ollama-integration.md)

Agent Pattern
-------------

[](#agent-pattern)

Agents provide a higher-level abstraction with conversation history:

```
// Define an agent
agent('support')
    ->provider('anthropic')
    ->system('You are a customer support agent')
    ->model('claude-3-haiku-20240307')
    ->temperature(0.3);

// Have a conversation
$agent = agent('support');
$agent->prompt('I need help with my order');
$agent->prompt('Order number is 12345');

// Access conversation history
foreach ($agent->messages as $message) {
    echo "[{$message['role']}]: {$message['content']}\n";
}
```

Provider Configuration
----------------------

[](#provider-configuration)

Pagent supports two ways to configure providers:

### String-Based (Simple)

[](#string-based-simple)

Use provider names for quick setup with default configuration:

```
agent('assistant')
    ->provider('anthropic')  // String name
    ->system('You are helpful');

// With config options
agent('custom')
    ->provider('ollama', ['base_url' => 'http://custom:11434', 'timeout' => 180])
    ->model('qwen3:8b');
```

### Instance-Based (Advanced)

[](#instance-based-advanced)

Use helper functions or direct instantiation for custom configuration:

```
// Using helper functions
agent('assistant')
    ->provider(anthropic(['api_key' => 'custom-key']))
    ->prompt('Hello');

agent('local')
    ->provider(ollama(['timeout' => 300, 'base_url' => 'http://10.0.0.5:11434']))
    ->model('llama3.1');

// Direct instantiation
use Pagent\Providers\OpenAI;

agent('custom')
    ->provider(new OpenAI(['api_key' => getenv('CUSTOM_KEY')]))
    ->prompt('Hello');
```

**When to use each:**

- **String-based**: Quick setup, standard configuration
- **Instance-based**: Custom config, multiple providers with same name, testing

Provider-Specific Features
--------------------------

[](#provider-specific-features)

The library is intentionally "leaky" - you can use provider-specific features:

```
// Anthropic-specific models
$response = anthropic()->prompt('Complex analysis task', [
    'model' => 'claude-3-opus-20240229',
    'max_tokens' => 4096
]);

// OpenAI-specific features
$response = openai()->prompt('Generate JSON data', [
    'model' => 'gpt-3.5-turbo-1106',
    'response_format' => ['type' => 'json_object']
]);
```

Tool Calling
------------

[](#tool-calling)

Define tools using PHP closures with automatic JSON schema generation:

```
use Pagent\Tool\Tool;

// Create a tool from a closure
$weatherTool = Tool::fromClosure(
    'get_weather',
    'Get the current weather for a location',
    fn(string $location, bool $include_forecast = false) => "Weather data..."
);

// Add tools to an agent
$agent = agent('assistant')
    ->provider('anthropic')
    ->tool('calculate', 'Perform calculations', fn(int $a, int $b) => $a + $b)
    ->tool('get_time', 'Get current time', fn(string $tz = 'UTC') => date('H:i:s'));

// Execute tools
$result = $agent->executeTool('calculate', [10, 5]); // 15

// Generate provider-specific schemas
$anthropicSchema = $weatherTool->toAnthropicSchema();
$openaiSchema = $weatherTool->toOpenAISchema();
```

Type hints are automatically converted to JSON schema types:

- `string` → `"string"`
- `int` → `"integer"`
- `float` → `"number"`
- `bool` → `"boolean"`
- `array` → `"array"`

### Class-Based Tools

[](#class-based-tools)

Pagent includes 9 production-ready class-based tools in the `Pagent\Tools` namespace:

```
use Pagent\Tools\FileRead;
use Pagent\Tools\FileWrite;
use Pagent\Tools\WebFetch;
use Pagent\Tools\Bash;
use Pagent\Tools\Grep;
use Pagent\Tools\Glob;
use Pagent\Tools\PdfReader;
use Pagent\Tools\DataExtract;
use Pagent\Tools\SearchTool;

// Use class-based tools with agents
$agent = agent('assistant')
    ->provider('anthropic')
    ->tool(new FileRead())
    ->tool(new WebFetch())
    ->prompt('Read the file data.json and fetch https://api.example.com/data');

// Add multiple tools at once
$agent = agent('file-assistant')
    ->provider('anthropic')
    ->tools([
        new FileRead(baseDir: '/project'),
        new FileWrite(baseDir: '/project'),
        new Glob(baseDir: '/project'),
        new Grep(baseDir: '/project'),
    ])
    ->prompt('List all PHP files and show me the config');

// Create custom class-based tools
use Pagent\Tools\Tool;

class DatabaseQuery extends Tool
{
    public function name(): string
    {
        return 'query_database';
    }

    public function description(): string
    {
        return 'Execute a database query and return results';
    }

    public function parameters(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'query' => ['type' => 'string', 'description' => 'SQL query to execute'],
                'limit' => ['type' => 'integer', 'description' => 'Maximum rows to return'],
            ],
            'required' => ['query'],
        ];
    }

    public function execute(array $params): mixed
    {
        // Your implementation here
        return ['results' => []];
    }
}

// Use your custom tool
agent('assistant')->tool(new DatabaseQuery());
```

Both closure-based and class-based tools implement `ToolInterface` and work seamlessly with all providers.

### SearchTool - Full-Text Search

[](#searchtool---full-text-search)

The `SearchTool` provides powerful full-text search capabilities powered by TNTSearch, enabling agents to search through documents, files, and databases:

```
use Pagent\Tools\SearchTool;

// Search through an array of documents (RAG pattern)
$documents = [
    ['id' => 1, 'title' => 'PHP Guide', 'content' => 'Learn PHP programming...'],
    ['id' => 2, 'title' => 'Laravel Tutorial', 'content' => 'Build web apps with Laravel...'],
];

agent('docs-assistant')
    ->tools([searchDocuments($documents)])
    ->prompt('Find information about PHP');

// Search through files in a directory
agent('codebase-helper')
    ->tools([new SearchTool(paths: ['docs/', 'src/'])])
    ->prompt('Find all documentation about API endpoints');

// Use a pre-built search index
agent('knowledge-bot')
    ->tools([searchIndex('knowledge/docs.index')])
    ->prompt('Search the knowledge base for deployment guides');

// Database-backed search
agent('db-search')
    ->tools([
        new SearchTool(
            query: 'SELECT id, title, content FROM articles',
            connection: ['driver' => 'mysql', 'host' => 'localhost', 'database' => 'mydb']
        )
    ])
    ->prompt('Find articles about Laravel');
```

**Key Features:**

- **Multiple Document Sources**: Arrays, files, directories, databases, or pre-built indexes
- **Fuzzy Matching**: Handles typos and approximate matches
- **BM25 Ranking**: Industry-standard relevance scoring
- **Flexible Returns**: Get just IDs or full document content
- **Fast Performance**: Sub-millisecond to millisecond search times
- **UTF-8 Support**: Works with international characters

**Configuration Options:**

```
new SearchTool(
    documents: $docs,           // Array of documents to index
    returnContent: true,        // Return full documents vs just IDs
    fuzzy: true,                // Enable fuzzy search
    fuzziness: 2,               // Levenshtein distance (1-3)
    maxResults: 20,             // Max results to return
    storage: ':memory:',        // Index storage location
    stemmer: PorterStemmer::class  // Custom stemmer class
);
```

**Search Results:**

```
[
    'hits' => 3,
    'execution_time' => '1.5ms',
    'results' => [
        ['id' => 1, 'score' => 4.2, 'document' => [...]],
        ['id' => 2, 'score' => 3.8, 'document' => [...]],
    ]
]
```

Perfect for building:

- RAG (Retrieval-Augmented Generation) systems
- Documentation search agents
- Knowledge base assistants
- Semantic code search
- Content discovery tools

Observability & Distributed Tracing
---------------------------------------

[](#observability--distributed-tracing)

Pagent includes comprehensive OpenTelemetry instrumentation for monitoring and debugging your LLM agents in production.

### Quick Start

[](#quick-start-1)

```
use function Pagent\{agent, telemetry_console};

// Enable console telemetry for debugging
telemetry_console(verbose: true);

agent('assistant')
    ->provider('anthropic')
    ->telemetry(true)  // Enable tracing for this agent
    ->prompt('Hello!');

// Console shows:
// ┌─ Span: agent.prompt
// │  Duration: 1.23s
// │  Attributes:
// │    - gen_ai.system: anthropic
// │    - gen_ai.usage.total_tokens: 125
// └─
```

### Production Monitoring

[](#production-monitoring)

Connect to Jaeger, Zipkin, or any OpenTelemetry-compatible platform:

```
use function Pagent\{agent, telemetry_jaeger};

// Export to Jaeger
telemetry_jaeger('http://localhost:14268/api/traces');

// All operations automatically traced
agent('support')
    ->telemetry(true)
    ->tool('search', 'Search knowledge base', $searchFn)
    ->prompt('Help me find documentation');

// View traces at http://localhost:16686
```

### What Gets Traced

[](#what-gets-traced)

- **Agent Operations** - Every prompt, stream, and tool execution
- **LLM Requests** - Provider calls with token usage
- **Tool Executions** - Arguments, results, and duration
- **Guard Checks** - Security validations
- **Memory Operations** - Load/save operations
- **Workflows** - Multi-agent pipeline orchestration

### Supported Platforms

[](#supported-platforms)

- **Jaeger** - Open-source distributed tracing
- **Zipkin** - Distributed tracing system
- **OTLP** - Generic protocol (Datadog, New Relic, Honeycomb, etc.)
- **Console** - Local debugging output

### Multi-Agent Workflow Tracing

[](#multi-agent-workflow-tracing)

```
use function Pagent\{agent, pipeline, telemetry_jaeger};

telemetry_jaeger('http://localhost:14268/api/traces');

// Enable telemetry on agents
agent('researcher')->provider('anthropic')->telemetry(true);
agent('writer')->provider('anthropic')->telemetry(true);

// Run workflow - creates hierarchical trace
pipeline('content-creation')
    ->step('research', agent('researcher'))
    ->step('write', agent('writer'))
    ->run('Write article about PHP');

// Trace shows:
// workflow.pipeline
//   ├─ workflow.step (research)
//   │  └─ agent.prompt → llm.request → tool.execute
//   └─ workflow.step (write)
//      └─ agent.prompt → llm.request
```

### Benefits

[](#benefits)

- **Debug Complex Workflows** - Visualize multi-agent interactions
- **Performance Monitoring** - Track latency and bottlenecks
- **Token Usage Tracking** - Real-time token consumption
- **Cost Visibility** - Understand API usage patterns
- **Compliance** - Complete audit trail

**📖 Full Guide:** [Observability Documentation](docs/observability.md)

Development
-----------

[](#development)

### Quick Commands

[](#quick-commands)

```
# Setup project
just setup              # Install dependencies and git hooks

# Testing
just test               # Run all tests
just coverage           # Run tests with coverage report

# Code Quality
just format             # Fix code style (PHP + Markdown)
just analyse            # Run PHPStan static analysis
just pr                 # Prepare for PR (fix, analyse, test)

# Observability Stack
just obs-up             # Start observability tools (Jaeger, Phoenix, Langfuse, etc.)
just obs-down           # Stop and remove observability stack
```

### Manual Testing

[](#manual-testing)

```
# Run unit tests (no API calls)
./vendor/bin/pest --exclude-group=api

# Run API integration tests (requires API keys)
cp .env.example .env    # Add your keys to .env
./vendor/bin/pest --group=api
```

Documentation
-------------

[](#documentation)

### The Complete Guide

[](#the-complete-guide)

The **[Pagent Guide](guide/complete.md)** is a comprehensive 28-chapter tutorial covering everything from basics to advanced patterns:

- **Part 1: Foundations** (Chapters 1-5) - Core concepts and basic usage
- **Part 2: Tool Integration** (Chapters 6-9) - External system interactions
- **Part 3: Real-Time Interaction** (Chapters 10-11) - Streaming responses
- **Part 4: Persistence and State** (Chapters 12-13) - Memory and conversations
- **Part 5: Reliability and Safety** (Chapters 14-15) - Production robustness
- **Part 6: Multi-Agent Orchestration** (Chapters 16-19) - Agent coordination
- **Part 7: Quality Assurance** (Chapters 20-21) - Testing and evaluation
- **Part 8: Observability** (Chapters 22-23) - Monitoring and debugging
- **Part 9: Integration** (Chapters 24-25) - Framework integration
- **Part 10: Production Excellence** (Chapters 26-28) - Optimization and deployment

See **[guide/README.md](guide/README.md)** for learning paths based on your experience level.

### Integration Guides

[](#integration-guides)

Learn how to integrate Pagent into your application:

- **[Vanilla PHP](docs/vanilla-php.md)** - Pure PHP integration without frameworks
- **[Slim Framework Integration](docs/slim-integration.md)** - Complete Slim 4.x setup with DI and middleware
- **[Laravel Integration](docs/laravel-integration.md)** - Laravel setup with service providers and facades
- **[Symfony Integration](docs/symfony-integration.md)** - Symfony bundle integration with DI container

### Feature Guides

[](#feature-guides)

Deep-dive into specific features:

- **[Streaming Guide](docs/streaming.md)** - Real-time SSE streaming implementation
- **[Memory & Persistence](docs/memory-persistence.md)** - SQLite, File, and custom storage adapters
- **[Orchestration Workflows](docs/orchestration-workflows.md)** - Multi-agent patterns: pipelines, handoffs, delegation

See the [docs/](docs/) folder for all guides.

---

Contributing
------------

[](#contributing)

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on:

- Development setup
- Running tests
- Code style guidelines
- Pull request process

Read our [Code of Conduct](CODE_OF_CONDUCT.md) and [Security Policy](SECURITY.md).

Changelog
---------

[](#changelog)

See [CHANGELOG.md](CHANGELOG.md) for recent changes.

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

Credits
-------

[](#credits)

Created by [Helge Sverre](https://helgesver.re).

Inspired by [Pest](https://pestphp.com)'s elegant API design.

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance73

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

166d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/68f3958f40262d577ddc0596e4ba78b42c0409ebc7de948bab47edee392d5f68?d=identicon)[HelgeSverre](/maintainers/HelgeSverre)

---

Top Contributors

[![HelgeSverre](https://avatars.githubusercontent.com/u/1089652?v=4)](https://github.com/HelgeSverre "HelgeSverre (172 commits)")

---

Tags

agentsllmllm-frameworkphptool-callingphppestaiopenaiAgentclaudechatbotllmanthropicgpttool-calling

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/helgesverre-pagent/health.svg)

```
[![Health](https://phpackages.com/badges/helgesverre-pagent/health.svg)](https://phpackages.com/packages/helgesverre-pagent)
```

###  Alternatives

[theodo-group/llphant

LLPhant is a library to help you build Generative AI applications.

1.5k311.5k5](/packages/theodo-group-llphant)[cognesy/instructor-php

The complete AI toolkit for PHP: unified LLM API, structured outputs, agents, and coding agent control

310107.9k1](/packages/cognesy-instructor-php)[sbsaga/toon

🧠 TOON for Laravel — a compact, human-readable, and token-efficient data format for AI prompts & LLM contexts. Perfect for ChatGPT, Gemini, Claude, Mistral, and OpenAI integrations (JSON ⇄ TOON).

6115.6k](/packages/sbsaga-toon)[vizra/vizra-adk

Vizra Agent Development Kit - A comprehensive Laravel package for building intelligent AI agents.

29026.1k](/packages/vizra-vizra-adk)[helgesverre/toon

Token-Oriented Object Notation - A compact data format for reducing token consumption when sending structured data to LLMs

11841.4k9](/packages/helgesverre-toon)[llm-agents/agents

LLM Agents PHP SDK - Autonomous Language Model Agents for PHP

16410.9k9](/packages/llm-agents-agents)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)