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.

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.

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

Create And Monitor AI Agents In Laravel - Video Tutorial

Valerio — Mon, 23 Jun 2025 15:58:36 +0000

In this tutorial I demonstrate how to develop and monitor an AI agent using Laravel and NeuronAI. The tutorial will guide you through the process of creating a YouTube video summary agent from scratch, explaining that NeuronAI was initially an internal project at Inspector.dev that was later released as an open-source solution to help the PHP ecosystem catch up with other technologies in AI Agents development. I show how to install the necessary packages, create an agent class, configure LLM providers like Anthropic, implement system instructions, and add tools for retrieving YouTube video transcriptions. Throughout the demonstration, it highlights how Inspector can monitor the agent's execution, providing visibility into each step and alerting developers to any errors in real-time. The tutorial concludes with a working example of an AI agent that can summarize YouTube videos, emphasizing the importance of starting small and monitoring behavior while gradually extending capabilities.

Three Key Takeaways:

NeuronAI makes it easy to integrate agentic components into existing PHP codebases, helping PHP developers catch up with AI capabilities available in other ecosystems.
Inspector provides real-time monitoring of AI agents, allowing developers to visualize execution steps, performance metrics, and receive immediate alerts for errors.
Building effective AI agents requires proper system instructions with clear role definition, step-by-step behavior guidance, and explicit output format specifications.

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:

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

Introducing Toolkits: Composable AI Agent Capabilities In PHP

Valerio — Fri, 20 Jun 2025 13:20:47 +0000

The philosophy behind Neuron's toolkit system emerged from a fundamental observation during AI Agents development: while individual tools provide specific capabilities, real-world AI agents often require coordinated sets of related functionalities. Rather than forcing developers to manually assemble collections of tools for common use cases, Neuron introduces toolkits as an abstraction layer that transforms how we think about agent capability composition.

The traditional approach requires instantiating each tool individually. Imagine you want to build agents that need mathematical reasoning – addition, subtraction, multiplication, division, and exponentiation tools must all be declared separately in the agent’s tool configuration. This granular approach quickly becomes unwieldy when agents require comprehensive functionality sets.

Toolkits represent Neuron's solution to this complexity, packaging tools created around the same scope into a single, coherent interface that can be attached to any agent with a single line of code.

Here is an example of the CalculatorToolkit:

namespace NeuronAI\Tools\Toolkits\Calculator;

use NeuronAI\Tools\Toolkits\AbstractToolkit;

class CalculatorToolkit extends AbstractToolkit
{
    public function guidelines(): ?string
    {
        return "This toolkit allows you to perform mathematical operations. You can also use this functions to solve
        mathematical expressions executing smaller operations step by step to calculate the final result.";
    }

    public function provide(): array
    {
        return [
            SumTool::make(),
            SubtractTool::make(),
            MultiplyTool::make(),
            DivideTool::make(),
            ExponentiateTool::make(),
        ];
    }
}

The AbstractToolkit base class establishes a consistent interface that all toolkits inherit, ensuring predictable behavior across the framework.

The guidelines() method provides contextual information that helps the underlying language model understand not just what tools are available, but how they should be used together. In the case of the CalculatorToolkit, the guidelines explicitly suggest that complex mathematical expressions can be solved through step-by-step operations, guiding the agent toward effective problem-solving strategies.

The provide() method returns the array of tools included in the toolkit by default. When a toolkit is attached to an agent, the individual tools become available exactly as if they had been added separately, but without the cognitive overhead of managing multiple tool declarations. Here is how you can add it to your agent:

<?php

namesoace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Calculator\CalculatorToolkit;

class MyAgent extens Agent
{
    ...

    public function tools(): array
    {
        return [
            CalculatorToolkit::make(),
        ];
    }
}

This approach maintains consistency with individual tool usage while providing the organizational benefits of grouped functionalities.

If you want to learn from a practical implementation read the article below about creating a Data Analyst Agent with the MySQLToolkit:

