工具与工具包

让智能体能够与你的应用上下文和服务交互。

核心 Agent 循环包括调用模型，让其选择要执行的工具，然后在不再需要工具来提供响应时结束：

什么是工具

工具使 Agent 能够超越文本生成，通过与您的应用服务或外部 API 交互来扩展能力。

可以将工具看作 AI Agent 在需要执行特定任务时能够使用的特殊函数。通过让 Agent 访问可在代码中调用的特定函数，您可以扩展其能力。

在 YouTubeAgent 示例中，我们可以定义一个工具，使 Agent 能够获取 YouTube 视频的转录文本，从而创建简短摘要：

namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Agent\SystemPrompt;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

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(): string 
    {
        return (string) new SystemPrompt(
            background: ["你是一名专门编写 YouTube 视频摘要的 AI Agent。"],
            steps: [
                "获取一个 YouTube 视频的网址，或者要求用户提供一个。",
                "使用可用工具获取视频的转录文本。",
                "编写摘要。",
            ],
            output: [
                "以一个段落编写摘要，不使用列表。只使用流畅的文字。",
                "在摘要后添加一个由三句话组成的列表，列出视频中最重要的三个要点。",
            ]
        );
    }
    
    protected function tools(): array
    {
        return [
            Tool::make(
                'get_transcription',
                '获取 YouTube 视频的转录文本。',
            )->addProperty(
                new ToolProperty(
                    name: 'video_url',
                    type: PropertyType::STRING,
                    description: 'YouTube 视频的网址。',
                    required: true
                )
            ->setCallable(function (string $video_url) {
                return "视频转录文本……";
            })
        ];
    }
}

让我们拆解一下这段代码。

我们将新方法 tools() 引入 Agent 类中。此方法应返回一个 Tool 对象数组，AI 可在需要时使用这些对象。

在此示例中，我们仅返回一个名为 get_transcription.

请注意，我们定义的 ToolProperty 应与您作为可调用对象使用的函数签名相匹配。该可调用对象接收 $video_url 参数，并且属性名称恰好是“video_url”。

最重要的是您为工具及其属性提供的名称和描述。所有这些信息都会以自然语言传递给 LLM。您的表述越明确、清晰，LLM 就越可能理解何时、是否以及为何应当使用该工具。

一旦 Agent 决定使用某个工具，就会执行可调用函数。您可以在这里实现获取视频转录文本的逻辑，并将信息返回给 LLM。

Neuron 为您提供了这些清晰、简单的 API，并自动处理与 LLM 的所有底层交互。一旦您理解其原理，就能立即将几乎任何想要的内容连接到 Agent。能够执行本地函数，意味着您可以调用任何外部 API 或应用组件。

自定义工具

得益于 Neuron 的模块化架构，工具是实现了 ToolInterface 的组件。您可以自由创建预封装的工具类，使 Agent 能够执行特定操作，并将其发布为外部 Composer 包，或向我们的仓库提交 PR，以将其集成到核心框架中。

要创建一个新工具，请执行以下控制台命令：

Unix

vendor/bin/neuron make:tool App\\Neuron\\GetTranscriptionTool

Windows

.\vendor\bin\neuron make:tool App\Neuron\GetTranscriptionTool

您可以使用以下代码自定义工具的脚手架：

<?php

namespace App\Neuron\Tools;

use GuzzleHttp\Client;
use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

class GetTranscriptionTool extends Tool
{
    protected Client $client;
    
    public function __construct(protected string $key)
    {
        // 定义工具名称和描述
        parent::__construct(
            'get_transcription',
            '获取 YouTube 视频的转录文本。',
        );
    }
    
    /**
     * 返回属性列表。
     */
    protected function properties(): array
    {
        return [
            new ToolProperty(
                name: 'video_url',
                type: PropertyType::STRING,
                description: 'YouTube 视频的网址。',
                required: true
            )
        ];
    }
    
    /**
     * 实现工具逻辑
     */
    public function __invoke(string $video_url): string
    {
        $response = $this->getClient()
            ->get('transcript?url=' . $video_url.'&text=true')
            ->getBody()
            ->getContents();

        $response = json_decode($response, true);

        return $response['content'];
    }
    
