# Neuron AI

> A PHP framework for building and orchestrating AI agents

- Category: Agents & Automation / Agent Frameworks & Builders
- Language: PHP
- Licence: MIT
- Repository: https://github.com/neuron-core/neuron-ai
- Website: https://docs.neuron-ai.dev
- Canonical page: https://ai-tldr.dev/tools/neuron-ai/

## In short

Neuron AI is a PHP framework for building and orchestrating AI agents. It covers the agentic development lifecycle end to end: LLM interfaces, data loading, multi-agent orchestration, and monitoring and debugging. It sits in the Agent Frameworks & Builders category of the Agents & Automation tools and is open-source, written in PHP and licensed MIT.

## Overview

Neuron is a PHP framework for creating and orchestrating AI agents inside PHP applications. It covers the agentic development lifecycle end to end: LLM interfaces, data loading, multi-agent orchestration, and monitoring and debugging. It requires PHP 8.1 or newer and installs with Composer.

You build an agent by extending the `Agent` class and overriding a few methods: `provider()` returns the LLM, `instructions()` the system prompt, and `tools()` the tools or toolkits the agent may call. The base class manages conversation memory, tool calls and structured output for you. A companion `RAG` class adds an embeddings provider and a vector store for retrieval-augmented chatbots, and a `neuron` CLI scaffolds both (`make:agent`, `make:rag`). Switching LLM providers is a one-line change — the README lists Anthropic, OpenAI (including the Responses API and Azure), OpenAI-compatible APIs, Ollama, Gemini and Gemini Vertex, Mistral, HuggingFace, Deepseek, Grok, AWS Bedrock Runtime, Cohere, ZAI and Alibaba DashScope.

For systems the ready-made Agent and RAG classes don't fit, Workflow lets you wire every Neuron component — providers, embeddings, data loaders, chat history, vector stores, and Agent or RAG themselves — into a custom event-driven graph of nodes. The project positions Workflow as the one architecture that scales from a first agent to a multi-agent system, with checkpointing, human-in-the-loop interruption, streaming adapters for AG-UI and the Vercel AI SDK, MCP connectors and asynchronous execution. Monitoring is handled by Inspector, the commercial service from the same team: setting `INSPECTOR_INGESTION_KEY` sends each agent's execution timeline to its dashboard.

## What it does

- Extendable `Agent` class with built-in chat memory, tool calling and structured output
- One-line switching between LLM providers, from Anthropic, OpenAI and Gemini to Ollama, Bedrock and any OpenAI-compatible API
- Tools and toolkits (e.g. a MySQL toolkit), plus an `McpConnector` that loads tools from any MCP server
- Structured output mapped onto plain PHP classes annotated with `#[SchemaProperty]`
- A `RAG` class with pluggable embeddings providers and vector stores
- Event-driven Workflow with middleware, checkpointing, human-in-the-loop, streaming and async execution

## Getting started

The README's three-step path: install the package, scaffold an agent, and chat with it. Neuron requires PHP 8.1 or newer.

1. Install with Composer

```bash
composer require neuron-core/neuron-ai
```

2. Create an agent

   Scaffold the class with the CLI, then set its provider and instructions. Put your own API key and model name in place of the placeholders.

```text
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 "You are a data analyst expert in creating reports from SQL databases.";
    }
}
```

3. Talk to the agent

   The agent keeps memory of the ongoing conversation, so a follow-up question can refer back to earlier messages.

```text
$agent = DataAnalystAgent::make();

$response = $agent->chat(
    new UserMessage("Hi, I'm Valerio. Who are you?")
)->getMessage();
echo $response->getContent();
```

4. Give it tools

   Return tools from `tools()` — a built-in toolkit, or every tool an MCP server exposes via `McpConnector`.

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

5. Optional: turn on monitoring

   With an Inspector account, set the ingestion key in the application's environment file to see each agent run's execution timeline.

```text
INSPECTOR_INGESTION_KEY=your-ingestion-key
```

## When to use it

- Add an AI agent to an existing Laravel or other PHP application without bringing in a second language runtime
- Let an agent answer questions about your database through a toolkit such as the MySQL toolkit
- Build a retrieval-augmented chatbot over your own documents with a vector store and embeddings provider
- Orchestrate multi-step or multi-agent processes that need human approval partway through
