fix toolkits guidelines and guidelines cache

• fix: Anthrpic cache control
• fix: OpenAI and OpenAIResponses cache breakpoint
• feat: place RAG retrieved documents in the last user message as ephemeral contents
• fix: system instructions cache
• feat: new agent context() method to defer the injection of changing system instructions.

• fix anthropic on vertex ignoring custom parameters;
• fix: make vertex providers ully lazy;
• fix: make vector stores lazy initializing collections at execution time: Chroma, MeiliSearch, File, MongoDB, Qdrant, Weviate;
• feat: New "add()" method in Toolkit to add new tools at runtime;
• fix: rector configuration;
• feat: New Mercure streaming channel;

• fix: AGUIInputTranslator treats an empty resume: [] as a resume, so a frontend-tool result is rejected with 400.
• fix: make:* reads only autoload.psr-4, which breaks neuron-evaluation's autoload-dev layout.
• fix: bin/neuron ignores Composer's _composer_autoload_path.
• fix: EvaluatorRunner doesn't check for ext-posix, and without it forked children close the parent's database connection.

• Dependabot
• Fix AG-UI 1.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.

Upgrade Guide

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.

Generative UI Demo

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

Documentation

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.

Documentation

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.

Documentation

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.

Documentation

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.

Upgrade Guide

• Fix MCP stdio transport PR #673 by @SmoKE585
• Fix stream reasoning chunks in ZAI provider PR #668 by @simPod
• Fix function call is missing thought_signature in Gemini provider

New Classifier component interface with TypeSafeAI as the first concrete implementation: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Classifier/README.md

• Fix adding new messages on SQL Chat history after calling flushAll()
• Fiz Summarization middleware to preserve user-assistant pairs and tool call pairs

Fix usage check in OpenAI audio providers.

Allow initializing resources in parallel tool children safely- #650 by @SmoKE585

Improve agent state hooks

Fix anthropic redacted reasoning management. Inspired by @emaferr90 in PR #648

Fix skills to not mention obsolete models. Includes PR #646 from @kasparovabi

Fix Structured Output flow when the AI response has no content. PR #644 by @emaferr90

Fix AWS Bedrock streaming with reasoning. Close #643

Fix overlap in text splitters

• Revert support for Guzzle 8
• Default observer now accept ObserverInterface - PR #637 by @jremmurd

MediaType enum

This release introduces the MediaType enum to make it easier to define media type of content blocks acriss the framework:

use NeuronAI\Chat\Enum\MediaType;

$message->addContent(
    new ImageContent(
        source: 'https://placehold.co/600x400/EEE/31343C',
        sourceType: SourceType::URL,
        mediaType: MediaType::PNG
    )
);

Improve Chat History Consistency

This release fixes an issue where chat history would get stuck in an inconsistent state if the http request against the provider API fails.

Now the agent store the incoming user message in the chat hisotry after the http request, so it will be sure to save the pair user-assistant always consistent.

Fix Tool Approval bug report: GHSA-8xhf-px34-f9q5

• Fix workflow DatabasePersistence to work with Postgre and SQLite
• Add --autoload-file option to neuron cli - PR #632 by @bytestream
• Allow JSON-safe metadata types in RAG Document - PR #631 by @bytestream

Parallel Evaluations

This release ships the support or running your evaluations suite in parallel.

vendor/bin/neuron evaluations --concurrency=3 --path=evaluators

You only have to take care o how many concurrent connections your providers allows you to run.

Code fixes and performance improvements by @Denitz

• #617
• #618
• #619
• #620
• #621
• #623
• #624
• #625
• #626
• #627

Fix OpenAI providers on structured output strict mode

Fix rerankers to get a string query.