Provider 도구

대부분의 프로바이더는 사용자가 정의한 함수 호출 외에도 웹 검색, 코드 실행, 컴퓨터 사용, 호스팅 검색 등을 비롯한 네이티브 도구를 제공합니다. TanStack AI는 각 프로바이더의 네이티브 도구를 어댑터 패키지별 전용 /tools 하위 경로에서 내보냅니다.

이미 어댑터를 연결했다고 가정합니다. 모델에 프로바이더 네이티브 기능(예: Anthropic 웹 검색)을 제공하면서 지원하지 않는 모델에 도구를 연결하지 않도록 하려는 상황입니다. 이 페이지를 마치면 팩토리를 가져와 chat({ tools: [...] })에 추가하고 지원되지 않는 조합을 잡아내는 컴파일 타임 가드를 이해하게 됩니다.

가져오기

모든 어댑터는 /tools 하위 경로에서 프로바이더 도구를 제공합니다.

import { webSearchTool } from '@tanstack/ai-anthropic/tools'
import { codeInterpreterTool } from '@tanstack/ai-openai/tools'
import { googleSearchTool } from '@tanstack/ai-gemini/tools'

chat({ tools })에서 사용

import { chat } from '@tanstack/ai'
import { anthropicText } from '@tanstack/ai-anthropic'
import { webSearchTool } from '@tanstack/ai-anthropic/tools'

const stream = chat({
  adapter: anthropicText('claude-opus-4-6'),
  messages: [{ role: 'user', content: "Summarize today's AI news." }],
  tools: [
    webSearchTool({
      name: 'web_search',
      type: 'web_search_20250305',
      max_uses: 3,
    }),
  ],
})

네이티브 프로바이더 동작을 선택하는 것은 공개 이름이 아니라 팩토리입니다. web_search, google_search, code_execution이라는 이름의 일반 함수는 사용자 정의 함수로 남습니다. { name: 'web_search', metadata: ... }를 직접 만들어 네이티브 페이로드가 되리라 기대하지 마세요.

이름이 다르면 팩토리 도구와 직접 만든 함수를 같은 chat({ tools }) 호출에 넣을 수 있습니다. 하나의 tools 배열에서 도구 이름은 고유해야 합니다. webSearchTool()과 web_search라는 이름의 직접 만든 함수를 모두 전달하면, chat()은 프로바이더와 통신하기 전에 DuplicateToolNameError를 발생시킵니다.

다중 턴 영속성

프로바이더 도구는 프로바이더 자체 인프라에서 실행되므로 그 결과(예: Anthropic web_search 소스와 web_fetch 페이지 콘텐츠)는 별도의 도구 메시지가 아니라 어시스턴트 턴에 포함되어 반환됩니다. TanStack AI는 이러한 결과를 어시스턴트 메시지에 보존하므로, 이전 대화를 다음 chat() 호출에 다시 전달하면 모델은 이전 근거를 계속 확인할 수 있습니다. 별도의 처리는 필요하지 않습니다.

import { chat, StreamProcessor } from '@tanstack/ai'
import { anthropicText } from '@tanstack/ai-anthropic'
import { webSearchTool } from '@tanstack/ai-anthropic/tools'

const adapter = anthropicText('claude-opus-4-6')
const tools = [webSearchTool({ name: 'web_search', type: 'web_search_20250305' })]

const processor = new StreamProcessor()
for await (const chunk of chat({
  adapter,
  tools,
  messages: [{ role: 'user', content: 'Find two sources on the drone market.' }],
})) {
  processor.processChunk(chunk)
}
processor.finalizeStream()

// The follow-up turn can still cite the previous search results.
const followUp = chat({
  adapter,
  tools,
  messages: [
    ...processor.getMessages(),
    { role: 'user', content: 'List the exact sources you used.' },
  ],
})

검색/가져오기 호출은 어시스턴트 메시지에서 프로바이더가 실행한 tool-call 파트로 나타나며, 에이전트 루프는 이를 클라이언트 측에서 실행하려고 하지 않습니다.

