DEV Community: Inspector.dev

Debug Your PHP App From Your Phone, Through Your AI Assistant

Valerio — Tue, 28 Jul 2026 14:53:27 +0000

Last month I was at dinner when my phone buzzed with an Inspector alert: an error on one of our own endpoints. The old routine kicks in automatically at that point. Open the dashboard on a screen too small for it, squint at a stack trace, tell yourself "I'll look properly when I’m back at the laptop", and spend the rest of the evening with that specific low grade guilt of knowing something is broken and choosing to do nothing about it.

This time I didn't do that. I opened Claude on my phone, asked it to check what was going on with that endpoint, and within a couple of messages it had pulled the actual error, traced it to a query that started timing out after a data migration earlier that day, and proposed the fix. I reviewed it, it looked right, and the incident was basically closed before the table finished eating. That gap, between getting the alert and being able to do something real about it, is what we spent the last stretch of work closing.

The part of the workflow nobody designed for

We built the Inspector MCP server so your AI coding assistant could read your production data directly: errors, response times, slow queries, the same information you’d normally go dig up in the dashboard. If you missed that first release, the original announcement covers what it does.

It worked well from day one, but only in one context: coding agents running on your own machine, like Claude Code or Cursor, where you paste your Inspector API token into a config file once and the tool uses it locally from then on. That's fine when the AI client lives on your laptop next to your code. It falls apart the moment the client is Claude or ChatGPT running as a hosted app in a browser or on your phone, because there's no config file there to paste a token into, and there shouldn’t be. Hosted apps authenticate through OAuth, the login-and-approve flow you already know from connecting Slack or Google Drive to some other tool, not through a secret you copy and paste. Our server simply didn’t speak that language yet, so the alert would land on your phone and the trail stopped right there. You could read that something broke. You couldn’t do anything about it without switching devices.

That's the specific moment this update is built for. Not "AI assistants can now use Inspector data", which was already true, but the alert-to-fix path being unbroken end to end, on whatever device you're holding when the alert arrives.

Connecting Inspector to your AI account, step by step

The whole point of this release is that there is no JSON configuration and no API token involved anymore. If you tried the first version and remember editing a config file, forget that part. Here is the actual flow, using Claude as the example, because it's the client I use most. ChatGPT and other web based agents follow the same pattern under different menu names.

Step 1: add the connector with just a URL
In Claude, open Settings and go to the Connectors section, then choose to add a custom connector. You give it a name, Inspector, and paste the server URL, which you'll find in your application settings inside the Inspector dashboard. It looks like this, with your own application ID at the end:

https://app.inspector.dev/mcp?app=YOUR_APP_ID

That's it. You don't need to touch "Advanced settings", and there is no field asking you for an authorization token, because the server now negotiates that part on its own.

Step 2: authorize the connection on Inspector

As soon as you connect, you're redirected to Inspector, where you'll see a plain authorization screen telling you which application is asking for access and what it will be able to do. In this case, Claude requesting permission to use the MCP server. You log in with the Inspector account you already have, click Authorize, and the handshake completes behind the scenes.

This is the piece that was missing before, and it's the reason the whole thing now works from a phone: your credentials stay between you and Inspector, and the AI client walks away with a scoped token it can refresh on its own.

Step 3: check the tools you just gave your assistant

You land back in Claude with a confirmation that you're connected, and the connector page now shows the tools the Inspector MCP server exposes, along with a permission switch for each one. You'll see the ability to analyze a specific error, pull recent errors from your production environment, list recent transactions, inspect the details of a single transaction, and get the ten worst performing transactions in your application.

Worth noticing that these are all read only. Your assistant can look at your production data and reason about it, but it isn’t changing anything in your Inspector account. You can also decide per tool whether Claude is always allowed to use it, should ask first, or shouldn’t touch it at all.

Step 4: try it with one prompt

The fastest way to confirm everything works is to ask something broad and see if it comes back with real data instead of a polite guess. Copy and paste this:

Look at Inspector and let me know what kind of transactions happened in my application recently.

You should get an actual summary of your traffic: the endpoints, jobs and commands that ran, how they performed, and anything that stands out. Once you see real numbers coming back, the connection is done and you can forget it exists.

What this looks like when something actually breaks

The setup above takes two minutes and then disappears into the background. The part that matters is the next time an alert reaches your phone while you're nowhere near a desk.

You open the assistant straight from the notification and start with something like this:

Inspector just flagged an error on the /checkout/complete endpoint. What's happening?

The assistant pulls the real error through the MCP connection: exception type, how often it's firing, when it started, which transactions are affected. Then you keep going in the same thread:

Show me the slowest transaction involved and suggest what to fix in the code.

It's working from actual execution data now, not from reading your code in isolation and guessing which branch is expensive. It can propose a fix, and if your coding agent is set up with access to your repository, open a pull request or push to a branch so the change is waiting for you already reviewed by the time you sit down.

