DEV Community: Valerio

Conversational Data Collection: Introducing AIForm for Neuron AI

Valerio — Wed, 01 Apr 2026 10:48:01 +0000

One of the more interesting things about building an open-source framework is that the community often knows what to build next before you do. When I started Neuron AI, I had a fairly clear picture in my head of the core primitives — agents, tools, workflows, structured output. What I didn’t fully anticipate was how quickly developers would start pushing those primitives toward very specific, practical use cases. The feature requests and questions that come through GitHub and the newsletter are often the most honest signal I have about where real-world PHP developers are actually trying to go.

Over the past few months, one request kept surfacing in different forms: how do I use Neuron AI to collect information from a user through a conversation instead of a traditional form? The details varied — a registration flow here, a support intake there, a booking assistant somewhere else — but the underlying need was the same. People were trying to build this themselves on top of the agent and workflow components, and it was working, but it required a non-trivial amount of plumbing.

So today I'm releasing AIForm, a Neuron AI component that handles exactly this use case.

What it does

The idea is straightforward. You define the data you want to collect as a plain PHP class using the same #[SchemaProperty] attributes you already know from Neuron AI's structured output system. You attach validation rules where needed. Then you extend AIForm, wire up a provider, and define what should happen when the form completes. The component takes care of the rest: managing the conversation across multiple turns, tracking which fields have been collected, retrying on validation failures, and calling your callback once everything is in order.

class RegistrationData
{
    #[SchemaProperty(description: 'User full name', required: true)]
    #[NotBlank]
    public string $name;

    #[SchemaProperty(description: 'Email address', required: true)]
    #[Email]
    public string $email;

    #[SchemaProperty(description: 'Phone number')]
    public ?string $phone = null;
}

class RegistrationForm extends AIForm
{
    protected string $formDataClass = RegistrationData::class;

    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: env('ANTHROPIC_API_KEY'),
            model: env('ANTHROPIC_MODEL'),
        );
    }

    protected function callback(): mixed
    {
        return function (RegistrationData $data) {
            $this->userService->register($data);
        };
    }
}

In a controller, you process each incoming message through the form instance and get back a state object telling you the current status, completion percentage, and any missing fields, everything you need to drive the UI.

$form = RegistrationForm::make()
    ->setChatHistory(new FileChatHistory("/tmp/chats/{$sessionId}"));

$handler = $form->process(new UserMessage($request->input('message')));
$state = $handler->run();

return response()->json([
    'status'          => $state->getStatus()->value,
    'message'         => $handler->getLastResponse(),
    'completion'      => $state->getCompletionPercentage(),
    'missing_fields'  => $state->getMissingFields(),
    'is_complete'     => $form->isComplete(),
]);

The confirmation step

Something that came up during the build was the question of what to do once all required data is collected but before the callback fires. In many real flows: registrations, bookings, checkout-adjacent interactions, you want the user to review what was collected and confirm before anything is committed. AIForm handles this with requireConfirmation(), which causes the workflow to throw a FormInterruptRequest instead of submitting immediately. You can serialize that interrupt into the session, present the AI-generated summary to the user, and then resume the workflow with the user's response. If they confirm, the callback runs. If they want to change something, the form drops back into collection mode.

$form = RegistrationForm::make()->requireConfirmation(true);

$handler = $form->process(new UserMessage($request->input('message')));
$state = $handler->run();

if ($handler->getInterrupt() instanceof FormInterruptRequest) {
    $_SESSION['form_interrupt'] = serialize($handler->getInterrupt());
    // return the AI-generated summary to the user
}

// on the next request, resume:
$interrupt = unserialize($_SESSION['form_interrupt']);
$handler = $form->process(new UserMessage($request->input('message')), $interrupt);

This is built on the same human-in-the-loop interruption mechanism introduced in NeuronAI v2 workflows, so the pattern will feel familiar if you've used that before.

Why this matters beyond the obvious

The instinct when you first see this is to think of it as a chatbot wrapper around a form. That's a reasonable first impression, but it slightly misses the point. The more interesting aspect is what happens with users who don't fill in forms cleanly: they skip optional fields, mistype emails, answer questions out of order, or abandon the flow halfway through because the interface felt rigid. A conversational flow handles all of this naturally — the AI asks follow-up questions, flags validation failures in plain language, and keeps state across turns without you writing any of that logic yourself.

There's also a less obvious benefit for mobile and voice-adjacent interfaces, where long forms are genuinely painful to use. If your PHP application already has an API layer and a frontend consuming it, plugging AIForm into a controller gives you a conversation endpoint you can connect to any interface — including ones that don't have keyboard input as their primary interaction model.

Built on the existing stack

AIForm is a NeuronAI workflow under the hood, which means it inherits everything the workflow system already provides. That includes native Inspector integration, if you have INSPECTOR_INGESTION_KEY set in your environment, every form conversation will appear in your Inspector dashboard with the full execution timeline. This matters in production when a conversation stalls or a validation loop behaves unexpectedly and you need to understand exactly what happened.

The package is available now on GitHub at neuron-core/ai-form. Install it with:

composer require neuron-ai/ai-form

Documentation for the structured output system and workflow components that AIForm builds on is at docs.neuron-ai.dev. If you build something with it, I'd genuinely like to hear about the use case — the community feedback is what shaped this component in the first place.

Neuron AI Now Supports ZAI — The GLM Series Is Worth Your Attention

Valerio — Mon, 23 Mar 2026 15:10:17 +0000

There's a pattern I’ve noticed over the past year while working on Neuron AI: the decisions that matter most are rarely about chasing trends. They’re about quietly recognizing something that works, testing it seriously, and integrating it so that other developers can benefit without having to do that work themselves.

That’s the honest story behind adding ZAI platform integration to Neuron AI.

I started evaluating the GLM models, because the numbers made me curious. GLM-5 is a 744 billion parameter Mixture-of-Experts model, with 40 billion parameters active per token, trained on 28.5 trillion tokens. For context: it currently holds the top spot among open-weight models on several banchmarks, and places competitively against frontier closed models on reasoning tasks. You can read more about their amazing job in this article: https://z.ai/blog/glm-5

It’s also open-weight. There's a real case to be made that GLM-5 represents the most capable open model available right now, and that matters if you care about the ability to self-host, audit, and control what runs inside your applications.

I tested it. It earned its place in the framework.

A note on ZAI

This integration is also the beginning of a collaboration with ZAI. They've offered to help spread the word about Neuron within their developer community, which I'm genuinely grateful for. The PHP ecosystem sometimes feels isolated from the broader AI conversation — most of the tooling, the tutorials, and the discourse assumes Python. Partnerships like this one help change that. I want Neuron to be where PHP developers go when they're serious about building agentic systems, and having ZAI’s support is a meaningful step in that direction. More will follow.

Using ZAI as an AI Provider

The core integration is straightforward. You swap in the ZAI provider and you're done — all of Neuron's agentic capabilities, including tools, streaming, structured output, middleware, MCP connectors, and RAG, work exactly as they do with any other provider.

Advanced Reasoning Models: Unlocking complex, multi-step agentic workflows.
Multimodal Input & Output: Allowing agents to natively perceive and interact with the world.
Image Generation: Giving your agents the ability to create visual assets on the fly.
Audio Transcription: Bridging the gap between voice and agentic action.

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\ZAI\ZAI;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new ZAI(
            key: 'ZAI_API_KEY',
            model: 'glm-5',
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Analyze the performance bottleneck in this query..."))
    ->getMessage();

echo $message->getContent();

The GLM series also supports reasoning models. If you want the model to think through a problem before responding, you pass the appropriate parameters through the parameters array, as you would with any other provider in Neuron.

Full documentation: docs.neuron-ai.dev/providers/ai-provider#zai

Image Generation

ZAI exposes an image generation endpoint through the glm-image model. In Neuron, this is implemented as a dedicated ZAIImage provider that implements the same AIProviderInterface used by all other providers. This means you can drop it directly into an agent, and it participates in the same middleware and workflow infrastructure.

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\ZAI\Image\ZAIImage;

class ImageAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new ZAIImage(
            key: 'ZAI_API_KEY',
            model: 'glm-image',
        );
    }
}

$message = ImageAgent::make()
    ->chat(new UserMessage("Generate a diagram of a distributed caching architecture"))
    ->getMessage();

