ToolSearchProcessor

ToolSearchProcessor 是一个 输入处理器，用于实现动态工具发现和加载。它不是一次性向代理提供所有工具，而是提供两个元工具（search_tools 和 load_tool），让代理可以按需查找和加载工具。这在使用大型工具库时可以减少上下文令牌的使用。

🌐 The ToolSearchProcessor is an input processor that enables dynamic tool discovery and loading. Instead of providing all tools to the agent upfront, it gives the agent two meta-tools (search_tools and load_tool) that let it find and load tools on demand. This reduces context token usage when working with large tool libraries.

使用示例

🌐 Usage example

import { ToolSearchProcessor } from "@mastra/core/processors";

const toolSearch = new ToolSearchProcessor({
  tools: {
    createIssue: githubTools.createIssue,
    sendEmail: emailTools.send,
    getWeather: weatherTools.forecast,
    // ... many more tools
  },
  search: {
    topK: 5,
    minScore: 0.1,
  },
});

构造函数参数

🌐 Constructor parameters

options:

ToolSearchProcessorOptions

Configuration options for the tool search processor

选项

🌐 Options

tools:

Record<string, Tool>

All tools that can be searched and loaded dynamically. These tools are not immediately available to the agent — they must be discovered via search and loaded on demand.

search?:

{ topK?: number; minScore?: number }

Configuration for the search behavior.

search.topK?:

number

Maximum number of tools to return in search results.

search.minScore?:

number

Minimum relevance score (0-1) for including a tool in search results.

ttl?:

number

Time-to-live for thread state in milliseconds. After this duration of inactivity, thread state will be cleaned up. Set to 0 to disable cleanup.

返回

🌐 Returns

id:

string

Processor identifier set to 'tool-search'

name:

string

Processor display name set to 'Tool Search Processor'

processInputStep:

(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>

Processes each step to inject search/load meta-tools and any previously loaded tools into the agent's tool set.

扩展使用示例

🌐 Extended usage example

src/mastra/agents/dynamic-tools-agent.ts

import { Agent } from "@mastra/core/agent";
import { ToolSearchProcessor } from "@mastra/core/processors";

// Tools from various integrations
import { githubTools } from "./tools/github";
import { slackTools } from "./tools/slack";
import { dbTools } from "./tools/database";

const toolSearch = new ToolSearchProcessor({
  tools: {
    ...githubTools,  // createIssue, listPRs, mergePR, ...
    ...slackTools,   // sendMessage, createChannel, ...
    ...dbTools,      // query, insert, update, ...
  },
  search: {
    topK: 5,
    minScore: 0.1,
  },
});

const agent = new Agent({
  name: "dynamic-tools-agent",
  instructions: "You are a helpful assistant with access to many tools. Use search_tools to find relevant tools, then load_tool to make them available.",
  model: "openai/gpt-4o",
  inputProcessors: [toolSearch],
});

代理工作流程如下：

🌐 The agent workflow is:

1. 代理接收到用户消息
2. 代理使用关键词（例如，“github issue”）调用 search_tools
3. 代理查看结果并使用工具名称调用 load_tool
4. 装载的工具将在下一回合可用
5. 代理正常使用已加载的工具

与其他处理器结合

🌐 Combining with other processors

import { Agent } from "@mastra/core/agent";
import {
  ToolSearchProcessor,
  TokenLimiter,
} from "@mastra/core/processors";

const agent = new Agent({
  name: "my-agent",
  model: "openai/gpt-4o",
  inputProcessors: [
    new ToolSearchProcessor({
      tools: allTools,
      search: { topK: 5 },
    }),
    // Place TokenLimiter last to ensure context fits
    new TokenLimiter(127000),
  ],
});

相关

🌐 Related

• 处理器
• 使用工具