This won't replace a proper debugging session for anything genuinely complex. But for the alert that hits during a commute, at dinner, or on a Sunday afternoon, the difference between "I'll deal with it tonight" and "I already dealt with it" is the whole reason we built this.

Why it took actual engineering work

We could have shipped a shortcut, some long lived token you paste into a web form, and called the mobile use case supported. It would have demoed fine. It also would have meant handing a static credential to a third party service, which is the exact failure mode OAuth exists to prevent, and it would have made revoking access a manual step that's easy to forget. Doing it properly means Inspector now behaves like any other real OAuth provider: connected applications are visible and revocable from your account, tokens expire and refresh on their own, and the security model matches what you already expect when you connect one service to another.

It's a small piece of infrastructure next to the monitoring itself, but it's the piece that decides whether "you can debug from your phone" is actually true or just true in a demo video. For us, it's the former now.

If you haven't connected it yet, the server URL is in your application settings in the Inspector dashboard. Add it to whichever AI assistant you carry around, laptop, browser, or phone.

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.

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.

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.

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/

Keeping Your AI Agents Under Control: Tool Max Tries in Neuron V2

Valerio — Mon, 08 Sep 2025 08:20:28 +0000

When you're building AI agents in PHP, one question keeps surfacing in production environments: what happens when your agent gets stuck in a loop? Whether it's an external API that's down, an LLM that's having an off day, or a tool that's returning unexpected responses, runaway tool calls can quickly turn a helpful agent into a resource-draining problem.

Neuron V2 introduces Tool Max Tries, a straightforward guardrail that puts you back in control of your agent's behavior. This feature sets a hard limit on how many times an agent can invoke any single tool during a conversation, preventing the cascading failures that can occur when AI reasoning goes sideways.

The Problem: When AI Gets Stuck

Picture this scenario: you've built an agent that helps customers track their orders. It uses a GetOrderStatus tool to fetch information from your backend API. Everything works perfectly in testing, but in production, your API occasionally returns a 500 error. Instead of gracefully handling the failure, your agent decides the best course of action is to keep trying the same tool call, over and over.

Without proper constraints, you might see something like this in your logs:

[2024-09-04 10:15:23] Tool call: getOrderStatus(order_id: 12345)
[2024-09-04 10:15:24] API Error: Internal Server Error
[2024-09-04 10:15:25] Tool call: getOrderStatus(order_id: 12345)
[2024-09-04 10:15:26] API Error: Internal Server Error
[2024-09-04 10:15:27] Tool call: getOrderStatus(order_id: 12345)
// ... continues indefinitely

This isn't just annoying—it's dangerous. Each failed tool call still consumes tokens, and if you're paying per API call to your LLM provider, those costs add up quickly. More importantly, it creates a terrible user experience as customers wait for responses that never come.

Simple but Effective Solution

Tool Max Tries addresses this by letting you set a maximum number of attempts for each tool in your agent's toolkit. Here's how you configure it:

try {

    $result = YouTubeAgent::make()
        ->toolMaxTries(5) // Max number of calls for each tool
        ->addTool(
            // It takes precedence over the global setting
            GetOrderStatus::make()->setMaxTries(2)
        )
        ->chat(...);

} catch (ToolMaxTriesException $exception) {
    // do something
}

By default the limit is 5 calls, and it count for each tool individually. You can customize this value with the toolMaxTries() method at agent level, or use setMaxTries() on the tool level. Setting max tries on single tool takes precedence over the global setting.

Now when your agent encounters that problematic API, it will attempt the call up to three times before giving up and informing the user that the service is currently unavailable. The conversation continues, but within reasonable bounds.

You can also apply this configuration for tools included in toolkit using the with method:

class MyAgent extends Agent
{
    ...

    public function tools(): array
    {
        return [
            MySQLToolkit::make()
                ->with(
                    MySQLSchemaTool::class, 
                    fn (ToolInterface $tool) => $tool->setMaxTries(1)
                ),
        ];
    }
}

Getting Started

Setting up Tool Max Tries is straightforward, and you can configure different limits for different tools based on their risk profiles and expected behavior. A tool that performs simple calculations might never need retries, while one that calls external APIs might benefit from two or three attempts.

The beauty of this approach is that it's opt-in and granular. You can set limits only where you need them, and adjust them based on your actual usage patterns. If you find that five attempts aren't enough for a particular tool, you can increase the limit. If you want to be more aggressive about preventing loops, you can set it to one or two.

The framework handles the operational complexities while letting you focus on solving business problems.

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

Neuron V2 – Is PHP Ready For Agentic Application Development?

Valerio — Thu, 04 Sep 2025 09:15:51 +0000

Since the beginning of my journey building Neuron I challenged myself with a simple question: "Is PHP ready for agentic application development?"