// Returns the URL of the generated image
echo $message->getImage()->getContent();

If you prefer to use the provider directly, without wrapping it in an agent class, that’s supported too:

use NeuronAI\Providers\ZAI\Image\ZAIImage;

$provider = new ZAIImage(
    key: 'ZAI_API_KEY',
    model: 'glm-image',
);

$message = $provider->chat(new UserMessage("A technical illustration of an event-driven system"));

echo $message->getImage()->getContent();

Full documentation: docs.neuron-ai.dev/providers/image#zai-image

Audio Transcription

The ZAI audio integration covers speech-to-text transcription via the glm-asr-2512 model. The pattern is consistent with how all audio providers work in Neuron: you pass an AudioContent object inside a UserMessage, and the provider returns a standard message whose text content contains the transcription.

use NeuronAI\Providers\ZAI\Audio\ZAITranscription;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Chat\Messages\Content\AudioContent;
use NeuronAI\Chat\Messages\Content\SourceType;

$provider = new ZAITranscription(
    key: 'ZAI_API_KEY',
    model: 'glm-asr-2512',
);

$message = $provider->chat(
    new UserMessage(
        new AudioContent(__DIR__ . '/assets/recording.mp3', SourceType::URL)
    )
);

echo $message->getContent();

This fits naturally into workflows that involve voice input, meeting transcription, or any pipeline where audio needs to feed into an agent. Because the transcription provider implements the standard AIProviderInterface, you can also embed it inside a larger agentic workflow and apply middleware — rate limiting, logging, guardrails — the same way you would anywhere else in Neuron.

Full documentation: docs.neuron-ai.dev/providers/audio#zai

What comes next

This is a first step. The collaboration with ZAI opens up the possibility of going deeper: more model capabilities, more joint content, more visibility for PHP developers who are building serious agentic applications. I’m not going to over-promise what that looks like in practice, but the intention on both sides is to keep building.

If you’re already using Neuron, you can start experimenting with ZAI models today. The full documentation covers everything you need. Feel free to open an issue on the Neuron repository or contribute if you find possible improvements: https://github.com/neuron-core/neuron-ai

Maestro: A Customizable CLI Agent Built Entirely in PHP

Valerio — Mon, 16 Mar 2026 14:18:04 +0000

For a long time, the implicit message from the AI tooling industry has been: if you want to build agents, learn Python. The frameworks, the tutorials, the conference talks, all pointed in the same direction. PHP developers who wanted to experiment with autonomous systems had two options: switch stacks or stitch something together from raw API calls and hope it holds.

That's the gap Neuron AI was built to close. And now, with Neuron v3 introducing a workflow-first architecture, I wanted to prove the point in the most direct way possible: build something that the ecosystem assumes can only be done in another language. That's how Maestro was born: a fully customizable, extension-driven CLI agent built entirely in PHP.

https://github.com/neuron-core/maestro

I really believe that it is important to create the basis for agentic systems development in PHP, and this project is a further step to provide PHP developers with all the necessary elements to build a native AI stack they can build upon to power the next generation of software solutions.

What is Neuron

Neuron is a PHP framework for developing agentic applications. By handling the heavy lifting of orchestration, data loading, and debugging, Neuron clears the path for you to focus on the creative soul of your project. From the first line of code to a fully orchestrated multi-agent system, you have the freedom to build AI entities that think and act exactly how you envision them.

We provide tools for the entire agentic application development lifecycle — from LLM interfaces, to data loading, to multi-agent orchestration, to monitoring and debugging. Neuron's architecture prioritizes the fundamentals that experienced engineers expect from production-grade software: a strong PHP 8 typing system with 100% PHPStan coverage, IDE-friendly method signatures, minimal external dependencies through standard PSR interfaces, and a design that works identically whether you're building a microservice in pure PHP, a Laravel application, or a Symfony project.

An Agent Runtime, Not just a Coding Tool

The easiest way to describe Maestro is to start with what it is not. It's not a code completion plugin. It's not a fixed-purpose tool that does one thing. It's a CLI agent runtime — a framework for running an AI agent in your terminal that you can shape toward any purpose through its extension system.

Out of the box, Maestro ships with a CodingExtension that turns it into a coding assistant: it gives the agent filesystem tools, a code-aware system prompt, and everything you'd expect from a tool that reads your project and proposes changes. But that extension is just a bundle of capabilities that happens to ship with the default installation. You can disable it. You can replace it. You can install extensions built by other people from Packagist. The agent runtime underneath — the conversation loop, the event system, the tool approval flow, the UI rendering pipeline — knows nothing about coding. It only knows how to run an agent and expose the right hooks for extensions to plug into.

This is the architectural decision that makes Maestro interesting as a project. The coding agent was the first demonstration, a proof that the patterns the industry has been building in Python and TypeScript are fully expressible in PHP. But "coding agent" was never the destination.

The Extension System

An extension is a PHP class that implements ExtensionInterface. The contract is intentionally minimal: a name() method that returns a string identifier, and a register() method that receives an ExtensionApi instance where you wire everything up.

class MyExtension implements ExtensionInterface
{
    public function name(): string
    {
        return 'my-extension';
    }

    public function register(ExtensionApi $api): void
    {
        $api->registerTool($myTool);
        $api->registerCommand($myCommand);
        $api->registerRenderer('my_tool', $myRenderer);
        $api->registerMemory('my-extension.guidelines', __DIR__ . '/memory/guidelines.md');
        $api->on(AgentResponseEvent::class, function ($event, $context) {
            // react to agent responses
        });
    }
}

Through the ExtensionApi, you have access to five integration points. Tools are the actions the AI agent can take — anything you register here becomes something the agent can decide to call during a conversation. Inline commands are slash-prefixed commands available in the interactive terminal session (/deploy, /status, /help) that run outside the AI loop, handled directly by your code. Memory files are Markdown documents injected into the agent's system prompt before the conversation starts, giving the agent domain knowledge, conventions, and instructions specific to your use case. Renderers control how the output of specific tools is displayed in the terminal. And event handlers let you react to what the agent is doing — thinking, responding, requesting tool approval — with arbitrary code.

The registerMemory call is worth dwelling on, because it's the mechanism that controls the agent’s personality and expertise. When you install the CodingExtension, the memory file it registers contains instructions about how to read and modify code safely, how to reason about diffs, when to ask for clarification. If you build a database migration assistant, your memory file contains your conventions for writing migrations, your team’s naming rules, which tables are sensitive. If you build a deployment workflow agent, it contains your environment topology, your rollback procedures, what the agent should always confirm before proceeding. The agent isn’t smart about your domain because it was trained on it, it's smart because your extension told it what to know.

Getting Started

Install as a global Composer tool:

composer global require neuron-core/maestro

Make sure Composer’s global bin directory is in your system PATH:

echo 'export PATH="$(composer config -g home)/vendor/bin:$PATH"' >> ~/.bashrc

Configuration lives in .maestro/settings.json at the root of your project. Run the init command to start the interactive setup guide:

cd /path/to/your/project
maestro init

At minimum, you need a provider and an API key. Maestro supports all the providers available through Neuron, such as Anthropic, OpenAI, Gemini, Cohere, Mistral, Ollama, Grok, and Deepseek, all routed through a ProviderFactory that maps the default field to the corresponding Neuron AI provider instance:

{
    "default": "anthropic",
    "providers": {
        "anthropic": {
            "api_key": "sk-ant-your-key-here",
            "model": "claude-sonnet-4-6"
        }
    }
}

If you want to run everything locally without sending data to an external API, point it at an Ollama instance instead:

{
    "default": "ollama",
    "providers": {
        "ollama": {
            "base_url": "http://localhost:11434",
            "model": "llama2"
        }
    }
}

The Tool Approval Flow

When the agent wants to modify a file, execution doesn't just proceed. It stops, and you see something like this:

The agent wants to write changes to src/Service/UserService.php

[1] Allow once
[2] Allow for session
[3] Reject

"Allow for session" is the option I use most in practice. It means I approve write operations on a given file type or tool once per session, without having to confirm each individual change.

This granularity matters. You probably want to approve the first few changes in an unfamiliar session to build confidence, then let the agent run more freely once it's demonstrated it understands what you’re asking.