https://inspector.dev/mysql-ai-toolkit-bringing-intelligence-to-your-database-layer-in-php/

Exclude Tools

One of the most powerful aspects of Neuron's toolkit system is the selective exclusion capability. During development of complex agents, I’ve frequently encountered scenarios where a toolkit provides mostly the right functionality but includes tools that could lead to undesired behavior in specific contexts. The exclude() method addresses this challenge elegantly, allowing developers to exclude a subset of tools from the toolkit. This becomes particularly useful when working with specialized agents that require limited capabilities, so you can reduce the probability of an agent to make mistakes, and why not reduce tokens consumption.

<?php

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Calculator\CalculatorToolkit;
use NeuronAI\Tools\Toolkits\Calculator\DivideTool;
use NeuronAI\Tools\Toolkits\Calculator\ExponentiateTool;
use NeuronAI\Tools\Toolkits\Calculator\MultiplyTool;

class MyAgent extends Agent
{
    ...

    public function tools(): array
    {
        return [
            CalculatorToolkit::make()->exclude([
                DivideTool::class,
                ExponentiateTool::class,
                MultiplyTool::class,
            ]),
        ];
    }
}

The exclusion mechanism operates at the class level, using fully qualified class names to identify tools for removal. This selective approach eliminates the need to create custom toolkit variations for every possible combination of required tools.

Extensibility & Ecosystem Opportunity

From an extensibility perspective, the toolkit system opens remarkable opportunities for community contribution and ecosystem growth. The consistent interface means that third-party developers can create domain-specific toolkits that integrate seamlessly with Neuron’s architecture. A developer building agents for financial applications might create a FinancialToolkit that includes tools for currency conversion, interest calculation, and risk assessment. Similarly, a WebScrapingToolkit could package HTTP request tools, HTML parsing capabilities, and data extraction utilities into a single, reusable component.

The implications for development velocity are profound. In my experience building production agents with Neuron, the toolkit system reduces the cognitive load of capability management while maintaining the flexibility that professional development demands. Instead of researching and configuring multiple individual tools, developers can leverage pre-built, tested toolkit combinations that represent common functionality patterns. This approach accelerates the initial development phase while providing clear extension points for customization as requirements evolve.

The toolkit architecture also promotes better code organization and maintainability. Related tools naturally cluster together in the same namespace, making it easier to understand an agent’s capabilities at a glance. When debugging or extending agent behavior, developers can reason about functionality at the toolkit level before diving into individual tool implementations.

We know that production agents need reliable, well-tested combinations of capabilities rather than just single tools. By providing both the flexibility of individual tools and the convenience of pre-assembled toolkits, Neuron accommodates both rapid prototyping and sophisticated production deployments within a single, coherent architecture.

The future potential of this system extends beyond current implementations. As the Neuron ecosystem grows, community-contributed toolkits could emerge as specialized capability libraries, much like how package ecosystems have evolved in other domains. A marketplace of verified, tested toolkits could dramatically accelerate agent development across industries, with each toolkit representing accumulated expertise in specific problem domains. This is our vision of NeuronAI as a platform for shared AI capability development, positioning PHP developers at the forefront of business-grade AI agent development.

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:

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

How to Create a RAG Agent with Neuron AI PHP framework

Valerio — Tue, 10 Jun 2025 07:39:41 +0000

To be honest, when I first encountered the term "RAG", I felt like I was staring at a wall of technical jargon. You've probably heard a lot of buzzwords floating around the AI Agents topic: vector databases, embeddings, retrieval augmented generation. These concepts can feel overwhelming, especially when every tutorial assumes you already understand the fundamental building blocks. After spending countless hours building agents with NeuronAI ADK, I've learned that the real challenge isn't the implementation—it's grasping what these systems actually do and why they matter.

Let me start by demystifying what RAG actually stands for and why it's become the cornerstone of modern AI agent development.

Understanding the Foundation: What RAG Really Means

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

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

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

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

The Magic Behind Embeddings and Vector Spaces

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

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

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

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

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