For months, developers have been asking whether they need to switch to Python to build production-grade AI systems, or if they can leverage their existing PHP expertise. More and more discussions have been posted in the forum about coordinating multiple agents or how to implement complex scenarios.

Neuron v2 provides a definitive answer. This release fundamentally changes how PHP developers can approach complex AI workflows, introducing an event-driven architecture that makes building sophisticated agentic systems both practical and performant.

If you are curious about the beginning of this journey you can read the article of the first launch:

https://inspector.dev/introduction-to-neuron-ai-create-full-featured-ai-agents-in-php/

Upgrade guide

Before moving forward you can bookmark the Upgrade guide on the documentation to learn more about the latest changes, and how they impact your application upgrading your implementations to V2: https://docs.neuron-ai.dev/overview/readme/upgrade-guide

What Changes in Neuron V2

Aside from removing "AI" from the name, the core advancement in v2 centers around a complete rearchitecture of the Workflow system. In v1 Workflow was marked as experimental. The previous implementation relied on a combination of nodes and edges to define the path workflow must follow to navigate through nodes. V2 introduces an event-driven model that uses only nodes as entities that handle incoming events and emit other events.

namespace App\Neuron;

use NeuronAI\Workflow\Node;
use NeuronAI\Workflow\StartEvent;
use NeuronAI\Workflow\WorkflowState;

class InitialOne extends Node
{
    public function __invoke(StartEvent $event, WorkflowState $state): FirstEvent
    {
        $state->set('node_one_executed', true);

        return new FirstEvent('First complete');
    }
}

This shift eliminates the Edge class entirely and opens up possibilities that weren’t feasible with the graph-like workflows. Nodes now trigger and respond to events, creating dynamic execution paths based on runtime conditions rather than predetermined sequences. It’s very easy now to create and maintain workflows with loops and braches. Here is an example:

https://docs.neuron-ai.dev/workflow/loops-and-branches

Real-Time Streaming in multi-agent systems

The most immediate impact developers can notice is streaming capability. V2 workflows can stream intermediate results to clients in real-time, transforming user experience from "loading…" states to live progress updates even in multi-agent systems.

$workflow = new Workflow();

$workflow->addNodes([
    new NodeOne(),
    new NodeTwo(),
    new NodeForSecond(),
]);

// Draw the workflow graph
echo $workflow->export()."\n\n\n";

$handler = $workflow->start();

foreach ($handler->streamEvents() as $event) {
    if ($event instanceof ProgressEvent) {
        echo "\n- {$event->message} \n";
    }
}

$finalState = $handler->getResult();

// It should print "Second complete"
echo $finalState->get('final_second_message');

Check out this example: https://github.com/inspector-apm/neuron-ai/blob/2.x/examples/workflow/workflow-stream.php

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.

Human-in-the-Loop Without Complexity

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.

$persistence = new FilePersistence(__DIR__);

$workflow = Workflow::make(new WorkflowState(), $persistence, 'test_workflow')
    ->addNodes([
        new NodeOne(),
        new InterruptableNode(),
        new NodeForSecond(),
    ]);

// Draw the workflow graph
echo $workflow->export()."\n\n\n";

// Run the workflow and catch the interruption
try {
    $finalState = $workflow->start()->getResult();
} catch (WorkflowInterrupt $interrupt) {
    // Verify interrupt was saved
    $savedInterrupt = $persistence->load('test_workflow');
    echo "Workflow interrupted at ".$savedInterrupt->getCurrentNode()::class;
}

// Resume the workflow providing external data
$finalState = $workflow->start(true, 'approved')->getResult();

// It should print "approved"
echo $finalState->get('received_feedback');

Check out this example: https://github.com/inspector-apm/neuron-ai/blob/2.x/examples/workflow/workflow-interrupt.php

The workflow state persists during these pauses, meaning the system can wait hours or days for human feedback before continuing. This persistence enables complex approval processes that span multiple stakeholders and time zones.

Performance at the Foundation

Under the hood, v2 addresses performance from the ground up. Large dataset iterations automatically chunk data, file access uses generators for better performance and memory management, and the strong type system helps PHP’s engine optimize reference lookups.

These optimizations aren't visible in the API but it makes PHP applications handling large AI workloads with easy.

Neuron CLI – Enhanced Developer Tools

V2 ships with practical developer experience improvements that address common friction points. The CLI tool brings the new "make" command that helps you scaffold common classes reducing boilerplate fatigue:

php vendor/bin/neuron make:agent App\\Neuron\\MyAgent

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

php vendor/bin/neuron make:workflow App\\Neuron\\MyWorkflow

Seeing It in Action – Deep Research Agent

The deep-research-agent demo project demonstrates these capabilities in practice. This implementation creates comprehensive research reports by orchestrating multiple AI services through an event-driven workflow that includes planning, research, content generation, and formatting phases.

The demo shows how complex agentic workflows can remain readable and maintainable while handling real-world requirements like API calls, result aggregation, and structured output formatting. Developers can examine the complete workflow implementation and see how each node contributes to the overall process.