This is one of the most interesting feature provided by the Neuron AI framework, thanks to the Workflow architecture. Neuron Workflow support execution interruption, so you can create fully customizable huma-in-the-loop experience. The agent will stop its execution, waiting to be resumed exactly from where it left off. Learn more on the official documentation.

Managing Extensions

Extensions are declared in the same settings.json file. You can enable or disable individual extensions, pass them configuration values, and control exactly what the agent is capable of in a given project:

{
    "default": "anthropic",
    "providers": { "..." },
    "extensions": {
        "NeuronCore\\Maestro\\Extension\\CodingExtension": {
            "enabled": true
        },
        "MyVendor\\DeployExtension\\DeployExtension": {
            "enabled": true,
            "config": {
                "environment": "staging",
                "api_key": "your-key"
            }
        }
    }
}

Disabling the CodingExtension and enabling only your own extension turns Maestro into a completely different agent — one that knows nothing about code and everything about your specific domain. The runtime doesn’t change. The conversation loop, the tool approval flow, the event system — all of that stays exactly the same.

Packaging and Distributing Extensions

Extensions are Composer packages. You write the code, define a composer.json with a dependency on neuron-core/maestro, and add an extra.maestro field that declares your extension class names:

{
    "name": "my-vendor/my-extension",
    "require": {
        "neuron-core/maestro": "^1.0"
    },
    "extra": {
        "maestro": {
            "extensions": [
                "MyVendor\\MyExtension\\MyExtension"
            ]
        }
    },
    "autoload": {
        "psr-4": {
            "MyVendor\\MyExtension\\": "src/"
        }
    }
}

Once a user installs your package with composer require my-vendor/my-extension, running composer dump-autoload triggers auto-discovery. Maestro reads the extension class names from the extra field and registers them without the user needing to touch settings.json at all, unless they want to configure or disable the extension explicitly.

This is intentionally familiar territory for any PHP developer who has worked with Laravel packages or Symfony bundles. Ship a package, declare what it contributes, let the host framework discover and integrate it. The entire extension ecosystem lives on Packagist, installed and updated the same way every other PHP dependency in your project.

MCP Integration

For extensions that need to reach beyond the local environment, Maestro supports Model Context Protocol servers in the configuration:

{
    "mcp_servers": {
        "tavily": {
            "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=your-key"
        }
    }
}

Each entry spins up a subprocess and connects it to the agent as an additional tool source. This is how an extension targeting a GitHub workflow gives the agent the ability to read issues, open pull requests, and trigger CI runs — without you having to implement those integrations yourself.

What This Demonstrates

Maestro is a working proof that the patterns the rest of the industry has been building in Python and TypeScript are fully expressible in PHP. But more than that, it's a proof that the PHP ecosystem has the right primitives to build a platform, not just a tool.

The extension system is what makes that distinction real. A coding agent is something you install and use. A platform with an extension system is something you build on, contribute to, and share through the package manager your entire community already uses. That's the version of the story I'm most excited about — not what Maestro does out of the box, but what it enables once developers start building on it.

I'm really looking forward to hearing your feedback, experiments, and ideas on how to develop this new chapter of the AI in the PHP space.

If you want to explore the code, the repository is at https://github.com/neuron-core/maestro. The Neuron AI documentation lives at https://docs.neuron-ai.dev. Questions, issues, and pull requests are open.

Neuron v3 is Here! 🚀 Agentic Workflows in PHP

Valerio — Wed, 25 Feb 2026 10:57:45 +0000

Exactly one year ago, we shared the first public lines of Neuron AI with the world. Six months ago, we stood at the crossroads of V2, refining our vision. Today, we arrive at Version 3 as the first agentic framework in the PHP world.

I'm aware that a major release every six months is a demanding pace. As developers, we value stability, we value the quiet confidence of code that doesn't shift beneath our feet. But the air in the AI space is thick with change. The landscape isn't just evolving, it's exploring totally new patterns of power and possibility. To wait would be to leave opportunities on the table, and my commitment to you has always been to bring these discoveries into the PHP ecosystem the moment they become substantial.

What does Neuron v3 means?

V3 is a decisive architectural shift which definitively put a lid on the gap with other technologies and makes PHP a first-class citizen in the world of agentic systems development.

This new major version introduces a Workflow-First architecture. This is a clear design choice that really marks the difference between Neuron and any other project in the PHP space. Workflow is what makes possible features that were impossible to implement in a simple class-based design, such as:

The unified messaging layer for multi-modal agents.
Native support for tool approval and fully customized human-in-the-loop flows.
Multi-agent streaming and collaboration.

Workflow is a solid primitive thanks to which you will be able to transform any PHP application into an autonomous agentic system, or breathe life into entirely new AI-powered products from scratch.

Check out the repository:

https://github.com/neuron-core/neuron-ai

Why build with Neuron AI

This journey made me understand that developers today finds themselves at a daunting threshold. You feel the pressure from other ecosystems, the noise of a hundred new technologies and trends, and the weight of an important question: "How can I learn, experiment, and integrate such technologies into my creations without losing my way? How can I stay relevant and navigate this change?"

It's easy to fall into the "hole" of indecision, choosing out-of-PHP-stack that feels alien, or frantically trying tools just because they are new. By building Neuron as an ecosystem-wide framework rather than a scoped package, we are focused on protecting your knowledge and creating a diverse and large community of AI builders in PHP.

Whether you are moving between different projects, your skills become a universal key. When you learn to build an agentic system in Neuron, that mastery travels with you and your company. It doesn't matter where your code lives, what matters is that you, the creator, have a consistent, reliable methodology to turn ideas into reality, using the most advanced technology in the programming language you know and love.

The Community

Most important, we are not building this in a vacuum, and we don't have all the answers. My role, and the role of the core team, is to listen. We have spent countless hours studying more advanced ecosystems, listen to your experiences, and test completely new paths. This contamination is the reason why Neuron offers a unique perspective on agentic applications development in PHP.

One of the most significant advantages of this project is the human contribution. When you choose this path, you aren't just adding a new entry in the composer file, but you're joining a conversation with hundreds of thousands of other developers around the world who believe "agentic" is the future of software products. And they are building it.

We want to empower creators in every form:

The Software Architect crafting the next generation of intelligent software.
The Content Creator building educational bridges for the next wave of developers.
The Contributor who sees a gap and helps us bridge it for everyone.

Moving Forward Together

Neuron V3 is our invitation to you to stop feeling like a passenger in the AI revolution but becoming the architect. We have worked hard to ensure that while the world outside is chaotic, your development environment is intuitive, elegant, and above all, deeply rooted in the PHP way.

We are here to help, in person, chat and collaborate with you to solve the unique problems that arise when theory meets production. Feel free to contact me on Linkedin or X, or follow Neuron channels to stay up to date:

Newsletter: https://neuron-ai.dev
Linkedin: https://www.linkedin.com/company/neuron-ai-php-framework
X: https://x.com/neuronai_php
Instagram: https://www.instagram.com/neuronai_php_adk/

Your feedback, your skepticism, and your successes are what built V3.

Let's see what we can create together.

https://docs.neuron-ai.dev

Struggling with RAG in PHP? Discover Neuron AI components

Valerio — Mon, 09 Feb 2026 09:11:05 +0000

Implementing Retrieval-Augmented Generation (RAG) is often the first "wall" PHP developers hit when moving beyond simple chat scripts. While the concept of “giving an LLM access to your own data” is straightforward, the tasks required to make it work reliably in a PHP environment can be frustrating. You have to manage document parsing, vector embeddings, storage in a vector database, and the final prompt orchestration. Most developers end up trying to glue several disparate libraries together, only to find that the resulting system is brittle and hard to maintain.

Neuron was designed to eliminate this friction. It provides a built-in RAG module that handles the heavy lifting of the data pipeline, allowing you to focus on the logic of your agent rather than the mechanics of vectors management and similarity search. In a typical scenario, like building a support agent that needs to “read” your company’s internal documentation, you don’t want to manually handle the chunking of text or the API calls to OpenAI’s embedding models. Neuron abstracts these into a fluent workflow where you define a “Data Source,” and the framework ensures the most relevant snippets of information are injected into the agent’s context window at runtime.

Understanding the Foundation: What RAG Really Means

Retrieval Augmented Generation breaks down into three critical components that work in harmony to solve a fundamental problem in AI: how do we give language models access to specific, up-to-date, or proprietary information that wasn’t part of their original training data?

