PHPackages                             carmelosantana/php-agents - 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. [Framework](/categories/framework)
4. /
5. carmelosantana/php-agents

ActiveLibrary[Framework](/categories/framework)

carmelosantana/php-agents
=========================

PHP 8.4+ agent framework — interfaces, tools, and providers for building AI agents

v0.15.0(4d ago)16.6k↓57.7%20MITPHPPHP ^8.4CI passing

Since Feb 12Pushed 4d ago1 watchersCompare

[ Source](https://github.com/carmelosantana/php-agents)[ Packagist](https://packagist.org/packages/carmelosantana/php-agents)[ RSS](/packages/carmelosantana-php-agents/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (16)Versions (69)Used By (20)

php-agents
==========

[](#php-agents)

 [![CI status](https://camo.githubusercontent.com/87e73b54b289719a444fbffa0f2addcb864d87decfdf29815df4c89d731f5161/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6361726d656c6f73616e74616e612f7068702d6167656e74732f63692e796d6c3f6272616e63683d6d61696e267374796c653d666f722d7468652d6261646765)](https://github.com/carmelosantana/php-agents/actions/workflows/ci.yml?branch=main) [![GitHub release](https://camo.githubusercontent.com/e205270268eeeb1e56b7abc6b7e65e0cf1dac427d18b9ef9f1c21c4ac2414b82/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6361726d656c6f73616e74616e612f7068702d6167656e74733f696e636c7564655f70726572656c6561736573267374796c653d666f722d7468652d6261646765)](https://github.com/carmelosantana/php-agents/releases) [![PHP 8.4+](https://camo.githubusercontent.com/ce5e24773098115a50622c27c941e289b32b14a58fca172ffd80fcaaba1f0066/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e342532422d3737374242343f7374796c653d666f722d7468652d6261646765266c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://www.php.net/) [![Discord](https://camo.githubusercontent.com/ad8c3cd1e373c696afd573100b3fc563fd552944e567eb2113a5cb486ebf6325/68747470733a2f2f696d672e736869656c64732e696f2f646973636f72642f313437313633323635343632343438393636383f6c6162656c3d446973636f7264266c6f676f3d646973636f7264266c6f676f436f6c6f723d776869746526636f6c6f723d353836354632267374796c653d666f722d7468652d6261646765)](https://discord.gg/Vc29xdvGAH) [![MIT License](https://camo.githubusercontent.com/1736263e7abccd5448e130c257555354792cbceae6b18535e86d6157f95b906f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75653f7374796c653d666f722d7468652d6261646765)](LICENSE)

PHP 8.4+ framework for building AI agents with tool-use loops, provider abstraction, and composable toolkits.

Build agents that reason, use tools, and iterate autonomously — powered by any OpenAI-compatible API, Anthropic, local models via Ollama, or a native llama.cpp runtime. You provide the toolkits; php-agents provides a non-opinionated agent loop.

 ```
graph LR
    APP[Your App] --> AGENT[Agent]
    AGENT --> PROVIDER[ProviderOpenAI / Anthropic / Ollama / llama.cpp]
    AGENT --> TOOLS[Tools & ToolkitsCustom Toolkits]
    AGENT --> OBSERVER[ObserversLogging / Streaming / Metrics]
    PROVIDER --> LLM[LLM]
    LLM -->|tool calls| AGENT
    TOOLS -->|results| AGENT
```

      Loading Features
--------

[](#features)

- **Agentic tool-use loop** — automatic iteration: the LLM calls tools, processes results, and decides when it's done
- **Multi-provider** — Ollama (local), native llama.cpp, the Claude Code CLI (`claude`), OpenAI, Anthropic, Gemini, xAI, Mistral, OpenRouter, or any OpenAI-compatible endpoint
- **Streaming + tool calls** — all providers support streaming with assembled tool call deltas
- **Structured output** — extract typed data from LLMs via JSON mode (OpenAI) or tool-use trick (Anthropic)
- **Image input** — send images to vision models via base64, URL, or file path (auto-converts between provider formats; URLs pre-downloaded for providers that don't support them natively)
- **Composable toolkits** — implement `ToolkitInterface` to give agents any capability; no built-in toolkit implementations
- **Context window management** — automatic conversation pruning when approaching token limits
- **Observer pattern** — attach `SplObserver` to watch agent lifecycle events in real time
- **Embedding & vector stores** — `EmbeddingProviderInterface` and `VectorStoreInterface` for semantic search
- **OpenClaw config** — centralized model routing with aliases, fallbacks, and per-provider settings
- **PSR-3 logging** — optional `LoggerInterface` on all providers for diagnostic visibility
- **Zero framework coupling** — depends only on `symfony/http-client` and `psr/log`

Provider Feature Matrix
-----------------------

[](#provider-feature-matrix)

FeatureOpenAI CompatibleOpenAI ResponsesOllamaAnthropicGeminixAIMistral`chat()`✅✅✅✅✅✅✅`stream()`✅✅✅✅✅✅✅`structured()`✅✅✅✅✅✅✅Tool calling✅✅✅✅✅✅✅Streaming + tool calls✅✅✅✅✅✅✅Image input (base64)✅✅✅✅✅✅✅Image input (URL)✅✅✅✅\*✅✅`models()` list✅✅✅✅✅✅✅`isAvailable()`✅✅✅✅✅✅✅*\* Gemini does not natively support URL image references. The provider auto-downloads URL images and converts them to base64 `inlineData`.*

Requirements
------------

[](#requirements)

- PHP 8.4 or later
- Extensions: `curl`, `json`, `mbstring`
- Composer 2.x
- [Ollama](https://ollama.ai) (recommended for local inference)

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

[](#installation)

```
composer require carmelosantana/php-agents
```

Local Inference Modes
---------------------

[](#local-inference-modes)

- `OllamaProvider` is the easiest local path and remains the default quick-start option.
- The native llama.cpp runtime is for direct FFI-based local inference without an HTTP sidecar.
- The full native setup, benchmarking, and comparison workflow lives in [docs/LOCAL-RUNTIME.md](docs/LOCAL-RUNTIME.md).

Fastest path to validate native llama.cpp in this repo:

```
composer setup:llama-cpp
source ./.llama-cpp.env
composer test:llama-cpp-runtime -- --skip-remote
composer compare:llama-cpp-vs-ollama
```

The setup script writes a local `.llama-cpp.env` file for your machine. That file is generated runtime state and should not be committed.

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

[](#quick-start)

Create an agent with a custom tool:

```