    protected function getClient(): Client
    {
        return $this->client ??= new Client([
            'base_uri' => 'https://api.supadata.ai/v1/youtube/',
            'headers' => [
                'x-api-key' => $this->key,
            ]
        ]);
    }
}

工具名称和描述：在工具构造函数中定义工具的名称和描述。投入提示工程工作，以帮助模型作出更好的决策。

properties 方法：实现此方法以返回工具所需的属性列表。

该 __invoke 方法：您需要在这里实现工具的逻辑，并返回一个将被传回模型的结果。默认使用 PHP 的 __invoke 魔术方法。

请注意， __invoke() 方法接受由以下内容定义的相同参数： ToolProperty 。在此示例中，我使用名为 Supadata.ai.

的外部服务来获取 YouTube 视频转录文本。您可以像往常一样在 Agent 类中附加该工具：

<?php

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Providers\AIProviderInterface;
use App\Neuron\Tools\GetTranscriptionTool;

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {...}
    
    protected function instructions(): string
    {...}
    
    protected function tools(): array
    {
        return [
            GetTranscriptionTool::make('API_KEY'),
        ];
    }
}

GetTranscriptions 只是一个示例。您还可以实现其他工具，使 Agent 能够获取其他视频元数据，从而增强其视频分析能力。

最后，您可以与 Agent 对话，请求它总结某个 YouTube 视频。

use NeuronAI\Chat\Messages\UserMessage;

$message = YouTubeAgent::make($user)->chat(
    new UserMessage('这个视频怎么样：https://www.youtube.com/watch?v=WmVLcj-XKnM')
)->getMessage();
    
echo $message->getContent();

/**

根据转录文本，我将对这则有力的环保 
“大自然母亲”的讯息提供摘要：
该视频展示了……

三个最重要的要点：

1. 大自然一直存在……

2. 人类的福祉……

3. 人类选择如何对待自然决定了……

*/

最大运行次数

Agent 具有一种安全机制，可跟踪执行会话期间工具被调用的次数。如果 Agent 超过此限制，执行将被中断，并抛出 ToolRunsExceededException 。默认限制为 10 次调用，并且每个工具单独计数。

您可以使用 toolMaxRuns() 方法在 Agent 级别自定义此值，或在工具级别使用 setMaxRuns() 。 为单个工具设置最大尝试次数优先于全局设置.

try {

    $response = YouTubeAgent::make()
        ->toolMaxRuns(5) // 每个工具的最大调用次数
        ->addTool(
            // 工具级配置优先于全局设置
            CustomTool::make()->setMaxRuns(2)
        )
        ->chat(...)
        ->getMessage();
        
} catch (ToolMaxTriesException $exception) {
    // 执行某些操作
}

可见性

您可以根据自定义规则限制工具的可用性。Tool 类提供了 visible 方法，用于确定 Agent 是否应该知道此工具的存在：

class YouTubeAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            GetTranscriptionTool::make('API_KEY')->visible(
                auth()->user()->can(...)
            ),
        ];
    }
}

如果 visible 方法返回 false，则该工具在 Agent 执行期间不可用。

工具审批

Neuron 完整支持包含工具审批在内的人机协作模式。这与可见性不同，因为“审批”是一个运行时守门机制。框架会拦截工具调用并暂停，等待用户的最终决定。

您可以通过我们内置的 ToolApproval 中间件将此功能接入您的 Agent。

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

中间件

工具搜索

默认情况下，每次调用提供商时，所有工具都会被加载并传输到后端 LLM。一个复杂的生产级 Agent 若连接到电子邮件、日历、云盘、CRM 以及多个 MCP 服务器，很容易就会拥有数百个工具；每个工具都携带其名称、描述、参数架构和使用提示。

工具搜索将工具目录重新定义为 Agent 按需查询的内容，而不是每次请求都随身携带的内容。

中间件

监控与调试

Neuron 会根据 LLM 决定调用的内容，自动为您管理工具循环。

要查看此工作流的内部情况，您应将 Agent 连接到 Inspector 监控仪表板 ，以实时查看工具调用的执行流程。

Neuron AI | Inspectordocs.inspector.dev

在下图中，您可以看到用于获取视频转录文本的工具执行的所有详细信息：

