Neuron — PHP-фреймворк для создания AI-агентов

Neuron — это PHP-фреймворк для создания AI-агентов и управления ими. Он задаёт архитектуру приложения: вы подключаете к агенту LLM, инструменты, векторную базу и память, а агент сам взаимодействует с вашими данными и интерфейсом. Лицензия — MIT, требование к языку — PHP 8.1 или новее. На момент публикации у репозитория около 2100 звёзд, последняя версия — 4.0.3, рабочая ветка — 4.x.

Проект не задуман как библиотека под одну узкую задачу. Разработчики позиционируют Neuron как основу приложения, в котором агент отвечает за логику работы системы. Речь не про чат-надстройку к привычному веб-приложению. Всё, что нужно для такого приложения, собрано в одном месте: работа с LLM, загрузка данных, оркестрация нескольких агентов, наблюдение и отладка.

Почему это нужно именно сейчас

Авторы README дают довольно смелый прогноз: следующее ваше приложение будет агентным. То есть всё большая доля нового софта — это не веб-приложение, в которое потом прикрутили AI-функции. Это приложение, построенное вокруг агента: агент сам выстраивает логику работы системы и общается с пользователем.

Чтобы такое приложение построить, нужны вполне конкретные вещи. Авторы перечисляют их прямо в README:

• событийные процессы с чекпоинтами, чтобы работу можно было продолжить после сбоя;
• человек в контуре — точка, где решение принимает живой человек, а не модель;
• прерывание выполнения;
• оркестрация нескольких агентов;
• потоковая выдача ответа;
• связка агента с интерфейсом через протоколы AG-UI и Vercel AI SDK;
• коннекторы к MCP-серверам;
• асинхронное выполнение.

Каждый пункт — отдельная глава официальной документации. Второй довод авторов: когда проект вырастет, второй фреймворк вам не понадобится. Тот же Workflow, который в инструкции для новичков запускает первого агента, спокойно работает в продакшене с системой из нескольких агентов, с состоянием, циклами и согласованиями с человеком. То, что вы разобрали в первый день, вы будете отправлять в продакшен и дальше.

Отдельный довод — найм. Новое приложение на агентах требует людей, которые умеют его проектировать, тестировать и поддерживать. Если архитектура у всех одна и та же, новый разработчик в команде говорит с вами на одном языке.

Установка и первый агент

Установка обычная, через Composer:

composer require neuron-core/neuron-ai

Дальше есть генератор агентов:

vendor/bin/neuron make:agent DataAnalystAgent

Класс агента наследуется от базового Agent. Он уже умеет работать с памятью, инструментами и RAG. Вам остаётся указать провайдера и системную инструкцию:

<?php

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\SystemMessage;
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(): SystemMessage
    {
        return new SystemMessage(
            "You are a data analyst expert in creating reports from SQL databases."
        );
    }
}

Общение выглядит так же, как обычный вызов функции. Привязываете агента к ветке диалога, передаёте сообщение, получаете ответ:

$agent = DataAnalystAgent::make()->setThreadId('user-42');

$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.

Обратите внимание на второй ответ. Агент помнит имя из первого сообщения, потому что у него есть память о текущем диалоге. Как она устроена — в разделе про память и историю чата в документации.

Промпт, который отдаётся агенту

В README лежит готовый промпт для установки. Вы копируете его и отдаёте своему агенту по разработке (Claude Code, OpenCode, Cursor). Дальше агент сам разбирается с Composer, ставит пакет, подключает скиллы и проверяет проект по чек-листу.

Смысл промпта в предостережении. Перед тем как писать код на Neuron, агенту велено загрузить нужный скилл из пакета. Причина простая: модель помнит старую версию фреймворка, а API между версиями менялся, поэтому код из памяти может не собраться.

Установка скиллов сводится к одной команде:

npx skills add ./vendor/neuron-core/neuron-ai/skills -y

Скиллы подключаются символическими ссылками, поэтому обновляются вместе с пакетом через Composer. Дальше промпт предлагает определить тип проекта по composer.json и структуре каталогов. Для Laravel активируется навык neuron-laravel-integration, для Symfony — neuron-symfony-integration. Если фреймворка нет, агент начинает с простого агента на чистом PHP.

LLM-провайдеры

Провайдеры вынесены в отдельный компонент. Смена модели — это правка одной строки, и код агента при этом не меняется.

Полный список с настройками — в разделе AI-провайдеры.

Инструменты и наборы инструментов

Инструменты — это то, что позволяет агенту не только говорить, но и делать: читать базу, вызывать API, работать с файлами. Их можно писать руками, а можно взять готовые. Набор инструментов (toolkit) — это просто коллекция инструментов под общей обёрткой.

Пример: агент-аналитик получает доступ к MySQL. Код выглядит на удивление коротко:

use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSelectTool;
use NeuronAI\Tools\Toolkits\MySQL\MySQLToolkit;

class DataAnalystAgent extends Agent
{
    protected function tools(): array
    {
        return [
            MySQLToolkit::make(
                \DB::connection()->getPdo()
            )->only([MySQLSchemaTool::class, MySQLSelectTool::class]),
        ];
    }
}

