Tool검색프로세서

그만큼ToolSearchProcessor은입력 프로세서런타임 정의 Tool 검색 및 로드를 가능하게 합니다. Agent에게 모든 Tool을 미리 제공하는 대신 Agent에게 두 가지 메타 Tool(search_tools그리고load_tool) 필요에 따라 Tool을 찾고 로드할 수 있습니다. 이렇게 하면 대규모 Tool 라이브러리로 작업할 때 컨텍스트 토큰 사용량이 줄어듭니다.

사용예

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,
  },
})

생성자 매개변수

options:

ToolSearchProcessorOptions

Tool 검색 프로세서의 구성 옵션입니다

ToolSearchProcessorOptions

tools:

Record<string, Tool>

검색하고 동적으로 로드할 수 있는 모든 Tool입니다. 이러한 Tool은 Agent가 즉시 사용할 수 없으며, 검색을 통해 발견한 후 필요할 때 로드해야 합니다.

includeResolvedTools?:

boolean

Agent가 이 요청에 대해 확인한 Tool(호출자의 자격 증명이 필요한 MCP Tool 또는 동적 Tool 함수가 반환한 모든 항목)도 검색할 수 있게 하고, Agent가 로드할 때까지 Prompt에서 제외합니다. 메타 Tool은 절대 제외되지 않습니다. 요청별로 확인된 Tool은 요청별로 인덱싱되므로 각 요청은 자체 Tool 인스턴스를 검색하고 로드합니다.

search?:

{ topK?: number; minScore?: number; autoLoad?: boolean }

검색 동작의 구성입니다.

search.topK?:

number

검색 결과로 반환할 최대 Tool 수입니다.

search.minScore?:

number

검색 결과에 Tool을 포함하기 위한 최소 관련성 점수(0~1)입니다.

search.autoLoad?:

boolean

true이면 search_tools가 반환한 Tool이 검색 과정의 일부로 즉시 활성화됩니다. load_tool 메타 Tool은 노출되지 않으므로 검색 후 로드하는 2단계 흐름이 단일 검색 단계로 축소됩니다. 발견된 Tool은 다음 턴부터 사용할 수 있습니다. 일치하는 모든 Tool이 활성화되므로 topK는 보수적으로 설정하세요.

storage?:

'in-memory' | 'context'

로드된 Tool의 상태를 저장하는 위치입니다. 'in-memory'(기본값)는 TTL 정리를 사용하는 스레드별 인메모리 맵에서 로드된 Tool을 추적합니다(ttl 참조). 재시작하면 상태가 손실되고 익명 요청은 'default' 항목을 공유합니다. 'context'는 대화 메시지에서 로드 상태를 파생합니다. Tool 이름을 포함하는 search_tools/load_tool 결과가 메시지에 남아 있는 동안 해당 Tool이 로드됩니다. 재시작에도 안전하고 Memory가 필요하지 않으며, 해당 결과가 메시지에서 사라지면 자동으로 언로드됩니다. 'context' 저장소는 명시적으로 선택해야 합니다.

ttl?:

number

인메모리 스레드 상태의 TTL(밀리초)입니다. 기본 저장소인 'in-memory'에만 적용되며, 이 시간 동안 활동이 없으면 스레드 상태가 정리됩니다. 정리를 비활성화하려면 0으로 설정하세요. 'context' 저장소에서는 무시됩니다.

filter?:

(args: ToolSearchFilterArgs) => boolean | Promise<boolean>

검색 결과에서 Tool을 숨기거나, Tool 로드를 차단하거나, 현재 요청에 대해 이미 로드된 Tool을 숨기는 선택적 요청 인식 후크입니다.

보고

id:

string

'tool-search'로 설정된 프로세서 식별자입니다

name:

string

'Tool Search Processor'로 설정된 프로세서 표시 이름입니다

processInputStep:

