Claude Agent SDK를 위한 AI SDK Provider

최신 릴리스: 버전 4.x는 Claude Agent SDK와 함께 AI SDK v7 안정 버전을 지원합니다. 버전 3.x는 ai-sdk-v6 태그 아래에서 AI SDK v6의 유지보수 단계로 전환됩니다.

ai-sdk-provider-claude-code를 사용하면 공식 @anthropic-ai/claude-agent-sdk와 Claude Code CLI를 통해 Vercel AI SDK로 클로드(Claude)를 사용할 수 있습니다.

버전 호환성

제공자 버전	AI SDK 버전	기반 SDK	NPM 태그	상태	브랜치
4.x.x	v7	`@anthropic-ai/claude-agent-sdk`	`latest`	Stable	`main`
...
Claude Code CLI: provider 4.3.3은 정확한 `@anthropic-ai/[email protected]` 고정(pin)을 통해 최신 CLI 릴리스인 Claude Code CLI `2.1.283`(2026-09-25)를 번들합니다. 만약 `pathToClaudeCodeExecutable`을 통해 자체 바이너리를 실행하는 경우, 개별 설정에 명시된 최소 Claude Code 버전을 확인하십시오.

각 줄의 설치 명령어는 아래 Installation에서 확인할 수 있습니다.

Zod 호환성

4.x 라인은 Zod ^4.1.8을 요구합니다. 버전 3.x는 ai-sdk-v6 태그를 통해 AI SDK v6용으로 계속 사용할 수 있습니다.

npm install ai-sdk-provider-claude-code ai zod@^4.1.8

참고: Zod 3 지원은 기반 @anthropic-ai/[email protected]가 Zod 4를 요구함에 따라 v3.2.0에서 제외되었습니다. Zod 3 지원이 필요하면 [email protected]를 사용하십시오.

설치 (Installation)

1. CLI 설치 및 인증

플랫폼별 옵션은 공식 문서를 참조하십시오.

curl -fsSL https://claude.ai/install.sh | bash
claude auth login

2. 제공자 추가 (Add the provider)

# AI SDK v7용 (4.x; 현재 최신 태그)
npm install ai-sdk-provider-claude-code ai

...

면책 조항 (Disclaimer)

이것은 비공식 커뮤니티 제공자이며 Anthropic 또는 Vercel과 제휴하거나 보증하지 않습니다. 이 제공자를 사용함으로써 다음 사항에 동의합니다:

귀하의 데이터가 Claude Agent SDK를 통해 Anthropic 서버로 전송된다는 점을 이해합니다.
Anthropic 서비스 약관을 준수하는 데 동의합니다.
이 소프트웨어는 어떠한 종류의 보증 없이 "있는 그대로(as is)" 제공됨을 인지합니다.

이 프로바이더를 사용할 때는 적절한 권한을 가지고 있으며 모든 적용 가능한 약관을 준수해야 합니다.

빠른 시작 (Quick Start)

AI SDK v7 (`latest`)

// npm install ai-sdk-provider-claude-code ai
import { streamText } from 'ai';
import { claudeCode } from 'ai-sdk-provider-claude-code';
...

AI SDK v6 (maintenance)

// npm install ai-sdk-provider-claude-code@ai-sdk-v6 ai@^6.0.0
import { streamText } from 'ai';
import { claudeCode } from 'ai-sdk-provider-claude-code';
...

AI SDK v5

// npm install ai-sdk-provider-claude-code@ai-sdk-v5 ai@^5.0.0
import { streamText } from 'ai';
import { claudeCode } from 'ai-sdk-provider-claude-code';
...

주요 변경 사항 (Breaking Changes)

Version 4.0.0 (AI SDK v7)

이 릴리스는 프로바이더를 AI SDK v7 / LanguageModelV4로 포팅하고, 첫 번째 등급의 Claude Agent SDK 콜백(callback), 쿼리 컨트롤러(query-controller), MCP 및 이미지 지원을 추가하며, v7 지원 경계를 명시적으로 유지합니다:

