도구 검색
도구 검색 (Tool Search)
ToolSearch 캐퍼빌리티는 defer_loading=True로 표시된 검색 가능 도구의 모델 주도 발견(detection)을 처리해요. 도구셋이 큰 에이전트는 모델이 필요로 하는 도구에만 토큰을 지불할 수 있게 됩니다. 위의 provider-adaptive tools처럼 활성 모델에 가장 좋은 경로를 골라요 — Anthropic과 OpenAI Responses에서는 네이티브 서버 실행 검색, 그 외에서는 로컬 search_tools 함수 도구 — 그리고 검색 가능한 지연 도구가 존재하면 모든 에이전트에 자동 주입됩니다. 번들 수준의 공개(disclosure)는 온디맨드 캐퍼빌리티가 담당해요.
출처: 문서
본문
기본 id로 'tool_search'를 선언하므로, 두 인스턴스는 중복 id 오류를 내는 대신 하나로 병합됩니다 — 병합 규칙은 커스텀 캐퍼빌리티 만들기를 참고하세요.
명시적인 ToolSearch를 전달하면 특정 strategy ('keywords', 'bm25', 'regex', 또는 커스텀 callable)를 고르거나 로컬 폴백을 조정할 수 있어요:
from pydantic_ai import Agent
from pydantic_ai.capabilities import ToolSearch
agent = Agent('anthropic:claude-sonnet-4-6', capabilities=[ToolSearch(strategy='keywords')])
로컬 search_tools 함수 도구가 사용될 때, 그 재시도 예산은 에이전트의 도구 예산을 따릅니다 — 그래서 Agent(retries={'tools': N})는 모델에게 잘못된 queries 인수를 바로잡을 N번의 시도를 주는데, 다른 도구와 같은 우선순위 사다리를 따릅니다. 결과를 찾지 못한 검색은 정상적으로 반환되며 재시도를 소모하지 않아요.
언제 사용해야 하는지, 전체 전략 표, 공급자 지원 세부 사항은 Tool Search를 참고하세요.