README

Important

Get early access to new features, exclusive tutorials, and expert tips for building AI agents in PHP. Join a community of PHP developers pioneering the future of AI development. Subscribe to the newsletter

Before moving on, support the Neuron AI community giving a GitHub star ⭐️. Thank you!

What is Neuron?

Neuron is a PHP framework for creating and orchestrating AI Agents. It allows you to integrate AI entities into your PHP applications with a powerful and flexible architecture. We provide tools for the entire agentic application development lifecycle, from LLM interfaces, data loading, multi-agent orchestration, to monitoring and debugging. In addition, we provide tutorials and other educational content to help you get started using AI Agents in your projects.

Video Tutorial

Why Neuron Is Unique

Most agentic frameworks ask you to pick a side. Some are simple enough to learn in an afternoon, and you hit a wall the first time your use case grows beyond a demo. Others are powerful enough for a use case but you spend weeks fighting their abstractions before you ship anything real.

Neuron is built on a Workflow architecture that removes those compromises. The first spark came from the Workflow concept on LLmaindex in the Python world. Shaped around the patterns of modern PHP, the Neuron Workflow is a PHP native solution that now follows a path of its own, one we continue to draw as the agentic ecosystem in PHP takes shape around it.

The result is one foundation that a newcomer can pick up on the first day, and that already carries everything a serious agent needs underneath: unified messaging layer, tools & toolkits, MCP, human-in-the-loop, agentic UI protocols, multi-agent interactions, asynchronous execution, and more. You never switch frameworks when your project gets ambitious. The architecture you learned at the start of this journey is the same one running your most complex system in production in the future.

A Vertical & Independent Ecosystem

Neuron is also the only vertical ecosystem for agentic applications development in PHP. Around the framework there is a registry of extensions, tools, and technologies designed specifically for agentic applications, and a growing number of companies building on the same architecture instead of assembling their own from scattered parts.

For a software house, this is a place to be recognized as a specialist rather than one more team claiming AI experience. For a company that needs an agentic foundation it can commit to for years, it means standardizing on an architecture whose whole direction is this space, not a general-purpose library where agents are a side feature.

Requirements

PHP: ^8.1

Official documentation

Go to the official documentation

Install

Install the latest version via composer:

composer require neuron-core/neuron-ai

Create an Agent

Neuron provides you with the Agent class you can extend to inherit the main features of the framework and create fully functional agents. This class automatically manages some advanced mechanisms for you, such as memory, tools, and function calls, up to RAG (Retrieval Augmented Generation). You can go deeper into these aspects in the documentation.

Let's create an Agent with the command below:

vendor/bin/neuron make:agent DataAnalystAgent

<?php

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Agent\SystemPrompt;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

class DataAnalystAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }

    protected function instructions(): string
    {
        return (string) new SystemPrompt(
            background: [
                "You are a data analyst expert in creating reports from SQL databases."
            ]
        );
    }
}

The SystemPrompt class is designed to take your base instructions and build a consistent prompt for the underlying model reducing the effort for prompt engineering.

Talk to the Agent

Send a message to the agent to get a response from the underlying LLM:

$agent = DataAnalystAgent::make();


$response = $agent->chat(
    new UserMessage("Hi, I'm Valerio. Who are you?")
)->getMessage();
echo $response->getContent();
// I'm a data analyst. How can I help you today?


$response = $agent->chat(
    new UserMessage("Do you remember my name?")
)->getMessage();
echo $response->getContent();
// Your name is Valerio, as you said in your introduction.

As you can see in the example above, the Agent has memory of the ongoing conversation. Learn more about memory in the documentation.

Monitoring & Debugging

Integrating AI Agents into your application, you’re not working only with functions and deterministic code, you program your agent influencing probability distributions. Same input ≠ output. That means reproducibility, versioning, and debugging become real problems.

Many of the Agents you build with Neuron will contain multiple steps with multiple invocations of LLM calls, tool usage, access to external memories, etc. As these applications get more and more complex, it becomes crucial to be able to inspect what exactly your agent is doing and why.

Why is the model taking certain decisions? What data is the model reacting to? Prompting is not programming in the common sense. No static types, small changes break output, long prompts cost latency, and no two models behave exactly the same with the same prompt.

The best way to take your AI application under control is with Inspector. After you sign up, make sure to set the INSPECTOR_INGESTION_KEY variable in the application environment file to start monitoring:

INSPECTOR_INGESTION_KEY=fwe45gtxxxxxxxxxxxxxxxxxxxxxxxxxxxx

After configuring the environment variable, you will see the agent execution timeline in your Inspector dashboard.

Learn more about Monitoring in the documentation.

Supported LLM Providers

With Neuron, you can switch between LLM providers with just one line of code, without any impact on your agent implementation. Supported providers:

Tools & Toolkits

Make your agent able to perform concrete tasks, like reading from a database, by adding tools or toolkits (collections of tools).

