Framework Neuron-AI 面向该语言生态的智能体框架

一、项目介绍

PHP 团队想上 AI 智能体，处境有点尴尬：现成的框架几乎都在 Python 生态，而 PHP 侧要么自己在 HTTP 客户端上手搓循环、工具调用与 RAG，要么硬把服务拆出去，中间那层胶水代码越写越多。Neuron 就是为 PHP 补上这一块。

它是一个面向 AI 智能体创建与编排的 PHP 框架，提供从 LLM 接口、数据加载、多智能体编排到监控与调试的完整工具链。文档把每项能力都做成了独立章节：事件驱动的工作流与检查点、人在回路、中断与恢复、流式输出、AG-UI 与 Vercel AI SDK 之类的界面协议集成、MCP 连接器、异步执行。

它强调"一套代码贯穿始终"——入门教程里跑起来的那个工作流，到生产环境能直接跑带状态、带回环和多智能体协作的系统，不用等规模变大再换框架。当前版本 4.1.17，MIT 协议。

PHP 生态长期缺一块 AI 拼图，这正是 Neuron 出现的背景。它的思路不是把 Python 生态硬搬过来，而是用 PHP 开发者熟悉的方式重建这些能力：Composer 管理依赖，vendor/bin/neuron make:agent 生成脚手架，框架提供的 Agent 基类自动接管记忆、工具与 RAG 这些横切能力。

它把智能体应用开发拆成了若干可独立学习的章节，每个能力对应一类真实需求。事件驱动的工作流与检查点解决长任务中断后如何续跑；人在回路解决关键决策必须有人确认的场景；中断与恢复让流程可以安全挂起；流式输出与 AG-UI、Vercel AI SDK 之类的界面协议集成，解决前端如何实时消费 Agent 的响应；MCP 连接器让已有的 MCP 工具服务可以直接复用；异步执行避免长任务阻塞请求线程。

"入门与生产同一套 API"是它文档里反复强调的一点。入门指南里跑起来的工作流，到生产环境能直接跑带状态、带回环和多智能体协作的系统——这意味着团队不用在项目长大之后被迫换框架、重学一遍 API，也不用担心两套代码行为不一致。

它还提供监控与调试工具，让智能体的运行过程可观测，这在生产环境里是刚需而非加分项。

二、项目基本信息

三、核心优势

• Composer 一条命令安装，是 PHP 生态里少数成体系的智能体框架
• 覆盖事件驱动工作流、检查点、人在回路、中断恢复等生产必需能力
• 原生支持流式输出，并可对接 AG-UI、Vercel AI SDK 等界面协议
• 内置 MCP 连接器与异步执行，不必自己再拼一层
• 配套监控与调试工具，智能体的运行状况可观测
• 入门与生产用同一套 Workflow API，不需要二次学习
• 官方提供视频教程与文档，PHP 开发者上手路径清晰
• Agent 基类自动接管记忆、工具与 RAG，子类只需关注业务逻辑
• 内置 MCP 连接器，可直接复用已有的 MCP 工具服务而不必重写适配层
• 提供监控与调试工具，智能体的执行过程与工具调用可追踪
• 官方提供视频教程与文档示例，PHP 开发者有较完整的学习路径

四、适用场景

适合以 PHP / Laravel 为主的技术栈、需要在现有应用中引入 AI 智能体能力的团队；也适合不希望为了 AI 而把服务拆到另一套技术栈的组织。

最直接的适用前提是：你的技术栈是 PHP，且不希望为了加 AI 功能就把服务拆成两套技术栈。如果团队本来就是 Python 主力，Neuron 未必是最佳选择。

第二个判断维度是应用形态。如果你要做的是"给现有 PHP 应用加一个能对话的助手"，Neuron 的渐进式接入很合适；如果要做的是多智能体协作平台，它提供的能力也够，但要先评估你团队对工作流、检查点这类概念的接受度。

上手路径建议按文档章节走：先跑通最小 Agent，再依次接工具、工作流、人在回路，最后上监控。官方还准备了视频教程，PHP 开发者可以更快建立整体印象。

工程上要注意依赖管理：它发布在 Packagist，用 Composer 安装，版本跟随语义化版本约定。生产环境建议锁定版本，并把模型密钥放到环境变量而不是提交进仓库。

如果你正被同类问题反复绊住——要么是人肉重复劳动没完，要么是工具装不上跑不通、要么是产出的结果根本没法用——那这个项目值得先花十分钟装一遍试试。

五、安装教程

当前最新版本 4.1.17。下面是可直接执行的安装方式：

# 在 PHP 项目中安装
composer require neuron-core/neuron-ai

# 生成一个 Agent 骨架
vendor/bin/neuron make:agent DataAnalystAgent

# 本地跑测试（Docker 方式）
docker compose run --rm php composer update --prefer-stable
docker compose run --rm php vendor/bin/phpunit

# 停止全部服务
docker compose down

常见报错与处理：依赖缺失时先确认运行时版本（Node、Python、Rust、PHP 等）是否满足项目要求；网络超时多半是镜像或代理问题，可换源重试；权限类报错请检查当前账号是否已登录对应平台，以及脚本是否需要管理员权限执行。

六、使用示例

下面这段是可以直接参照的真实用法：

<?php

namespace App\\Neuron;

use Neuron\\Core\\Agent;
use Neuron\\Core\\Tool\\Attributes\\Tool;

class DataAnalystAgent extends Agent
{
    protected string $systemPrompt = '你是一名数据分析助手，负责读取表格并给出结论。';

    #[Tool('统计某个数据表的总行数')]
    public function countRows(string $table): int
    {
        // 你的业务逻辑
        return 0;
    }
}

// 在应用里直接使用
$agent = new DataAnalystAgent();
$response = $agent->run('帮我统计 orders 表的行数');
echo $response->getContent();

七、常见问题

问：必须用 Python 侧的服务吗？答：不需要，Neuron 是纯 PHP 框架，直接运行在现有 PHP 应用里。

问：流式输出怎么接？答：框架提供 stream adapters，可以把智能体的流式响应直接对接 AG-UI、Vercel AI SDK 等界面协议。

问：怎样做到人在回路？答：工作流支持中断与恢复，可以在关键节点暂停、等待人工审批后再继续执行。

问：怎么接 MCP？答：框架内置 MCP 连接器，可直接复用已有的 MCP 工具服务。

问：需要什么 PHP 版本？答：建议使用项目 README 与 Composer 配置中声明的版本要求，装依赖时 composer 会直接校验。

问：能接多个模型供应商吗？答：框架提供 LLM 接口层，可对接不同供应商，具体以文档中的 provider 配置为准。

以上是实际使用中最常被问到的几个问题。若遇到文档未覆盖的情况，可以先翻项目的 Issues 与 Discussions 区，那里有更多真实踩坑记录。

八、总结

Neuron-AI 在把一类应用的写法标准化这件事上做到了足够扎实的程度：它不追求大而全，而是把一个具体环节做透，让原本要靠人盯的流程变成可以交给工具执行的流程。

从上面的安装步骤和使用示例可以看出，它的接入成本并不高：一条命令装好，按提示完成配置，然后就能把它放进你原有的工作流里。如果你正在被同类问题困扰，不妨先在自己的一小块任务上试一轮，确认顺手了再推广到日常流程中。