The “G” part of the RAG acronym is straightforward—we’re talking about “Generative” AI models like GPT, Claude, Gemini, or any large language model that can produce human-like text responses. These models are incredibly powerful, but they have a significant limitation: they only know what they were trained on, and that knowledge has a cutoff date. They can’t access your company’s internal documents, your personal notes, or real-time information from your databases.

This is where the “Retrieval Augmented” component becomes transformative. Instead of relying solely on the model’s pre-trained knowledge, we augment its capabilities by retrieving relevant information from external sources at the moment of generation. Think of it as giving your AI agent a research assistant that can instantly find and present relevant context before answering any question.

Below you can see an example of how this process should work:

The Magic Behind Embeddings and Vector Spaces

To understand how retrieval works in practice, we need to dive into embeddings—a concept that initially seems abstract but becomes intuitive once you see it in action. An embedding is essentially a mathematical representation of text, images, or any data converted into a list of numbers called a vector. What makes this powerful is that similar concepts end up with similar vectors, creating a mathematical space where related ideas cluster together.

When I first started working with Neuron AI, I was amazed by how this actually works in practice. Imagine you have thousands of documents—customer support tickets, product manuals, internal wikis, research papers. Traditional keyword search would require exact matches or clever Boolean logic to find relevant information. But with embeddings, you can ask a question like “How do I troubleshoot connection issues?” and the system will find documents about network problems, authentication failures, and server timeouts, even if those documents never use the exact phrase “connection issues”.

The process works by converting both your question and all your documents into these mathematical vectors. The system then calculates which document vectors are closest to your question vector in this multi-dimensional space. It’s like having a librarian who understands the meaning and context of your request, not just the literal words you used.

You can go deeper into this technology in the article below.

https://inspector.dev/vector-store-ai-agents-beyond-the-traditional-data-storage/

The Challenge of real RAG Implementations

The conceptual understanding of RAG is one thing, actually building a working system is another challenge entirely. This is where the complexity really emerges, and it’s why Neuron is such a valuable tool for PHP developers entering this space.

The ecosystem involves multiple moving parts: you need to chunk your documents effectively, generate embeddings using appropriate models, store and index those embeddings in a vector database, implement semantic search functionality, and then orchestrate the retrieval and generation process seamlessly.

Each of these steps involves technical decisions that can significantly impact your agent’s performance (speed, and quality of responses). How do you split long documents into meaningful chunks? Which embedding model works best for your domain? How do you handle updates to your knowledge base? How do you balance retrieval accuracy with response speed? These questions become more pressing when you’re building production systems that need to scale and perform reliably.

In the detailed implementation guide that follows, we’ll explore how Neuron simplifies this complex orchestration, providing PHP developers with tools and patterns that make RAG agent development both accessible and powerful.

Install Neuron AI

To get started, you can install the core framework and the RAG components via Composer:

composer require neuron-core/neuron-ai

Create a RAG Agent

To create a RAG, Neuron provides you with a dedicated class you can extend to orchestrate the necessary components like the AI provider, vector store and the embeddings provider.

First, let’s create the RAG class:

php vendor/bin/neuron make:rag App\\Neuron\\MyRAG

Here is an example of a RAG implementation:

namespace App\Neuron;

use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\RAG\Embeddings\EmbeddingsProviderInterface;
use NeuronAI\RAG\Embeddings\OpenAIEmbeddingsProvider;
use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\FileVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

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

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

    protected function vectorStore(): VectorStoreInterface
    {
        return new FileVectorStore(
            directory: __DIR__,
            name: 'demo'
        );
    }
}

In the example above we provided the RAG with a connection to:

The LLM (Anthropic in this case)
The Embedding provider – The service able to transform text into vector embeddings
The vector store to persist the generated embeddings and perform document retrieval

Be sure to provide the appropriate infomration to connect with these services. You have plenty of options for each of these components. You can use local systems or managed services, so feel free to explore the documentation to choose your preferred ones: https://docs.neuron-ai.dev/components/ai-provider

Feed Your RAG With A Knowledge Base
At this stage the vector store behind our RAG agent is empty. If we send a prompt to the agent it will be able to respond leveraging only the underlying LLM training data.

use NeuronAI\Chat\Messages\UserMessage;

$response = MyRAG::make()
    ->chat(
        new UserMessage('What size is the door handle on our top car model?')
    );

echo $response->getContent();

// I don't really know specifically about your top car model. Do you want to provide me with additional information?
We need to feed the RAG with some knowledge to make it able to respond to questions about private information outside its default training data.

Neuron AI Data Loader

To build a structured AI application you need the ability to convert all the information you have into text, so you can generate embeddings, save them into a vector store, and then feed your Agent to answer the user’s questions.

Neuron has a dedicated module to simplify this process. In order to answer the previous question (What size is the door handle on our top car model?) we can feed the rag with documents (Markdown files, PDFs, HTML pages, etc) containing such information.

You can do it in a just a few lines of code:

use NeuronAI\RAG\DataLoader\FileDataLoader;

// Use the file data loader component to process documents
$documents = FileDataLoader::for(__DIR__)
        ->addReader('pdf', new \NeuronAI\RAG\DataLoader\PdfReader())
        ->addReader(['html', 'xhtml'], new \NeuronAI\RAG\DataLoader\HtmlReader())
        ->getDocuments();

MyRAG::make()->addDocuments($documents);

As you can see from the example above you can just point the data loader to a directory containing all the files you want to load into the vector store, and it automatically does:

Extract all text inside files
Chunk the content with a splitting strategy
Pass all the documents into the RAG to generate ambeddings and finally persist all this information into the vector store.

It’s just an example to demonstrate how you can create a complete data pipeline for your agentic application in 5 lines of code. You can learn more about the extensibility and customization opportunities for readers and splitters in the documentation: https://docs.neuron-ai.dev/rag/data-loader

Talk to the chat bot

Imagine having previously populated the vector store with the knowledge base you want to connect to the RAG agent, and now you want to ask questions.

To start the execution of a RAG you call the chat() method:

use App\Neuron\MyRAG;
use NeuronAI\Chat\Messages\UserMessage;

$response = MyRAG::make()->chat(
    new UserMessage('What size is the door handle on our top car model?')
);

echo $response->getContent();

// Based on 2025 sales results, the top car model in your catalog is XXX...

Monitoring & Debugging

Many of the Agents you build with NeuronAI 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. Share feedback on the editor

Why is the model taking certain decisions? What data is the model reacting to?

The Inspector team designed Neuron AI with built-in observability features, so you can monitor AI agents were running, helping you maintain production-grade implementations with confidence.

To start monitoring your agentic systems you need to add the INSPECTOR_INGESTION_KEY variable in your application environment file. Authenticate on app.inspector.dev
to create a new one.

INSPECTOR_INGESTION_KEY=nwse877auxxxxxxxxxxxxxxxxxxxxxxxxxxxx

When your agents are being executed, you will see the details of their internal steps on the Inspector dashboard.

Resources

If you are getting started with AI Agents, or you simply want to elevate your skills to a new level here is a list of resources to help you go in the right direction:

Neuron AI – Agent Development Kit for PHP: https://github.com/inspector-apm/neuron-ai
Newsletter: https://neuron-ai.dev
E-Book (Start With AI Agents In PHP): https://www.amazon.com/dp/B0F1YX8KJB

Moving Forward

The complexity of orchestrating embeddings, vector databases, and language models might seem a bit daunting, but remember that every expert was once a beginner wrestling with these same concepts.

The next step is to dive into the practical implementation. Neuron AI framework is designed specifically to bridge the gap between RAG theory and production-ready agents, handling the complex integrations while giving you the flexibility to customize the behavior for your specific use case. Start building your first RAG agent today and discover how powerful context-aware AI can transform your applications.

Neuron AI Laravel SDK

Valerio — Mon, 12 Jan 2026 13:44:47 +0000

For a long time, the conversation around "agentic AI" seemed to happen in a language that wasn't ours. If you wanted to build autonomous agents, the industry nudge was often to step away from the PHP ecosystem and move toward Python. But for those of us who have built our careers, companies, and products on Laravel, that's not just a technical hurdle, it's a disruption to our livelihoods and the stable assets we've maintained for years.

