https://github.com/carmelosantana/php-agents
PHP 8.4+ AI agent framework
https://github.com/carmelosantana/php-agents
Last synced: 21 days ago
JSON representation
PHP 8.4+ AI agent framework
- Host: GitHub
- URL: https://github.com/carmelosantana/php-agents
- Owner: carmelosantana
- License: mit
- Created: 2026-02-12T21:34:07.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-21T21:03:27.000Z (21 days ago)
- Last Synced: 2026-04-21T23:12:40.468Z (21 days ago)
- Language: PHP
- Size: 416 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: docs/AGENTS.md
Awesome Lists containing this project
- awesome-php-ml - carmelosantana/php-agents - model support (LLMs & AI APIs / Recommended core stack)
README
# php-agents
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, or local models via Ollama. You provide the toolkits; php-agents provides the agent loop.
```mermaid
graph LR
APP[Your App] --> AGENT[Agent]
AGENT --> PROVIDER[Provider
OpenAI / Anthropic / Ollama]
AGENT --> TOOLS[Tools & Toolkits
Custom Toolkits]
AGENT --> OBSERVER[Observers
Logging / Streaming / Metrics]
PROVIDER --> LLM[LLM]
LLM -->|tool calls| AGENT
TOOLS -->|results| AGENT
```
## Features
- **Agentic tool-use loop** — automatic iteration: the LLM calls tools, processes results, and decides when it's done
- **Multi-provider** — Ollama (local), 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
| Feature | OpenAI Compatible | OpenAI Responses | Ollama | Anthropic | Gemini | xAI | Mistral |
| ---------------------- | :---------------: | :--------------: | :----: | :-------: | :----: | :---: | :-----: |
| `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
- PHP 8.4 or later
- Extensions: `curl`, `json`, `mbstring`
- Composer 2.x
- [Ollama](https://ollama.ai) (recommended for local inference)
## Installation
```bash
composer require carmelosantana/php-agents
```
## Quick Start
Create an agent with a custom tool:
```php
addTool(new Tool(
name: 'add',
description: 'Add two numbers',
parameters: [
new NumberParameter('a', 'First number', required: true),
new NumberParameter('b', 'Second number', required: true),
],
callback: fn(array $args): ToolResult => ToolResult::success(
(string) ($args['a'] + $args['b']),
),
));
$output = $agent->run(new UserMessage('What is 42 + 58?'));
echo $output->content . "\n";
```
> Make sure Ollama is running: `ollama serve` and a model is pulled: `ollama pull llama3.2`
## Providers
```php
use CarmeloSantana\PHPAgents\Provider\OllamaProvider;
use CarmeloSantana\PHPAgents\Provider\OpenAICompatibleProvider;
use CarmeloSantana\PHPAgents\Provider\AnthropicProvider;
use CarmeloSantana\PHPAgents\Provider\GeminiProvider;
use CarmeloSantana\PHPAgents\Provider\XAIProvider;
use CarmeloSantana\PHPAgents\Provider\MistralProvider;
// Ollama (local — no API key needed)
$provider = new OllamaProvider(model: 'llama3.2');
// OpenAI
$provider = new OpenAICompatibleProvider(
model: 'gpt-4o',
apiKey: getenv('OPENAI_API_KEY'),
);
// Anthropic
$provider = new AnthropicProvider(
model: 'claude-sonnet-4-20250514',
apiKey: getenv('ANTHROPIC_API_KEY'),
);
// Google Gemini
$provider = new GeminiProvider(
model: 'gemini-2.5-flash',
apiKey: getenv('GEMINI_API_KEY'),
);
// xAI (Grok)
$provider = new XAIProvider(
model: 'grok-3',
apiKey: getenv('XAI_API_KEY'),
);
// Mistral
$provider = new MistralProvider(
model: 'mistral-large-latest',
apiKey: getenv('MISTRAL_API_KEY'),
);
// Any OpenAI-compatible endpoint (OpenRouter, Together, Groq, vLLM, etc.)
$provider = new OpenAICompatibleProvider(
model: 'meta-llama/llama-3.1-70b-instruct',
apiKey: getenv('OPENROUTER_API_KEY'),
baseUrl: 'https://openrouter.ai/api/v1',
);
```
## Creating Custom Agents
Extend `AbstractAgent` and implement `instructions()`:
```php
addToolkit()` to give your agent capabilities.
## Creating Custom Tools
Define tools with typed parameters and a callback:
```php
use CarmeloSantana\PHPAgents\Tool\Tool;
use CarmeloSantana\PHPAgents\Tool\ToolResult;
use CarmeloSantana\PHPAgents\Tool\Parameter\StringParameter;
$tool = new Tool(
name: 'word_count',
description: 'Count words in the given text',
parameters: [
new StringParameter('text', 'The text to count words in', required: true),
],
callback: fn(array $args): ToolResult => ToolResult::success(
'Word count: ' . str_word_count($args['text']),
),
);
```
Group related tools into a toolkit by implementing `ToolkitInterface`:
```php
use CarmeloSantana\PHPAgents\Contract\ToolkitInterface;
final class MyToolkit implements ToolkitInterface
{
public function tools(): array
{
return [$this->buildWordCountTool(), /* ... */];
}
public function guidelines(): string
{
return 'Use these tools to analyze text.';
}
}
```
### Toolkit Auto-Discovery
Publish your toolkit as a Composer package with auto-discovery:
```json
{
"extra": {
"php-agents": {
"toolkits": ["Acme\\MyToolkit\\MyToolkit"],
"credentials": {
"MY_API_KEY": "API key for MyService — get one at https://myservice.com/keys"
}
}
}
}
```
## Documentation
| Guide | Description |
| ---------------------------------------------- | -------------------------------------------------------- |
| [Architecture](docs/architecture.md) | System design, Mermaid diagrams, extension points |
| [Getting Started](docs/getting-started.md) | Installation, provider setup, first agent |
| [Providers](docs/providers.md) | Feature matrix, streaming, structured output, images |
| [Tools & Toolkits](docs/tools-and-toolkits.md) | Parameter types, execution policies, publishing packages |
| [Agents](docs/agents.md) | Agent loop, observers, cancellation, context window |
| [Embeddings & Vector Stores](docs/memory.md) | Vector similarity search, embedding providers |
## Examples
Working examples live in the [`examples/`](examples/) directory:
| Example | Description | Run |
| --------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------- |
| [CLI Chat](examples/cli-chat.php) | Interactive terminal conversation with an LLM | `php examples/cli-chat.php` |
| [README Summarizer](examples/web-summarizer/) | Web UI that auto-summarizes this README using an agent | `php -S localhost:8080 -t examples/web-summarizer/` |
## `php-agents` In The Wild
[Coqui](https://github.com/AgentCoqui/coqui) is a full AI assistant product built on php-agents. It demonstrates the framework's extensibility:
- **php-agents** is the **library** — agent loop, providers, tools, messages, embeddings
- **Coqui** is the **product** — REPL, API server, session persistence, multi-agent orchestration, credential management, security policies, toolkit discovery
Coqui adds product logic on top of `php-agents` framework code, with zero code duplication. Each Coqui agent (`OrchestratorAgent`, `ChildAgent`) extends `AbstractAgent` — they are purely configuration layers.
## License
MIT