Vector Databases: The Memory System Your Agent Needs

This brings us to vector databases, which serve as the memory system for your RAG agent. Traditional databases are excellent for structured data—names, dates, categories, transactions. But they struggle with the nuanced relationships between concepts and ideas. Vector databases are specifically designed to store these embedding vectors and perform lightning-fast similarity searches across millions of documents.

During my experience developing with Neuron ADK, I've seen how vector databases transform the user experience. Instead of agents that give generic responses or claim they don't have access to specific information, you get agents that can instantly access and synthesize information from your entire knowledge base. The agent doesn’t just know about general topics—it knows about your specific products, your company’s policies, your customer's history, and your unique business context.

The Challenge of RAG Implementation

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

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

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

Working with Neuron ADK has taught me that successful RAG implementation isn't just about understanding the individual components—it's about orchestrating them into a cohesive system that feels natural and intelligent to users. Neuron ADK handles many of the complex integration challenges, allowing developers to focus on the business logic and user experience rather than the underlying infrastructure.

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

Install NeuronAI

Install the latest version with the composer command below:

composer require inspector-apm/neuron-ai

Implement the first RAG Agent

To create your RAG agent you must extend the NeuronAI\RAG\RAG class, and attach the required components such as a vector store, and an embeddings provider along with the AI provider.

Here is an example of a RAG class:

<?php

namespace App\Neuron;

use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\RAG\Embeddings\EmbeddingsProviderInterface;
use NeuronAI\RAG\Embeddings\OpenAIEmbeddingProvider;
use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\FileVectoreStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

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

    protected function embeddings(): EmbeddingsProviderInterface
    {
        return new OpenAIEmbeddingProvider(
            key: 'OPENAI_API_KEY',
            model: 'OPENAI_MODEL'
        );
    }

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

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

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

You have plenty of options for each of these components, so feel free to explore the documentation to choose your preferred ones: https://docs.neuron-ai.dev/components/ai-provider

Feed Your RAG With A Knowledge Base

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

use NeuronAI\Chat\Messages\UserMessage;

$response = MyChatBot::make()
    ->answer(
        new UserMessage('How can I create an agent with Neuron AI ADK?.')
    );

echo $response->getContent();

// I don't really know specifically about Neuron ADK. Do you want to provide me 
// with additional information?

We need to feed the RAG with some knowledge to make it able to respond to questions about our specific needs.

Neuron AI Data Loader

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

Neuron gives you several tools (data loaders) to simplify this process. In order to answer the previous question (How can I create an AI Agent with Neuron ADK?) we can feed the rag with the README.md file of the Neuron composer package.

use NeuronAI\RAG\DataLoader\FileDataLoader;

MyChatBot::make()->addDocuments(
    // Use the file data loader component to process a text file
    FileDataLoader::for(__DIR__.'/README.md')->getDocuments()
);

Using the Neuron ADK you can create data loading pipelines with the benefits of unified interfaces to facilitate interactions between components, like embedding providers, vector stores, and file readers.

The code above must be implemented in a separated command and executed to make your chatbot able to answer questions about Neuron AI. You load text files, PDF, simple strings from a database and other sources. Explore the dedicated section in the documentation: https://docs.neuron-ai.dev/components/data-loader

After loading data into the RAG agent we can now send our question again:

use NeuronAI\Chat\Messages\UserMessage;

$response = MyChatBot::make()
    ->answer(
        new UserMessage('How can I create an agent with Neuron AI ADK?.')
    );

echo $response->getContent();

// Neuron is an ADK that simplifies the development of AI Agents in PHP. 
// Here is an example of how to implement an AI Agent using Neuron components...

Monitoring

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

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

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

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

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:

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

Moving Forward: From Theory to Practice

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

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

Create A Data Analyst Agent In PHP - NeuronAI MySQL Toolkit

Valerio — Fri, 06 Jun 2025 09:20:06 +0000