I've been watching the Laravel community dive into AI recently, and it's clear we don't want to leave our ecosystem; we want to bring the power of AI into it. That is why I've released the Neuron AI Laravel SDK.

Brief Introduction to Neuron AI

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

This package isn't an attempt to rewrite how you work with Neuron. Instead, it's a bridge designed to integrate the the most common framework components directly into the Laravel container, along with other useful configurations.

It provides:

A configuration-driven service class to manage AI providers.
Artisan commands to scaffold agents and reduce boilerplate.
Eloquent-backed Chat History components for persistent memory.
A ready-to-use configuration file that follows standard Laravel conventions.
100% typed code to ensure your IDE remains your best friend.

Is PHP Ready for the Agentic Era?

When we talk about whether PHP is "ready" for agentic applications, we aren’t just talking about syntax. We are talking about the infrastructure of the web. Millions of businesses run on PHP. Families are supported by PHP-based SaaS products. Decades of business logic are wrapped in PHP objects and Service classes. Forcing a migration to a different language to stay relevant in the AI agents trend is a high-risk, low-reward move for most production environments.

The Neuron AI Laravel SDK is built on the belief that the most efficient way to build agentic systems is to do it where your data already lives. Neuron itself uses a very lean approach, there are no invasive abstractions that hide what’s happening under the hood. In this package we put our focus on a couple od Laravel integration points without limiting the access to the Neuron native components.

You can also use our code as an inspiration to design your own custom integration pattern.

Building Your First Agent in a Laravel app

The integration is designed to feel native. After installing the package, you can define your agents and interact with them using the service container. You don't have to worry about manually managing API keys or complex provider instantiations every time you want to trigger a task.

First install the package:

composer require neuron-core/neuron-laravel

Now you can run the command to create your first agent class, just like the native Neuron AI experience:

php artisan neuron:agent MyAgent

This command will create a new agent class: App\Neuron\MyAgent

AI Provider

Neuron allows you to implement AI agents using many different providers, like Anthropic, Gemini, OpenAI, Ollama, Mistral, and many more. Learn more about supported providers in the Neuron AI documentation: https://docs.neuron-ai.dev/the-basics/ai-provider

To get an instance of the AI Provider you want to attach to your agent, you can use the NeuronAI\Laravel\Facades\AIProvider facade.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\SystemPrompt;
use NeuronAI\Laravel\Facades\AIProvider;
use NeuronAI\Providers\AIProviderInterface;

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        // return an instance of Anthropic, OpenAI, Gemini, Ollama, etc...
        return AIProvider::driver('anthropic');
    }

    public function instructions(): string
    {
        return (string) new SystemPrompt(...config('neuron.system_prompt');
    }
}

You can see all the available providers in the documentation: https://docs.neuron-ai.dev/the-basics/ai-provider

This package also provides you with a configuration file you can use to store all the confogiration options for ai providers. You can use the environment variable below to connect the agent with your preferred service:

# Support for: anthropic, gemini, openai, openai-responses, mistral, ollama, huggingface, deepseek
NEURON_AI_PROVIDER=anthropic

ANTHROPIC_KEY=
ANTHROPIC_MODEL=

GEMINI_KEY=
GEMINI_MODEL=

OPENAI_KEY=
OPENAI_MODEL=

MISTRAL_KEY=
MISTRAL_MODEL=

OLLAMA_URL=
OLLAMA_MODEL=

# And many others

Here is a quick look at how you might implement a simple agent within a standard Laravel controller:

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

class AgentController extends Controller
{
    public function __invoke(Request $request)
    {
        // Get a configured instance of an agent
        $agent = MyAgent::make();

        // Run the agent
        $response = $agent->chat(
            new UserMessage($request->input('prompt'))
        );

        return response()->json([
            'answer' => $response->getContent(),
        ]);
    }
}

This approach respects the Laravel lifecycle. Because Neuron is 100% typed and relies on clear interfaces, you can build custom plugins or extensions without guessing what the data structures look like. It handles the "agentic" part, the reasoning, the tool calling, and the memory, while you focus on the business logic.

Eloquent Chat History

An additional Laravel specific component we provide is a predictable way to store chat histories in your existing database. The included Eloquent Chat History component, for example, allows you to treat AI interactions just like any other database record, making debugging and auditing straightforward.

Once you run the appropriate database migration you can use it in your agent with a simple line of code:

namespace App\Neuron;

use App\Models\ChatMessage;
use NeuronAI\Agent;
use NeuronAI\Chat\History\ChatHistoryInterface;
use NeuronAI\Chat\History\EloquentChatHistory;

class MyAgent extends Agent
{
    ...

    protected function chatHistory(): ChatHistoryInterface
    {
        return new EloquentChatHistory(
            threadId: 'THREAD_ID',
            modelClass: ChatMessage::class,
            contextWindow: 50000
        );
    }
}

You don't need to learn a new stack to build sophisticated AI workflows. You just need the right integration points. I encourage you to explore the Neuron AI documentation and start experimenting. Whether you’re building a simple support bot or a complex multi-agent system, see how it feels to build "agentic" within the comfort of php.

https://docs.neuron-ai.dev

PHP’s Next Chapter: From Web Framework to Agent Framework

Valerio — Tue, 18 Nov 2025 11:06:11 +0000

I've spent the last year building Neuron, a PHP framework designed specifically for agentic AI applications. What started as a technical challenge became something else entirely when developers began reaching out with stories I wasn't prepared to hear. They weren't asking about framework features or deployment strategies. They were telling me about losing their jobs.

One senior developer had spent eight years at a fintech company, building and maintaining their entire backend infrastructure in PHP. The systems worked. The codebase was clean. Then the leadership decided to pivot toward AI-driven automation. Within six months, the entire PHP team was let go, replaced by Python engineers who could integrate LangChain and build agent workflows. He watched his expertise become irrelevant not because he wasn't skilled, but because the tools he knew couldn't participate in the conversation that mattered to his company's future.

Here is the link to the post on the Neuron GitHub repository: https://github.com/neuron-core/neuron-ai/discussions/156#discussioncomment-13436693

Another engineer contacted me after his SaaS company made a similar shift. They didn't abandon PHP because it was slow or outdated. They abandoned it because when the CTO asked "can we build autonomous agents that handle customer support and data analysis", the answer from the PHP ecosystem was silence. No frameworks, no examples, no path forward. Python had entire conferences dedicated to agentic architectures while PHP developers were still arguing about whether type hints mattered.

These aren't isolated incidents. I hear versions of this story regularly now, and what disturbs me most is how predictable it all was. The PHP community saw the AI wave coming and collectively decided it was someone else's problem. We kept optimizing for the web patterns we've always known, reassuring ourselves that "PHP powers a significant portion of the internet" as if market share from past decisions protects against future irrelevance.

The Cost of Ignoring What's Actually Happening

Some people dismiss AI development as a trend, a temporary excitement that will settle down and return us to familiar patterns. This perspective fundamentally misunderstands what's occurring. Agentic applications aren’t a feature being added to existing software. They represent a different approach to building systems entirely. Companies aren't experimenting with this because it's fashionable. They're adopting it because it changes their operational economics in ways that matter to survival.

When a business realizes they can automate complex workflows that previously required multiple employees, they don't care about your framework preference or language loyalty. They care about implementation speed and ecosystem maturity to deploy effective solutions as soon as possible. If the only credible path to building these systems runs through Python, then Python is what they'll use. Your years of PHP expertise become a liability rather than an asset because you can’t deliver what the company needs to remain competitive.

The PHP community's response to this has been inadequate bordering on negligent. We write articles titled "Why PHP is the Best Choice" that convince nobody because they address none of the actual questions people are asking. Nobody talk about how to build agentic applications that can interact with multiple APIs, maintain conversation context, and make autonomous decisions. They don't provide patterns for integrating language models into Laravel applications or handling the operation complexity that agent workflows require. They just repeat the same defensive talking points about PHP's web capabilities while the industry moves toward problems PHP developers claim they can't solve.

This creates a self-fulfilling prophecy. PHP appears unsuitable for AI development because no one builds the tools to make it suitable. Talented developers leave for ecosystems that support their career growth. Companies hire outside the PHP community because we don't demonstrate competence in the areas they're investing in. Then we point to the exodus as evidence that maybe PHP really isn't meant for this kind of work, completing a cycle of irrelevance we constructed ourselves.