Check out the GitHub repository >> https://github.com/neuron-core/deep-research-agent

Is PHP Ready For Agentic Application Development?

The release of Neuron V2 makes me feel one step closer toward answering whether PHP is ready for serious agentic application development. The event-driven architecture, streaming capabilities, and production-focused performance optimizations create a foundation for building AI systems that can compete with implementations in other languages.

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 framework maintains a general backward compatibility while introducing advanced capabilities. Teams can adopt v2 features without requiring full rewrites.

Getting Started With Neuron

The most effective way to understand v2's capabilities is to experiment with the Deep Research Agent at https://github.com/neuron-core/deep-research-agent. This implementation demonstrates real-world workflow patterns and provides a starting point for building custom agentic systems.

For developers ready to explore how quickly ideas can become working applications, Neuron v2 offers the tools to turn concepts into production-ready AI systems without leaving the PHP ecosystem. The question isn't whether PHP is ready for agentic development anymore – it's what you’ll build with it.

Check out the official Neuron Documentation.

AI Coding Agents Meet Production Environment with the Inspector MCP Server

Valerio — Wed, 27 Aug 2025 13:29:25 +0000

Software development has undergone a profound transformation in the past two years, one that even the most forward-thinking developers didn't anticipate. Coding assistants have evolved from experimental curiosities to powerful development partners, fundamentally changing how we approach problem-solving, debugging, and architectural decisions.

I've witnessed this evolution firsthand, initially approaching AI coding tools with the healthy skepticism that comes from a navigated software engineer. However, after integrating Claude Code into my daily workflow, I've experienced a productivity leap that genuinely surprised me. The ability to delegate complex refactoring tasks, explore alternative architectural approaches, and receive intelligent suggestions for optimization has transformed my development process in ways that traditional tooling never achieved.

This experience sparked the idea to create the Inspector MCP server to allow these programming assistants to access production errors and monitoring data in real-time.

The Context Gap in AI-Assisted Development

Yet this transformation has revealed a critical gap that becomes apparent only when you actually try AI assistance for coding. They can analyze code, but they remain blind to the runtime behavior that ultimately determines application success or failure. A coding assistant might suggest elegant solutions to theoretical problems while remaining completely unaware that your production system is currently experiencing a cascade of database timeouts that renders those suggestions irrelevant.

Error patterns that emerge in production often reveal architectural assumptions that seemed reasonable during development but prove problematic at scale. Performance bottlenecks frequently manifest in ways that static code analysis, however sophisticated, simply cannot predict.

As the creator of Inspector, I've spent years building observability solutions that help developers understand their applications' runtime behavior. This perspective has made the gap between AI coding assistance and production awareness particularly stark. Developers using advanced AI tools were still context-switching between their development environment and monitoring dashboards, manually correlating code suggestions with production telemetry. The inefficiency was obvious, but more importantly, it represented a missed opportunity for truly integrated development workflows.

Bridging Development and Production with MCP

The Inspector MCP Server emerged from this recognition that AI coding assistants need production context to reach their full potential. By implementing the Model Context Protocol, we've created a bridge that allows AI agents to access real-time error data, performance metrics, and system behavior directly from Inspector's monitoring infrastructure.

https://github.com/inspector-apm/mcp-server

From a practical standpoint, the Inspector MCP Server enables workflows that were previously impossible. Developers can now ask their AI assistant to analyze recent production errors, identify common failure patterns, and suggest preventive measures based on actual error frequencies and contexts. Performance optimization becomes a collaborative process where AI analysis combines with real telemetry to identify bottlenecks and propose solutions. Error triage transforms from manual investigation to intelligent analysis that can rapidly distinguish between critical issues requiring immediate attention and noise that can be addressed systematically.

This production-aware approach becomes even more compelling when combined with the broader ecosystem we've built around Inspector and the Neuron AI framework. PHP developers have historically been underserved in the AI tooling space, despite PHP powering the majority of web applications. The combination of Inspector's observability capabilities, Neuron's AI agent framework, and now the MCP server creates an integrated development experience specifically designed for the PHP ecosystem’s unique characteristics and deployment patterns.

Get started with Inspector MCP server

You can install the server as a dev-dependency in your project:

composer require inspector-apm/mcp-server --dev

The next step is to provide the MCP client with the configuration to connect to this server and use the tools. The MCP client is your coding assistant like Claude Code, Gemini Code Assist, or an agentic IDE like Jetbrains, Visual Studio Code, Cursor, or similar.

This is the configuration:

{
  "mcpServers": {
    "inspector": {
      "command": "php",
      "args": [
        "absolute-path-to-your-app-vendor-folder/inspector-apm/mcp-server/server.php"
      ],
      "env": {
        "INSPECTOR_API_KEY": "XXX",
        "INSPECTOR_APP_ID": "XXX"
      }
    }
  }
}