(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>

각 단계를 처리하여 검색/로드 메타 Tool과 이전에 로드된 모든 Tool을 Agent의 Tool 집합에 주입합니다.

행동 양식

국정감사(유산'in-memory' store)

이 메서드는 기본 'in-memory' 저장소에서만 작동합니다. 상태를 프로세스 내 맵이 아닌 대화 메시지에 저장하는 'context' 저장소에서는 아무 작업도 하지 않습니다.

clearState(threadId)

단일 스레드에 대한 로드된 Tool 상태를 지웁니다.

processor.clearState('thread-123')

clearAllState()

모든 스레드에 대해 로드된 Tool 상태를 지웁니다.

processor.clearAllState()

getStateStats()

Memory 내 증가를 디버깅하기 위해 추적된 스레드 수와 가장 오래된 액세스 시간을 반환합니다.

const { threadCount, oldestAccessTime } = processor.getStateStats()

보고:{ threadCount: number; oldestAccessTime: number | null }

cleanupNow()

예약된 스윕을 기다리는 대신 즉시 TTL 정리를 실행합니다.

const cleaned = processor.cleanupNow()

반환값: number: 정리된 스레드 수입니다.

요청 인식 필터링

filter를 사용하여 런타임에 정의된 Tool에 요청별 정책을 적용하세요. 후크는 확인된 Tool ID를 toolName으로 받고, Tool, 요청 컨텍스트, 단계도 함께 받습니다. toolName은 search_tools가 반환한 ID이며, tools 객체에 사용된 키와 다를 수 있습니다.

import { ToolSearchProcessor } from '@mastra/core/processors'

const toolSearch = new ToolSearchProcessor({
  tools: allTools,
  filter: ({ toolName, requestContext, phase }) => {
    const plan = requestContext?.get('plan')

    if (phase === 'search') {
      return true
    }

    return plan === 'pro' || !toolName.startsWith('premium_')
  },
})

phase 값은 필터가 적용되는 위치를 나타냅니다.

• search: search_tools가 반환한 결과를 필터링합니다.
• load: 허용되지 않은 Tool을 load_tool이 로드하지 못하도록 차단합니다.
• active: 이미 로드된 Tool이 더 이상 허용되지 않을 경우 현재 요청에서 숨깁니다. 후크가 오류를 발생시키거나 거부되면 ToolSearchProcessor는 해당 요청에서 그 Tool을 허용되지 않은 것으로 처리합니다. 후크는 일치하는 모든 검색 후보에 대해 실행될 수 있으므로 비동기 정책 검사는 빠르게 처리하거나 캐시하세요. search_tools 메타 Tool은 항상 사용할 수 있습니다. search.autoLoad가 활성화되지 않은 경우 load_tool도 사용할 수 있습니다. Agent 또는 processInputStep을 통해 직접 전달된 Tool은 ToolSearchProcessor 외부에서 필터링하거나 includeResolvedTools를 활성화하지 않는 한 계속 사용할 수 있습니다.

요청 해결 Tool 검색

tools 옵션은 생성 시 고정되므로 요청별로만 존재하는 Tool(호출자의 자격 증명이 필요한 MCP Tool 또는 동적 tools 함수가 반환한 모든 항목)을 나열할 수 없습니다. 기본적으로 이러한 Tool은 검색을 우회하고 매 턴마다 Prompt 공간을 차지합니다. 요청에 대해 해당 Tool을 인덱싱하고 Agent가 로드할 때까지 Prompt에서 제외하려면 includeResolvedTools: true를 설정하세요.

src/mastra/agents/mcp-agent.ts

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

const toolSearch = new ToolSearchProcessor({
  tools: staticTools,
  includeResolvedTools: true,
})

const agent = new Agent({
  id: 'mcp-agent',
  name: 'mcp-agent',
  instructions: 'Search for a tool when you need a capability you do not have.',
  model: 'openai/gpt-5.6-sol',
  // Resolved per request, then searchable alongside staticTools
  tools: async ({ requestContext }) => mcpClient.getTools(requestContext.get('userToken')),
  inputProcessors: [toolSearch],
})

각 요청은 자체적으로 색인화되므로 한 호출자가 로드한 Tool은 동일한 Tool 이름의 다른 호출자의 인스턴스로 확인되지 않습니다.

이 옵션은 Memory, Workspace, Skill 및 브라우저 Tool을 포함하여 요청에 대해 확인된 모든 Tool에 적용됩니다. search_tools 및 load_tool 메타 Tool만 Prompt에 남으므로 Agent가 암묵적으로 의존하는 Tool도 호출하기 전에 검색을 통해 찾아야 합니다.

확장된 사용 예

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({
  id: 'dynamic-tools-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-5.6-sol',
  inputProcessors: [toolSearch],
})

Agent Workflow는 다음과 같습니다.

1. Agent가 사용자 메시지를 받습니다.
2. Agent가 키워드(예: "github issue")로 search_tools를 호출합니다
3. Agent가 결과를 검토하고 Tool 이름으로 load_tool을 호출합니다
4. 로드된 Tool은 다음 턴부터 사용할 수 있습니다.
5. Agent가 로드된 Tool을 정상적으로 사용합니다.

단일 단계 검색autoLoad

별도의 로드 단계를 생략하려면 search.autoLoad를 true로 설정하세요. search_tools가 반환한 Tool이 즉시 활성화되고 load_tool 메타 Tool은 노출되지 않습니다. 이렇게 하면 검색할 때마다 Model 턴이 하나 줄어 토큰 사용량과 지연 시간이 감소하며, 모든 Provider에서 동일하게 작동합니다.

const toolSearch = new ToolSearchProcessor({
  tools: allTools,
  search: {
    topK: 3,
    autoLoad: true,
  },
})

autoLoad를 사용하면 Workflow는 다음과 같이 바뀝니다.

1. Agent가 사용자 메시지를 받습니다.
2. Agent가 키워드로 search_tools를 호출합니다
3. 일치하는 Tool이 자동으로 활성화되어 다음 턴부터 사용할 수 있습니다.
4. Agent가 Tool을 정상적으로 사용합니다. 일치하는 모든 Tool이 활성화되므로 Agent에 필요하지 않은 Tool까지 추가되지 않도록 topK를 작게 유지하세요(예: 3). 활성화된 Tool은 기존 Tool 뒤에 추가되므로 Prompt 캐싱을 지원하는 Provider에서 캐시된 Prompt 접두사가 안정적으로 유지됩니다.

로드된 Tool 보관

storage 옵션은 로드된 Tool 집합을 추적할 위치를 제어합니다. 기본값은 'in-memory'입니다. 'context' 저장소는 명시적으로 선택해야 합니다.

'in-memory'(기본)

로드된 Tool은 스레드별 인메모리 맵에서 추적되며, ttl 옵션(기본값 1시간)에 따라 TTL 기반으로 정리됩니다. 이는 기존 동작입니다.

• Memory 구성이 필요하지 않습니다.
• 프로세스를 다시 시작하면 상태가 손실됩니다.
• 스레드 ID가 없는 요청은 단일 스레드를 공유합니다.'default' entry.

clearState, clearAllState, getStateStats, cleanupNow를 사용하여 이 저장소를 검사하거나 초기화하세요.

'context'

로드 상태는 대화 메시지에서 파생됩니다. Tool 이름을 포함하는 search_tools 또는 load_tool 결과가 메시지에 남아 있는 동안 해당 Tool이 로드됩니다. 이 모드는 다음과 같습니다.

• Memory 구성이 필요하지 않습니다.
• 다시 시작해도 안전합니다. 지속 가능한 기록은 지속되는 메시지 기록입니다.
• 해당 결과가 더 이상 메시지에 없으면 Tool을 자동으로 디로드합니다.

import { ToolSearchProcessor } from '@mastra/core/processors'

const toolSearch = new ToolSearchProcessor({
  tools: allTools,
  storage: 'context',
})

로드 Tool은 두 모드 모두에서 캐시 친화적입니다. 로드는 추가 전용이므로 캐시된 Prompt 접두사는 Prompt 캐싱을 지원하는 공급자에 대해 안정적으로 유지됩니다.

Tool을 언로드하면 Model에 전송되는 Tool 정의가 변경되어 캐시된 접두사가 이동하고, 다음 턴에는 캐시 적중 대신 캐시 쓰기 비용이 발생합니다. 'in-memory' 모드에서는 ttl에 따라 스레드 상태가 제거될 때 이런 일이 발생합니다. 'context' 모드에서는 Tool 검색 결과가 메시지에 더 이상 존재하지 않을 때(예: 오래된 메시지가 잘릴 때) 발생합니다. Tool이 언로드되며, 다시 사용하려면 Model이 해당 Tool을 다시 검색해야 합니다. 이는 예상된 동작입니다. 사용하지 않는 Tool을 제거하면 캐시 쓰기 한 번을 감수하는 대신 이후 턴의 접두사가 더 작아집니다.

다른 프로세서와 결합

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

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

관련된

• 프로세서
• Tool 사용