> 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/middleware.md).

# 中间件

与 Agent 执行流程交互以自定义其行为。

中间件是基础 Workflow 组件的一个特性。因此，你也可以将自定义中间件附加到 Agent 和 RAG 上，以介入它们的执行循环。

### Agent 工作流

Agent 类是 Workflow 组件的扩展。Workflow 是 Neuron 中拼图的基础部分。Agent 和 RAG 组件的许多特性都从底层 Workflow 的能力中继承其逻辑。

下面是用于创建 agent 实现的工作流的一个简单示意图：

<figure><img src="https://99736354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGHx4l2LknIex7vFIUg1R%2Fuploads%2FVPEHxq92m1veny50VHp6%2FNeuronAI.png?alt=media&amp;token=8fcbbb62-4b06-492d-8208-1880d664c00b" alt=""><figcaption></figcaption></figure>

考虑到这种架构，你可以自由使用中间件来挂接 agent 工作流，使用中断来保持人工介入，或者查看下面我们为常见用例提供的一组内置组件。

### 上下文摘要

这个中间件旨在包装 agent 实际调用 LLM 的节点，在接近 token 限制时自动总结对话历史。在 Neuron 中，根据你要执行的调用类型，有三个可能负责此任务的节点： `ChatNode`, `StreamingNode`，以及 `StructuredNode`。你应该将中间件附加到所有这些节点上，以确保它在 agent 运行的任何模式下都能工作。

```php
use NeuronAI\Agent\Agent;
use NeuronAI\Agent\Middleware\Summarization;
use NeuronAI\Agent\Nodes\InferenceNode;

class MyAgent extends Agent
{
    ...

    /**
     * 将中间件附加到节点。
     */
    protected function middleware(): array
    {
        return [
            InferenceNode::class => [
                new Summarization(
                    provider: $this->resolveProvider(), // 或使用专用的 provider 实例
                    maxTokens: 10000,
                    messagesToKeep: 5,
                )
            ]
        ];
    }
}
```

`maxTokens` 和 `messagesToKeep` 共同定义需要执行摘要的阈值。上面的示例中，如果上下文达到 30K token，则聊天历史中至少需要有 10 条消息，摘要才会开始。向聊天历史添加新消息最终会同时跨过这两个阈值，从而触发摘要。

### 工具搜索

默认情况下，每次调用 provider 时，所有工具都会被加载并传输到后端 LLM。一个连接了邮件、日历、网盘、CRM 以及多个 MCP 服务器的复杂生产级 agent，很容易达到数百个工具，每个工具都携带其名称、描述、参数 schema 和使用提示。

这会在每一轮消耗数千个 token，但更令人头疼的问题是质量：当模型一次看到太多工具时，描述会彼此混淆，名字相似的工具会争夺注意力，agent 开始做出微妙但错误的选择，混淆参数或编造参数，因为它试图同时在工作记忆中保留太多签名。

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

你可以使用全局中间件 `ToolSearchMiddleware` 来在你的 agent 上启用动态工具选择：

```php
class MyAgent extends Agennt
{
    ...
    
    /**
     * 定义全局中间件。
     */
    protected function globalMiddleware(): array
    {
        return [
            new ToolSearchMiddleware([
                MyCustomTool::make(),
                ...CalculatorToolkit::make()->tools()
                ...MCPConnector::make([...])->tools()
            ]),
        ];
    }
    
    /**
     * 向 agent 提供核心工具。
     */
    protected function tools(): array
    {
        return [
            // 模型始终可用的一组核心工具
            TavilySearchTool::make(...),
        ];
    }
}
```

{% embed url="<https://www.youtube.com/watch?v=qYmidHAXEYM>" %}

这个中间件会自动注入 `ToolSearch` 工具到每次请求时模型可用的默认工具列表中，并将你提供的工具列表保存在一个内部数组中。

agent 会以一组最小工具集开始一轮对话，通常只有 `ToolSearch` 它自身，以及你始终希望可用的任何核心工具；当它需要当前没有的能力时，它会调用 `ToolSearch` ，并使用自然语言查询返回带有完整 schema 的工具描述符排序列表。此时，位于 agent 与下一次推理调用之间的中间件会检查搜索结果，提取工具标识符，在底层注册表中查找它们，并将其完整定义添加到下一次发送给模型的 tools 数组中。

从模型的视角看，下一轮只是带着更丰富的工具列表到来，而它可以直接使用正确的 schema 验证调用这些新暴露出来的工具，就像它们从一开始就在那里一样。