工具属性

Neuron 允许您定义希望工具函数接收的数据格式。您可以将这些对象相互嵌套，以定义复杂的数据结构。

ToolProperty

此类表示简单的标量值，例如字符串、整数或布尔值。

namespace App\Neuron\Tools;

use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

class MyTool extends Tool
{
    public function __construct(){...}
	
    protected function properties(): array
    {
        return [
            new ToolProperty(
                name: 'arg',
                type: PropertyType::STRING,
                description: '描述您期望的值',
                required: true,
                nullable: false
            )
        ];
    }
    
    public function __invoke(string $arg){...}
}

ArrayProperty

该 ArrayProperty 允许您要求一个具有特定特征的项目列表。

使用参数 items 来指定数组元素的数据类型。在下面的示例中，我们要求一个字符串数组。

namespace App\Neuron\Tools;

use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ArrayProperty;
use NeuronAI\Tools\ToolProperty;

class MyTool extends Tool
{
    public function __construct(){...}
	
    protected function properties(): array
    {
        return [
            new ArrayProperty(
                name: 'prop_array',
                description: '描述您期望的值',
                required: true,
                items: new ToolProperty(
                    name: 'prop',
                    type: PropertyType::STRING,
                    description: '描述您期望的值',
                    required: true
                )
            )
        ];
    }
    
    public function __invoke(string $arg){...}
}

最大值和最小值限制

ArrayProperty 还允许您使用 minItems 和 maxItems 参数定义预期数组大小的限制。

$property = new ArrayProperty(
    name: "tags",
    description: "与该项目关联的标签列表",
    required: true,
    items: new ToolProperty(
        name: "标签",
        type: PropertyType::STRING,
        description: "单个标签",
        required: true
    ),
    minItems: 1,
    maxItems: 10
);

对象属性

类似于上面的数组示例，你可以定义一个对象数据结构：

namespace App\Neuron\Tools;

use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ObjectProperty;
use NeuronAI\Tools\ToolProperty;

class MyTool extends Tool
{
    public function __construct(){...}
	
    protected function properties(): array
    {
        return [
            new ObjectProperty(
                name: 'colors',
                description: 'RGB 颜色',
                required: true,
                properties: [
                    new ToolProperty(
                        name: 'r',
                        type: PropertyType::NUMBER,
                        description: 'RGB 的红色部分',
                        required: true
                    ),
                    new ToolProperty(
                        name: 'g',
                        type: PropertyType::NUMBER,
                        description: 'RGB 的绿色部分',
                        required: true
                    ),
                    new ToolProperty(
                        name: 'b',
                        type: PropertyType::NUMBER,
                        description: 'RGB 的蓝色部分',
                        required: true
                    )
                ]
            )
        ];
    }
    
    public function __invoke(string $arg){...}
}

结构化工具输入

如果你想要的对象有很多属性，你可以将一个结构化的 PHP 类传递给 对象属性 而不是手动定义 schema。Neuron 会将此类的一个实例作为工具函数的输入参数提供给你：

namespace App\Neuron\Tools;

use App\Neuron\Dto\Color;
use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

class MyTool extends Tool
{
    public function __construct(){...}
	
    protected function properties(): array
    {
        return [
            new ObjectProperty(
                name: 'color',
                description: '颜色组合',
                required: true,
                class: Color::class
            )
        ];
    }
    
    public function __invoke(Color $color){...}
}

Colors 类如下所示：

<?php

namespace App\Neuron\Dto;

use NeuronAI\StructuredOutput\SchemaProperty;

class Color
{
    #[SchemaProperty(description: "RGB 的红色部分", required: true)]
    public float $r;
    
    #[SchemaProperty(description: "RGB 的绿色部分", required: true)]
    public float $g;
    
    #[SchemaProperty(description: "RGB 的蓝色部分", required: true)]
    public float $b;
}

提供方工具

一些提供商提供使用其内置工具（如 web_search、file_search 等）而非依赖外部服务的 შესაძლებლություն。即使他们提供这项服务，使用这些工具也会带来很多限制。为你的智能体添加能力，最灵活且可靠的方式仍然是 Tools 和 Toolkit 系统。

你可以像往常一样在智能体的 tools 数组中添加提供方工具：

