Agent SDK TypeScript 레퍼런스
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
TypeScript/JavaScript Agent SDK API 레퍼런스입니다. 패키지는 플랫폼별 Claude Code 네이티브 바이너리를 optional dependency로 포함합니다.
npm install @anthropic-ai/claude-agent-sdk
단일 실행 파일로 묶는 빌드 패턴은 공식 "Compile to a single executable" 절을 참고하세요.
핵심 개념
query(): 메인 진입점. string 또는AsyncIterable<SDKUserMessage>프롬프트startup()/ WarmQuery: 워밍·재사용 연결tool()/createSdkMcpServer(): 커스텀 도구·인프로세스 MCP- 세션 헬퍼:
listSessions,getSessionMessages,getSessionInfo,renameSession,tagSession resolveSettings(): 설정 해석
V2 session API(unstable_v2_*)는 제거되었습니다. multi-turn은 async iterable 또는 resume을 사용하세요.
상세
query()
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Summarize the repo structure",
options: {
model: "claude-sonnet-4-5",
allowedTools: ["Read", "Glob", "Grep"],
settingSources: ["project"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
반환 Query 객체는 async iterable이며 interrupt, rewindFiles 등 제어 메서드를 제공할 수 있습니다.
주요 Options 필드 (개념)
model,fallbackModel,permissionMode,allowedTools/tools/disallowedToolssystemPrompt(string | preset)settingSources,mcpServers,plugins,agents,hookscwd,resume,continue,maxTurnsenableFileCheckpointing,extraArgs,envcanUseTool권한 콜백- effort/thinking/budget 관련 옵션
타입 하이라이트
| 타입 | 역할 |
|---|---|
SettingSource |
user/project/local |
PermissionMode |
권한 전략 |
CanUseTool / PermissionResult |
런타임 승인 |
AgentDefinition |
서브에이전트 정의 |
McpServerConfig / SdkPluginConfig |
MCP·플러그인 |
SDKMessage 유니온 |
assistant/user/result/system/partial/... |
HookEvent / HookCallback / HookInput / HookJSONOutput |
훅 |
ToolInputSchemas |
Agent, Bash, Edit, Read 등 도구 입력 |
메시지 타입
스트림은 SDKAssistantMessage, SDKUserMessage, SDKResultMessage, SDKSystemMessage, partial/compact/permission/plugin 관련 메시지 등을 포함합니다. UI·로깅은 type/subtype 분기로 처리합니다.
훅
TypeScript는 Python보다 넓은 이벤트 집합(SessionStart/End, TaskCompleted, Elicitation 등)을 지원합니다. matcher + callback 배열로 등록합니다.
도구 입력
ToolInputSchemas로 Bash.command, Edit 경로, Agent 프롬프트 등 타입 안전 접근이 가능합니다.
체크리스트
-
@anthropic-ai/claude-agent-sdk최신 권장 버전 - V2 API 잔존 import 제거
- multi-turn은 generator 또는 resume
- result error throw를 try/catch
- 전체 시그니처는 공식 페이지 대조