You need three information to complete this configuration:

Absolute path of the vendor folder: This is the root path where the vendor folder of your project is located in your computer. The next part is the path to point to the file that runs the MCP server (inspector-apm/mcp-server/server.php)
INSPECTOR_API_KEY: Click Here to generate a new API key
INSPECTOR_APP_ID: This is the unique identifier of your application inside Inspector. You can get this information in the Application Settings menu in the Inspector dashboard

Claude Code Configuration
Once you have the information above you can connect the Inspector MCP server to Claude Code with the command below:

claude mcp add inspector --env INSPECTOR_API_KEY=YOUR_KEY --env INSPECTOR_APP_ID=YOUR_APP_ID -- php [absolute_path_to_your_app_vendor_folder]/inspector-apm/mcp-server/server.php

For other agents check out their documentation on how to connect to local (STDIO) MCP servers.

Now you can ask a simple question:

"Hey Claude, what happened overnight in the production environment?"

Transforming Development Workflows

The timing of this integration reflects a broader maturation in how we think about AI-assisted development. Sustainable productivity gains require deeper integration with the entire development lifecycle.

Consider the qualitative difference this integration creates. Instead of an AI assistant suggesting generic solutions to abstract problems, it can now analyze actual production errors with full context about frequency, impact, and environment conditions. When debugging becomes a collaborative process between developer intuition and AI analysis backed by real telemetry data, the speed and accuracy of problem resolution can improve dramatically. The assistant can identify patterns across multiple errors, correlate issues with recent deployments, and suggest targeted fixes based on actual system behavior rather than theoretical best practices.

As AI coding assistants continue to evolve, their effectiveness will increasingly depend on access to the contextual information that production systems provide. The Inspector MCP Server establishes this foundation for the PHP ecosystem.

The future of AI-assisted development lies not in more sophisticated code generation, but in more intelligent integration with the complete software lifecycle. By bridging the gap between development environment and production telemetry, we're enabling a new class of development workflows where artificial intelligence becomes truly valuable for real-world application development and maintenance.

Connect Inspector with your coding agent now: https://github.com/inspector-apm/mcp-server

Introducing NeuronAI Workflow: The future of agentic PHP applications

Valerio — Fri, 04 Jul 2025 14:38:04 +0000

Three months ago, when I started building the Workflow component for NeuronAI, I knew it would be complex. What I didn't anticipate was that it would become the most technically challenging development of my entire career—alongside Neuron itself.

The core challenge wasn't just about creating another workflow engine. It was about enabling true human-in-the-loop patterns while maintaining clean architecture, readable code organization, and building on interoperable components that developers could easily extend and interchange—especially the persistence layer.

Sounds interesting? Support the project starring the GitHub repository: https://github.com/inspector-apm/neuron-ai

What is a Workflow

Think of a Workflow as a smart flowchart that describes how your AI applications should work. Instead of your AI making every decision independently, a Workflow lets you create a step-by-step process where AI handles what it does best, and humans step in when judgment or oversight is needed.

Here's what makes NeuronAI Workflows special: they're built around interruption and human-in-the-loop capabilities. This means your agentic system can 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.

Imagine you're building a content moderation system. Instead of having AI make final decisions about borderline content, your Workflow can:

Analyze the content using AI
Flag anything uncertain
Pause and ask a human moderator for review
Wait for the human decision
Continue processing based on that feedback

The key breakthrough is that interruption isn't a bug – it's a feature. Your Workflow remembers exactly where it stopped, what data it was working with, and what question it needs answered.

Why Use NeuronAI Workflow Instead of Regular Scripts?
You might be thinking: "This sounds great, but why can't I just write a regular PHP script with some if-statements and functions?" It's a fair question, and one I heard a lot while building NeuronAI. The answer becomes clear when you consider what happens when your process needs to pause, wait, and resume exactly where it left off.

Another scenario that is practically impossible to reproduce with a procedural approach is when you need complex workflows with many branches, several loops and intermediate checkpoints, etc. When you are at the beginning of a project and your use case is yet quite simple, it’s not easy to see the real potential of Workflow, and it’s normal. Keep in mind that if things hit the fan, NeuronAI already has a solution to help you scale.

Create a Workflow
A Workflow in NeuronAI is made up of two elements:

Nodes, with each node responsible for handling a unit of execution (manipulate data, call an agent, etc.).

Edges, responsible to define how the workflow must move from one node to the next. They can be conditional branches or fixed transitions.

In short: Nodes do the work, Edges tell what to do next.

As an illustrative example, let’s consider a simple workflow with two nodes. The connection (Edge) tells the workflow to go from A to B to C.

<?php

namespace App\Neuron\Workflow;

use App\Neuron\Workflow\InitialNode;
use App\Neuron\Workflow\MiddleNode;
use App\Neuron\Workflow\FinishNode;
use NeuronAI\Workflow\Edge;
use NeuronAI\Workflow\Workflow;

