升级

从 v2 升级到 v3

在这个新的重大版本中，Neuron 组件的公开 API 并没有发生剧烈变化（我们尽可能将影响降到最低），但 Agent、RAG 和消息系统的底层架构已经基于 Workflow 组件完全重建，而现在整个框架都由它驱动。

现在 Agent 和 RAG 不再是简单对象，而是工作流。它们继承了在之前独立实现中无法集成的功能，例如：

• 统一的 消息系统 用于多模态智能体

• 原生支持 工具审批 以及完全可自定义的人在回路流程

• 多智能体 流式 与协作。

我们还借此版本修复了 v2 中出现的其他关键设计问题，例如 对所有提供方的推理模型提供完整支持，以及其他设计改进，使我们能够以更少的破坏性变更在未来更自由地演进框架。

我们将继续努力提供尽可能好的开发者体验，帮助你用 PHP 创建成功的 AI 产品。

更新依赖

你应该更新应用程序中的以下依赖项 composer.json 文件：

• neuron-core/neuron-ai 为 ^3.0

高影响变更

新的 Agent 命名空间

Agent 类及相关类和 trait 已从根目录移至专用命名空间 NeuronAI\Agent.

你需要在使用 Agent 类的文件中更新命名空间，从：

use NeuronAI\Agent;

到：

use NeuronAI\Agent\Agent;

SystemPrompt 类也一样。新的命名空间是 NeuronAI\Agent\SystemPrompt.

移除 chatAsync()

该 chatAsync() 方法已从 AgentInterface中完全移除。如果你在应用程序中使用了此方法，你必须切换到新的异步模式。

了解异步

Agent 返回类型

由于 Agent 现在是一个工作流，你需要使用略有不同的 API 来真正运行 agent 并获取 LLM 响应。

以前你会直接从 chat() 方法中获得一个 Message 实例。现在 chat 方法返回一个工作流状态，你可以用它来获取最终的 agent 响应。

返回的 agent 状态让你可以轻松访问 LLM 响应，同时也可以检查 agent 内部执行的其他方面。下面是运行 agent 并输出 LLM 生成内容的新语法示例。

// 旧版本的 chat() 返回 LLM 响应
$message = MyAgent::make()->chat(new UserMessage("Hi, who are you?"));

// V3 - 你需要调用 "getMessage()"
$message = MyAgent::make()
    ->chat(new UserMessage("Hi, who are you?"))
    ->getMessage();

echo $message->getContent();

消息内容块

内容块现在取代了基于“附件”的旧方案。旧的附件系统已被移除。迁移方式：

旧方案 （不再可用）：

$message = new UserMessage('Analyze this');
$message->addAttachment(new Image($url, AttachmentContentType::URL));

新方案:

// 简单文本消息（向后兼容）
$message = new UserMessage("Hi");

// 传递图片、文件等的新格式
$message = new UserMessage([
    new TextBlock('分析这个'),
    new ImageBlock($url, SourceType::URL)
]);

// 添加更多块
$message->addContent(
    new TextBlock('记得以专业礼宾的身份回答。')
);

// 打印所有文本内容块
echo $message->getContent();

该方法 getContent() 没有变化，但现在会返回所有文本块拼接后的结果，并跳过媒体类型。

块的组合解锁了多模态支持，如果你需要在执行过程中动态注入额外提示或指令，这会非常有帮助。

了解消息

流式分块

在之前的版本中，流式接口会为 LLM 响应分块返回简单字符串，以及 ToolCallMessage，或者 ToolCallResultMessage 实例直接用于工具相关操作。这会让消息实例与你的应用读取流之间耦合得过于紧密。

我们实现了专用的分块类 TextChunk, ReasoningChunk, ToolCallChunk, ToolResultChunk等，以便为每种流增量提供专门的容器。这样更清晰的职责分离，为 适配器系统的实现打开了大门，并让我们在未来以更少的破坏性变更改进这一层，同时保持统一消息系统的稳定。

ToolCallChunk

在上一版本中，Neuron 直接流式输出 ToolCallMessage 包含本次迭代中涉及工具列表的实例。现在你会得到一个专用的 ToolCallChunk 用于模型请求执行的每个工具。

阅读更多关于流式传输的信息

结构化输出

我们扩展了 SchemaProperty 属性的角色，使其成为类属性 JSON schema 定义的真实来源。它现在支持 最小值, 最大值, 最小长度, 最大长度, anyOf.

use NeuronAI\StructuredOutput\SchemaProperty;

class Person 
{
    #[SchemaProperty(
        description: '用户名称。',
        required: true,
        minLength: 3,
        maxLength: 255,
    )]
    public string $name;
    
    #[SchemaProperty(
        description: '用户喜欢吃什么。', 
        required: false,
        min: 18,
        max: 64,
    )]
    public ?int $age = null;
}

对象数组

如果某个属性是结构化对象数组，你不再需要指定该属性类型的 doc-block，只需在 anyOf 参数：

class Report
{
    #[SchemaProperty(
        description: '报告内容。', 
        required: true,
        anyOf: [TextBlock::class, TableBlock::class, ImageBlock::class]
    )]
    public array $content;
}

