6 6
7> Claude Code를 라이브러리로 사용하여 프로덕션 AI 에이전트 구축하기7> Claude Code를 라이브러리로 사용하여 프로덕션 AI 에이전트 구축하기
8 8
9자율적으로 파일을 읽고, 명령을 실행하고, 웹을 검색하고, 코드를 편집하는 등의 작업을 수행하는 AI 에이전트를 구축하십시오. Agent SDK는 Claude Code를 강화하는 동일한 도구, 에이전트 루프 및 컨텍스트 관리를 Python 및 TypeScript로 프로그래밍할 수 있도록 제공합니다. 에이전트 하네스 설계의 배경에 대해서는 블로그의 [A harness for every task: dynamic workflows in Claude Code](https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code)를 참조하십시오.9에이전트는 자신의 단계를 계획하고 파일을 읽거나, 명령을 실행하거나, 코드를 편집하는 도구를 호출하여 작업을 완료하는 애플리케이션입니다. Agent SDK는 Claude Code를 강화하는 동일한 도구, [에이전트 루프](/docs/ko/agent-sdk/agent-loop), 및 컨텍스트 관리를 Python 및 TypeScript로 프로그래밍할 수 있도록 제공합니다.
10 10
11<CodeGroup>11<h2 id="compare-the-agent-sdk-to-other-claude-tools">
12 ```python Python theme={null}12 Agent SDK를 다른 Claude 도구와 비교
13 import asyncio
14 from claude_agent_sdk import query, ClaudeAgentOptions
15
16
17 async def main():
18 async for message in query(
19 prompt="Find and fix the bug in auth.py",
20 options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
21 ):
22 print(message) # Claude reads the file, finds the bug, edits it
23
24
25 asyncio.run(main())
26 ```
27
28 ```typescript TypeScript theme={null}
29 import { query } from "@anthropic-ai/claude-agent-sdk";
30
31 for await (const message of query({
32 prompt: "Find and fix the bug in auth.ts",
33 options: { allowedTools: ["Read", "Edit", "Bash"] }
34 })) {
35 console.log(message); // Claude reads the file, finds the bug, edits it
36 }
37 ```
38</CodeGroup>
39
40Agent SDK에는 파일 읽기, 명령 실행 및 코드 편집을 위한 기본 제공 도구가 포함되어 있으므로 도구 실행을 직접 구현하지 않고도 에이전트가 즉시 작업을 시작할 수 있습니다. 빠른 시작을 살펴보거나 SDK로 구축한 실제 에이전트를 탐색하십시오:
41
42<CardGroup cols={2}>
43 <Card title="빠른 시작" icon="play" href="/ko/agent-sdk/quickstart">
44 몇 분 안에 버그 수정 에이전트 구축하기
45 </Card>
46
47 <Card title="예제 에이전트" icon="star" href="https://github.com/anthropics/claude-agent-sdk-demos">
48 이메일 어시스턴트, 연구 에이전트 등
49 </Card>
50</CardGroup>
51
52<h2 id="get-started">
53 시작하기
54</h2>13</h2>
55 14
56<Steps>15Agent SDK, CLI, Client SDK, Managed Agents는 각각 다른 요구사항에 맞습니다. 구축 중인 것에 맞는 도구를 찾으려면 표를 사용하십시오.
57 <Step title="SDK 설치">
58 <Tabs>
59 <Tab title="TypeScript">
60 ```bash theme={null}
61 npm install @anthropic-ai/claude-agent-sdk
62 ```
63 </Tab>
64
65 <Tab title="Python (uv)">
66 [uv](https://docs.astral.sh/uv/)는 가상 환경을 자동으로 처리하는 빠른 Python 패키지 관리자입니다:
67
68 ```bash theme={null}
69 uv init
70 uv add claude-agent-sdk
71 ```
72 </Tab>
73
74 <Tab title="Python (pip)">
75 가상 환경을 생성하고 활성화한 다음 패키지를 설치합니다. 가상 환경에 설치하면 최근 Debian, Ubuntu 및 Homebrew 설치의 시스템 Python이 venv 외부의 `pip install`에 대해 반환하는 `error: externally-managed-environment` 오류를 피할 수 있습니다.
76
77 macOS 또는 Linux에서:
78
79 ```bash theme={null}
80 python3 -m venv .venv
81 source .venv/bin/activate
82 pip install claude-agent-sdk
83 ```
84
85 Windows에서:
86
87 ```powershell theme={null}
88 py -m venv .venv
89 .venv\Scripts\Activate.ps1
90 pip install claude-agent-sdk
91 ```
92
93 PowerShell이 실행 정책 오류로 `Activate.ps1`을 차단하면 먼저 `Set-ExecutionPolicy -Scope Process RemoteSigned`를 실행합니다.
94
95 Python 패키지는 Python 3.10 이상이 필요합니다. pip에서 `No matching distribution found for claude-agent-sdk`를 보고하면 인터프리터가 3.10보다 오래된 것입니다. macOS 또는 Linux에서 `python3 --version`을 실행하거나 Windows에서 `py --version`을 실행하여 확인하십시오.
96 </Tab>
97 </Tabs>
98
99 <Note>
100 TypeScript SDK는 선택적 종속성으로 플랫폼용 네이티브 Claude Code 바이너리를 번들로 제공하므로 Claude Code를 별도로 설치할 필요가 없습니다.
101 </Note>
102 </Step>
103
104 <Step title="API 키 설정">
105 [콘솔](https://platform.claude.com/)에서 API 키를 가져온 다음 환경 변수로 설정합니다.
106
107 macOS 또는 Linux에서:
108
109 ```bash theme={null}
110 export ANTHROPIC_API_KEY=sk-ant-xxxxx
111 ```
112
113 Windows PowerShell에서:
114
115 ```powershell theme={null}
116 $env:ANTHROPIC_API_KEY = "sk-ant-xxxxx"
117 ```
118
119 SDK는 또한 타사 API 제공자를 통한 인증을 지원합니다:
120
121 * **Amazon Bedrock**: `CLAUDE_CODE_USE_BEDROCK=1` 환경 변수를 설정하고 AWS 자격 증명을 구성합니다
122 * **Claude Platform on AWS**: `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` 및 `ANTHROPIC_AWS_WORKSPACE_ID`를 설정한 다음 AWS 자격 증명을 구성합니다
123 * **Google Cloud의 Agent Platform**: `CLAUDE_CODE_USE_VERTEX=1` 환경 변수를 설정하고 Google Cloud 자격 증명을 구성합니다
124 * **Microsoft Azure**: `CLAUDE_CODE_USE_FOUNDRY=1` 환경 변수를 설정하고 Azure 자격 증명을 구성합니다
125
126 [Amazon Bedrock](/ko/amazon-bedrock), [Claude Platform on AWS](/ko/claude-platform-on-aws), [Google Cloud의 Agent Platform](/ko/google-vertex-ai), 또는 [Microsoft Foundry](/ko/microsoft-foundry)의 설정 가이드를 참조하십시오.
127
128 <Note>
129 이전에 승인되지 않은 경우, Anthropic은 타사 개발자가 Claude Agent SDK로 구축한 에이전트를 포함하여 자신의 제품에 대해 claude.ai 로그인 또는 속도 제한을 제공하도록 허용하지 않습니다. 대신 이 문서에 설명된 API 키 인증 방법을 사용하십시오.
130 </Note>
131 </Step>
132 16
133 <Step title="첫 번째 에이전트 실행">17| 다음의 경우... | 사용 | 이유 |
134 이 예제는 기본 제공 도구를 사용하여 현재 디렉토리의 파일을 나열하는 에이전트를 만듭니다.18| ------------------------------------------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
19| 도구 루프를 직접 구현하지 않고 에이전트를 구축하는 경우 | **Agent SDK** | Python 또는 TypeScript에서 자신의 프로세스에서 에이전트 루프를 실행하는 라이브러리입니다. |
20| 터미널에서 대화형 개발을 수행하거나 일회성 작업을 실행하는 경우 | [**Claude Code CLI**](/docs/ko/overview) | 일일 대화형 사용을 위해 구축된 터미널 인터페이스입니다. |
21| API를 직접 호출하고 도구 루프를 직접 구현하는 경우 | [**Client SDK**](https://platform.claude.com/docs/en/api/client-sdks) | Claude Code가 아닌 Anthropic API에 직접 액세스합니다. 도구 루프를 직접 구현합니다. |
22| 자신의 샌드박스 또는 세션 인프라를 관리하지 않고 장기 실행 또는 비동기 에이전트를 실행하는 경우 | [**Managed Agents**](https://platform.claude.com/docs/en/managed-agents/overview) | 호스팅된 REST API로, Agent SDK와는 별개의 제품입니다. Anthropic이 에이전트와 샌드박스를 실행합니다. |
135 23
136 <CodeGroup>24SDK는 Python 및 TypeScript용 라이브러리로만 사용 가능합니다. 다른 언어에서 동일한 에이전트 루프를 실행하려면 `-p` 플래그 및 `--output-format json`과 함께 [CLI를 서브프로세스로 실행](/docs/ko/headless)하십시오.
137 ```python Python theme={null}
138 import asyncio
139 from claude_agent_sdk import query, ClaudeAgentOptions
140
141
142 async def main():
143 async for message in query(
144 prompt="What files are in this directory?",
145 options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
146 ):
147 if hasattr(message, "result"):
148 print(message.result)
149
150
151 asyncio.run(main())
152 ```
153
154 ```typescript TypeScript theme={null}
155 import { query } from "@anthropic-ai/claude-agent-sdk";
156
157 for await (const message of query({
158 prompt: "What files are in this directory?",
159 options: { allowedTools: ["Bash", "Glob"] }
160 })) {
161 if ("result" in message) console.log(message.result);
162 }
163 ```
164 </CodeGroup>
165 </Step>
166</Steps>
167
168**구축할 준비가 되셨나요?** [빠른 시작](/ko/agent-sdk/quickstart)을 따라 몇 분 안에 버그를 찾고 수정하는 에이전트를 만드십시오.
169 25
170<h2 id="capabilities">26<h2 id="capabilities">
171 기능27 기능
172</h2>28</h2>
173 29
174Claude Code를 강력하게 만드는 모든 것이 SDK에서 사용 가능합니다:30이러한 Claude Code 기능은 SDK에서 사용 가능합니다:
175
176<Tabs>
177 <Tab title="기본 제공 도구">
178 에이전트는 기본적으로 파일을 읽고, 명령을 실행하고, 코드베이스를 검색할 수 있습니다. 주요 도구는 다음과 같습니다:
179
180 | 도구 | 기능 |
181 | --------------------------------------------------------------------------- | ------------------------------------ |
182 | **Read** | 작업 디렉토리의 모든 파일 읽기 |
183 | **Write** | 새 파일 생성 |
184 | **Edit** | 기존 파일에 정확한 편집 수행 |
185 | **Bash** | 터미널 명령, 스크립트, git 작업 실행 |
186 | **Monitor** | 백그라운드 스크립트를 감시하고 각 출력 라인에 이벤트로 반응 |
187 | **Glob** | 패턴으로 파일 찾기(`**/*.ts`, `src/**/*.py`) |
188 | **Grep** | 정규식으로 파일 내용 검색 |
189 | **WebSearch** | 현재 정보를 위해 웹 검색 |
190 | **WebFetch** | 웹 페이지 내용 가져오기 및 구문 분석 |
191 | **[AskUserQuestion](/ko/agent-sdk/user-input#handle-clarifying-questions)** | 여러 선택 옵션으로 사용자에게 명확히 하는 질문 하기 |
192
193 이 예제는 코드베이스에서 TODO 주석을 검색하는 에이전트를 만듭니다:
194
195 <CodeGroup>
196 ```python Python theme={null}
197 import asyncio
198 from claude_agent_sdk import query, ClaudeAgentOptions
199
200
201 async def main():
202 async for message in query(
203 prompt="Find all TODO comments and create a summary",
204 options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
205 ):
206 if hasattr(message, "result"):
207 print(message.result)
208
209
210 asyncio.run(main())
211 ```
212
213 ```typescript TypeScript theme={null}
214 import { query } from "@anthropic-ai/claude-agent-sdk";
215
216 for await (const message of query({
217 prompt: "Find all TODO comments and create a summary",
218 options: { allowedTools: ["Read", "Glob", "Grep"] }
219 })) {
220 if ("result" in message) console.log(message.result);
221 }
222 ```
223 </CodeGroup>
224 </Tab>
225
226 <Tab title="Hooks">
227 에이전트 라이프사이클의 주요 지점에서 사용자 정의 코드를 실행합니다. SDK 훅은 콜백 함수를 사용하여 에이전트 동작을 검증, 로깅, 차단 또는 변환합니다.
228
229 **사용 가능한 훅:** `PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `SessionEnd`, `UserPromptSubmit` 등.
230
231 이 예제는 모든 파일 변경 사항을 감사 파일에 기록합니다:
232
233 <CodeGroup>
234 ```python Python theme={null}
235 import asyncio
236 from datetime import datetime
237 from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
238
239
240 async def log_file_change(input_data, tool_use_id, context):
241 file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
242 with open("./audit.log", "a") as f:
243 f.write(f"{datetime.now()}: modified {file_path}\n")
244 return {}
245
246
247 async def main():
248 async for message in query(
249 prompt="Refactor utils.py to improve readability",
250 options=ClaudeAgentOptions(
251 permission_mode="acceptEdits",
252 hooks={
253 "PostToolUse": [
254 HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
255 ]
256 },
257 ),
258 ):
259 if hasattr(message, "result"):
260 print(message.result)
261
262
263 asyncio.run(main())
264 ```
265
266 ```typescript TypeScript theme={null}
267 import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
268 import { appendFile } from "fs/promises";
269
270 const logFileChange: HookCallback = async (input) => {
271 const filePath = (input as any).tool_input?.file_path ?? "unknown";
272 await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
273 return {};
274 };
275
276 for await (const message of query({
277 prompt: "Refactor utils.py to improve readability",
278 options: {
279 permissionMode: "acceptEdits",
280 hooks: {
281 PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
282 }
283 }
284 })) {
285 if ("result" in message) console.log(message.result);
286 }
287 ```
288 </CodeGroup>
289
290 [훅에 대해 자세히 알아보기 →](/ko/agent-sdk/hooks)
291 </Tab>
292
293 <Tab title="서브에이전트">
294 특화된 에이전트를 생성하여 집중된 부작업을 처리합니다. 주 에이전트가 작업을 위임하고 서브에이전트가 결과를 보고합니다.
295 31
296 특화된 지침으로 사용자 정의 에이전트를 정의합니다. 서브에이전트가 Agent 도구를 통해 호출되므로 `allowedTools`에 `Agent`를 포함하여 해당 호출을 자동으로 승인합니다:32| 기능 | 기능 | 자세히 알아보기 |
33| ---------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
34| 기본 제공 도구 | 파일 읽기, 쓰기, 편집, 명령 실행 및 웹 검색 | [도구 참조](/docs/ko/tools-reference) |
35| Hooks | 에이전트 라이프사이클의 주요 지점에서 사용자 정의 코드 실행 | [Hooks](/docs/ko/agent-sdk/hooks) |
36| Subagents | 집중된 부작업을 위해 특화된 에이전트 생성 | [Subagents](/docs/ko/agent-sdk/subagents) |
37| MCP | Model Context Protocol을 통해 외부 도구 및 데이터 소스 연결 | [MCP](/docs/ko/agent-sdk/mcp) |
38| 권한 | 어떤 도구가 자동으로 실행되는지, 어떤 도구가 승인이 필요한지 제어 | [권한](/docs/ko/agent-sdk/permissions) |
39| 세션 | 교환 전체에서 컨텍스트 유지, 나중에 재개 또는 포크 | [세션](/docs/ko/agent-sdk/sessions) |
40| Skills, 명령 및 메모리 | 프로젝트의 `.claude/` 및 `~/.claude/`에서 자동으로 로드, Claude Code와 동일 | [Skills](/docs/ko/agent-sdk/skills), [명령](/docs/ko/agent-sdk/skills#commands-in-agent-sdk-sessions), [메모리](/docs/ko/agent-sdk/modifying-system-prompts), [구성 로드](/docs/ko/agent-sdk/claude-code-features) |
41| Plugins | Skills, 에이전트, Hooks 및 MCP 서버를 패키징하고 로컬 경로로 로드 | [Plugins](/docs/ko/agent-sdk/plugins) |
297 42
298 <CodeGroup>43<h2 id="get-started">
299 ```python Python theme={null}44 시작하기
300 import asyncio
301 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
302
303
304 async def main():
305 async for message in query(
306 prompt="Use the code-reviewer agent to review this codebase",
307 options=ClaudeAgentOptions(
308 allowed_tools=["Read", "Glob", "Grep", "Agent"],
309 agents={
310 "code-reviewer": AgentDefinition(
311 description="Expert code reviewer for quality and security reviews.",
312 prompt="Analyze code quality and suggest improvements.",
313 tools=["Read", "Glob", "Grep"],
314 )
315 },
316 ),
317 ):
318 if hasattr(message, "result"):
319 print(message.result)
320
321
322 asyncio.run(main())
323 ```
324
325 ```typescript TypeScript theme={null}
326 import { query } from "@anthropic-ai/claude-agent-sdk";
327
328 for await (const message of query({
329 prompt: "Use the code-reviewer agent to review this codebase",
330 options: {
331 allowedTools: ["Read", "Glob", "Grep", "Agent"],
332 agents: {
333 "code-reviewer": {
334 description: "Expert code reviewer for quality and security reviews.",
335 prompt: "Analyze code quality and suggest improvements.",
336 tools: ["Read", "Glob", "Grep"]
337 }
338 }
339 }
340 })) {
341 if ("result" in message) console.log(message.result);
342 }
343 ```
344 </CodeGroup>
345
346 서브에이전트의 컨텍스트 내의 메시지에는 `parent_tool_use_id` 필드가 포함되어 있어 어떤 메시지가 어떤 서브에이전트 실행에 속하는지 추적할 수 있습니다.
347
348 [서브에이전트에 대해 자세히 알아보기 →](/ko/agent-sdk/subagents)
349 </Tab>
350
351 <Tab title="MCP">
352 Model Context Protocol을 통해 외부 시스템에 연결합니다: 데이터베이스, 브라우저, API 및 [수백 개 이상](https://github.com/modelcontextprotocol/servers).
353
354 이 예제는 [Playwright MCP 서버](https://github.com/microsoft/playwright-mcp)를 연결하여 에이전트에 브라우저 자동화 기능을 제공합니다:
355
356 <CodeGroup>
357 ```python Python theme={null}
358 import asyncio
359 from claude_agent_sdk import query, ClaudeAgentOptions
360
361
362 async def main():
363 async for message in query(
364 prompt="Open example.com and describe what you see",
365 options=ClaudeAgentOptions(
366 mcp_servers={
367 "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
368 }
369 ),
370 ):
371 if hasattr(message, "result"):
372 print(message.result)
373
374
375 asyncio.run(main())
376 ```
377
378 ```typescript TypeScript theme={null}
379 import { query } from "@anthropic-ai/claude-agent-sdk";
380
381 for await (const message of query({
382 prompt: "Open example.com and describe what you see",
383 options: {
384 mcpServers: {
385 playwright: { command: "npx", args: ["@playwright/mcp@latest"] }
386 }
387 }
388 })) {
389 if ("result" in message) console.log(message.result);
390 }
391 ```
392 </CodeGroup>
393
394 [MCP에 대해 자세히 알아보기 →](/ko/agent-sdk/mcp)
395 </Tab>
396
397 <Tab title="권한">
398 에이전트가 사용할 수 있는 도구를 정확히 제어합니다. 안전한 작업을 허용하고, 위험한 작업을 차단하거나, 민감한 작업에 대한 승인을 요구합니다.
399
400 <Note>
401 대화형 승인 프롬프트 및 `AskUserQuestion` 도구는 [승인 및 사용자 입력 처리](/ko/agent-sdk/user-input)를 참조하십시오.
402 </Note>
403
404 이 예제는 코드를 분석할 수 있지만 수정할 수 없는 읽기 전용 에이전트를 만듭니다. `allowed_tools`는 `Read`, `Glob` 및 `Grep`을 사전 승인합니다.
405
406 <CodeGroup>
407 ```python Python theme={null}
408 import asyncio
409 from claude_agent_sdk import query, ClaudeAgentOptions
410
411
412 async def main():
413 async for message in query(
414 prompt="Review this code for best practices",
415 options=ClaudeAgentOptions(
416 allowed_tools=["Read", "Glob", "Grep"],
417 ),
418 ):
419 if hasattr(message, "result"):
420 print(message.result)
421
422
423 asyncio.run(main())
424 ```
425
426 ```typescript TypeScript theme={null}
427 import { query } from "@anthropic-ai/claude-agent-sdk";
428
429 for await (const message of query({
430 prompt: "Review this code for best practices",
431 options: {
432 allowedTools: ["Read", "Glob", "Grep"]
433 }
434 })) {
435 if ("result" in message) console.log(message.result);
436 }
437 ```
438 </CodeGroup>
439
440 [권한에 대해 자세히 알아보기 →](/ko/agent-sdk/permissions)
441 </Tab>
442
443 <Tab title="세션">
444 여러 교환에 걸쳐 컨텍스트를 유지합니다. Claude는 읽은 파일, 수행한 분석 및 대화 기록을 기억합니다. 나중에 세션을 재개하거나 다양한 접근 방식을 탐색하기 위해 포크합니다.
445
446 이 예제는 첫 번째 쿼리에서 세션 ID를 캡처한 다음 전체 컨텍스트로 계속하기 위해 재개합니다:
447
448 <CodeGroup>
449 ```python Python theme={null}
450 import asyncio
451 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage
452
453
454 async def main():
455 session_id = None
456
457 # First query: capture the session ID
458 async for message in query(
459 prompt="Read the authentication module",
460 options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
461 ):
462 if isinstance(message, SystemMessage) and message.subtype == "init":
463 session_id = message.data["session_id"]
464
465 # Resume with full context from the first query
466 async for message in query(
467 prompt="Now find all places that call it", # "it" = auth module
468 options=ClaudeAgentOptions(resume=session_id),
469 ):
470 if isinstance(message, ResultMessage):
471 print(message.result)
472
473
474 asyncio.run(main())
475 ```
476
477 ```typescript TypeScript theme={null}
478 import { query } from "@anthropic-ai/claude-agent-sdk";
479
480 let sessionId: string | undefined;
481
482 // First query: capture the session ID
483 for await (const message of query({
484 prompt: "Read the authentication module",
485 options: { allowedTools: ["Read", "Glob"] }
486 })) {
487 if (message.type === "system" && message.subtype === "init") {
488 sessionId = message.session_id;
489 }
490 }
491
492 // Resume with full context from the first query
493 for await (const message of query({
494 prompt: "Now find all places that call it", // "it" = auth module
495 options: { resume: sessionId }
496 })) {
497 if ("result" in message) console.log(message.result);
498 }
499 ```
500 </CodeGroup>
501
502 [세션에 대해 자세히 알아보기 →](/ko/agent-sdk/sessions)
503 </Tab>
504</Tabs>
505
506<h3 id="claude-code-features">
507 Claude Code 기능
508</h3>
509
510SDK는 또한 Claude Code의 파일 시스템 기반 구성을 지원합니다. 기본 옵션을 사용하면 SDK는 작업 디렉토리의 `.claude/` 및 `~/.claude/`에서 이를 로드합니다. 로드되는 소스를 제한하려면 옵션에서 `setting_sources`(Python) 또는 `settingSources`(TypeScript)를 설정하십시오.
511
512| 기능 | 설명 | 위치 |
513| ------------------------------------------------ | ------------------------------------------- | ---------------------------------- |
514| [Skills](/ko/agent-sdk/skills) | Claude가 자동으로 사용하거나 `/name`으로 호출하는 특화된 기능 | `.claude/skills/*/SKILL.md` |
515| [Commands](/ko/agent-sdk/slash-commands) | 레거시 형식의 사용자 정의 명령. 새로운 사용자 정의 명령은 Skills 사용 | `.claude/commands/*.md` |
516| [Memory](/ko/agent-sdk/modifying-system-prompts) | 프로젝트 컨텍스트 및 지침 | `CLAUDE.md` 또는 `.claude/CLAUDE.md` |
517| [Plugins](/ko/agent-sdk/plugins) | Skills, 에이전트, 훅 및 MCP 서버로 확장 | `plugins` 옵션을 통한 프로그래밍 방식 |
518
519<h2 id="compare-the-agent-sdk-to-other-claude-tools">
520 Agent SDK를 다른 Claude 도구와 비교
521</h2>45</h2>
522 46
523Claude 플랫폼은 Claude로 구축하는 여러 방법을 제공합니다. Agent SDK가 어떻게 적합한지 다음과 같습니다:47[빠른 시작](/docs/ko/agent-sdk/quickstart)을 따라 SDK를 설치하고, API 키를 설정하고, 기존 코드의 버그를 찾아 수정하는 첫 번째 에이전트를 구축합니다.
524
525<Tabs>
526 <Tab title="Agent SDK vs Client SDK">
527 [Anthropic Client SDK](https://platform.claude.com/docs/ko/api/client-sdks)는 직접 API 액세스를 제공합니다: 프롬프트를 보내고 도구 실행을 직접 구현합니다. **Agent SDK**는 기본 제공 도구 실행이 있는 Claude를 제공합니다.
528
529 Client SDK를 사용하면 도구 루프를 구현합니다. Agent SDK를 사용하면 Claude가 처리합니다:
530
531 <CodeGroup>
532 ```python Python theme={null}
533 # Client SDK: You implement the tool loop
534 response = client.messages.create(...)
535 while response.stop_reason == "tool_use":
536 result = your_tool_executor(response.tool_use)
537 response = client.messages.create(tool_result=result, **params)
538
539 # Agent SDK: Claude handles tools autonomously
540 async for message in query(prompt="Fix the bug in auth.py"):
541 print(message)
542 ```
543
544 ```typescript TypeScript theme={null}
545 // Client SDK: You implement the tool loop
546 let response = await client.messages.create({ ...params });
547 while (response.stop_reason === "tool_use") {
548 const result = yourToolExecutor(response.tool_use);
549 response = await client.messages.create({ tool_result: result, ...params });
550 }
551 48
552 // Agent SDK: Claude handles tools autonomously49<Note>
553 for await (const message of query({ prompt: "Fix the bug in auth.ts" })) {50 사전에 승인되지 않은 경우, Anthropic은 제3자 개발자가 claude.ai 로그인 또는 Agent SDK로 구축한 에이전트를 포함한 제품에 대한 속도 제한을 제공하는 것을 허용하지 않습니다. 대신 [빠른 시작](/docs/ko/agent-sdk/quickstart)에 설명된 API 키 인증 방법을 사용합니다.
554 console.log(message);51</Note>
555 }
556 ```
557 </CodeGroup>
558 </Tab>
559
560 <Tab title="Agent SDK vs Claude Code CLI">
561 동일한 기능, 다른 인터페이스:
562
563 | 사용 사례 | 최선의 선택 |
564 | ------------- | ------ |
565 | 대화형 개발 | CLI |
566 | CI/CD 파이프라인 | SDK |
567 | 사용자 정의 애플리케이션 | SDK |
568 | 일회성 작업 | CLI |
569 | 프로덕션 자동화 | SDK |
570
571 많은 팀이 둘 다 사용합니다: 일일 개발을 위한 CLI, 프로덕션을 위한 SDK. 워크플로우는 둘 사이에서 직접 변환됩니다.
572 </Tab>
573
574 <Tab title="Agent SDK vs Managed Agents">
575 [Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview)는 호스팅된 REST API입니다: Anthropic이 에이전트와 샌드박스를 실행하고, 애플리케이션이 이벤트를 보내고 결과를 다시 스트리밍합니다. **Agent SDK**는 자신의 프로세스 내에서 에이전트 루프를 실행하는 라이브러리입니다.
576
577 | | Agent SDK | Managed Agents |
578 | -------------- | ------------------------------------- | ---------------------------------------------------- |
579 | **실행 위치** | 사용자의 프로세스, 사용자의 인프라 | Anthropic 관리 인프라 |
580 | **인터페이스** | Python 또는 TypeScript 라이브러리 | REST API |
581 | **에이전트 작업 대상** | 사용자의 인프라의 파일 | 세션당 관리되는 샌드박스 |
582 | **세션 상태** | 파일시스템의 JSONL | Anthropic 호스팅 이벤트 로그 |
583 | **사용자 정의 도구** | 프로세스 내 Python 또는 TypeScript 함수 | Claude가 도구를 트리거합니다; 사용자가 실행하고 결과를 반환합니다 |
584 | **최적 용도** | 로컬 프로토타이핑, 파일시스템 및 서비스에서 직접 작동하는 에이전트 | 샌드박스 또는 세션 인프라를 운영할 필요가 없는 프로덕션 에이전트, 장기 실행 및 비동기 세션 |
585
586 일반적인 경로는 Agent SDK로 로컬에서 프로토타입을 만든 다음 프로덕션을 위해 Managed Agents로 이동하는 것입니다.
587 </Tab>
588</Tabs>
589 52
590<h2 id="changelog">53<h2 id="changelog">
591 변경 로그54 변경 로그
596* **TypeScript SDK**: [CHANGELOG.md 보기](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md)59* **TypeScript SDK**: [CHANGELOG.md 보기](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md)
597* **Python SDK**: [CHANGELOG.md 보기](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md)60* **Python SDK**: [CHANGELOG.md 보기](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md)
598 61
599<h2 id="reporting-bugs">62<h2 id="report-bugs">
600 버그 보고63 버그 보고
601</h2>64</h2>
602 65
634 다음 단계97 다음 단계
635</h2>98</h2>
636 99
637<CardGroup cols={2}>100이러한 리소스는 Agent SDK로 구축하기 위한 더 깊이 있는 기술 세부 정보와 예제 프로젝트를 다룹니다.
638 <Card title="빠른 시작" icon="play" href="/ko/agent-sdk/quickstart">
639 몇 분 안에 버그를 찾고 수정하는 에이전트 구축하기
640 </Card>
641
642 <Card title="예제 에이전트" icon="star" href="https://github.com/anthropics/claude-agent-sdk-demos">
643 이메일 어시스턴트, 연구 에이전트 등
644 </Card>
645
646 <Card title="TypeScript SDK" icon="code" href="/ko/agent-sdk/typescript">
647 전체 TypeScript API 참조 및 예제
648 </Card>
649 101
650 <Card title="Python SDK" icon="code" href="/ko/agent-sdk/python">102* [빠른 시작](/docs/ko/agent-sdk/quickstart): 버그를 찾고 수정하는 첫 번째 에이전트 구축하기
651 전체 Python API 참조 및 예제103* [마이그레이션 가이드](/docs/ko/agent-sdk/migration-guide): Claude Code SDK 패키지에서 Agent SDK로 마이그레이션하기
652 </Card>104* [에이전트 루프](/docs/ko/agent-sdk/agent-loop): Claude가 계획하고, 도구를 호출하고, 작업이 완료되었을 때를 결정하는 방법
653</CardGroup>105* [예제 에이전트](https://github.com/anthropics/claude-agent-sdk-demos): 로컬 개발을 위한 데모 앱
106* [TypeScript SDK](/docs/ko/agent-sdk/typescript): 전체 TypeScript API 참조 및 예제
107* [Python SDK](/docs/ko/agent-sdk/python): 전체 Python API 참조 및 예제
108* [에이전트 하네스 설계](https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code): Claude Code 팀이 동적 워크플로우를 사용하여 많은 서브에이전트를 한 번에 오케스트레이션하는 방법