class SimpleWorkflow extends Workflow
{
    public function nodes(): array
    {
        return [
            new InitialNode(),
            new MiddleNode(),
            new FinishNode(),
        ];
    }

    public function edges(): array
    {
        return [
            // Tell the workflow to go to MiddleNode after InitialNode
            new Edge(InitialNode::class, MiddleNode::class),

            // Tell the workflow to go to FinishNode after MiddleNode
            new Edge(MiddleNode::class, FinishNode::class),
        ];
    }

    protected function start(): string
    {
        return InitialNode::class;
    }

    protected function end(): array
    {
        return [
            FinishNode::class,
        ];
    }
}

Learn all this concept in details on the documentation: https://docs.neuron-ai.dev/workflow/getting-started

Understanding Workflow Structure: Nodes and Edges

Before diving into the interruption capabilities, it's important to understand how Workflows are structured. Think of a Workflow as a graph made up of two key components: nodes and edges.

**Nodes **are where the actual work happens – they're like individual functions or operations in your Workflow. A node might analyze text, make an API call, process data, or request human input. Each node has a specific job and produces some output.

Edges are the connections between nodes – they define the flow of your Workflow. But here's where NeuronAI gets interesting: edges aren't just simple arrows pointing from one node to the next. They can be conditional, and make decisions about where to route your data based on conditions, outcomes, or even dynamic logic.

For example, imagine a content moderation Workflow:

An analysis node examines a piece of content
Multiple edges lead out from this node: one for "clearly safe content," another for "clearly problematic content", and a third for "needs human review"
The edge that gets taken depends on the confidence level of the AI analysis

This means your Workflow can automatically branch into different paths based on real-time conditions. An edge might route high-confidence decisions straight to approval, while routing uncertain cases through human review nodes. You can even have edges that loop back to previous nodes, creating iterative processes where content gets refined through multiple rounds of AI analysis and human feedback.

The real power comes from conditional edges – connections that evaluate the output of a node and decide which path to take next. This lets you build sophisticated decision trees where the Workflow adapts its behavior based on what it discovers along the way.

Human In The Loop

NeuronAI Workflows flip this paradigm. Instead of building AI systems that try to be perfect, you build systems that are intelligently imperfect. They know their limitations and actively seek help when they need it.

Here's how it works technically:

Interruption Points: Any node in your Workflow can request an interruption by specifying what kind of human input it needs. This could be a simple yes/no decision, a content review, data validation, or creative input.

State Preservation: When an interruption happens, NeuronAI automatically saves the complete state of your Workflow – all variables, processed data, and context. Your Workflow essentially goes to sleep, waiting for human input.

Resume Capability: Once a human provides the requested input, the Workflow wakes up exactly where it left off. No data is lost, no context is forgotten. It's like the AI was never paused at all.

External Feedback Integration: The human input becomes part of the Workflow's data, available to all subsequent nodes. This means later steps can make better decisions based on both AI analysis and human judgment.

$persistence = new FilePersistence(__DIR__);
$workflow = new Workflow($persistence, 'test_workflow');

$workflow->addNodes([
        new BeforeInterruptNode(),
        new InterruptNode(),
        new AfterInterruptNode(),
    ])
    ->addEdges([
        new Edge(BeforeInterruptNode::class, InterruptNode::class),
        new Edge(InterruptNode::class, AfterInterruptNode::class)
    ])
    ->setStart(BeforeInterruptNode::class)
    ->setEnd([AfterInterruptNode::class]);

try {
    $workflow->run(new WorkflowState(['value' => 8]));
} catch (WorkflowInterrupt $interrupt) {
    // Catch interruption as a normal exception

    // Verify interrupt signal was saved
    $savedInterrupt = $persistence->load('test_workflow');
    echo "Workflow interrupted at {$savedInterrupt->getCurrentNode()}.";
}

// Resume passing the human feedback
$result = $workflow->resume(['approved' => true]);

echo $result->get('final_value');

Beyond One Shot Interactions

Single AI Agents work like this: you give them input, they process it using their tools or external information, and they give you output. That's it. If the AI makes a mistake, you only find out after the fact.

Working on NeuronAI, we've seen developers struggle with this limitation. They’d build sophisticated agents, but couldn't deploy them in high-stakes situations because there was no safety net. No way to verify output before they mattered. No way to inject human feedback when the Agent reached the limits of its abilities.

Traditional approaches to solving this usually involve building separate review systems, complex approval processes, or having humans check everything after the fact. These solutions are clunky, expensive, and often too slow for real-world applications.

From a developer perspective, NeuronAI Workflow solves several painful problems:

Model and maintain complex iterations: With these simple building blocks you will be able to create simple processes with a few steps, up to complex workflows with iterative loops and intermediate checkpoints.

Human in the Loop: Seamlessly incorporate human oversight. You can deploy AI in sensitive areas because humans are always in the loop for critical decisions.