Node.js ≥ 22 및 Zod ^4.1.8 요구됨
ESM 전용 패키지 출력; CommonJS의 require()는 더 이상 사용 불가능함
도구 실패(Tool failures)는 이제 프로바이더별 tool-error 스트림 확장 대신, isError: true를 가진 spec tool-result 파트/이벤트를 사용합니다.

구현되지 않은 선택적 AI SDK v7 표면 (Optional AI SDK v7 surfaces not implemented)

Version 4.0.0은 Claude Agent SDK가 영구적인 프로바이더 참조 매핑(durable provider-reference mapping)을 가지고 있지 않는 한, 선택적 프로바이더 표면이 의도적으로 누락되어 있습니다.

ProviderV4.files()는 아직 구현되지 않았습니다. AI SDK 인터페이스는 { type: 'data' } 또는 { type: 'text' } 바이트를 업로드하고 재사용 가능한 Provider 참조를 반환하지만, Claude Agent SDK 0.3.283은 해당 계약에 대한 직접적인 업로드/재사용 API를 노출하지 않습니다. 이 Provider는 프롬프트 내에서 인라인 이미지 파일 부분을 전달하며, 비(非) 이미지 인라인 파일(예: PDF)은 지원되지 않는 파일 호출 경고를 발생시키고 전달되지 않습니다. 또한 영구적인 Provider 참조에 파일을 업로드하지 않습니다.
표준 V4 툴 결과 파일 부분(tool-result file parts)은 [File <name>: <mediaType>]과 같은 텍스트 마커로 대화 기록에 재연됩니다. 원본 파일 바이트는 재연 시 다시 전송되지 않습니다. 실제 이미지/파일 바이트를 툴 결과 파일 부분으로 다시 보내는 것과 같은 더 풍부한 툴 결과 파일 재연은 보류되었습니다.
ProviderV4.skills() 역시 아직 구현되지 않았습니다. Claude Code 스킬은 아래의 기존 skills 설정을 사용하여 구성된 사용자/프로젝트/로컬 스킬 디렉토리에서 로드됩니다. 스킬 번들(skill bundle)을 업로드하고 AI SDK Provider 참조를 반환하는 Agent SDK API는 없습니다.
워크플로우 직렬화(Workflow serialization)는 보류되었습니다. @ai-sdk/[email protected]은 AI SDK v7 스택의 Provider 모델 클래스에 대해 WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE, 그리고 serializeModelOptions()를 노출하지만, 이 Provider는 Provider 인스턴스나 설정에 대한 직렬화 계약을 추가하지 않았습니다. canUseTool, 훅(hooks), logger, spawnClaudeCodeProcess, 및 SessionStore 메서드와 같은 콜백/함수 설정은 JSON-직렬화가 불가능하며 애플리케이션에 의해 재구성되어야 합니다.
V4의 custom 및 reasoning-file 부분은 아직 Provider 출력으로 방출되지 않습니다. Claude Agent SDK 0.3.283은 AI SDK의 reasoning-file과 매핑되는 영구적인 추론 파일(reasoning-file) 아티팩트 출력이 없습니다. 어시스턴트 기록(assistant-history)의 custom 및 reasoning-file 부분에는 Claude Code 재연 표현이 없어 건너뛰어지며 (알 수 없는 지원되지 않는 콘텐츠 변형은 여전히 경고를 발생시킵니다).

Version 3.0.0 (AI SDK v6 Stable)

이 버전에서는 Provider 유형이 업데이트된 AI SDK v6 안정화 버전으로 업그레이드됩니다:

**usage.raw**는 이제 원시 제공업체 사용량(이전에는 providerMetadata['claude-code'].rawUsage에 있었음)을 포함합니다.
LanguageModelV3Usage 및 LanguageModelV3FinishReason의 내부 타입 변경 사항이 있습니다(대부분의 사용자에게는 투명함).

버전 2.0.0 (Claude Agent SDK 마이그레이션)