use NeuronAI\Tools\ProviderTool;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new OpenAIResponses(
            key: 'OPENAI_API_KEY',
            model: 'OPENAI_MODEL',
        );
    }

    protected function tools(): array
    {
        return [
            ProviderTool:make(
                type: 'web_search'
            )->setOptions([...]),
        ];
    }
}

目前只有 OpenAIResponses, Gemini，以及 Anthropic 支持这些工具。

工具包

Neuron 工具包系统背后的理念源于 AI Agent 开发过程中的一个基本观察：单个工具虽然提供特定能力，但现实世界中的 AI 智能体往往需要一组协同的相关功能。

Neuron 引入工具包作为一个抽象层，改变我们对智能体能力组合的思考方式，而不是强迫开发者为常见用例手动组装工具集合。以下是将工具包添加到智能体的示例：

<?php

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Calculator\CalculatorToolkit;

class MyAgent extends Agent
{
    ...
	
    protected function tools(): array
    {
        return [
            CalculatorToolkit::make(),
        ];
    }
}

传统方法要求逐个实例化每个工具。想象一下，你要构建需要数学推理的智能体——加法、减法、乘法、除法和幂运算工具都必须在智能体的工具配置中单独声明。当智能体需要完整的功能集时，这种粒度化的方法很快就会变得难以管理。

工具包体现了 Neuron 针对这种复杂性的解决方案，它将围绕同一范围创建的工具打包到一个统一、连贯的接口中，只需一行代码即可附加到任何智能体上。

以下是 CalculatorToolkit:

namespace NeuronAI\Tools\Toolkits\Calculator;

use NeuronAI\Tools\Toolkits\AbstractToolkit;

class CalculatorToolkit extends AbstractToolkit
{
    public function guidelines(): ?string
    {
        return "这个工具包允许你执行数学运算。你也可以使用这些函数来解决
        数学表达式，通过逐步执行较小的运算来计算最终结果。";
    }

    public function provide(): array
    {
        return [
            SumTool::make(),
            SubtractTool::make(),
            MultiplyTool::make(),
            DivideTool::make(),
            ExponentiateTool::make(),
        ];
    }
}

该 AbstractToolkit 基类建立了一个一致的接口，所有工具包都继承它，从而确保整个框架中行为可预测。

指导说明

该 guidelines() 该方法在智能体开发中具有特别重要的作用——它提供上下文信息，帮助底层语言模型不仅理解有哪些工具可用，还理解这些工具应如何协同使用。就 CalculatorToolkit，其指导说明明确建议可以通过逐步运算来解决复杂的数学表达式，引导智能体采用有效的问题解决策略。

提供

该 provide() 该方法默认返回工具包中包含的工具数组。当将工具包附加到智能体时，各个工具的可用性与分别添加它们时完全相同，但无需承担管理多个工具声明的认知负担。

过滤器

在开发复杂智能体的过程中，我经常遇到这样的场景：工具包提供的功能大体正确，但其中包含的某些工具在特定上下文中可能导致不期望的行为，或者只是需要单独限制和配置。

排除

该 exclude() 该方法优雅地解决了这一挑战，使开发者在附加完整工具包的同时，仍能对可用能力进行细粒度控制。当处理需要特定能力的专用智能体时，这一点尤其有用，因为你希望降低智能体出错的概率，并减少 token 消耗。

class MyAgent extends Agent
{
    ...
	
    protected function tools(): array
    {
    	return [
            CalculatorToolkit::make()->exclude([
                DivideTool::class,
                ExponentiateTool::class,
                MultiplyTool::class,
            ]),
        ];
    }
}

排除机制在类级别运行，使用完全限定类名来标识要移除的工具。

仅

同样地，你也可以使用该方法 only() 来请求工具包中可用工具的一个子集。

class MyAgent extends Agent
{
    ...
	
    protected function tools(): array
    {
    	return [
            CalculatorToolkit::make()->only([
                StandardDeviationTool::class,
                MedianTool::class,
            ]),
        ];
    }
}

使用

按照同样的模式，你可能需要从工具包中检索某个特定工具的实例来更改其设置。你可以使用 with() 方法来实现。你可以传入完整限定类名来声明你想检索哪个工具，工具实例将被注入到回调中，这样你就可以更改其设置并将其返回。