What Happens When the Tools Finally Exist

The developers who lost their positions didn't lack skill or intelligence. They were caught in an ecosystem that hadn't yet evolved with the problems businesses needed solved. But some of them found their way to Neuron and discovered something that changed their trajectory: PHP handles agentic applications naturally once you have the right enabling paltform in place. The language's mature capabilities, and large package ecosystem, provide exactly what these systems need.

** What was missing wasn't potential but actual implementation.**

These developers started building again. Not toy projects or proofs of concept, but production agentic systems handling real business logic. Customer service agents that resolve support tickets autonomously. Data analysis agents that generate insights from business metrics. Workflow automation that adapts to changing conditions without manual intervention.

They're now demonstrating capabilities their previous employers assumed required abandoning PHP entirely. What changed was their access to tools designed for the problems they were solving. They didn't have to become Python developers or learn entirely new paradigms. They applied their existing PHP knowledge to agentic architectures using a framework that understood both domains. Their career trajectories shifted because PHP finally has a credible answer when someone asks about building intelligent, autonomous systems.

The community forming around this work represents PHP's actual future, not its past. These developers understand that web frameworks were just the first chapter, and that the language's evolution doesn't end with serving HTTP requests. They're building the proof that PHP developers can lead in agentic development rather than watch from the sidelines. Every production agent they deploy, every autonomous workflow they implement, every business problem they solve with AI-driven systems reinforces that PHP belongs in this space.

That gap is closing now, and the developers who bridge it first are positioning themselves at the front of PHP's next chapter. Your expertise in PHP doesn't have to be a limitation in an AI-driven industry. The tools exist now to take what you already know and apply it to the systems companies are actually building. The question isn’t whether PHP can participate in agentic development anymore. The question is whether you’ll be part of this revolution.

Discover the new space Neuron is creating in the PHP ecosystem. Start developing your next application with Neuron-powered AI agents at https://neuron-ai.dev

Storing LLM Context the Laravel Way: EloquentChatHistory in Neuron AI

Valerio — Fri, 07 Nov 2025 15:34:51 +0000

I've spent the last few weeks working on one of the most important components of Neuron the Chat History. Most solutions treat conversation history in AI Agents forcing you to build everything from scratch. When I saw Laravel developers adopting Neuron AI, I realized they deserved better than that.

The current implementation of the ChatHisotry already allows developers to store the agent context on file or in a general SQL table. The new EloquentChatHistory component changes how you manage LLM context in Laravel applications. Instead of fighting with custom storage solutions or maintaining parallel data structures, you now work with conversation history the same way you handle any other data in your application: through Eloquent models.

It could be a starting point for future imporvements, so if you are working on Laravel and you think this integration can be improved feel free to let us know posting on the repository discussion. We are glad to receive any feedback. Other Laravel integrations can eventually be bundled into a dedicated integration package.

Why This Matters for Your Laravel Projects

When you're building AI features into a real application, context management quickly becomes a practical problem. You need to show conversation history in admin panels, filter chats by user or project, run background jobs that reference past interactions, or export data for analytics. With traditional approaches, you’re constantly translating between your AI framework's storage format and your application’s data layer.

EloquentChatHistory want to mitigates or even eliminates that friction. Your chat history lives in your database as a proper Eloquent model, which means it integrates naturally with everything else in your Laravel ecosystem. Need to scope conversations by organization? Use query builders you already know. Building an admin panel with Filament or Nova? Your chat history is just another resource.

namespace App\Neuron;

use App\Models\ChatMessage;
use NeuronAI\Agent;
use NeuronAI\Chat\History\ChatHistoryInterface;
use NeuronAI\Chat\History\EloquentChatHistory;

class MyAgent extends Agent
{
    ...

    protected function chatHistory(): ChatHistoryInterface
    {
        return new EloquentChatHistory(
            thread_id: 'THREAD_ID',
            modelClass: ChatMessage::class,
            contextWindow: 50000
        );
    }
}

The component works with your existing database structure. You define the Eloquent model, specify which columns map to message roles and content, and Neuron handles the rest. It's a thin adapter that respects how Laravel developers actually work.

Real Integration, Not Just Storage

Your chat messages become first-class citizens in your application architecture. You can attach them to tickets, orders, or support conversations through standard Eloquent relationships. Background jobs can query relevant context without special handling. Your testing suite can seed and verify conversation flows using factories and assertions you already use for everything else.

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class ChatMessage extends Model
{
    protected $fillable = [
        'thread_id', 'role', 'content', 'meta'
    ];

    protected $casts = [
        'content' => 'array', 
        'meta' => 'array'
    ];

    /**
     * The conversation that owns the chat message.
     *
     * @return BelongsTo<Conversation, $this>
     */
    public function conversation(): BelongsTo
    {
        return $this->belongsTo(Conversation::class, 'thread_id');
    }
}

Starting Point, Not Final Destination

I'm releasing EloquentChatHistory as a foundation you can build on. The implementation handles the common case: storing and retrieving messages with proper threading. But your application probably has specific requirements around metadata, search, etc. The component is designed to be extended, not prescribed.

I'm particularly interested in seeing how the community extends this. The Neuron GitHub repository is where improvements and variations can evolve. If you build something useful on top of EloquentChatHistory , sharing that helps everyone building AI features in Laravel apps.

Getting Started

The documentation walks through setup and configuration. You'll need to create a migration for your chat messages table, define your Eloquent model, and configure the field mappings. From there, it's standard Neuron AI workflow.

Create the migration script:

php artisan make:migration create_chat_messages_table --create=chat_messages

The schema below is the basic starting point:

Schema::create('chat_messages', function (Blueprint $table) {
     $table->id();
     $table->string('thread_id')->index();
     $table->string('role');
     $table->json('content');
     $table->json('meta')->nullable();
     $table->timestamps();

     $table->index(['thread_id', 'id']); // For efficient ordering and trimming
});

The real test isn't whether EloquentChatHistory covers every edge case perfectly. It's whether it helps you move faster when building AI features in Laravel applications you already maintain. If you've been putting off adding AI capabilities because the integration overhead seemed too high, this might lower that barrier enough to start experimenting.

Try it out, see what works for your use case, and let me know what could be better. The framework improves when people building real applications share what they learn.

Subscribe to the Neuron AI Newsletter.

Managing Human-in-the-Loop With Checkpoints – Neuron Workflow

Valerio — Mon, 29 Sep 2025 08:36:45 +0000

The integration of human oversight into AI workflows has traditionally been a Python-dominated territory, leaving PHP developers to either compromise on their preferred stack or abandon sophisticated agentic patterns altogether. The new checkpointing feature in Neuron’s Workflow component continues to strengthen the dynamic of bringing production-ready human-in-the-loop capabilities directly to PHP environments.

Checkpointing addresses a fundamental challenge in agentic applications: maintaining workflow state when human intervention becomes necessary. When an AI agent requires human feedback, approval or correction, the entire process cannot simply pause and resume arbitrarily. The context, intermediate results, and computational state must be preserved to ensure continuity when execution wakes up.

The State Preservation Challenge

Consider a typical scenario where an AI agent analyzes customer feedback, determines sentiment, and requires human approval before proceeding with automated responses. Without proper checkpointing, resuming the workflow would require re-executing expensive AI operations, potentially producing different results due to model non-determinism. This creates an unreliable foundation for business-critical processes.

The checkpointing mechanism solves this by creating discrete save points within workflow nodes. When a checkpoint is established, the result of the wrapped operation is preserved. Upon resumption, the workflow can continue from exactly where it left off, with all previous computations intact.

Implementation Patterns

The checkpoint() method follows a straightforward pattern that integrates naturally with existing code:

class CustomerServiceNode extends Node
{
    public function __invoke(InquiryEvent $event, WorkflowState $state): ResponseEvent
    {
        $customerContext = $this->checkpoint('customer-lookup', function () use ($event) {
            return $this->buildCustomerContext($event->customerId);
        });

        $sentimentAnalysis = $this->checkpoint('sentiment-analysis', function () use ($event) {
            return SentimentAnalyzer::make()->structured(
                new UserMessage($event->message),
                Analyses::class
            );
        });

        // High-value customers or negative sentiment require human review
        if ($customerContext->isHighValue() || $sentimentAnalysis->isNegative()) {
            $humanDecision = $this->interrupt([
                'customer_tier' => $customerContext->tier,
                'sentiment_score' => $sentimentAnalysis->score,
            ]);

            if ($humanDecision['escalate']) {
                return new EscalationEvent($humanDecision['notes']);
            }
        }

        return new ResponseEvent();
    }
}