When I first began developing Neuron AI, I encountered the conceptual hurdle that trips up nearly every developer in their initial approach to AI agent development. Coming from years of building traditional web applications, where data flows predictably through controllers, models, and views, the notion of an AI agent that could autonomously interact with databases seemed almost unsettling.

The transition from writing explicit code that does exactly what you tell it to do, to creating agents that can reason about your data and take independent action, represents one of the most radical shifts in how we think about software architecture.

In classical web development, when a user wants to retrieve information from a database, we write specific routes, controllers, and queries that execute in a predetermined sequence. The flow is rigid, predictable, and entirely under our control. But AI agents operate on an entirely different paradigm: they analyze requests in natural language, determine what actions are necessary, and then dynamically select and execute the appropriate tools to accomplish their goals.

This different flow it's a bit hard to digest because it challenges our deeply ingrained assumptions about control and predictability in application development. During the early development of Neuron's MySQL toolkit, I spent a lot of hours wrestling with this fundamental tension. How do you maintain the reliability and security that production grade applications demand while simultaneously granting an AI agent the autonomy to make decisions about database operations? The answer lies in understanding that tools and function calls provide a structured way to extend an agent's capabilities while maintaining strict boundaries around what actions it can perform.

Spoiler: Talk To Your Database

Before exploring the technical details of the MySQL Toolkit I want to show you how you can create a data analyst agent in just a few lines of code. To play with this toolkit you obviously need a MySQL database. I created a script to create and populate a blog database as an example. You can execute it with php load_db.php: https://gist.github.com/ilvalerione/a2215a81b63ff3a41fe87a014141c1fb

Create the DataAnalystAgent with the MySQLToolkit:

<?php

namespace App\Neuron;

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

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

    public function instructions(): string 
    {
        return new SystemPrompt(
            background: ["You are a data analyst."],
        );
    }

    protected function tools(): array
    {
        return [
            ...MySQLToolkit::make(
                new \PDO("mysql:host=localhost;dbname=blog;charset=utf8mb4", 'root', '')
            )->tools();
        ];
    }
}

If your application is built on top of a framewrok you can easily get the PDO connecttion from the ORM. Here are a couple of examples in the context of Laravel or Symfony applications:

Laravel Eloquent ORM

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLToolkit;

class DataAnalystAgent extends Agent
{
    ...

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

Symfony and Doctrine ORM

Inject the database connection instance into your controller, and pass the PDO instance to the agent:

namespace App\Controller;

use App\Neuron\DataAnalystAgent;
use Doctrine\DBAL\Connection;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;

class YourController extends AbstractController
{
    public function someAction(Connection $connection): Response
    {
        // Get the underlying PDO instance
        $pdo = $connection->getNativeConnection();

        $response = DataAnalystAgent::make($pdo)->chat(...);

        return $response->getContent();
    }
}

The Agent will look like this:

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Tools\Toolkits\MySQL\MySQLToolkit;

class DataAnalystAgent extends Agent
{
    public function __construct(protected \PDO $pdo){}

    ...