class MyAgent extends Agent
{
    ...
	
    protected function tools(): array
    {
    	return [
            MySQLToolkit::make()
                ->with(
                    MySQLSchemaTool::class, 
                    fn (ToolInterface $tool) => $tool->setMaxTries(1)
                ),
        ];
    }
}

从可扩展性的角度来看，工具包系统为社区贡献和生态系统增长打开了非凡的机会。统一的接口意味着第三方开发者可以创建与特定领域相关的工具包，并与 Neuron 的架构无缝集成。为金融应用构建智能体的开发者可能会创建一个 FinancialToolkit，其中包含货币转换、利息计算和风险评估等工具。同样，WebScrapingToolkit 也可以将 HTTP 请求工具、HTML 解析能力以及数据提取实用程序打包成一个单一、可复用的组件。

可用工具包

Neuron 附带了若干内置工具和工具包，可帮助你快速为智能体配备多种能力。你可以单独使用这些工具，也可以用一行代码挂载整个工具包。

计算器

CalculatorToolkit 提供了一整套计算工具，旨在让你的 AI 智能体执行准确的计算。它可以与提供数据访问的互补工具包无缝集成——例如数据库连接器、CSV 处理器、API 客户端或电子表格读取器——使 AI 智能体能够进行复杂的统计计算，并针对复杂的业务查询提供全面洞察。

<?php

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Calculator\CalculatorToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            CalculatorToolkit::make(),
        ];
    }
}

求和	NeuronAI\Tools\Toolkits\Calculator\SumTool
相减	NeuronAI\Tools\Toolkits\Calculator\SubtractTool
相乘	NeuronAI\Tools\Toolkits\Calculator\MultiplyTool
相除	NeuronAI\Tools\Toolkits\Calculator\DivideTool
指数	NeuronAI\Tools\Toolkits\Calculator\ExponentialTool
平方根	NeuronAI\Tools\Toolkits\Calculator\SquareRootTool
n 次方根	NeuronAI\Tools\Toolkits\Calculator\NthRootTool
平均值	NeuronAI\Tools\Toolkits\Calculator\MeanTool
中位数	NeuronAI\Tools\Toolkits\Calculator\MedianTool
众数	NeuronAI\Tools\Toolkits\Calculator\ModeTool
标准差	NeuronAI\Tools\Toolkits\Calculator\StandardDeviationTool
方差	NeuronAI\Tools\Toolkits\Calculator\VarianceTool

日历

​此工具包提供全面的日期和时间操作。使用这些工具可以让你的智能体处理日期、时间、格式化、计算以及时区转换。

<?php

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\CalendarToolkit\CalendarToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            CalendarToolkit::make(),
        ];
    }
}

current_datetime	NeuronAI\Tools\Toolkits\Calendar\CurrentDateTimeTool
get_timestamp	NeuronAI\Tools\Toolkits\Calendar\GetTimestampTool
format_date	NeuronAI\Tools\Toolkits\Calendar\FormatDateTool
date_difference	NeuronAI\Tools\Toolkits\Calendar\DateDifferenceTool
add_time	NeuronAI\Tools\Toolkits\Calendar\AddTimeTool
subtract_time	NeuronAI\Tools\Toolkits\Calendar\SubtractTimeTool
calculate_age	NeuronAI\Tools\Toolkits\Calendar\CalculateAgeTool
convert_timezone	NeuronAI\Tools\Toolkits\Calendar\ConvertTimezoneTool
get_timezone_info	NeuronAI\Tools\Toolkits\Calendar\GetTimezoneInfoTool
get_weekday	NeuronAI\Tools\Toolkits\Calendar\GetWeekdayTool
is_weekend	NeuronAI\Tools\Toolkits\Calendar\IsWeekendTool
is_leap_year	NeuronAI\Tools\Toolkits\Calendar\IsLeapYearTool
get_days_in_month	NeuronAI\Tools\Toolkits\Calendar\GetDaysInMonthTool
start_of_period	NeuronAI\Tools\Toolkits\Calendar\StartOfPeriodTool
end_of_period	NeuronAI\Tools\Toolkits\Calendar\EndOfPeriodTool
get_week_number	NeuronAI\Tools\Toolkits\Calendar\GetWeekNumberTool
compare_dates	NeuronAI\Tools\Toolkits\Calendar\CompareDatesTool
is_date_in_range	NeuronAI\Tools\Toolkits\Calendar\IsDateInRangeTool