Debugging with inspector: Instead of wondering why your AI made a particular decision, you can see exactly how humans and AI collaborated at each step.

User Trust: When users know a human reviewed important decisions, they’re more likely to trust and adopt your AI system.

The Future of AI Development

Creating the NeuronAI Workflow component has convinced me that the future of AI isn’t about building systems that never need human help. It's about building systems that know exactly when and how to ask for help.

Instead of trying to replace human judgment, we're amplifying it. Instead of fearing AI mistakes, we’re building systems that catch and correct them in real-time.

The most successful AI applications of the next decade won’t be the ones that are most autonomous. They'll be the ones that are most collaborative – seamlessly blending artificial intelligence with human wisdom, creativity, and oversight.

NeuronAI Workflows it's the first step to make this collaboration not just possible, but efficient, all in PHP.

The best part? Your users will trust these systems more because they'll know a human was involved in the important decisions. And you'll sleep better at night knowing your AI can't make critical mistakes without human oversight.

That's the power of building AI systems that know when to ask for help. Build the future of intelligent PHP applications with NeuronAI.

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:

How to create a RAG Agent: https://inspector.dev/how-to-create-a-rag-agent-with-neuron-adk-for-php/
Introducing Toolkits: Composable AI Agent Capabilities In PHP
Newsletter: https://neuron-ai.dev
E-Book (Start With AI Agents In PHP): https://www.amazon.com/dp/B0F1YX8KJB

Vector Store & AI Agents – Beyond The Traditional Data Storage

Valerio — Fri, 04 Jul 2025 08:30:31 +0000

When I first encountered a vector store while working on Neuron AI, the ADK (Agent Development Kit) for PHP, I'll admit I made the same assumptions that many web developers make when they hear the term "database". The natural inclination is to think in familiar terms – tables, rows, columns, SQL queries, user records, and all the structured data patterns we've grown comfortable with over years of building web applications. But vector stores represent something fundamentally different, and understanding this difference is crucial for anyone stepping into the world of AI agent development.

The confusion often begins with how vector databases are marketed and discussed in AI circles. You'll frequently hear them described as "the database for AI agents", which immediately triggers our existing mental models. If you’re building an AI-powered customer service agent, for instance, your first instinct might be to think you need to store your customer records, user preferences, and application data in a vector store. This seems logical – after all, if it's the database for AI agents, shouldn’t it hold the same kind of structured information that powers your traditional applications?

This misconception runs deeper than just terminology. When we think about databases in the context of web development, we think about storing records, relationships, and structured information that we can query with precision. We ask questions like "Show me all users who signed up in the last month" or "Find all orders over $100 for customer ID 12345". These queries have definitive, binary answers – either a record matches our criteria or it doesn't. The database returns exact matches based on explicit conditions we’ve defined.

Vector databases operate on an entirely different principle. Rather than storing structured facts about your users or application data, they store the semantic meaning of text chunks – the conceptual essence of information rather than the information itself. When you insert text into a vector store, the system doesn't care about the literal words it contains in the way a traditional search index might.

Instead, it requires that text to be transformed into a mathematical representation that captures its meaning, context, and conceptual relationships to other pieces of text. This representation consists of a series of numbers called vector embeddings.

For developers who have spent years thinking about data in terms of strings, integers, and relational tables, the idea that we can somehow capture the “meaning” of text in an array of floating-point numbers feels almost mystical.

The struggle is understandable. In traditional web development, we've grown accustomed to exact matches and structured queries. When a user searches for "red shirt" in an e-commerce application, we look for products where the description contains exactly those words, perhaps with some basic stemming or fuzzy matching. The relationship between the query and the data is transparent and predictable. But vector embeddings operate on an entirely different principle.

Introduction To Vector Embeddings

To grasp vector embeddings, we need to abandon our attachment to exact string matching and embrace a fundamentally different way of thinking about text similarity. Imagine trying to explain to someone why "automobile" and "car" mean essentially the same thing, or why "happy" is more similar to "joyful" than to "purple". These relationships exist in the realm of meaning rather than literal character sequences, and vector embeddings are the mathematical tool to perform these queries.

Vector embeddings work by representing each piece of text as a point in a high-dimensional mathematical space—typically containing hundreds or even thousands of dimensions.

You probably remember how to represent a point on a chart with the classical two dimentìsions.

In the case of a multidimensional vector it's an array of thousands of numbers that ideally represents a lot of axes. It’s a mathematical concept since it doesn’t make so much sense because in the real world we can represent basically anything in a 3D space.

The more dimensions (aka more numbers) the vector has, the more accurately the meaning of a piece of text can be represented.

While we cannot visualize these spaces directly, we can think of them as vast landscapes where semantically similar concepts cluster together. In this space, "dog" and "wolf" end up positioned close to each other, not because they share letters, but because they appear in similar contexts across the vast corpus of text used to train the embedding model.