    protected function tools(): array
    {
        return [
            ...MySQLToolkit::make($this->pdo)->tools(),
        ];
    }
}

More advanced Symfony users can configure the Agent itself as a service to automatically autowire the connection into the agent contructor.

Ask The DataAnalystAgent For A Report
Now we can ask the agent to generate a report. This a simple PHP script you can run in the terminal:

<?php

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

$response = DataAnalystAgent::make()->chat(
    new UserMessage("How many votes did the authors get in the last 14 days?");
);

echo $response->getContent();

The result will be something like:

If it sounds interesting enough I strongly recommend to follow the rest of the article to uncover all the development opportunities it can brings in your applications.

Tools & Function Calls In AI Agents

Function calling, at its core, represents the AI agent's ability to recognize when it needs to perform an action that goes beyond generating text. When a user asks an agent "How many active customers do we have this month?", the agent doesn't simply guess or hallucinate an answer. Instead, it recognizes that this question requires database access, identifies the appropriate tool from its available arsenal, constructs the necessary parameters, and executes a function call that retrieves real data from your system. This process transforms static language models into dynamic, interactive systems that can engage with live data and perform real-world tasks.

The MySQL toolkit in Neuron exemplifies this principle in practice. Rather than forcing developers to build custom integrations or write complex prompt engineering to handle database interactions, the toolkit provides three distinct tools that map directly to the fundamental operations any data-driven application requires.

The MySQLSchemaTool allows agents to understand the structure of your database, enabling them to construct intelligent queries without requiring you to hardcode table structures or relationships into prompts.

The MySQLSelectTool enables read operations, allowing agents to retrieve and analyze data in response to natural language queries.

The MySQLWriteTool extends this capability to modifications, enabling agents to insert, update, or delete records based on conversational instructions.

What makes this approach particularly powerful is how it preserves the separation of concerns that experienced developers value while dramatically expanding the interface through which users can interact with your applications.

The learning curve for developers often involves overcoming the instinct to micromanage every aspect of the agent's behavior. In traditional programming, we specify exactly which functions to call, in what order, with which parameters. With AI agents, we instead define the available tools and trust the agent to orchestrate their usage appropriately. This requires a fundamental shift in mindset from imperative programming to declarative capability definition. You're not writing step-by-step instructions; you’re defining a toolkit and letting the agent determine how to use it. Your prompt engineering skills are crucial not to make this process predictable, but reliable.

Throughout my work on Neuron, I've observed that developers who successfully make this transition begin to see AI agents not as unpredictable black boxes, but as sophisticated orchestrators that can coordinate multiple tools to accomplish complex tasks. The MySQL toolkit becomes more than just a database interface—it becomes part of a larger ecosystem where agents can seamlessly combine data retrieval, analysis, and modification with other capabilities like file processing, API calls, or external service integrations.

Neuron MySQL Toolkit In-Depth

All tools in the MySQL toolkit require a PDO instance as a constructor argument, which provides both flexibility and security in how you configure database access for your agents. If you’re working within a framework environment or already using an ORM, you can easily extract the underlying PDO instance from your existing database layer and pass it directly to the tools.

The PDO requirement also opens up strategic possibilities for controlling agent behavior. Since the PDO instance represents a connection to a specific database with specific credentials, you can create dedicated database users with precisely the permissions your agent needs. This approach allows you to implement fine-grained access control, potentially limiting agents to read-only operations on sensitive tables while granting full access to others. The toolkit recognizes this security consideration by providing separate tools for reading and writing operations, allowing you to selectively grant capabilities based on your confidence in the agent's behavior and the sensitivity of the operations.

MySQLSchemaTool

The MySQLSchemaTool serves as your agent's introduction to your database structure, providing detailed information about tables, columns, relationships, and constraints that enables the generation of precise and efficient queries. This tool essentially gives your agent the equivalent of a database administrator's understanding of your schema, allowing it to craft queries that respect your data model and take advantage of existing indexes and relationships.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;

class DataAnalystAgent extends Agent
{
    ...

    protected function tools(): array
    {
        return [
            MySQLSchemaTool::make(
                new \PDO("mysql:host=localhost;dbname=$dbname;charset=utf8mb4", $dbuser, $dbpass),
            ),
        ];
    }
}

The schema tool's real power emerges when you consider the alternative approaches to providing database context to AI agents. Without this tool, developers typically resort to embedding schema information directly in prompts or system messages, creating static descriptions that quickly become outdated as databases evolve. The MySQLSchemaTool dynamically retrieves current schema information, ensuring your agent always works with accurate, up-to-date database structure data.

For applications with large or complex databases, the tool accepts an optional second parameter that allows you to specify which tables should be included in the schema information passed to the language model. This capability proves invaluable for focusing agent attention on relevant data while reducing token usage and improving response times.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;

class DataAnalystAgent extends Agent
{
    ...