MySQL 与 PostgreSQL

这些工具包让你的智能体能够与数据库交互。如果你问“作者在过去 14 天里获得了多少票？”，智能体不会猜测或幻觉出一个答案。相反，它会识别出这个问题需要访问数据库，确定涉及的合适表，并从你的系统中检索真实数据。

MySQL 和 PostgreSQL 工具包中的所有工具都需要一个 PDO 实例作为构造函数参数。如果你处于框架环境中，或者你本身已经在使用 ORM，那么你可以从 ORM 中获取底层的 PDO 实例并将其传递给这些工具。你可以在这篇深入文章中了解更多关于该实现策略的信息： https://inspector.dev/mysql-ai-toolkit-bringing-intelligence-to-your-database-layer-in-php/

PDO 实例本质上就是连接到某个特定数据库的连接，因此你也可以考虑为你的智能体创建专用凭据。这样有助于控制智能体对数据库的访问级别。

无论如何，你都有用于读取和写入数据库的独立工具。如果你对智能体的行为没有把握，也可以不提供写入工具。

<?php

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLToolkit;
use NeuronAI\Tools\Toolkits\MySQL\PGSQLToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            // 连接到 MySQL 数据库
            MySQLToolkit::make(
                new \PDO("mysql:host=localhost;dbname=DB_NAME;charset=utf8mb4", "DB_USER", "DB_PASS"),
            ),
            
            // 或者 Postgre 数据库
            PGSQLToolkit::make(
                new \PDO("pgsql:host=localhost;dbname=DB_NAME;charset=utf8mb4", "DB_USER", "DB_PASS"),
            ),
        ];
    }
}

这些示例指的是 MySQLToolkit ，但使用 PGSQLToolkit.

完全相同

这个工具让智能体能够理解你的数据库结构，使其无需将表结构或关系硬编码到提示中，也能构造出智能查询。这个工具本质上让你的智能体具备类似数据库管理员对模式的理解能力，使其能够编写符合数据模型并充分利用现有索引和关系的查询。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            MySQLSchemaTool::make(new \PDO(...)),
            
            // PGSQLSchemaTool::make(new \PDO(...)),
        ];
    }
}

这个工具还接受第二个参数 $tables。你基本上可以传入一个表列表，将其包含到传递给 LLM 的模式信息中。这基本上是一种限制智能体之后在数据库上执行查询范围的方式。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            MySQLSchemaTool::make(
                new \PDO(...),
                ['users', 'categories', 'articles', 'tags']
            ),
        ];
    }
}

通过限制模式范围，你可以创建专注于应用特定领域的专用智能体。内容管理智能体可能只需要访问 articles、categories 和 tags，而用户管理智能体则需要看到 users、roles 和 permissions 表。这种方法不仅提升了性能，还减少了语言模型的认知负担，从而带来更准确、更聚焦的响应。

MySQLSelectTool / PGSQLSelectTool

使用此工具可以让你的智能体对数据库执行 SELECT 查询。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSelectTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            MySQLSchemaTool::make(new \PDO(...)),
            MySQLSelectTool::make(new \PDO(...)),
        ];
    }
}

MySQLWriteTool / PGSQLWriteTool

使用此工具可以让你的智能体对数据库执行写操作（INSERT、UPDATE、DELETE）。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\MySQL\MySQLSchemaTool;
use NeuronAI\Tools\Toolkits\MySQL\MySQLWriteTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            MySQLSchemaTool::make(new \PDO(...)),
            MySQLWriteTool::make(new \PDO(...)),
        ];
    }
}

文件系统

此工具包让智能体能够与本地文件系统交互。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\FileSystem\FileSystemToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            FileSystemToolkit::make(),
        ];
    }
}

