PHP Agentic 实战〡04. Agent 基础认知与实操使用

Agent 是什么？

AI Agent（AI 代理 / 智能体） 是一种自主软件系统，它感知环境、理解目标、规划步骤、调用工具执行，并自我反思修正，最终完成复杂任务。它不是只回答问题，而是主动干活。

Neuron Agent

在 Neuron AI 框架中，Agent 是一个继承自 NeuronAI\Agent\Agent 的类，它封装了与 LLM 交互的完整能力，内置了记忆、工具调用和系统提示三大机制。你只需要继承这个基类并实现几个关键方法，就能得到一个可独立运行、甚至可打包成 composer 包发布的功能完整的智能体。

官方强烈推荐继承 Agent 类来创建 Agent，而不是用链式调用（fluent definition）。原因是：继承方式把所有"零件"封装在一个实体里，更易添加自定义方法和行为，也便于移植和复用。

Agent 四大核心组件

一个标准的 Neuron Agent 由以下部分构成（前两个是必需的）：

下面这张图展示了一个 Neuron Agent 从接收到用户消息到产出最终回复的完整内部工作流，可以看出 Memory、Provider、Tools 如何协同运作：

最小实现示例

官方文档用这个例子演示了一个完整 Agent 的写法：

<?php/** * @desc TinywanAgent.php 描述信息 * @author Tinywan(ShaoBo Wan) */declare(strict_types=1);namespace app\neuron\agent;use NeuronAI\Agent\Agent;use NeuronAI\Providers\AIProviderInterface;use NeuronAI\Providers\Deepseek\Deepseek;classTinywanAgentextendsAgent{publicfunctionprovider(): AIProviderInterface{returnnew Deepseek(            key: getenv('DEEPSEEK_KEY'),            model: 'deepseek-v4-flash',            parameters: ['thinking' => ['type' => 'disabled']],        );    }publicfunctioninstructions(): string{return'你是由开源技术小栈开发的 Agent';    }}// 调用finalclassIndexController{publicfunctionindex(Request $request): ?string{        $input = '简单介绍一下webman框架';        $agent = TinywanAgent::make()            ->chat(new UserMessage($input))            ->getMessage();return $agent->getContent();    }}

请求访问：http://127.0.0.1:8488/index/index

SystemPrompt 三段式结构

官方推荐的 SystemPrompt 类把提示词拆成三段，降低 prompt engineering 的负担：

• background：定义 Agent 的角色，宏观任务目标
• steps：定义 Agent 的行为方式，多步骤让它行为更一致
• output：定义 Agent 的回复格式，明确期望的输出形态 当然，你也可以直接 return "一段字符串";，但官方推荐用 SystemPrompt 类以获得更稳定的结果。

两种执行方式

Agent 创建好后，有两种执行方式，对应不同的信息获取深度：

方式一：chat()->getMessage() —— 只拿最终回复

$message = TinywanAgent::make()    ->chat(new UserMessage("Who are you?"))    ->getMessage();echo $message->getContent();// Hi, I'm a friendly AI agent specialized in summarizing YouTube videos!

方式二：chat()->run() —— 拿到完整 AgentState（推荐调试用）

Agent 本质上是 Workflow 的扩展，run() 返回一个 AgentState 对象，能让你透视 Agent 内部发生了什么：

$state = TinywanAgent::make()    ->chat(new UserMessage("Who are you?"))    ->run();// 1. 最终回复echo $state->getMessage()->getContent();// 2. 查看执行过程中所有消息（系统指令、用户消息、模型回复、工具调用、工具结果）foreach ($state->getSteps() as $message) {echo"- " . $message::class . "\n";}// 3. 查看每个工具被调用了几次（框架会自动限制 maxRuns 防止死循环）foreach ($state->getToolRuns() as $toolName => $runs) {echo"- The tool {$toolName} was used {$runs} times\n";}

这一点在调试复杂 Agent 时非常关键——getMessage() 只能看到"最终答案"，但 Agent 内部可能经历了多轮工具调用循环才得出结论，getSteps() 能让你看到完整的推理链路。

统一的输入输出接口

Agent 的输入输出统一是 Message 对象：

• 输入：UserMessage（用户消息）
• 输出：AssistantMessage（助手消息）

flowchart LR    I[UserMessage<br/>用户输入] --> A[Agent]    A --> O[AssistantMessage<br/>助手回复]

用户消息和助手消息交替排列，就构成了一段 ChatHistory（对话历史），框架会自动管理这段历史并带上上下文。

继承式 vs 链式调用

官方同时支持两种构建方式，但推荐继承式.

链式调用（inline）

官方不推荐，零件分散，难复用

$agent = Agent::make()    ->setAiProvider(new Anthropic(...))    ->setInstructions("...")    ->addTool([...]);$agent->chat(new UserMessage("..."));

继承式调用（inline）

官方推荐，高内聚，可打包成独立 composer 包

<?php/** * @desc WritingAgent.php 描述信息 * @author Tinywan(ShaoBo Wan) */declare(strict_types=1);namespace app\ai\agent\neuron;use NeuronAI\Agent\Agent;use NeuronAI\Providers\AIProviderInterface;use NeuronAI\Providers\Deepseek\Deepseek;classReviewAgentextendsAgent{protectedfunctionprovider(): AIProviderInterface{returnnew Deepseek(            key: getenv('DEEPSEEK_KEY'),            model: 'deepseek-v4-flash',            parameters: [],            strict_response: false        );    }}// 调用ReviewAgent::make()->chat(new UserMessage("..."));

继承式的核心优势：所有"零件"（Provider、指令、工具）封装在一个类里，你可以把这个类扔到项目的任何角落运行，甚至发布成独立的 composer 包供他人使用。

快速生成脚手架

官方还提供了 CLI 命令一键生成 Agent 骨架，省去手写样板代码：

vendor/bin/neuron make:agent App\\Neuron\\TinywanAgent# Windows.\vendor\bin\neuron make:agent App\Neuron\TinywanAgent

执行后会自动生成包含 provider()、instructions()、tools() 三个方法的基本类结构，你只需填充实现即可。

总结：Neuron AI 的 Agent = AI Provider（大脑）+ System Instructions（灵魂）+ Tools（双手）+ Memory（记忆，框架自动管理），通过继承 Agent 类把四者封装成一个可独立运行、可复用、可调试的智能体实体。