This contextual understanding is what makes vector embeddings so powerful for AI agents. When a user asks your agent about "troubleshooting connection issues", the system doesn't just look for documents containing those exact words. Instead, it finds content about "network problems", "connectivity failures", or "debugging communication errors"—all of which occupy nearby regions in the embedding space despite using completely different terminology.

This fundamental shift from storing data to storing meaning changes everything about how you interact with the database. Instead of asking "Find all documents with the exact phrase 'customer complaint'", you might ask something more nuanced like "Find content that expresses customer dissatisfaction or frustration". The vector database doesn't look for literal matches but rather searches for text that shares similar semantic space – content that means something similar, even if it uses completely different words.

Vector Store Performs Retrieval – Not Queries

During my work with Neuron AI ADK, I've seen countless developers struggle with this conceptual leap. They approach vector stores with SQL-like thinking, trying to create precise queries for exact matches, when the real power lies in the system's ability to understand and match meaning across different expressions of similar concepts. A customer might say "This product is terrible", "I'm not happy with my purchase", or "This didn’t meet my expectations", and a well-configured vector store will recognize these as semantically similar expressions of dissatisfaction, even though they share no common keywords.

The queries you perform against vector stores are fundamentally different beasts altogether. Rather than the precise, boolean logic of SQL where conditions are either true or false, vector queries operate in the realm of similarity and proximity. You're not asking “Does this record exactly match my criteria?” but rather "What stored information is most similar in meaning to what I’m looking for?" The database returns results ranked by their conceptual closeness to your query, opening up possibilities for discovery and connection that traditional databases simply cannot provide.

This semantic approach becomes particularly powerful when working with AI agents because it mirrors how human understanding actually works.

When someone asks your customer service agent about "billing issues", they might actually be referring to payment problems, invoice discrepancies, subscription concerns, or pricing confusion. A traditional database would require you to anticipate and explicitly map all these variations, but a vector store naturally understands the conceptual relationships between these different expressions of the same underlying concern.

This contextual awareness becomes the foundation for building AI agents that can understand not just what users are saying, but what they actually mean.

As we prepare to dive deeper into the internal mechanics of vector databases and the sophisticated algorithms that power their similarity searches, it's important to hold onto this fundamental understanding: you’re not just adopting a new type of database, you're embracing an entirely different paradigm for how information is stored, organized, and retrieved.

Vector Store Similarity Search

Understanding similarity search requires us to think about how machines can mathematically represent the concept of "closeness" between ideas. In traditional databases, we're accustomed to exact matches – either two values are identical or they’re not. But in the realm of vector databases, we’re dealing with degrees of similarity.

The actual search process operates through various distance metrics, with cosine similarity being perhaps the most intuitive to understand. Imagine each piece of text as a point in space, with the angle between any two points representing how similar their meanings are. When you perform a query, the system calculates these angles between your search vector and every stored vector, returning the ones with the smallest angles – essentially finding the content that points in the most similar semantic direction.

What makes this particularly powerful for AI agent development is how similarity search handles the messiness of human language. Traditional keyword search would miss the connection between "I can't access my account" and "login problems", but similarity search recognizes these as variations of the same underlying issue. The mathematical representation captures not just the words themselves, but the relationships, context, and intent behind them, allowing for discovery of relevant information even when the surface-level language is completely different.

The performance characteristics of similarity search also differ dramatically from traditional database queries. Instead of the binary speed of indexed lookups, you're dealing with computational complexity that scales with the size of your vector space and the dimensionality of your embeddings. This is where the sophisticated algorithms we'll explore next become crucial – techniques like approximate nearest neighbor search that make similarity search practical at scale while maintaining the semantic richness that makes vector databases so powerful for AI applications.

Performance Optimization Indexing Around Centroids

Vector stores clusters the index vectors according to their relative proximity. For each cluster, they then identify its centroid, the center of gravity of that cluster, a high-dimensional point minimizing the distance with every vector in the cluster.

We then structure the data on storage by placing each vector in a file named like the centroid it is closest to.

When processing a query, we then can then focus on relevant vectors by looking only in the centroid files closest to that query vector, effectively pruning the search space.

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

Conclusion

The journey from traditional web development to AI agent development requires more than just learning new syntax or frameworks – it demands a fundamental shift in how we think about data, search, and user interaction. Vector databases represent one of the most significant paradigm shifts in this transition, moving us away from the rigid precision of SQL queries toward the fluid, contextual understanding that mirrors human cognition.

If you're ready to put these concepts into practice, I encourage you to explore implementing your first Retrieval-Augmented Generation (RAG) system using Neuron AI ADK for PHP. The framework provides an accessible entry point for PHP developers to experiment with vector databases and semantic search without getting overwhelmed by the underlying complexity.

Create a RAG with Neuron AI: https://docs.neuron-ai.dev/rag