Upgrade
Upgrade to v3 from v2
This new major version was required because even if the public APIs of Neuron components weren't changed dramatically (we minimized the impact keeping the same public APIs as much as possible), the underlying design of Agent, RAG, and the Message system were completely rebuilt on top of the Workflow component that now powers the entire framework.
Such a profound change can't be released without a major version. But it comes for a good reason. Now that Agent and RAG are also workflows they inherit increadible features that were impossible to integrate in the previous standalone implementation, like:
Native support for tool approval and human in the loop
Automatic conversation summarization for better context management
Extensibility and hooks provided by the new middleware layer integrated into the Workflow itself and inherited by Agent and RAG.
We also took advantage of this release to fix other critical design issues emerged in the last release to have more freedom to improve the framework with less breaking changes in the future.
We continue to work to provide the best possible developer experience, to help you create successful AI products in PHP.
Updating Dependencies
You should update the following dependencies in your application's composer.json file:
neuron-core/neuron-ai to ^3.0
High Impact Changes
New Agent namespace
The Agent class and related classes and traits have been moved from the root directory under the dedicated namespace NeuronAI\Agent.
You need to update the namespace in the files where you use the Agent class, from:
use NeuronAI\Agent;To:
use NeuronAI\Agent\Agent;The same for the SystemPrompt class. The new namespace is NeuronAI\Agent\SystemPrompt.
Remove chatAsync()
The chatAsync() method was completely removed from the AgentInterface. If you are using this method in your application you have to switch to the synchronous chat() method. You can eventually parallelize multiple LLM calls using background job processing systems, like Laravel Queue, or Symfony Messenger.
Workflow Interrupt
In the previous version when you asked for an interrupt inside a Node you could pass an array of data to inform the client about the reason and the actions behind the interruption.
$feedback = $this->interrupt(['message' => 'do you want to approve?']);This lazy typed method led to inconsistencies and errors. We introduced the InterruptRequest object to help you create interrutpion flows with a typed structure you can serialize for later use.
$feedback = $this->interrupt(new InterruptRequest(
reason: 'Do you want to approve?',
actions: [
new Action(...)
]
));Learn more in the dedicated section of the documentation.
Message Content Blocks
The content blocks now replace the old approach based on "attachments". The legacy attachment system has been removed. To migrate:
Old Approach (removed):
$message = new UserMessage('Analyze this');
$message->addAttachment(new Image($url, AttachmentContentType::URL));New Approach:
// Simple text message (backward compatible)
$message = new UserMessage("Hi");
// New format for passing images, files, etc.
$message = new UserMessage([
new TextBlock('Analyze this'),
new ImageBlock($url, SourceType::URL)
]);The method getContent() didn't change, but now returns all text blocks concatenated, so you can continue to use it without changing anything in your app.
Streaming Chunks
In previous versions the streaming interface will return simple string for LLM response chunk, and ToolCallMessage, or ToolCallResultMessage instances directly for tool related operations. This creates too direct a coupling between the message instances and the client reading the stream.
We implemented dedicated chunk classes StreamChunk, ToolCallChunk, ToolResultChunk, in order to have dedicated containers for each kind of stream delta so we can continue to improve this layer in the future without affecting the chat message components.
Medium Impact
Monitoring & Observers
Agent, RAG, and Workflow entities no longer implement the PHP \SplSubject interface, and the observer classes no longer implement the \SplObserver interface. We introduced the new ObserverInterface that must be implemented only by event listeners like LogObserver. This lighter structure helped us to make the workflow building blocks observable like Workflow, node, and middleware. This means you can emit events from your custom node as built-in feature, and you only need to create and register your custom observer to listen for these events.
Read more on the Monitoring section.
Qdrant 1.10.x
The Qdrant vector store components was updated to support the new query APIs that are included starting from the version 1.10.x. If you use a previous version of the Qdrant database you need to upgrade your instance.
Last updated