结构化输出

工作流中断请求（人在回路）

在上一版本中，当你在 Node 内请求中断时，可以传递一个数据数组，向客户端说明中断的原因和背后的操作。

旧语法

$feedback = $this->interrupt(['message' => 'do you want to approve?']);

这种懒类型方法导致了不一致和错误。我们引入了 InterruptRequest 原语，帮助你使用带类型结构创建中断流程，以便安全地集成到 UI 中。

新语法

$feedback = $this->interrupt(new ApprovalRequest(
    reason: 'Do you want to approve?',
    actions: [
        new Action(...)
    ]
));

在文档的专门章节中了解更多。

工作流中断

工作流数据库持久化变更

工作流持久化数据库表的列名已更改：

• data -> interrupt

工作流持久化

中等影响

重命名 ToolCallResultMessage

该类已重命名为 ToolResultMessage.

监控与观察者

Agent、RAG 和 Workflow 实体不再实现 PHP \SplSubject 接口，而观察者类也不再实现 \SplObserver 接口。我们引入了新的 ObserverInterface ，它只需由诸如 LogObserver这样的事件监听器实现。这个更轻量的结构帮助我们使 Workflow、node 和 middleware 等工作流构建块具备可观察性。这意味着你可以从自定义节点发出事件，只需创建并注册自定义观察者来监听这些事件即可。

阅读 监控部分.

移除 HttpClientOptions

该类已被移除，转而采用框架内对 HttpClient 的完整抽象。我们采用了适配器模式，让你可以将自定义 http 客户端注入框架组件，并自定义其配置。Guzzle 客户端适配器还支持 handler stack、自定义头等。

你可以在 异步 部分。

Qdrant 1.10.x

Qdrant 向量存储组件已更新，以支持从 1.10.x 版本开始包含的新的 查询 API 。如果你使用的是旧版本的 Qdrant 数据库，则需要升级你的实例。

AbstractChatHistory 方法签名

如果你实现了自定义聊天历史组件，你需要调整这些钩子方法的签名。它们的可见性级别已从 public 改为 protected，并且不再有返回类型：

class MyChatHistory extends AbstractChatHistory
{
    protected function setMessages(array $messages): void
    {
        // 一次性处理保存整个历史记录。
    }

    protected function onNewMessage(Message $message): void
    {
        // 处理单条消息的添加。
    }

    protected function onTrimHistory(int $index): void
    {
        // 当触发裁剪时，位置从 0 到 $index 的消息必须被移除。
    }

    protected function clear(): void
    {
        // 移除所有消息。
    }
}

新功能

工具审批与条件审批

得益于底层工作流架构支持的人在回路模式，我们创建了一个内置中间件，使你可以像即插即用的功能一样在智能体中启用工具审批：

new ToolApproval(
    tools: [
        BuyTicketTool::class => function (array $args): bool {
            return $args['amount'] > 100;
        }
    ]
)

工具审批

Mistral 专用提供方

Mistral 提供方不再是纯粹的 OpenAI 实现，而是演进为拥有自己的 API 格式实现，以支持多模态输入和推理模型。

Mistral AI 提供方

Cohere AI 提供方

此版本附带一个全新的提供方，用于支持 Cohere 推理平台的云端和私有部署。

Cohere AI 提供方

文本转语音提供方

得益于消息的新块组合方式，现在可以轻松处理输入和输出多模态。在此版本中，我们加入了几个可用于处理音频内容的提供方。

文本转语音提供方

流式适配器

适配器充当 Neuron 内部流式事件（文本分块、工具调用、推理步骤）与特定前端协议之间的转换器，例如 Vercel AI SDK、AG-UI，或你的自定义前端需求。

这种架构使你无需修改核心智能体逻辑，就能将 Neuron 智能体无缝集成到各种前端框架（React、Vue 等）中。

了解更多关于适配器的信息

文件 ID 内容块

通常你可以通过 URL 或 base64 编码格式，将文件（图片或文档）附加到消息中。许多提供方允许你在其平台上一次性上传文件，然后在消息中用简单的 ID 引用这些文件。这可以大幅节省 token 消耗，并提高模型响应时间。

在从提供商平台收到文件 ID 后，你可以使用以下方式向消息添加文件块 SourceType::ID.

// 引用之前在提供商平台上上传的文件 ID
$message = new UserMessage([
    new TextBlock('分析这个'),
    new FileBlock("file_id_xxxx", SourceType::ID)
]);

基于你的提供方规格，你对 Image、Video 等也可以采用相同方式。

中间件

中间件提供了一种严格控制工作流内部发生内容的方法，因此也适用于你的 Agent 和 RAG，因为它们现在也都是工作流。

核心的工作流执行涉及根据其他节点返回的事件来调用节点。中间件暴露出钩子，以便在执行过程中介入 之前 和 之后 节点的执行：

此架构已被用于创建 内置中间件 ，适用于 Agent 类，例如上下文摘要或工具审批。

了解更多关于中间件的信息