4.0.0
Neuron 4
Upgrading with your coding agent
The repository ships with an upgrade directory containing a step by step plan written for your AI coding assistant.
A reengineered Workflow engine
The internal Workflow engine was rebuilt from the ground up to simplify the public API. V3 exposed too much of the machinery needed to control an execution. It worked, but it made developers feel a complexity that a better framework design can remove. In V4, running an agent, handling a tool approval, and resuming it are short, readable operations.
This will be beneficial not only for products development but also for integrating Neuron in custom architectures.
Performance
Streaming is faster and more predictable, and if your application depends on it you should upgrade as soon as you can.
We conducted an extensive review of the internal engine to remove every source of performance degradation we could find, and several bugs and bottlenecks in the streaming system were fixed along the way. I also removed Guzzle as a dependency. The deault HTTP client is a low level implementation using the PHP ext-curl that maximize perormance.
UI protocols
UI protocol integration was extended to support the rendering of custom events and human-in-the-loop automatically.
We believe the frontend integration is critical for the ecosystem to connect agentic entities to the user interface as easily as possible. Neuron already provides the best-in-class support for frontend communication. However, certain architectural limitations in v3 make the full implementation of some protocols difficult.
The frontend community is expanding rapidly, and user experience cannot stay in the background. In V4 the streaming adapter system moves out of the Agent and becomes part of the underlying Workflow architecture, which is what gives adapters like AG-UI and Vercel AI protocols, access to the full execution lifecycle of the framework, including approval events, interruptions, errors.
Streaming Channels
Your agent can run in a background worker and still stream its response to the browser in real time.
As Agents become more interactive and capable, application developers are increasingly forced to run them outside the HTTP request lifecycle because of its timeout limits, which leaves the streamed output with no way to reach the UI.
V4 introduces Streaming Channels, a component to deliver the streamed output of Agents and Workflows to the user interface through external real-time streaming systems such as Pusher, websockets, a Redis queue, or whatever your application already uses. Backed by its own interface, customizable and extendable.
Built-in channels
- Redis pub/sub Channel
- Pusher and Pusher compatible channel
Chat History
Chat history has undergone a major refactor to achieve two goals:
- Separate the message store from the history and context window management
- Making Neuron integration in your application easier
ChatHisotryInterface was removed. The new public APIs are backed by the new MessageStoreInterface. As the name says, the message store is responsible only for storing your messages in a persistence layer. It marks messages that fall out of the context window as archived instead of deleting them, so the model sees a trimmed thread while your storage keeps the full history.
Long-term memory
Your agent can now remember what matters to a person across multiple conversations. Users with multiple active threads can see the agent remember their past conversations and preferences.
V4 introduces the SemanticMemoryRetrieval component, which automatically stores and recalls memories across user sessions. It belongs to the RAG agent can be customized or replaced to fit your application logic.
Observability
Neuron now emits its events through a standard PSR-14 event dispatcher, so it connects natively with the dispatcher architecture your application probably already use, whether Symfony, Laravel, or other framework. The PHP-native observer system was deprecated in favor of this interface. More interoperability, more freedom to build.
In the same spirit, Inspector is no longer a dependency of the framework. Inspector is the company that funds this work and pays my salary, and until V3 its monitoring client shipped inside Neuron by default. It doesn't anymore. Observability is a choice you make with the tools you trust.
Tools and Toolkits
The Tool class is now abstract and can no longer be used directly. Its design is now intended to be extendable, allowing you to implement your own tools with less code and more flexibility.
New CalculatorToolkit
Single math op were remove in favor of a single evaluate tool. This implementation consume a lot less tokens and makes the model able to performs complex mathematical calculations in one shot.
Tool input casting
Tool inputs are now cast to their declared property types. So a number the model sends as "5" or 5.0 arrives as an int, and a value that cannot be converted comes back to the model as a ToolOutput::error() naming the parameter and the expected type instead of aborting the run with a TypeError. This drastically reduce tool errors just for casting mismatch, and improve tool call reliability.
Tool Approval
The tool approval flow was entirely rewritten. The ToolApproval middleware has been removed. The Agent now manages the entire process. You just need to take care of rendering the UI so users can decide whether to approve or reject a tool call.
The status of tools requiring approval is stored into the chat history within the last ToolCallMessage. This allows you to design the UI to just render the messages in the chat history, and when it meets a ToolCallMessage you can check the approval status of the tools to show the Approve/Deny actions, or the normal tool call already happened.
This feature ships with AG-UI and Vercel AI support already built-in.
Frontend Tools
Until now a tool was a single thing: a representation of a PHP function the model can ask to run and the backend executes. FrontendTool allows you to define tools that will be executed by the frontend of your application. Once complted they will sent back the result of the tool execution, and Neuron will provide this result to the model continuing the loop.
This is how backend agents can get access to the browser APIs, or the device capabailities in a mobile app, transparently.
FrontendTool makes this a first-class concept in Neuron. The model sees it and can call it, but the backend never executes it. When the model calls a frontend tool, the agent suspends the run, hands the pending calls to you, and continues from exactly that point once you submit the results.
Updated MCP protocol version
The MCP client now speaks protocol revision 2025-11-25, forwarding the version negotiated during initialize as the MCP-Protocol-Version header on every Streamable HTTP request.
Bugs & Security Fixes
- fix use read-only transactions in database toolkits
- fixed cypher injection in Neo4j component
- fix SSRF in TokenCounter
- fix OpenAI providers stream ending
- fix URL construction in OpenAI child classes
- fix RAG reindex process consistency
- fix Mistral tool call when reasoning
- fix Ollama messages mapping lose tool calls
- fix Tool ObjectProperty cast
- fix BashTool output overflow
- fix tool visibility inside a toolkit
- fix Structured output deserializer to write only public properties
- fix curl http client accepting non-URL address
- fix curl http client silently send empty body
- fix curl http client silently redirect
- fix curl http client accepting headers with line breaks
- feat FileVectorStore support concurrency
- fix FileVectorStore avoid corruption if documents fail json encoding
- fix FileVectorStore and FileMessageStore name pointing outside the directory
- fix Tool consistency in property recognition
- fix structured output validation rules check and feedback message
- fix structured output validation rules on nested objects
- fix MCP client error propagation
- fix MCP StdioTransport security issue when run local commands
- fix local MCP server receive full application env variables
- feat MCP tool call support multimodality
- fix Evaluation Trajecotry output
- fix Evaluation tool approval simulation
- fix Evaluation to support "maxDistance: 0" in StringDistance
- fix providers handling broken tool call arguments
- fix Vertex providers authentication
- fix Gemini provider for missing fields in response
- feat Audio and Image providers stream base64 content as concrete resource
- fix OpenAIResponses to report tool call text part
- fix Mistral reasoning content
- fix providers report stop reason when streaming
- fix extension association in file readers
- fix toolkit guideline injection in instructions
Upgrading with your coding agent
The repository ships with an upgrade directory containing a step by step plan written for your AI coding assistant.