> For the complete documentation index, see [llms.txt](https://docs.neuron-ai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/agent.md).

# 代理

借助内置记忆和工具使用，轻松实现 LLM 交互。

{% hint style="warning" %}

#### 编码代理技能

使用 **`/neuron-agent`** 来教你的编码代理如何使用 Neuron AI 组件实现一个代理。

[AI 辅助开发](https://docs.neuron-ai.dev/neuron-v3-zh/gai-lan/agentic-development.md)
{% endhint %}

### 简介

你可以通过扩展 `NeuronAI\Agent\Agent` 类来继承框架的主要功能并创建完全可用的代理。

该类会自动为你管理一些机制，例如记忆、工具和函数调用。我们将在后续章节中更详细地介绍这些内容。

我们强烈建议扩展 Agent 类，而不是使用 [流式定义](#fluent-agent-definition)。这种策略使给代理添加自定义方法和行为更容易，也更有利于可移植性，因为所有运行组件都封装在单一实体中，你可以在应用中的任何地方运行它，甚至将其发布为独立的 Composer 包。

让我们开始创建一个用于总结 YouTube 视频的 AI 代理。我们首先创建 `YouTubeAgent` 类：

{% tabs %}
{% tab title="Unix" %}

```bash
vendor/bin/neuron make:agent App\\Neuron\\YouTubeAgent
```

{% endtab %}

{% tab title="Windows" %}

```powershell
.\vendor\bin\neuron make:agent App\Neuron\YouTubeAgent
```

{% endtab %}
{% endtabs %}

该命令会创建如下类：

```php
<?php

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Agent\SystemPrompt;
use NeuronAI\Providers\AIProviderInterface;

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        // 返回 Anthropic、OpenAI、Gemini、Ollama 等的实例...
    }
    
    protected function instructions(): string
    {
        return new SystemMessage(
            "你是一个使用 Neuron 框架创建的友好 AI 代理。"
        );
    }
    
    /**
     * @return \NeuronAI\Tools\ToolInterface[]
     */
    protected function tools(): array
    {
        return [];
    }
}
```

### 监控与调试

你使用 Neuron 构建的许多应用都会包含多个步骤以及多次 LLM 调用。随着这些应用变得越来越复杂，能够检查你的代理系统内部究竟发生了什么变得至关重要。做到这一点的最佳方式是使用 [Inspector](https://inspector.dev/).

{% embed url="<https://docs.inspector.dev/guides/neuron-ai>" %}

### AI 提供商

最小实现需要指定一个 AI 提供商，它将成为你代理的语言和推理引擎。

唯一需要实现的方法是 `provider()` ，它返回你想使用的提供商实例。我们假设它是 Anthropic。

```php
<?php

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Message\SystemMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        // 返回 Anthropic、OpenAI、Gemini、Ollama 等的实例...
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }
    
    protected function instructions(): SystemMessage
    {
        return new SystemMessage(
            "你是一个使用 Neuron 框架创建的友好 AI 代理。"
        );
    }
    
    /**
     * @return \NeuronAI\Tools\ToolInterface[]
     */
    protected function tools(): array
    {
        return [];
    }
}
```

如果你希望在本地运行模型，也可以使用 OpenAI、Gemini 或 Ollama 等其他提供商。查看 [支持的提供商](https://docs.neuron-ai.dev/neuron-v3-zh/ti-gong-shang/ai-provider.md).

### 系统指令

第二个重要构建块是系统指令。系统指令用于指导 AI 按照我们想要实现的任务行事。它们是固定指令，会在每次交互中发送给 LLM。

这就是它们由内部方法定义并封装在代理实体中的原因。让我们实现 `instructions()` 方法：

```php
<?php

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\SystemMessage;;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        // 返回 AI 提供商实例（Anthropic、OpenAI、Ollama、Gemini 等）
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }
    
    protected function instructions(): SystemMessage
    {
        return new SystemMessage(<<<TEXT
            你是一名专门编写 YouTube 视频摘要的 AI 代理。
            获取 YouTube 视频的 URL，或者让用户提供一个。
            使用你可用的工具来获取视频的转录内容。
            写一段摘要，不要使用列表。只使用流畅的文本。
            在摘要之后，再添加一个包含三句话的列表，作为视频中最重要的三个要点。
        TEXT);
    }
    
    /**
     * @return \NeuronAI\Tools\ToolInterface[]
     */
    protected function tools(): array
    {
        return [];
    }
}
```

SystemMessage 类还可以用多个内容块 SystemContent 来填充，以便动态注入系统指令内容：

```php
class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        ...
    }
    
    protected function instructions(): SystemMessage
    {
        $message = new SystemMessage(<<<TEXT
            你是一名专门编写 YouTube 视频摘要的 AI 代理。
            获取 YouTube 视频的 URL，或者让用户提供一个。
            使用你可用的工具来获取视频的转录内容。
        TEXT);
        
        $message->addContent(
            new SystemContent("写一段摘要，不要使用列表。只使用流畅的文本。")
        );
        
        $message->addContent(
            new SystemContent("在摘要之后，再添加一个包含三句话的列表，作为视频中最重要的三个要点。")
        );
                
        return $message;
    }
}
```

如果你希望像 Anthropic 这类提供商使用系统提示缓存，可以在每个想要缓存的内容部分上调用 cache() 方法：

```php
$message->addContent(
    new SystemContent("...")->cache()
);
```

或者对 `SystemMessage` 调用 cache 方法，以缓存整个系统提示：

```php
    protected function instructions(): SystemMessage
    {
        $message = new SystemMessage(...);
        
        $message->addContent(
            new SystemContent(...)
        );
        
        $message->addContent(
            new SystemContent(...)
        );
                
        return $message->cache(); // <- 缓存全部内容
    }
```

### 与代理对话

我们已经准备好测试代理会如何根据新指令对我们的消息作出响应。

```php
use NeuronAI\Chat\Messages\UserMessage;

$message = YouTubeAgent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("你是谁？"))
    ->getMessage();
    
echo $message->getContent();
// 嗨，我是一个友好的 AI 代理，专门用于总结 YouTube 视频！
// 你能给我一个你想要快速摘要的 YouTube 视频 URL 吗？
```

### 代理状态

由于 Agent 是 Workflow 的扩展，而不是通过 `getMessage()` 方法获取最后一次模型响应，你只需运行代理工作流，并将原始代理状态作为返回值。代理状态包含额外信息，可帮助你检查代理执行过程中发生了什么。

```php
$state = MyAgent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("你是谁？"));

// $state 是 NeuronAI\Agent\AgentState 类的实例
$state->getMessage();
```

#### 步骤

调用 `getMessage()` 方法时，你只能获取模型生成的最后一条消息来回答你的提示。但在内部，代理在得出最终答案之前可能会执行多次工具调用迭代。

代理状态会存储当前执行周期中代理与提供商之间的所有消息列表，而不仅仅是最终答案。因此，你可以通过 `getSteps()` 方法访问消息列表：

```php
$state = MyAgent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("你是谁？"));

// 访问执行期间的步骤列表
foreach($state->getSteps() as $message) {
    echo "- ".$message::class."\n";
}

// 最终答案
echo $state->getMessage()->getContent();
```

#### 工具运行

如果代理在执行过程中决定使用工具，代理状态会记录工具运行次数，以便在 [maxRuns](https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/tools.md#max-runs) 限制达到时停止执行。你可以访问这个映射：

```php
$state = MyAgent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("你是谁？"));

// 访问工具运行映射
foreach($state->getToolRuns() as $toolName => $runs) {
    echo "- 工具 {$toolName} 已被使用 {$runs} 次\n";
}
```

### 消息

代理始终接受输入，形式为 `消息` 类，并返回 Message 实例。

正如你在上面的示例中看到的，我们向代理发送了一个 `UserMessage` 实例，并检索到回复消息，它将是一个 `AssistantMessage` 实例。助手消息和用户消息的列表会创建一个聊天。

我们稍后将进一步了解 [ChatHistory](https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/chat-history-and-memory.md) ，但重要的是要知道，代理输入和输出的统一接口是 `消息` 对象。

<a href="https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/messages.md" class="button primary" data-icon="arrow-right-long">了解更多关于消息的信息</a>

### 流式代理定义

作为单类封装的替代方案，你也可以使用流式方法链在行内指示代理：

```php
$agent = Agent::make()
    ->setThreadId('chat_id')
    ->setAiProvider(
        new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        )
    )
    ->setInstructions(
        new SystemMessage(...)
    )
    ->addTool([...]);
    
$message = $agent->chat(new UserMessage(...))->getMessage();
echo $message->gentContent();
```