타입 수준 가드

각 프로바이더별 도구 팩토리(예: webSearchTool, computerUseTool)는 ProviderTool<TProvider, TKind> 브랜드를 반환합니다. 어댑터의 toolCapabilities(각 모델의 supports.tools 목록에서 파생됨)는 어떤 브랜드를 tools에 할당할 수 있는지 제한합니다.

computerUseTool(...)을 지원하지 않는 모델에 넣으면 TypeScript는 팩토리 호출이나 런타임이 아니라 해당 배열 요소에서 오류를 보고합니다. 사용자가 정의한 toolDefinition() 도구는 브랜드가 지정되지 않으므로 항상 할당할 수 있습니다. ai-anthropic과 ai-openai에서 내보내는 customTool 팩토리도 일반 Tool(즉, ProviderTool 브랜드가 아님)을 반환하므로 toolDefinition()과 마찬가지로 모든 채팅 모델에서 허용됩니다.

사용 가능한 도구

프로바이더	도구
Anthropic	webSearchTool, webFetchTool, codeExecutionTool, computerUseTool, bashTool, textEditorTool, memoryTool — Anthropic 어댑터를 참조하세요.
OpenAI	webSearchTool, webSearchPreviewTool, fileSearchTool, imageGenerationTool, codeInterpreterTool, mcpTool, computerUseTool, localShellTool, shellTool, applyPatchTool — OpenAI 어댑터를 참조하세요.
Gemini	codeExecutionTool, fileSearchTool, googleSearchTool, googleSearchRetrievalTool, googleMapsTool, urlContextTool, computerUseTool — Gemini 어댑터를 참조하세요.
OpenRouter	webSearchTool, webFetchTool — OpenRouter 어댑터를 참조하세요.
Grok	함수 도구만 지원합니다(프로바이더별 도구는 없습니다).
Groq	함수 도구만 지원합니다(프로바이더별 도구는 없습니다).

어떤 모델이 어떤 도구를 지원하나요?

각 어댑터의 supports.tools 배열이 기준 정보입니다. 비교 매트릭스는 model-meta.ts와 함께 관리되며 이 문서에도 반영됩니다.

• Anthropic: 등록된 모든 모델이 전체 도구 상위 집합을 지원합니다(지원 범위가 더 좁았던 사용 중단된 Claude 3.x 모델은 제거되었습니다).
• OpenAI: GPT-5 제품군과 추론 모델(O 시리즈)은 전체 상위 집합을 지원합니다. GPT-4 시리즈는 웹/파일/이미지/코드/mcp를 지원하지만 preview/shell 변형은 지원하지 않습니다. GPT-3.5 및 오디오 중심 모델은 지원하지 않습니다.
• Gemini: 3.x Pro/Flash 모델은 전체 도구 집합을 지원합니다. Lite와 이미지/동영상 변형은 지원 범위가 더 좁습니다.
• OpenRouter: 모든 채팅 모델이 게이트웨이를 통해 webSearchTool과 webFetchTool을 지원합니다.

모델별 정확한 목록은 어댑터 페이지를 열거나 model-meta.ts에서 해당 모델의 supports.tools 배열을 직접 확인하세요.

프로바이더 스킬

Anthropic과 OpenAI는 프로바이더가 관리하는 호스팅 스킬 번들을 지원하며, 이 번들은 프로바이더의 서버 측 샌드박스에서 실행됩니다. 스킬은 실행 도구(Anthropic의 경우 codeExecutionTool, OpenAI의 경우 shellTool)에 연결되고 ID로 참조되며, 설치와 실행은 프로바이더가 처리합니다.

전체 설정 단계와 예시는 프로바이더 스킬을 참조하세요.

이전 버전에서 마이그레이션

@tanstack/ai-openrouter의 createWebSearchTool을 사용하고 있었다면 마이그레이션 가이드 §6을 참조하세요.