    protected function tools(): array
    {
        return [
            MySQLSchemaTool::make(
                new \PDO(...),
                ['users', 'categories', 'articles', 'tags']
            ),
        ];
    }
}

By limiting the schema scope, you can create specialized agents that focus on specific areas of your application. A content management agent might only need access to articles, categories, and tags, while a user administration agent requires visibility into users, roles, and permissions tables. This approach not only improves performance but also reduces the cognitive load on the language model, leading to more accurate and focused responses.

MySQLSelectTool: Querying with Natural Language

The MySQLSelectTool transforms how you can interact with your application's data by enabling natural language queries that automatically translate into appropriate SELECT statements. You can simply describe what information you need and let the agent construct the appropriate queries.

The select tool's implementation demonstrates the sophisticated reasoning capabilities that modern language models bring to database interactions. When a user asks "Show me all articles published this month by authors from Italy", the agent must understand temporal references, join relationships between articles and authors, and construct appropriate WHERE clauses. The tool handles these complexities automatically, generating optimized queries that leverage your database's indexing strategy and relationship structure.

namespace App\Neuron;

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

class DataAnalystAgent extends Agent
{
    ...

    protected function tools(): array
    {
        return [
            MySQLSchemaTool::make(new \PDO(...)),
            MySQLSelectTool::make(new \PDO(...)),
        ];
    }
}

This capability proves particularly valuable for business intelligence and reporting scenarios where you need to explore data without technical expertise. Sales managers can ask for "revenue trends by region over the last quarter", content editors can request "the most popular articles in the technology category", and customer service representatives can find "all support tickets from premium customers in the last week". Each of these requests gets translated into precise SQL queries without requiring previous understanding of table structures, join syntax, or date functions.

MySQLWriteTool: Enabling Data Modifications Through Conversation

The MySQLWriteTool extends agent capabilities to include INSERT, UPDATE, and DELETE operations, enabling applications to accept natural language instructions for data modifications. This tool represents the most powerful—and potentially sensitive—capability in the MySQL toolkit, allowing agents to make permanent changes to your database based on conversational input.

Remember to take in consideration to limiting the tables your agent will be able to interact with using the tables property in the MySQLSchemaTool.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLWriteTool;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;

class DataAnalystAgent extends Agent
{
    ...

    protected function tools(): array
    {
        return [
            MySQLSchemaTool::make(new \PDO(...)),
            MySQLWriteTool::make(new \PDO(...)),
        ];
    }
}

The separation between read and write tools allows for graduated trust models in agent deployment. Applications can begin by deploying agents with only schema and select capabilities, allowing users to explore and analyze data safely. As you continue to monitor the agentic flow, and confidence in agent behavior grows, write capabilities can be selectively enabled for specific operations or user roles.

The Path vs Intelligent Applications With Neuron AI

An agent equipped with database tools, file processing capabilities, and external API access can handle complex workflows that previously required custom development. A content management agent might retrieve article data from the database, generate summaries using language model capabilities, update publication status based on editorial guidelines, and notify stakeholders through external communication tools—all from a single conversational interface.

The implications for PHP developers are particularly significant because this capability comes from within the ecosystem they already know and trust.

Production-Grade Monitoring

When I first demonstrated an early version of a database-connected agent to a customer, their initial excitement quickly turned to concern. "This is impressive", the CTO said, "but how do I know what it's actually doing? How do I debug when something goes wrong? How do I optimize performance when my database queries start timing out?".

Traditional web applications have mature monitoring ecosystems precisely because developers learned that you cannot reliably operate what you cannot observe. AI agents, with their dynamic decision-making and autonomous tool usage, amplify this need exponentially. When an agent constructs a database query based on natural language input, the query’s performance characteristics, execution plan, and resource consumption become critical operational metrics.

This integration represents exactly why Neuron emerged from Inspector. The MySQL toolkit isn't just a set of database tools—it's a production-ready system with the observability infrastructure that modern businesses require to trust autonomous systems with their critical data operations.

Here is an example of how you can see the agent execution flow using the MySQL toolkit and Inspector:

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:

MySQL Toolkit Doc: https://docs.neuron-ai.dev/tools-and-function-calls#mysql
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