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

Tinywan

发布于 2026-07-01 18:08:49

1700

Agent 是什么？

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

维度	传统大模型（LLM）	AI Agent
功能	只负责聊天/生成文字	规划 + 执行 + 反馈 + 记忆
自主性	被动（等你提问）	主动（自己拆任务、选工具、重试）
工具调用	无（只能输出文字）	有（浏览器、代码执行、API、文件、CLI等）
过程	一次推理 + 输出	循环：感知 → 推理 → 执行 → 观察 → 修正
典型场景	问“帮我写一篇文章”	问“帮我分析100篇论文、画图、写总结、发邮件”

Neuron Agent

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

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

Agent 四大核心组件

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

组件	对应方法	是否必需	作用
AI Provider（大脑）	provider()	✅ 必需	返回 Anthropic / OpenAI / Gemini / Ollama 等实例，作为语言和推理引擎
System Instructions（灵魂）	instructions()	✅ 必需	固定指令，每次交互都发给 LLM，定义 Agent 的角色、行为步骤、输出格式
Tools（双手）	tools()	❌ 可选	返回 ToolInterface[] 数组，让 Agent 能调用外部工具（搜索、数据库、API 等）
Memory（记忆）	框架自动管理	—	框架自动维护对话历史，无需手动管理

下面这张图展示了一个 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;

class TinywanAgent extends Agent
{
    publicfunction provider(): AIProviderInterface
    {
        returnnew Deepseek(
            key: getenv('DEEPSEEK_KEY'),
            model: 'deepseek-v4-flash',
            parameters: ['thinking' => ['type' => 'disabled']],
        );
    }

    publicfunction instructions(): string
    {
        return'你是由开源技术小栈开发的 Agent';
    }
}

// 调用
finalclass IndexController
{
    publicfunction index(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;

class ReviewAgent extends Agent
{
    protectedfunction provider(): 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 类把四者封装成一个可独立运行、可复用、可调试的智能体实体。

PHP Agentic 实战03〡Neuron Skills 技能

PHP Agentic 实战02〡环境准备与框架安装

PHP Agentic 实战01〡Neuron 框架入门认知

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2026-06-29，如有侵权请联系 cloudcommunity@tencent.com 删除

工具

本文分享自开源技术小栈微信公众号，前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度