본문으로 건너뛰기

프로바이더 스킬

공급자 스킬은 모델이 필요에 따라 로드하여 공급자의 서버 측 샌드박스 내에서 실행하는 호스팅된 공급자 관리 기능 번들입니다. 모델은 스킬 ID 를 참조하며, 공급자가 설치 및 실행을 처리합니다.

@tanstack/ai-code-mode-snippets과 혼동하지 마세요. 해당 스니펫은 애플리케이션이 생성하여 자체 Code Mode 샌드박스(로컬 JS 격리 환경)에서 실행하는 TypeScript 함수입니다. 프로바이더 스킬은 전적으로 프로바이더 인프라에서 실행됩니다.

스킬은 실행 도구 없이는 작동하지 않습니다. 실행 도구가 샌드박스를 활성화하며, 스킬은 그 안에서 실행되는 추가 번들입니다:

  • Anthropic: 스킬은 codeExecutionTool(@tanstack/ai-anthropic/tools)에 연결됩니다.
  • OpenAI: 스킬은 shellTool(@tanstack/ai-openai/tools) 내부에 중첩되며 Responses API가 필요합니다.

이미 작동하는 chat() 호출이 있습니다. 이 페이지를 끝까지 읽으면 호스팅된 스킬을 올바른 실행 도구에 연결하고, 나머지는 provider가 처리하도록 구성할 수 있습니다.

이식 가능한 스킬과 호스팅된 스킬​

TanStack AI에서 모델에 스킬을 제공하는 방법은 두 가지이며, 각각 서로 다른 문제를 해결합니다:

  • 이식 가능한 스킬(withSkills)은 카탈로그를 렌더링하고 모델이 load_skill을 호출하도록 합니다. 모든 도구 호출 모델에서 실행되며, 서버 샌드박스가 필요하지 않고 폴더, 번들 또는 자체 저장소에서 SKILL.md을 읽습니다. 먼저 이 방식을 사용합니다.
  • 호스팅된(provider) 스킬인 이 페이지의 스킬은 provider의 서버 측 샌드박스 내부에서 실행되며 ID로 참조됩니다. 이식할 수 없고 실행 도구가 필요하지만, 실행은 provider가 담당합니다.

provider의 샌드박스가 필요할 때(코드 실행, 파일 생성)는 호스팅된 스킬을 사용합니다. 그 외의 모든 경우에는 이식 가능한 스킬을 사용합니다.

두 방식은 하나의 chat() 호출에서 함께 사용할 수 없습니다. 호스팅된 스킬을 code_execution 또는 shell 도구에 연결하면서 withSkills도 추가하면 미들웨어가 예외를 발생시킵니다. 모델이 두 개의 카탈로그와 두 개의 프로토콜을 보게 되기 때문입니다. 호출마다 하나의 제공 방식만 선택합니다.

Anthropic: codeExecutionTool을 통한 스킬​

1. 패키지 설치​

npm install @tanstack/ai-anthropic

2. 스킬과 함께 codeExecutionTool 추가​

어댑터 루트가 아니라 codeExecutionTool를 @tanstack/ai-anthropic/tools에서 가져옵니다. 두 번째 인수로 skills 배열을 전달합니다.

import { chat, toServerSentEventsResponse } from '@tanstack/ai'
import { anthropicText } from '@tanstack/ai-anthropic'
import { codeExecutionTool } from '@tanstack/ai-anthropic/tools'

export async function POST(request: Request) {
  const { messages } = await request.json()

  const stream = chat({
    adapter: anthropicText('claude-sonnet-4-5'),
    messages,
    tools: [
      codeExecutionTool(
        { type: 'code_execution_20250825', name: 'code_execution' },
        {
          skills: [{ type: 'anthropic', skill_id: 'pptx', version: 'latest' }],
        },
      ),
    ],
  })

  return toServerSentEventsResponse(stream)
}

어댑터가 자동으로 수행하는 작업:

  • 스킬을 요청의 최상위 container.skills 매개변수로 올립니다 (Anthropic API에 필요한 형태입니다).
  • code-execution-2025-08-25 베타 헤더를 추가하고, 스킬이 있으면 skills-2025-10-02 베타 헤더도 추가합니다.

베타 헤더를 수동으로 설정하지 않습니다.

스킬 형태​

skills 배열의 각 항목은 AnthropicContainerSkill입니다:

필드타입필수비고
type'anthropic' | 'custom'예Anthropic 호스팅 스킬에는 'anthropic', 자체 번들에는 'custom'입니다.
skill_idstring예1~64자입니다.
versionstring아니요특정 버전 문자열이거나 'latest'입니다(생략하면 기본값).

요청당 최대 8개의 스킬을 사용할 수 있습니다. 이 한도를 초과하거나 잘못된 skill_id를 제공하면 팩토리가 호출 시 예외를 발생시킵니다.

지원 중단 안내​

modelOptions.container.skills 를 통해 스킬을 설정하는 것은 더 이상 지원되지 않습니다. codeExecutionTool(config, { skills }) 를 사용하세요 — 기존 경로는 자동 베타 헤더 와이어링 을 우회합니다.

OpenAI: shellTool 를 통한 스킬 (Responses API 만 지원)​

OpenAI shellTool 는 environment 객체를 받아들이며, 이 객체는 skills 배열을 포함할 수 있습니다. 이는 Responses API 전용이며, Chat Completions API 는 shell 도구를 지원하지 않습니다.

1. 패키지를 설치합니다​

npm install @tanstack/ai-openai

2. shellTool 에 스킬을 추가합니다​

import { chat, toServerSentEventsResponse } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
import { shellTool } from '@tanstack/ai-openai/tools'

export async function POST(request: Request) {
  const { messages } = await request.json()

  const stream = chat({
    adapter: openaiText('gpt-5.2'),
    messages,
    tools: [
      shellTool({
        environment: {
          type: 'container_auto',
          skills: [
            { type: 'skill_reference', skill_id: 'skill_abc', version: '2' },
          ],
        },
      }),
    ],
  })

  return toServerSentEventsResponse(stream)
}

스킬 모양​

skills 배열의 각 항목은 SkillReference 입니다:

필드유형필수주석
type'skill_reference'예OpenAI 에 대해 항상 'skill_reference' 합니다.
skill_idstring예OpenAI 가 제공하는 스킬 식별자입니다.
versionstringno'2' 문자열로 된 양의 정수 또는 'latest'.

참고: version 은 숫자가 아닌 문자열입니다.

범위​

이 공장들은 호스팅되고 id 로 관리되는 스킬만 연결합니다:

  • Anthropic: type: 'anthropic' 또는 type: 'custom'
  • OpenAI: type: 'skill_reference'

인라인 번들, 로컬 경로 참조, 및 업로드 API 스킬 생성은 codeExecutionTool 또는 shellTool 에서 처리되지 않습니다.