描述目录内容	NeuronAI\Tools\Toolkits\FileSystem\DescribeDirectoryContentTool
读取文件	NeuronAI\Tools\Toolkits\FileSystem\ReadFileTool
grep 文件内容	NeuronAI\Tools\Toolkits\FileSystem\GrepFileContentTool
glob 路径	NeuronAI\Tools\Toolkits\FileSystem\GlobPathTool
预览文件	NeuronAI\Tools\Toolkits\FileSystem\PreviewFileTool
解析文件	NeuronAI\Tools\Toolkits\FileSystem\ParseFileTool

Tavily

此工具包使你的智能体能够进行网页搜索、页面内容提取和爬取。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Tavily\TavilyToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            TavilyToolkit::make(
                key: 'TAVILY_API_KEY'
            ),
        ];
    }
}

Tavily 网页搜索

它让你的智能体能够搜索网络。它需要访问 Tavily API.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Tavily\TavilySearchTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            TavilySearchTool::make(
                key: 'TAVILY_API_KEY'
            ),
        ];
    }
}

你可以通过在 withOptions 方法中传入你的偏好来定制默认的搜索结果获取选项：

TavilySearchTool::make(
    key: 'TAVILY_API_KEY'
 )->withOptions([
    'days' => 30,
    'max_results' => 10,
]),

Tavily 提取

从一个 URL 提取网页内容。它需要访问 Tavily API.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Tavily\TavilyExtractTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            TavilyExtractTool::make(
                key: 'TAVILY_API_KEY'
            ),
        ];
    }
}

Tavily 爬取

Tavily Crawl 是一种基于图的站点遍历工具，借助内置提取和智能发现功能，可以并行探索数百条路径。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Tavily\TavilyCrawlTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            TavilyCrawlTool::make(
                key: 'TAVILY_API_KEY'
            ),
        ];
    }
}

Jina

此工具包使你的智能体能够进行网页搜索，并读取特定 URL 的内容。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Jina\JinaToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            JinaToolkit::make(
                key: 'JINA_API_KEY'
            ),
        ];
    }
}

Jina 网页搜索

它让你的智能体能够搜索网络。它需要访问 Jina API.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Jina\JinaWebSearch;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            JinaWebSearch::make(
                key: 'JINA_API_KEY'
            ),
        ];
    }
}

Jina URL 读取器

从一个 URL 提取网页内容。它需要访问 Jina API.

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Jina\JinaUrlReader;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            JinaUrlReader::make(
                key: 'JINA_API_KEY'
            ),
        ];
    }
}

Zep 记忆

此工具包将 NeuronAI 智能体连接到 Zep 知识图谱。这类系统允许智能体存储在与其交互过程中可能出现的相关事实。从长期记忆的意义上说，它不局限于当前对话，就像 ChatHistory 组件那样。它是一个外部的持久化存储，智能体会用它来存储和检索单条信息，从而提供更个性化的回答。

要进一步了解这类系统的能力，你可以访问 Zep 网站： https://www.getzep.com/

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Zep\ZepLongTermMemoryToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            ZepLongTermMemoryToolkit::make(
                key: 'ZEP_API_KEY',
                user_id: 'ID'
            ),
        ];
    }
}

该 user_id 参数允许你在需要服务多个用户时，将长期记忆拆分到不同的孤岛中。根据你的使用场景，你可以将此参数作为一个“键”，用于区分智能体所交互的各种实体（用户、公司等）的记忆。

AWS SES

简单电子邮件服务（SES）

此工具允许智能体向一个或多个收件人发送电子邮件消息、通知、确认、报告或任何其他基于电子邮件的通信。该工具会自动处理正确的邮件投递和基本错误处理。

要使用此工具，必须安装适用于 PHP 的 AWS SDK。

composer require aws/aws-sdk-php

该工具获取一个 SesClient 类的实例，来自 AWS PHP SDK。

namespace App\Neuron;

use Aws\Ses\SesClient;
use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\AWS\SESTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            SESTool::make(
                sesClient: new SesCleint(...),
                fromEmail: '[email protected]'
            ),
        ];
    }
}

Supadata YouTube

此工具包通过 Supadata.ai 提供对 YouTube 视频转录、元数据、频道信息和播放列表数据的访问，用于内容分析和研究。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Supadata\SupadataYouTubeToolkit;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            SupadataYouTubeToolkit::make(
                key: 'SUPADATA_API_KEY',
            ),
        ];
    }
}