본 버전은 더 나은 제어를 위한 새로운 기본값과 함께 @anthropic-ai/claude-agent-sdk로 마이그레이션합니다:

**시스템 프롬프트(System prompt)**가 더 이상 기본적으로 적용되지 않습니다.
파일시스템 설정(CLAUDE.md, settings.json)이 더 이상 기본적으로 로드되지 않습니다.
마이그레이션 세부 정보는 아래 Claude Agent SDK로 마이그레이션하기 섹션을 참조하십시오.

버전 1.x (AI SDK v5)

v0.x에서 v1.x로 마이그레이션하는 자세한 내용은 Breaking Changes Guide를 참조하십시오.

주요 변경 사항:

AI SDK v5가 필요합니다.
새로운 스트리밍 API 패턴이 도입되었습니다.
토큰 사용량 속성이 업데이트되었습니다.
메시지 유형이 변경되었습니다.

모델

fable - Claude Fable (가장 뛰어남)
opus - Claude Opus (매우 뛰어남)
sonnet - Claude Sonnet (균형 잡힌 성능)
haiku - Claude Haiku (가장 빠르고, 가장 비용 효율적)

직접 전체 모델 식별자(예: claude-fable-5, claude-sonnet-4-6, claude-opus-4-8)를 사용할 수도 있습니다.

문서화

세션 관리 - 세션 생성, 재개, 포크(forking), 검사 및 삭제
예제 - 샘플 스크립트 및 패턴
사용 가이드 - 종합적인 예제 및 구성 (Provider 2.x / AI SDK v5용으로 작성됨; 대부분의 패턴은 여전히 적용 가능)
문제 해결 - 일반적인 문제 및 해결 방법 (Provider 2.x / AI SDK v5용으로 작성됨)
도구 스트리밍 지원 - 이벤트 의미론 및 성능 참고 사항 (Provider 2.x / AI SDK v5용으로 작성됨)
Breaking Changes - v0.x에서 v1.x로의 마이그레이션 가이드 (역사적 자료)

docs/ai-sdk-v4/ 및 docs/ai-sdk-v5/ 디렉토리는 레거시 프로바이더 버전(각각 0.x 및 1.x–2.x)을 다루며 참고용으로 유지됩니다.

Claude Agent SDK로 마이그레이션 (v2.0.0)

Version 2.0.0은 @anthropic-ai/claude-code에서 @anthropic-ai/claude-agent-sdk로 마이그레이션됩니다. 두 가지 기본 설정이 변경되었습니다:

시스템 프롬프트(System prompt)가 더 이상 기본적으로 적용되지 않습니다.
파일시스템 설정(CLAUDE.md, settings.json)이 기본적으로 로드되지 않습니다.

기존 동작을 명시적으로 복원하려면:

import { claudeCode } from 'ai-sdk-provider-claude-code';