In this example, the content analysis operation—which might involve multiple LLM calls, vector searches, or complex processing—executes only once. When the workflow wakes up after human intervention, the $sentimentAnalysis variable contains the exact same data structure that was present before the interruption.

Take a look at the documentation for more details: https://docs.neuron-ai.dev/workflow/human-in-the-loop

Checkpoint Naming and Uniqueness

Each checkpoint requires a unique identifier within its containing node. This naming convention serves both organizational and technical purposes. From a technical standpoint, the framework uses these identifiers to map saved results to their corresponding code locations. From an organizational perspective, descriptive names improve code readability and debugging capabilities.

Performance Considerations

The framework serializes checkpoint results using PHP’s native serialization mechanisms, ensuring compatibility with complex objects and maintaining type safety upon restoration.

The serialization process handles most PHP data structures transparently, including objects, arrays, and primitive types. However, you should be aware that resources (such as database connections or file handles) cannot be serialized and should be re-established when the workflow resumes.

Production Readiness

Thanks to Neuron PHP developers can implement sophisticated agentic patterns without abandoning their existing technology stack or compromising on production reliability. The combination of modern PHP’s performance characteristics, Neuron’s workflow capabilities, and proper debugging creates a foundation for AI applications that can scale alongside existing business systems.

This feature contributes to removing the barriers to implementing human-in-the-loop AI patterns in PHP environments, opening new possibilities for integrating AI into existing applications.

Ready to implement human-in-the-loop workflows in your PHP applications? Start building with Neuron framework.

Multi-Agent Systems in PHP: A Practical Deep Research Implementation

Valerio — Mon, 22 Sep 2025 18:51:34 +0000

For years, building sophisticated multi-agent systems meant switching to Python. The release of Neuron V2 makes me feel one step closer toward answering whether PHP is ready for serious agentic application development, and the Deep Research Agent project provides a definitive answer.

This comprehensive research system demonstrates how Neuron is an agentic framework that allows you to create full-featured multi-agent architectures in PHP through practical implementation of coordinated AI agents working together to generate detailed research reports. The system orchestrates multiple specialized agents, each handling distinct phases of research planning, data gathering, content generation, and formatting.

The Multi-Agent Architecture

The Deep Research Agent breaks complex research tasks into manageable components through event-driven workflow architecture. A workflow is an event-driven, node-based way to control the execution flow of an application. Your application is divided into sections called Nodes which are triggered by Events, and themselves return Events which trigger further nodes.

Each agent in the system specializes in a specific aspect of research:

Planning Agent: Creates structured report outlines and identifies research areas
Query Generation Agent: Transforms topics into targeted search queries
Web Search Agent: Executes searches and processes results
Content Generation Agent: Synthesizes findings into coherent sections
Formatting Agent: Compiles the final report structure

Neuron Workflow modular approach enables sophisticated coordination while maintaining code clarity and debugging capabilities that were previously impossible in PHP.

Implementation Overview

The system's entry point demonstrates the simplicity of launching complex multi-agent workflows:

class DeepResearchAgent extends Workflow
{
    /**
     * @throws WorkflowException
     */
    public function __construct(string $query, protected int $maxSections = 3)
    {
        parent::__construct(new WorkflowState(['topic' => $query]));
    }

    protected function nodes(): array
    {
        return [
            new Planning($this->maxSections),
            new GenerateSectionContent(), // Loop until all sections are generated
            new Format(),
        ];
    }
}

Behind this interface, the workflow coordinates multiple agents through event-driven nodes.

Planning: Creates the structure of the report
GenerateSectionContent: Generates content for each section using search results
Format: Compiles the final report, with additional nodes handling query generation and web searches.

Event-Driven Coordination

What makes NeuronAI Workflows special is their streaming and interruption capabilities. This means your multi-agent system can stream updates directly to clients, pause mid-process, ask for human input, wait for feedback, and then continue exactly where it left off – even if that’s hours or days later.

The workflow architecture enables agents to communicate through events rather than direct function calls:

class Planning extends Node
{
    public function __construct(protected int $template)
    {
    }

    public function __invoke(StartEvent $event, WorkflowState $state): GenerationEvent
    {
        /** @var ReportPlanOutput $plan */
        $plan = ResearchAgent::make()
            ->withInstructions(
                "You are an expert in research. You are given a user query and you need to generate a report plan for the user."
            )
            ->structured(
                new UserMessage(str_replace('{topic}', $state->get('topic'), $template)),
                ReportPlanOutput::class
            );

        return new GenerationEvent($plan);
    }
}

Each event triggers subsequent nodes automatically, creating a self-coordinating system where agents respond to completed work from other specialists.

Real-Time Streaming Capabilities

The system provides visibility into the research process as it happens. Users can observe planning completion, watch search queries execute, and see content generation in real-time. This streaming architecture means users see planning complete, watch research queries execute, and observe content generation happen step by step. For applications where users need to understand what the AI system is doing, this visibility builds confidence in the process.

class GenerateQueries extends Node
{
    /**
     * @throws \Throwable
     */
    public function __invoke(StartEvent $event, WorkflowState $state): \Generator|SearchEvent
    {
        $prompt = \str_replace('{query}', $state->get('query'), Prompts::SEARCH_QUERY_INSTRUCTIONS);

        yield new ProgressEvent("\n\n========== Generating search queries ==========\n\n");

        /** @var SearchQueriesOutput $response */
        $response = ResearchAgent::make()
            ->structured(
                new UserMessage($prompt),
                SearchQueriesOutput::class
            );

        yield new ProgressEvent(\implode("- ", $response->queries)  ."\n");

        return new SearchEvent($response->queries);
    }
}

This streaming capability addresses one of the fundamental challenges in AI applications: providing transparency in automated processes that traditionally operate as black boxes.

Human-in-the-Loop

One of the most practical features v2 reinforced is seamless human intervention. Workflows can pause execution, request human input, and resume exactly where they stopped. This capability makes AI systems viable for sensitive business processes where human oversight is required.

class InterruptionNode extends Node
{
    public function __invoke(InputEvent $event, WorkflowState $state): OutputEvent
    {
        // Interrupt the workflow and wait for the feedback.
        $feedback = $this->interrupt([
            'question' => 'Should we continue?',
            'current_value' => $state->get('accuracy')
        ]);

        if ($feedback['approved']) {
            $state->set('is_sufficient', true);
            $state->set('user_response', $feedback['response']);
            return new OutputEvent();
        }

        $state->set('is_sufficient', false);
        return new InputEvent();
    }
}

This pattern enables deployment of AI systems in production environments where complete automation isn’t appropriate or trusted.

Monitoring & Debugging

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.

The Deep Research Agent integrates with Inspector for comprehensive observability:

INSPECTOR_INGESTION_KEY=fwe45gtxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This monitoring reveals the complete execution timeline, showing which agents made decisions, how long each phase took, and where any issues occurred. For multi-agent systems, this visibility proves essential for optimization and debugging.

Getting Started

The complete implementation is available at the Deep Research Agent repository. Setup requires minimal configuration:

composer install

php research.php

It’s a complete implementation that creates comprehensive research reports by orchestrating multiple AI services. Planning, research, content generation, formatting – all streaming in real-time, all built with the new event-driven workflow architecture.

The Broader Implications

This implementation demonstrates that sophisticated AI architectures are no longer exclusive to Python. For teams with substantial PHP expertise, v2 removes the primary arguments for switching to Python for AI development. Complex agentic workflows are now feasible within the PHP ecosystem, using familiar patterns and deployment infrastructure.

The Deep Research Agent represents more than a technical achievement. It proves that PHP developers can build production-ready multi-agent systems without abandoning their existing skills, deployment infrastructure, or codebase. Neuron definitively fills the gap for AI Agents development between PHP and other ecosystems like Python or Javascript, enabling teams to innovate within their current technology stack.

For developers curious about agentic applications, the Deep Research Agent provides both a learning resource and a foundation for building specialized multi-agent systems.

The question isn’t whether PHP can handle multi-agent systems anymore. The question is what you’ll build with these capabilities.