视频转录

允许智能体检索 YouTube 视频的转录文本。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Supadata\SupadataVideoTranscriptTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            SupadataVideoTranscriptTool::make(
                key: 'SUPADATA_API_KEY',
            ),
        ];
    }
}

视频元数据

允许智能体检索 YouTube 视频的元数据。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Supadata\SupadataVideoMetadataTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            SupadataVideoMetadataTool::make(
                key: 'SUPADATA_API_KEY',
            ),
        ];
    }
}

频道元数据

允许智能体检索 YouTube 频道的元数据，包括名称、描述、订阅者数量等。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Supadata\SupadataYoutubeChannelTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            SupadataYoutubeChannelTool::make(
                key: 'SUPADATA_API_KEY',
            ),
        ];
    }
}

播放列表元数据

允许智能体检索 YouTube 播放列表的元数据，包括标题、描述、视频数量等。

namespace App\Neuron;

use NeuronAI\Agent;
use NeuronAI\Tools\Toolkits\Supadata\SupadataYoutubePlaylistTool;

class MyAgent extends Agent
{
    ...
    
    protected function tools(): array
    {
        return [
            SupadataYoutubePlaylistTool::make(
                key: 'SUPADATA_API_KEY',
            ),
        ];
    }
}

并行工具调用

如果你的智能体非常依赖工具，而模型在单次请求中要求多次工具调用，你可以启用并行执行。

顺序执行（标准）

智能体调用工具 一次一个，在开始下一个之前等待每个工具完成：

1. 调用工具 A → 等待结果
2. 调用工具 B → 等待结果  
3. 调用工具 C → 等待结果

总时间：Time(A) + Time(B) + Time(C)

并行执行（使用 pcntl)

智能体会调用 多个工具同时执行，让它们同时运行：

1. 一次调用工具 A、B 和 C
2. 等待全部完成

总时间：Max(Time(A), Time(B), Time(C))

要求

要使用此功能，你需要安装 spatie/fork 包。更多信息请查看 GitHub 仓库： https://github.com/spatie/fork

composer require spatie/fork

限制

此实现需要 pcntl 扩展，该扩展在许多 Unix 和 Mac 系统中默认安装。

pcntl 仅适用于 CLI 进程，不适用于 Web 场景。

如果 pcntl 如果运行智能体的系统中不存在该扩展（例如 Windows 机器），该 trait 会自动回退到标准的工具调用执行方式。如果你的本地开发环境与生产环境不匹配，这会很有帮助。你可以在本地开发时使用 pcntl 禁用，然后部署到可能启用它的生产环境中——而无需修改一行代码。智能体会自动适应其所处的任何执行环境。

启用并行执行

在你的 Agent 或 RAG 中设置 parallelToolCalls(true) 。框架将注入专用节点 ParallelToolNode 而不是标准的 ToolNode 到工作流中。

class DemoAgent extends Agent
{
    public function __construct()
    {
        parent::__construct();
        $this->parallelToolCalls(true);
    }
    
    protected function provider(): AIProviderInterface
    {
        ...
    }

    protected function tools(): array
    {
        return [
            CalculatorToolkit::make(),
        ];
    }
}

错误处理器

现在的问题是如何处理工具错误。为了适应不同的场景和需求，这里有几个选项。

该 ToolNode 接受一个 $errorHandler 参数 （代码）。它是一个回调，接收工具抛出的异常以及失败工具的实例。

它允许你在工具出错时实现自定义逻辑（通用工具异常，或 ToolRunsExceededException). 如果你返回一个值，它将作为工具的结果返回给模型。 默认情况下，ToolNode 会重新抛出执行错误。

流式定义：

$agent = Agent::make()
    ->toolErrorHandler(
        fn(Throwable $e, ToolInterface $tool): string => "Error: {$e->getMessage()}"
    );

扩展 Agent

你也可以直接实现 resolveToolErrorHandler() 来定义要运行的回调。

class MyAgent extends Agent
{
    ...

    protected function resolveToolErrorHandler(): ?callable
    {
        return fn(Throwable $e, ToolInterface $tool): string => "Error: {$e->getMessage()}";
    }
}