const model = claudeCode('sonnet', {
...

CLAUDE.md 파일은 다음을 요구합니다:

systemPrompt: { type: 'preset', preset: 'claude_code' }
settingSources에 'project'가 포함되어야 합니다.

새로운 권장 동작 (명시적 설정):

const model = claudeCode('sonnet', {
  systemPrompt: 'You are a helpful assistant specialized in ...',
  settingSources: ['project'], // 또는 파일시스템 설정을 사용하지 않으려면 생략
...

CLI 설치 및 인증은 변경되지 않았습니다:

curl -fsSL https://claude.ai/install.sh | bash
claude auth login

v1.x에서 v2.0.0으로 마이그레이션하기

버전 1.x에서 업그레이드하는 경우 다음을 따르십시오:

패키지 업데이트: npm install ai-sdk-provider-claude-code@ai-sdk-v5

기본 시스템 프롬프트 또는 CLAUDE.md에 의존한 경우, 명시적 설정을 추가하십시오:

const model = claudeCode('sonnet', {
  systemPrompt: { type: 'preset', preset: 'claude_code' },
  settingSources: ['user', 'project', 'local'],

...

3. **CLAUDE.md 또는 사용자 지정 시스템 프롬프트를 사용한 적이 없는 경우**, 변경할 필요가 없습니다. v2.0.0은 이전과 동일하게 작동합니다.

**v2.0.0의 이점**: 

- 환경 전반에 걸친 예측 가능한 동작 (숨겨진 파일시스템 설정 없음)
- CI/CD 및 멀티 테넌트 애플리케이션에 더 적합함
- 암묵적인 기본값보다 명시적 구성 선호
- Claude Agent SDK 디자인과의 미래 지향적 정렬

## Structured Outputs

이 프로바이더는 Claude Agent SDK의 `outputFormat` 옵션을 통해 **네이티브 구조화된 출력(native structured outputs)**을 지원합니다. CLI가 모델의 답변을 스키마와 검증하고, 불일치 시 모델에게 재시도하도록 요청합니다. 4.x 버전대(AI SDK v7)에서는 `generateText()`를 사용하며, 이때 `Output.object({ schema })`와 같은 `output` 사양을 지정한 후, 결과에서 `output`을 디스트럭처링해야 합니다. 동일한 `output` 설정을 사용하여 `streamText()`를 사용하는 것도 가능하며, 부분 객체가 전달되는 방식은 [스트리밍 구조화된 출력](#streaming-structured-output)을 참조하십시오.

```typescript
import { generateText, Output } from 'ai';
import { claudeCode } from 'ai-sdk-provider-claude-code';
import { z } from 'zod';
...

장점 (Benefits):

✅ 스키마 준수(Schema compliance) (지원 기능) - CLI가 출력물을 스키마와 검증합니다.
✅ JSON 파싱 오류 없음 - AI SDK가 사용자의 스키마에 대한 유효성 검사를 처리합니다.
✅ 프롬프트 엔지니어링 불필요 - 스키마 강제 적용이 SDK에 네이티브로 내장되어 있습니다.
✅ 향상된 성능 - 재시도/추출 로직이 필요 없습니다.

Claude Agent SDK를 위한 AI SDK Provider (ben-vargas/ai-sdk-provider-claude-code)

요약

핵심 포인트

Claude Agent SDK를 위한 AI SDK Provider

버전 호환성

Zod 호환성

설치 (Installation)

1. CLI 설치 및 인증

2. 제공자 추가 (Add the provider)

면책 조항 (Disclaimer)

빠른 시작 (Quick Start)

AI SDK v7 (latest)

AI SDK v6 (maintenance)

AI SDK v5

주요 변경 사항 (Breaking Changes)

Version 4.0.0 (AI SDK v7)

구현되지 않은 선택적 AI SDK v7 표면 (Optional AI SDK v7 surfaces not implemented)

Version 3.0.0 (AI SDK v6 Stable)

버전 2.0.0 (Claude Agent SDK 마이그레이션)

버전 1.x (AI SDK v5)

모델

문서화

Claude Agent SDK로 마이그레이션 (v2.0.0)

v1.x에서 v2.0.0으로 마이그레이션하기

댓글

Claude Agent SDK를 위한 AI SDK Provider

버전 호환성

Zod 호환성

설치 (Installation)

1. CLI 설치 및 인증

2. 제공자 추가 (Add the provider)

면책 조항 (Disclaimer)

빠른 시작 (Quick Start)

AI SDK v7 (latest)

AI SDK v6 (maintenance)

AI SDK v5

주요 변경 사항 (Breaking Changes)

Version 4.0.0 (AI SDK v7)

구현되지 않은 선택적 AI SDK v7 표면 (Optional AI SDK v7 surfaces not implemented)

Version 3.0.0 (AI SDK v6 Stable)

버전 2.0.0 (Claude Agent SDK 마이그레이션)

버전 1.x (AI SDK v5)

모델

문서화

Claude Agent SDK로 마이그레이션 (v2.0.0)

v1.x에서 v2.0.0으로 마이그레이션하기

AI SDK v7 (`latest`)

AI SDK v7 (`latest`)