NanoAgent PHP

Add AI agents to your PHP app in an afternoon — no Python sidecar, no framework to learn.

`composer require`, write a function, done. NanoAgent is a lightweight library designed to strip away the complexity of modern AI development. While other libraries force you into steep learning curves, massive dependency trees, and rigid architectural patterns, NanoAgent takes a different approach: **simplicity as a feature.** Whether you are building a complex autonomous agent or just need to integrate smart decision-making into a project, NanoAgent lets you focus on the task, not the configuration. ## Why NanoAgent? The AI landscape is filled with "everything-included" frameworks that are often too heavy for practical, day-to-day PHP development. * **Stop wrestling with complex configurations:** No need to learn a new DSL (Domain-Specific Language) or manage a dozen config files. * **Drop-in ready:** Works with Laravel, Symfony, Slim, or plain PHP scripts. * **Zero friction:** Go from `composer install` to a working agent in minutes. ## Features * **⚡ Adaptable**: Seamlessly switch between OpenAI, Groq, Anthropic, DeepSeek, and OpenRouter with a single line of config. * **🛠️ Tool-First Architecture**: Give your AI "hands." Easily map PHP functions as tools that your agent can intelligently execute to interact with your database, APIs, or filesystem. * **🔌 MCP Support**: Connect to any Model Context Protocol server (Streamable HTTP) and let the agent call its tools alongside your own. * **🎯 Goal-Oriented Execution**: Define clear, context-aware tasks. The agent handles the reasoning, you handle the results. * **💎 Minimalist Design**: A tiny footprint with massive potential. Use only what you need, with no hidden magic. ## 🚀 Quick Start This guide provides step-by-step instructions for installing, configuring, and running the NanoAgent PHP library in any PHP environment. ### Prerequisites - **PHP 8.0** or higher - **Composer** installed globally ### 📦 Installation & Setup 1. Initialize a project: 2. **Configuration** : Create `config.php` (copy the example from `NanoAgent/config.php.example`) in the project root to manage credentials. Then usage becomes: 3. **Troubleshooting** - **Class not found**: Run `composer dump-autoload` to regenerate the autoload files. - **API Error**: Check `config.php` or your environment variables to ensure the API key is correct. - **PHP Version**: Ensure you are running PHP 8.0+ by checking `php -v`. ## 🛠️ Advanced Usage: Tools Give your agent "hands" by defining tools. ### Connecting to an MCP Server Register every tool an [MCP](https://modelcontextprotocol.io) server exposes in one call — they behave exactly like local tools from there on. ## 🧠 Persistent Memory PHP forgets everything between requests. Attach a memory driver and the agent loads the conversation for a session, then saves it after every completed `chat()` / `stream()` call. | Driver | Storage | Requires | | --- | --- | --- | | `ArrayMemory` | Current process only (tests, workers) | — | | `FileMemory` | One JSON file per session | — | | `PdoMemory` | SQL table (SQLite, MySQL, PostgreSQL) | `ext-pdo` + driver | See the [PdoMemory guide](docs/pdo-memory.md) for MySQL/PostgreSQL connections, table schemas and cleanup. Need another backend (Redis, a framework cache, Eloquent)? Implement `NanoAgent\Contracts\Memory`: `load()`, `save()`, `clear()`. ## 📚 Resources * **Landing page**: [hammrouni.github.io/nanoagentphp](https://hammrouni.github.io/nanoagentphp/) — overview, specs, usage snippets and links * **Articles & posts** * [Why I Keep Coming Back to PHP (Even for AI Agents)](https://dev.to/khaled_hammrouni_bc97ab98/why-i-keep-coming-back-to-php-even-for-ai-agents-39g2) — Dev.to * [Why I Keep Coming Back to PHP, even for AI Agents](https://www.linkedin.com/pulse/why-i-keep-coming-back-php-even-ai-agents-khaled-hammrouni-dj53f) — LinkedIn * **Code**: [github.com/hammrouni/nanoagentphp](https://github.com/hammrouni/nanoagentphp) * **Package**: [packagist.org/packages/hammrouni/nanoagent](https://packagist.org/packages/hammrouni/nanoagent) ## 📂 Examples Check the `examples/` directory for advanced use cases: | Example | Description | | --- | --- | | **[Basic Usage](examples/basic.php)** | Fundamental agent initialization and task execution. | | **[Chat](examples/chat.php)** | Stateful conversation loop using PHP Sessions. | | **[Memory Chat](examples/memory_chat.php)** | Persistent conversation history with a pluggable memory driver. | | **[Structured Output](examples/structured_output.php)** | Extract JSON data from unstructured text. | | **[Knowledge Base](examples/knowledge_base_search.php)** | RAG: Ask questions against private documents. | | **[Streaming](examples/streaming.php)** | Real-time token streaming (SSE). | | **[Agent Chain](examples/agent_chain.php)** | Multi-agent workflow (Researcher feeds Writer). | | **[Multi-Tool](examples/multi_tool_workflow.php)** | Orchestrate multiple tools to solve complex requests. | | **[Advanced Tools](examples/advanced_tools.php)** | Complex multi-step tool usage with simulated database state. | | **[API Integration](examples/api_integration.php)** | Fetch real-world data from external APIs. | | **[Multi-Provider](examples/multi_provider.php)** | Switch between different AI providers programmatically. | | **[MCP Tools](examples/mcp_tools.php)** | Call tools discovered from a remote MCP server. | ## Supported Providers Every provider below is covered by the automated test suite (see the CI badge above). Groq has also been verified against the real API. * Groq * OpenAI * OpenRouter * DeepSeek * Anthropic — experimental. Built separately from the others, not yet verified against the real API, and streaming isn't fully wired up in this library yet. ## Changelog ### 0.5.0 1. Added persistent memory: `Agent::setMemory()` keeps conversations across requests, with `ArrayMemory`, `FileMemory` and `PdoMemory` (SQLite, MySQL, PostgreSQL) drivers, or your own via `NanoAgent\Contracts\Memory`. See the [PdoMemory guide](docs/pdo-memory.md). 2. Clarified in the README that all providers are already covered by the mocked unit test suite. ### 0.4.0 1. Added MCP (Model Context Protocol) client support: connect to any Streamable HTTP MCP server and register its tools on an `Agent` with `registerMcpServer()`. ### 0.3.0 1. Inject a custom provider directly into `Agent`, no config array needed. 2. Configure `temperature`, `max_tokens`, and a custom `base_url` per provider. 3. Streaming now supports tool calls. 4. More reliable request encoding for non-English text. ### 0.2.0 1. HTTP requests now have timeouts and surface real API errors instead of hanging or failing silently. 2. Tool-calling loops are capped to avoid runaway API usage. 3. Task context no longer leaks between calls. 4. Added static analysis (PHPStan) and a wider PHP version test matrix (8.0-8.4). ### 0.1.0 ## License MIT