<?php

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\Agent\SystemPrompt;
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\Toolkits\MySQL\MySQLToolkit;

class DataAnalystAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }

    protected function instructions(): string
    {
        return (string) new SystemPrompt(
            background: [
                "You are a data analyst expert in creating reports from SQL databases."
            ]
        );
    }

    protected function tools(): array
    {
        return [
            MySQLToolkit::make(
                \DB::connection()->getPdo()
            ),
        ];
    }
}

Ask the agent something about your database:

$response = DataAnalystAgent::make()->chat(
    new UserMessage("How many orders we received today?")
)->getMessage();

echo $response->getContent();

Learn more about Tools in the documentation.

MCP Connector

Instead of implementing tools manually, you can connect tools exposed by an MCP server with the McpConnector component:

<?php

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\MCP\McpConnector;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\Tool;

class DataAnalystAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        ...
    }

    protected function instructions(): string
    {
        ...
    }

    protected function tools(): array
    {
        return [
            // Connect to an MCP server
            ...McpConnector::make([
                'command' => 'npx',
                'args' => ['-y', '@modelcontextprotocol/server-everything'],
            ])->tools(),
        ];
    }
}

Learn more about MCP connector in the documentation.

Structured Output

There are scenarios where you need Agents to understand natural language, but output in a structured format, like business processes automation, data extraction, etc. to use the output with other downstream systems.

use App\Neuron\MyAgent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\StructuredOutput\SchemaProperty;

/*
 * Define the output structure as a PHP class.
 */
class Person
{
    #[SchemaProperty(
        description: 'The user name',
        required: true
    )]
    public string $name;

    #[SchemaProperty(
        description: 'What the user love to eat'
    )]
    public string $preference;
}

/*
 * Talk to the agent requiring the structured output
 */
$person = MyAgent::make()->structured(
    new UserMessage("I'm John and I like pizza!"),
    Person::class
);

echo $person->name ' like '.$person->preference;
// John like pizza

Learn more about Structured Output on the documentation.

RAG

To create a RAG, you need to attach some additional components other than the AI provider, such as a vector store, and an embeddings provider.

Let's create a RAG with the command below:

vendor/bin/neuron make:rag MyChatBot

Here is an example of a RAG implementation:

<?php

namespace App\Neuron;

use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\RAG\Embeddings\EmbeddingsProviderInterface;
use NeuronAI\RAG\Embeddings\VoyageEmbeddingProvider;
use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\PineconeVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }

    protected function embeddings(): EmbeddingsProviderInterface
    {
        return new VoyageEmbeddingProvider(
            key: 'VOYAGE_API_KEY',
            model: 'VOYAGE_MODEL'
        );
    }

    protected function vectorStore(): VectorStoreInterface
    {
        return new PineconeVectorStore(
            key: 'PINECONE_API_KEY',
            indexUrl: 'PINECONE_INDEX_URL'
        );
    }
}

Learn more about RAG in the documentation.

Workflow

Think of a Workflow as a smart flowchart for your AI applications. The idea behind Workflow is to allow developers to use all the Neuron components like AI providers, embeddings, data loaders, chat history, vector store, etc., as standalone components to create totally customized agentic systems.

Agent and RAG classes represent a ready to use implementation of the most common patterns when it comes to retrieval use cases, or tool calls, structured output, etc. Workflow allows you to program your agentic system completely from scratch. Agent and RAG can be used inside a Workflow to complete tasks as any other component if you need their built-in capabilities.

Neuron Workflow supports a robust human-in-the-loop pattern, enabling human intervention at any point in an automated process. This is especially useful in large language model (LLM)-driven applications where model output may require validation, correction, or additional context to complete the task.

Learn more about Workflow on the documentation.

AI Assisted Development

When working with AI coding assistants like Claude Code, Opencode, Cursor, or other similar tools, you have two options to give the AI deep context about Neuron components. This leads to more accurate code suggestions, better understanding of component APIs, and fewer hallucinations when generating Neuron code:

Security Vulnerabilities

If you discover a security vulnerability within Neuron, please send an e-mail to the Inspector team via support@inspector.dev. All security vulnerabilities will be promptly addressed.

Official documentation

Go to the official documentation

Development

To run the full test suite locally, use Docker Compose to spin up all the services required by the CI environment:

# Start all services
docker compose up -d

Run the test suite:

# Install dependencies and run tests
docker compose run --rm php composer update --prefer-stable
docker compose run --rm php vendor/bin/phpunit

To stop all services:

docker compose down

neuron-core / neuron-ai

Maintainers

Package info

Fund package maintenance!

Statistics

Security

README

What is Neuron?

Why Neuron Is Unique

A Vertical & Independent Ecosystem

Requirements

Official documentation

How To

Install

Create an Agent

Talk to the Agent

Monitoring & Debugging

Supported LLM Providers

Tools & Toolkits

MCP Connector

Structured Output

RAG

Workflow

AI Assisted Development

Security Vulnerabilities

Official documentation

Development