10 개요10 개요
11</h2>11</h2>
12 12
13Claude Code SDK의 이름이 **Claude Agent SDK**로 변경되었으며 설명서가 재구성되었습니다. 이 변경은 코딩 작업을 넘어 AI 에이전트를 구축하기 위한 SDK의 광범위한 기능을 반영합니다.13Claude Code SDK는 **Claude Agent SDK**로 이름이 변경되었으며 설명서가 재구성되었습니다. 이 변경은 코딩 작업을 넘어 AI 에이전트를 구축하기 위한 SDK의 더 광범위한 기능을 반영합니다.
14
15OpenAI Agents SDK에서 마이그레이션하고 있습니까? [OpenAI Agents SDK 마이그레이션 레시피](https://platform.claude.com/cookbook/claude-agent-sdk-04-migrating-from-openai-agents-sdk)는 단일 작업 예제를 통해 각 기본 요소를 Claude Agent SDK에 매핑합니다.
14 16
15<h2 id="what’s-changed">17<h2 id="what’s-changed">
16 변경 사항18 변경 사항
17</h2>19</h2>
18 20
19| 항목 | 이전 | 새로운 |21| 항목 | 이전 | 신규 |
20| :----------------- | :-------------------------- | :------------------------------- |22| :----------------- | :-------------------------- | :--------------------------------------------------------- |
21| **패키지 이름 (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |23| **패키지 이름 (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |
22| **Python 패키지** | `claude-code-sdk` | `claude-agent-sdk` |24| **Python 패키지** | `claude-code-sdk` | `claude-agent-sdk` |
23| **설명서 위치** | Claude Code 문서 | API 가이드 → Agent SDK 섹션 |25| **문서 위치** | Claude Code 문서 | Claude Code 문서 → 전용 [Agent SDK](/docs/ko/agent-sdk/overview) 섹션 |
24
25<Note>
26 **설명서 변경 사항:** Agent SDK 설명서가 Claude Code 문서에서 API 가이드의 전용 [Agent SDK](/ko/agent-sdk/overview) 섹션으로 이동되었습니다. Claude Code 문서는 이제 CLI 도구 및 자동화 기능에 중점을 두고 있습니다.
27</Note>
28 26
29<h2 id="migration-steps">27<h2 id="migration-steps">
30 마이그레이션 단계28 마이그레이션 단계
34 TypeScript/JavaScript 프로젝트의 경우32 TypeScript/JavaScript 프로젝트의 경우
35</h3>33</h3>
36 34
37**1. 이전 패키지 제거:**35**1. 기존 패키지 제거:**
38 36
39```bash theme={null}37```bash theme={null}
40npm uninstall @anthropic-ai/claude-code38npm uninstall @anthropic-ai/claude-code
51`@anthropic-ai/claude-code`에서 `@anthropic-ai/claude-agent-sdk`로 모든 임포트를 변경합니다:49`@anthropic-ai/claude-code`에서 `@anthropic-ai/claude-agent-sdk`로 모든 임포트를 변경합니다:
52 50
53```typescript theme={null}51```typescript theme={null}
54// 이전52// Before
55import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";53import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";
56 54
57// 이후55// After
58import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";56import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
59```57```
60 58
61**4. package.json 의존성 업데이트:**59**4. package.json 업데이트:**
62
63`package.json`에 패키지가 나열되어 있으면 업데이트합니다:
64
65이전:
66
67```json theme={null}
68{
69 "dependencies": {
70 "@anthropic-ai/claude-code": "^0.0.42"
71 }
72}
73```
74
75이후:
76 60
77```json theme={null}61`package.json`에 `@anthropic-ai/claude-code`가 여전히 나열되어 있으면 `@anthropic-ai/claude-agent-sdk`로 바꾸고 버전 범위도 업데이트합니다. 예를 들어 `"^0.0.42"`에서 `"^0.3.0"`으로 변경합니다.
78{
79 "dependencies": {
80 "@anthropic-ai/claude-agent-sdk": "^0.2.0"
81 }
82}
83```
84 62
85**5. [주요 변경 사항](#breaking-changes) 검토**63**5. [주요 변경 사항](#breaking-changes) 검토**
86 64
87마이그레이션을 완료하는 데 필요한 코드 변경을 수행합니다.65마이그레이션을 완료하기 위해 필요한 코드 변경을 수행합니다.
88 66
89<h3 id="for-python-projects">67<h3 id="for-python-projects">
90 Python 프로젝트의 경우68 Python 프로젝트의 경우
91</h3>69</h3>
92 70
93**1. 이전 패키지 제거:**71**1. 기존 패키지 제거:**
94 72
95```bash theme={null}73```bash theme={null}
96pip uninstall claude-code-sdk74pip uninstall -y claude-code-sdk
97```75```
98 76
77기존 패키지가 설치되어 있지 않으면 pip에서 `WARNING: Skipping claude-code-sdk as it is not installed.`를 출력합니다. 이는 정상이며 다음 단계로 진행할 수 있습니다.
78
99**2. 새 패키지 설치:**79**2. 새 패키지 설치:**
100 80
101```bash theme={null}81```bash theme={null}
102pip install claude-agent-sdk82pip install claude-agent-sdk
103```83```
104 84
85`requirements.txt` 또는 `pyproject.toml`에 `claude-code-sdk`가 나열되어 있으면 `claude-agent-sdk`로 바꿉니다.
86
105**3. 임포트 업데이트:**87**3. 임포트 업데이트:**
106 88
107`claude_code_sdk`에서 `claude_agent_sdk`로 모든 임포트를 변경합니다:89`claude_code_sdk`에서 `claude_agent_sdk`로 모든 임포트를 변경합니다:
108 90
109```python theme={null}91```python theme={null}
110# 이전92# Before
111from claude_code_sdk import query, ClaudeCodeOptions93from claude_code_sdk import query, ClaudeCodeOptions
112 94
113# 이후95# After
114from claude_agent_sdk import query, ClaudeAgentOptions96from claude_agent_sdk import query, ClaudeAgentOptions
115```97```
116 98
117**4. 타입 이름 업데이트:**99**4. [주요 변경 사항](#breaking-changes) 검토**
118
119`ClaudeCodeOptions`를 `ClaudeAgentOptions`로 변경합니다:
120 100
121```python theme={null}101마이그레이션을 완료하기 위해 필요한 코드 변경을 수행합니다.
122# 이전
123from claude_code_sdk import query, ClaudeCodeOptions
124
125options = ClaudeCodeOptions(model="claude-opus-4-7")
126
127# 이후
128from claude_agent_sdk import query, ClaudeAgentOptions
129
130options = ClaudeAgentOptions(model="claude-opus-4-7")
131```
132
133**5. [주요 변경 사항](#breaking-changes) 검토**
134
135마이그레이션을 완료하는 데 필요한 코드 변경을 수행합니다.
136 102
137<h2 id="breaking-changes">103<h2 id="breaking-changes">
138 주요 변경 사항104 주요 변경 사항
139</h2>105</h2>
140 106
141<Warning>107<Warning>
142 격리 및 명시적 구성을 개선하기 위해 Claude Agent SDK v0.1.0은 Claude Code SDK에서 마이그레이션하는 사용자를 위한 주요 변경 사항을 도입합니다. 마이그레이션하기 전에 이 섹션을 주의 깊게 검토하십시오.108 격리 및 명시적 구성을 개선하기 위해 Claude Agent SDK v0.1.0은 Claude Code SDK에서 마이그레이션하는 사용자를 위한 주요 변경 사항을 도입합니다.
143</Warning>109</Warning>
144 110
145<h3 id="python-claudecodeoptions-renamed-to-claudeagentoptions">111<h3 id="python-claudecodeoptions-renamed-to-claudeagentoptions">
146 Python: ClaudeCodeOptions를 ClaudeAgentOptions로 이름 변경112 Python: ClaudeCodeOptions가 ClaudeAgentOptions로 이름 변경됨
147</h3>113</h3>
148 114
149**변경 사항:** Python SDK 타입 `ClaudeCodeOptions`의 이름이 `ClaudeAgentOptions`로 변경되었습니다.115**변경 사항:** Python SDK 타입 `ClaudeCodeOptions`가 `ClaudeAgentOptions`로 이름이 변경되었습니다.
150 116
151**마이그레이션:**117**마이그레이션:**
152 118
153```python theme={null}119```python theme={null}
154# 이전 (claude-code-sdk)120# BEFORE (claude-code-sdk)
155from claude_code_sdk import query, ClaudeCodeOptions121from claude_code_sdk import query, ClaudeCodeOptions
156 122
157options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")123options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
158 124
159# 이후 (claude-agent-sdk)125# AFTER (claude-agent-sdk)
160from claude_agent_sdk import query, ClaudeAgentOptions126from claude_agent_sdk import query, ClaudeAgentOptions
161 127
162options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")128options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
163```129```
164 130
165**변경 이유:** 타입 이름이 이제 "Claude Agent SDK" 브랜딩과 일치하며 SDK의 명명 규칙 전체에서 일관성을 제공합니다.
166
167<h3 id="system-prompt-no-longer-default">131<h3 id="system-prompt-no-longer-default">
168 시스템 프롬프트가 더 이상 기본값이 아님132 시스템 프롬프트가 더 이상 기본값이 아님
169</h3>133</h3>
176 ```typescript TypeScript theme={null}140 ```typescript TypeScript theme={null}
177 import { query } from "@anthropic-ai/claude-agent-sdk";141 import { query } from "@anthropic-ai/claude-agent-sdk";
178 142
179 // 이전 (v0.0.x) - 기본적으로 Claude Code의 시스템 프롬프트 사용143 // BEFORE (v0.0.x) - 기본적으로 Claude Code의 시스템 프롬프트를 사용했습니다
180 const before = query({ prompt: "Hello" });144 const before = query({ prompt: "Hello" });
181 145
182 // 이후 (v0.1.0) - 기본적으로 최소 시스템 프롬프트 사용146 // AFTER (v0.1.0) - 기본적으로 최소 시스템 프롬프트를 사용합니다
183 // 이전 동작을 얻으려면 Claude Code의 프리셋을 명시적으로 요청합니다:147 // 이전 동작을 얻으려면 Claude Code의 프리셋을 명시적으로 요청하세요:
184 const presetResult = query({148 const presetResult = query({
185 prompt: "Hello",149 prompt: "Hello",
186 options: {150 options: {
188 }152 }
189 });153 });
190 154
191 // 또는 사용자 정의 시스템 프롬프트를 사용합니다:155 // 또는 사용자 정의 시스템 프롬프트를 사용하세요:
192 const customResult = query({156 const customResult = query({
193 prompt: "Hello",157 prompt: "Hello",
194 options: {158 options: {
198 ```162 ```
199 163
200 ```python Python theme={null}164 ```python Python theme={null}
201 # 이전 (v0.0.x) - 기본적으로 Claude Code의 시스템 프롬프트 사용165 from claude_agent_sdk import query, ClaudeAgentOptions
166 import asyncio
167
168
169 async def main():
170 # BEFORE (v0.0.x) - 기본적으로 Claude Code의 시스템 프롬프트를 사용했습니다
202 async for message in query(prompt="Hello"):171 async for message in query(prompt="Hello"):
203 print(message)172 print(message)
204 173
205 # 이후 (v0.1.0) - 기본적으로 최소 시스템 프롬프트 사용174 # AFTER (v0.1.0) - 기본적으로 최소 시스템 프롬프트를 사용합니다
206 # 이전 동작을 얻으려면 Claude Code의 프리셋을 명시적으로 요청합니다:175 # 이전 동작을 얻으려면 Claude Code의 프리셋을 명시적으로 요청하세요:
207 from claude_agent_sdk import query, ClaudeAgentOptions
208
209 async for message in query(176 async for message in query(
210 prompt="Hello",177 prompt="Hello",
211 options=ClaudeAgentOptions(178 options=ClaudeAgentOptions(
214 ):181 ):
215 print(message)182 print(message)
216 183
217 # 또는 사용자 정의 시스템 프롬프트를 사용합니다:184 # 또는 사용자 정의 시스템 프롬프트를 사용하세요:
218 async for message in query(185 async for message in query(
219 prompt="Hello",186 prompt="Hello",
220 options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),187 options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
221 ):188 ):
222 print(message)189 print(message)
190
191
192 asyncio.run(main())
223 ```193 ```
224</CodeGroup>194</CodeGroup>
225 195
226**변경 이유:** SDK 애플리케이션에 더 나은 제어 및 격리를 제공합니다. 이제 Claude Code의 CLI 중심 지침을 상속하지 않고 사용자 정의 동작으로 에이전트를 구축할 수 있습니다.
227
228<h3 id="settings-sources-default">196<h3 id="settings-sources-default">
229 설정 소스 기본값197 설정 소스 기본값
230</h3>198</h3>
231 199
232이 기본값은 v0.1.0에서 잠시 변경되었다가 되돌려졌으므로 마이그레이션 조치가 필요하지 않습니다.200이 기본값은 v0.1.0에서 파일 시스템 설정을 로드하지 않도록 잠시 변경되었다가 되돌려졌으므로 마이그레이션 조치가 필요하지 않습니다.
233 201
234**현재 동작:** `query()`에서 `settingSources`를 생략하면 CLI와 일치하는 사용자, 프로젝트 및 로컬 파일 시스템 설정이 로드됩니다. 여기에는 `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, CLAUDE.md 파일 및 사용자 정의 명령이 포함됩니다.202**현재 동작:** `query()`에서 `settingSources`를 생략하면 사용자, 프로젝트 및 로컬 파일 시스템 설정을 로드하며, 이는 CLI와 일치합니다. 여기에는 `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, CLAUDE.md 파일 및 사용자 정의 명령이 포함됩니다.
235 203
236파일 시스템 설정에서 격리되어 실행하려면 빈 배열을 전달합니다:204파일 시스템 설정에서 격리된 상태로 실행하려면 `settingSources: []` 또는 Python에서 `setting_sources=[]`를 전달하세요. 각 소스가 로드하는 항목에 대해서는 [settingSources로 파일 시스템 설정 제어](/docs/ko/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources)를 참조하세요.
237 205
238<CodeGroup>206격리는 특히 CI/CD 파이프라인, 배포된 애플리케이션, 테스트 환경 및 로컬 사용자 정의가 유출되지 않아야 하는 다중 테넌트 시스템에서 중요합니다.
239 ```typescript TypeScript theme={null}
240 import { query } from "@anthropic-ai/claude-agent-sdk";
241
242 const isolatedResult = query({
243 prompt: "Hello",
244 options: {
245 settingSources: [] // 파일 시스템 설정이 로드되지 않음
246 }
247 });
248
249 // 또는 특정 소스만 로드합니다:
250 const projectOnlyResult = query({
251 prompt: "Hello",
252 options: {
253 settingSources: ["project"] // 프로젝트 설정만
254 }
255 });
256 ```
257
258 ```python Python theme={null}
259 from claude_agent_sdk import query, ClaudeAgentOptions
260
261 async for message in query(
262 prompt="Hello",
263 options=ClaudeAgentOptions(setting_sources=[]), # 파일 시스템 설정이 로드되지 않음
264 ):
265 print(message)
266
267 # 또는 특정 소스만 로드합니다:
268 async for message in query(
269 prompt="Hello",
270 options=ClaudeAgentOptions(
271 setting_sources=["project"] # 프로젝트 설정만
272 ),
273 ):
274 print(message)
275 ```
276</CodeGroup>
277
278격리는 특히 CI/CD 파이프라인, 배포된 애플리케이션, 테스트 환경 및 로컬 사용자 정의가 유입되지 않아야 하는 다중 테넌트 시스템에 중요합니다.
279 207
280<Note>208<Note>
281 SDK v0.1.0은 잠시 설정이 로드되지 않는 것으로 기본값을 설정했으나 이후 릴리스에서 되돌려졌습니다. Python SDK 0.1.59 이하는 빈 목록을 옵션 생략과 동일하게 처리했으므로 `setting_sources=[]`에 의존하기 전에 업그레이드하십시오. `settingSources`가 `[]`일 때 읽히는 입력에 대해서는 [settingSources가 제어하지 않는 것](/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)을 참조하십시오.209 Python SDK 0.1.59 이하는 빈 목록을 옵션 생략과 동일하게 처리했으므로 `setting_sources=[]`에 의존하기 전에 업그레이드하세요. `settingSources`가 `[]`일 때도 읽혀지는 입력에 대해서는 [settingSources가 제어하지 않는 항목](/docs/ko/agent-sdk/claude-code-features#what-settingsources-does-not-control)을 참조하세요.
282</Note>210</Note>
283 211
284<h2 id="why-the-rename">
285 이름 변경 이유
286</h2>
287
288Claude Code SDK는 원래 코딩 작업을 위해 설계되었지만 모든 유형의 AI 에이전트를 구축하기 위한 강력한 프레임워크로 진화했습니다. 새로운 이름 "Claude Agent SDK"는 그 기능을 더 잘 반영합니다:
289
290* 비즈니스 에이전트 구축 (법률 보조원, 재무 고문, 고객 지원)
291* 전문화된 코딩 에이전트 생성 (SRE 봇, 보안 검토자, 코드 검토 에이전트)
292* 도구 사용, MCP 통합 등으로 모든 도메인에 대한 사용자 정의 에이전트 개발
293
294<h2 id="getting-help">
295 도움말 받기
296</h2>
297
298마이그레이션 중에 문제가 발생하면:
299
300**TypeScript/JavaScript의 경우:**
301
3021. 모든 임포트가 `@anthropic-ai/claude-agent-sdk`를 사용하도록 업데이트되었는지 확인합니다
3032. package.json에 새 패키지 이름이 있는지 확인합니다
3043. `npm install`을 실행하여 의존성이 업데이트되었는지 확인합니다
305
306**Python의 경우:**
307
3081. 모든 임포트가 `claude_agent_sdk`를 사용하도록 업데이트되었는지 확인합니다
3092. requirements.txt 또는 pyproject.toml에 새 패키지 이름이 있는지 확인합니다
3103. `pip install claude-agent-sdk`를 실행하여 패키지가 설치되었는지 확인합니다
311
312<h2 id="next-steps">212<h2 id="next-steps">
313 다음 단계213 다음 단계
314</h2>214</h2>
315 215
316* [Agent SDK 개요](/ko/agent-sdk/overview)를 탐색하여 사용 가능한 기능에 대해 알아봅니다216* [Agent SDK 개요](/docs/ko/agent-sdk/overview)를 탐색하여 사용 가능한 기능에 대해 알아봅니다
317* [TypeScript SDK 참조](/ko/agent-sdk/typescript)를 확인하여 자세한 API 설명서를 봅니다217* [TypeScript SDK 참조](/docs/ko/agent-sdk/typescript)를 확인하여 자세한 API 설명서를 봅니다
318* [Python SDK 참조](/ko/agent-sdk/python)를 검토하여 Python 관련 설명서를 봅니다218* [Python SDK 참조](/docs/ko/agent-sdk/python)를 검토하여 Python 관련 설명서를 봅니다
319* [사용자 정의 도구](/ko/agent-sdk/custom-tools) 및 [MCP 통합](/ko/agent-sdk/mcp)에 대해 알아봅니다219* [사용자 정의 도구](/docs/ko/agent-sdk/custom-tools) 및 [MCP 통합](/docs/ko/agent-sdk/mcp)에 대해 알아봅니다