Метод only() оставляет только два инструмента из набора: посмотреть схему и выполнить SELECT. Дальше с агентом можно общаться как с обычным собеседником:

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

echo $response->getContent();

README отдельно предупреждает про безопасность. Инструмент SELECT выполняет каждый запрос в транзакции только для чтения, поэтому база отклонит любую запись. Но прочитать он может всё, что разрешено пользователю подключения. Для продакшена авторы советуют три вещи: отдельное подключение для набора инструментов, пользователя, которому разрешён только SELECT к нужным таблицам, и лимит времени на выполнение запроса.

Подробности — в разделе Tools.

Коннектор к MCP

Если инструменты уже есть у MCP-сервера, писать их руками не нужно. Компонент McpConnector забирает список инструментов у сервера и отдаёт их агенту:

use NeuronAI\MCP\McpConnector;

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

То есть агент запускает MCP-сервер, спрашивает у него перечень инструментов и подключает их к себе. Дальше всё выглядит так же, как с обычными инструментами. Подробности — в разделе MCP connector.

Структурированный вывод

Часто бывает, что на естественном языке понять ответ нельзя. Его нужно получить в виде данных, чтобы передать дальше в другие системы: автоматизация бизнес-процессов, извлечение данных из текста. Схему ответа вы описываете обычным PHP-классом с атрибутами:

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()->setThreadId('demo')->structured(
    new UserMessage("I'm John and I like pizza!"),
    Person::class
);

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

Метод structured() возвращает готовый объект типа Person. Дальше с ним можно работать как с любым другим объектом. Подробности — в разделе Structured Output.

RAG

Для RAG нужны ещё два компонента поверх AI-провайдера: провайдер эмбеддингов и векторное хранилище. Базовый класс RAG — это заготовка, в которой вы описываете эти три вещи.

Для RAG в пакете тоже есть генератор:

vendor/bin/neuron make:rag MyChatBot

Дальше заполняете три метода:

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'
        );
    }
}

В примере эмбеддинги считает Voyage, а хранит Pinecone. Подробности — в разделе RAG.

Workflow: когда готовых классов мало

Классы Agent и RAG — это готовые решения под типовые сценарии: поиск по базе, вызов инструментов, структурированный вывод. Workflow — другой уровень. Авторы описывают его как умную блок-схему для вашего приложения.

Смысл в другом: компоненты Neuron можно брать по отдельности, как детали конструктора. Это AI-провайдер, эмбеддинги, загрузчики данных, история чата, векторное хранилище. Из них вы собираете систему целиком, по тем правилам, которые нужны именно вам. Классы Agent и RAG при этом тоже можно использовать внутри Workflow как обычные компоненты, если их встроенных возможностей хватает.

Отдельная важная возможность Workflow — человек в контуре процесса. В любой момент процесс можно остановить и передать его человеку: проверить результат, поправить или добавить контекст. Это важно там, где ответ модели нужно подтвердить перед тем, как он уйдёт дальше по системе. Подробнее — в разделе Workflow и отдельной странице про human-in-the-loop.

Ещё два направления, о которых говорит README, — потоковая выдача ответа с адаптерами под интерфейсы и асинхронное выполнение. Это streaming и async.

Наблюдение и отладка

Агент в продакшене — это цепочка из множества шагов: вызовы LLM, работа с инструментами, чтение из внешней памяти. Когда шагов много, важно понять, что именно агент делает и почему он ответил именно так.

Стандартный путь в Neuron — сервис Inspector. После регистрации достаточно задать переменную окружения:

INSPECTOR_INGESTION_KEY=fwe45gtxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Дальше в панели Inspector появляется лента выполнения агента: сколько было вызовов, какие инструменты сработали, сколько занял каждый шаг. Подробности — в разделе Observability.

Скиллы и MCP-сервер для ИИ-агентов

Отдельный раздел README посвящён работе с ИИ-помощниками вроде Claude Code, OpenCode и Cursor. Авторы предлагают два способа дать модели глубокое понимание компонентов Neuron: скиллы и MCP-сервер. По их словам, это приводит к более точным подсказкам в коде, правильному пониманию API и меньшему числу выдумок.

Скиллы лежат прямо в пакете, в каталоге skills/, и ставятся одной командой из шага выше. На момент публикации их 13:

Требования, версии и разработка

Требование к языку — PHP 8.1 или новее (^8.1). Пакет лежит на Packagist, официальная документация — на docs.neuron-ai.dev.

Разработчикам самого фреймворка тесты удобно гонять через Docker Compose. Он поднимает тот же набор сервисов, что и в CI:

# Start all services
docker compose up -d

# 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

Обнаруженные уязвимости авторы просят отправлять на support@inspector.dev. Лицензия MIT лежит в репозитории.

Итого

Neuron закрывает весь путь работы с агентами в одном PHP-проекте: выбор модели, инструменты, память, RAG, несколько агентов, человек в контуре, отладка. Если команда уже пишет на PHP, всё это живёт в том же проекте. Главный совет авторов — начинать с готовых классов Agent и RAG, а переходить на Workflow только тогда, когда типовое решение перестало хватать. И всегда ставьте скиллы из пакета: модель помнит старые версии API, а это источник ошибок.