If you want to learn more about how to get started your AI journey in PHP check out the learning section in the documentation.

Building Multi-Agent Systems in Laravel – A Practical Demo

Valerio — Sat, 20 Sep 2025 13:44:15 +0000

As PHP developers, we've watched the AI agent conversation happen around us rather than with us. While Python frameworks multiplied and JavaScript libraries emerged, PHP remained notably absent from the agentic application development landscape. The question isn’t whether PHP developers want to build intelligent applications—it's whether the tools exist to do it properly.

The answer is increasingly yes, and a new Laravel travel planner application demonstrates exactly how accessible multi-agent development has become for PHP developers who prefer to stick with their existing expertise rather than retool their entire skillset.

The Multi-Agent Architecture Challenge

Building applications that coordinate multiple AI agents presents unique architectural challenges. Unlike single-agent systems that follow linear request-response patterns, multi-agent workflows require orchestration, state management, and coordination between different specialized components. Each agent needs to understand its role, communicate with others, and contribute to a larger objective without creating bottlenecks or conflicts.

Traditional PHP applications handle these coordination patterns well—think about how Laravel’s job queues manage complex background processes or how service containers resolve dependencies. The missing piece has been frameworks that apply these familiar patterns to AI agent coordination.

Introducing Neuron's Workflow Component

The Neuron framework's Workflow component addresses this gap by providing a structured approach to multi-agent orchestration that feels natural to PHP developers. Rather than forcing developers to learn entirely new paradigms, it builds on established patterns like dependency injection, event handling, and pipeline processing.

A Workflow in Neuron defines how multiple agents collaborate to complete complex tasks. Each workflow consists of specialized nodes that handle specific responsibilities, with the framework managing communication and state between them. This approach separates concerns while maintaining the flexibility to handle dynamic, context-dependent decision making.

The Travel Planner Agent: Multi-Agent Coordination in Practice

The travel planner project demonstrates these concepts through a practical application that most developers can immediately understand. When a user requests travel recommendations, the system doesn’t rely on a single agent trying to handle flights, hotels, and attractions simultaneously. Instead, it coordinates specialized agents, each optimized for specific tasks.

The architecture includes several key components:

TravelPlannerAgent serves as the workflow orchestrator, managing the overall process and ensuring all components work together toward the final itinerary.

Receptionist Node handles initial user interaction, collecting destination preferences, dates, budget constraints, and other requirements. This separation ensures user input validation happens consistently, regardless of how complex the downstream processing becomes.

Delegator Node coordinates parallel research across three specialized areas—flights, hotels, and places to visit. Rather than processing these sequentially, the workflow can handle multiple research streams simultaneously, improving both performance and result quality.

GenerateItinerary Node synthesizes all gathered information into a cohesive travel plan, ensuring recommendations work together rather than existing as isolated suggestions.

This structure provides several advantages over monolithic approaches. Each agent can be developed, tested, and optimized independently. The system can scale specific components based on demand.

Implementation Simplicity

Despite the sophisticated coordination happening behind the scenes, the implementation remains straightforward for Laravel developers. The workflow definition looks familiar to anyone who has worked with Laravel's service providers or pipeline components:

class TravelPlannerAgent extends Workflow
{
    /**
     * @throws WorkflowException
     */
    public function __construct(
        protected ChatHistoryInterface $history,
        ?WorkflowState $state = null,
        ?PersistenceInterface $persistence = null,
        ?string $workflowId = null
    ){
        parent::__construct($state, $persistence, $workflowId);
    }

    protected function nodes(): array
    {
        return [
            new Receptionist($this->history),
            new Delegator(),
            new Flights(),
            new Hotels(),
            new Places(),
            new GenerateItinerary($this->history)
        ];
    }
}

Each node handles its specific responsibility while the framework manages state transitions and inter-node communication. The result is code that’s both powerful and maintainable, without requiring developers to become experts in distributed systems or advanced AI orchestration patterns.

Monitoring & Debugging

When your application makes decisions based on LLM outputs and external API calls, understanding why specific choices were made becomes crucial for both debugging and optimization.

The travel planner integrates with Inspector for comprehensive monitoring of agent interactions, decision points, and performance metrics. Feel free to try this experience, it's free and it can give you even more insights on how the system works behind the scenes.

Just add the Inspector ingestion key to your environment file and the agent will be automatically monitored:

INSPECTOR_INGESTION_KEY=fwe45gtxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Beyond Travel Planning

While the travel planner serves as an accessible demonstration, the underlying patterns apply to numerous business applications. Content management systems could coordinate research agents, writing agents, and editorial agents to produce comprehensive articles. E-commerce platforms might coordinate inventory agents, pricing agents, and recommendation agents to optimize product suggestions.

The key insight is that many complex business processes already involve coordination between specialized roles—Neuron’s Workflow component simply provides a framework for implementing these patterns helping AI agents collaborate with human operators.

Getting Started

The travel planner project provides a complete, runnable example that developers can clone, configure, and modify for their own use cases. Setting up requires standard Laravel dependencies plus API keys for language models and external services like SerpAPI for travel data.

Installation follows familiar Laravel patterns:

composer install

npm run build

php artisan migrate

Configuration happens through environment variables, making it straightforward to swap different language models or external services without code changes.

If you want to learn more about how to get started your AI journey in PHP check out the learning section in the documentation.

Monitoring Laravel Livewire Components

Valerio — Thu, 11 Sep 2025 16:07:40 +0000

Livewire is a full-stack framework in Laravel that makes it easy to create reactive interfaces without writing any Javascript, just using PHP. This means developers can leverage the power of Laravel and Blade templates to build dynamic UIs. You can respond to user’s actions such as form submissions, scrolling, mouse movements, or button clicks, using PHP classes and methods.

After the initial rendering of the page containing the Livewire component, Livewire binds some javascript event listeners to its components and watches for every action. Each action is sent to the server as an asynchronous API request.

The Problem

When the user clicks on a button in the UI, Livewire makes a network request to the server to interact with the PHP component associated. The server then performs the action, generates a new template and the current new state of the component, and sends it back to the client.

Take a look at the example below that implement a simple counter:

resources/views/livewire/counter.blade.php

<div>
    <h1>{{ $count }}</h1>

    <button wire:click="increment">+</button>

    <button wire:click="decrement">-</button>
</div>

app/Livewire/Counter.php

class Counter extends Component
{
    public $count = 1;

    public function increment() {
        $this->count++;
    }

    public function decrement() {
        $this->count--;
    }

    public function render()
    {
        return view('livewire.counter');
    }
}

Every click on the counter button generates an HTTP request handled by the associated PHP component. And this happen for all UI component you have in the user interface.

All these HTTP requests are routed to the default Livewire URL: /livewire/update

That's why you see tons of requests to the endpoint "POST /livewire/update" in your Inspector monitoring dashboard. So, everything under /livewire/update it's like a grey area, because you don’t have any clue of what component is behing executed, what is its state, etc.

This behaviour it’s also the reason many applications in performance sensible environments do not adopt this stack, and eventually go for a dedicated Javscript framework like Vue or React to manage reactivity entirely on the frontend side, offloading the server.

Inspector Trait

To solve this problem the Inspector Laravel package includes the LivewireInspector trait that you can attach to your Livewire PHP class.

app/Livewire/Counter.php

use Inspector\Laravel\LivewireInspector;

class Counter extends Component
{
    use LivewireInspector;

    public $count = 1;

    public function increment() {
        $this->count++;
    }

    public function decrement() {
        $this->count--;
    }

    public function render()
    {
        return view('livewire.counter');
    }
}

A new transaction category, livewire, will now appear in the Inspector dashboard:

As you can see, the transaction name is the name of the component class. This way, you’ll have all the components monitored individually.

From the individual component’s detail page, you can access the history of every time that component has been run. Any exceptions will also be attached to the component’s transaction, so everything remains clear.

Here the link to the documentation: https://docs.inspector.dev/guides/laravel/livewire

Monitor your Laravel application for free

Inspector is a Code Execution Monitoring tool specifically designed for PHP developers. You don't need to install anything on the server level, just install the Laravel package and you are ready to go.

If you are looking for HTTP monitoring, database query insights, and the ability to forward alerts and notifications into your preferred messaging environment try Inspector for free. Register your account.

Or learn more on the website: https://inspector.dev/