Agent SDK overview

기준일: 2026-07-26
공식 기준: Agent SDK overview

Agent SDK overview 문서는 Claude Code 공식 문서(agent-sdk/overview)를 한국어로 정리한 가이드입니다. Build production AI agents with Claude Code as a library 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치 버전과 공식 원문을 확인하세요.

핵심 요약

Build production AI agents with Claude Code as a library

한국어 가이드 범위: agent-sdk/overview 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

이 사이트에서의 SDK 트랙

단계	가이드
개요 (현재)	Agent SDK 개요
설치·첫 에이전트	Agent SDK Quickstart
권한	Agent SDK permissions
호스팅·보안	secure deployment

빠른 설치 (Quickstart와 동일)

# TypeScript
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

# Python
uv add claude-agent-sdk
# 또는: pip install claude-agent-sdk

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Agent SDK overview
• Get started
• Capabilities
• Claude Code features
• Compare the Agent SDK to other Claude tools
• Changelog
• Reporting bugs
• Branding guidelines
• License and terms
• 다음 단계

상세 내용

Agent SDK overview

Build production AI agents with Claude Code as a library

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Get started

Setting "type": "module" in package.json lets your agent script use top-level await, and tsx runs TypeScript files directly. In an existing CommonJS project, skip the first two commands and name your script agent.mts instead of agent.ts.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• Amazon Bedrock: set CLAUDE_CODE_USE_BEDROCK=1 environment variable and configure AWS credentials
• Claude Platform on AWS: set CLAUDE_CODE_USE_ANTHROPIC_AWS=1 and ANTHROPIC_AWS_WORKSPACE_ID, then configure AWS credentials
• Google Cloud's Agent Platform: set CLAUDE_CODE_USE_VERTEX=1 environment variable and configure Google Cloud credentials
• Microsoft Foundry: set CLAUDE_CODE_USE_FOUNDRY=1 environment variable and configure Azure credentials

Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.is) runs TypeScript files directly. In an existing CommonJS project, skip the first two commands and name your script `agent.mts` instead of `agent.ts`.
      

      

        [uv](https://docs.astral.sh/uv/) is a fast Python package manager that handles virtual environments automatically:

Create and activate a virtual environment, then install the package. Installing into a virtual environment avoids the `error: externally-managed-environment` failure that system Python on recent Debian, Ubuntu, and Homebrew installs returns for `pip install` outside a venv.

        On macOS or Linux:

If PowerShell blocks `Activate.ps1` with an execution policy error, run `Set-ExecutionPolicy -Scope Process RemoteSigned` first.

        The Python package requires Python 3.10 or later. If pip reports `No matching distribution found for claude-agent-sdk`, your interpreter is older than 3.10. Run `python3 --version` on macOS or Linux, or `py --version` on Windows, to check.
      

    

    

      Both the TypeScript and Python SDKs bundle a native Claude Code binary for your platform, so you don't need to install Claude Code separately.
    

  

  

    Get an API key from the [Console](https://platform.claude.com/), then set it as an environment variable.

    On macOS or Linux:

On Windows PowerShell:

Capabilities

Everything that makes Claude Code powerful is available in the SDK:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Run custom code at key points in the agent lifecycle. SDK hooks use callback functions to validate, log, block, or transform agent behavior.

    **Available hooks:** `PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, and more.

    This example logs all file changes to an audit file:

After the agent finishes, run `cat audit.log` to see the recorded file changes.

    [Learn more about hooks →](https://code.claude.com/docs/en/agent-sdk/hooks)
  

  

    Spawn specialized agents to handle focused subtasks. Your main agent delegates work, and subagents report back with results.

    Define custom agents with specialized instructions. Subagents are invoked via the Agent tool, so include `Agent` in `allowedTools` to auto-approve those invocations:

Claude Code features

The SDK also supports Claude Code's filesystem-based configuration. With default options the SDK loads these from .claude/ in your working directory and ~/.claude/. To restrict which sources load, set setting_sources (Python) or settingSources (TypeScript) in your options.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Feature	Description	Location
Skills	Specialized capabilities Claude uses automatically or you invoke with /name	.claude/skills/*/SKILL.md
Commands	Custom commands in the legacy format. Use skills for new custom commands	.claude/commands/*.md
Memory	Project context and instructions	CLAUDE.md or .claude/CLAUDE.md
Plugins	Extend with skills, agents, hooks, and MCP servers	Programmatic via plugins option

Compare the Agent SDK to other Claude tools

The Claude Platform offers multiple ways to build with Claude. Here's how the Agent SDK fits in:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Changelog

View the full changelog for SDK updates, bug fixes, and new features:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• TypeScript SDK: view CHANGELOG.md
• Python SDK: view CHANGELOG.md

Reporting bugs

If you encounter bugs or issues with the Agent SDK:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• TypeScript SDK: report issues on GitHub
• Python SDK: report issues on GitHub

Branding guidelines

For partners integrating the Claude Agent SDK, use of Claude branding is optional. When referencing Claude in your product:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• "Claude Agent" (preferred for dropdown menus)
• "Claude" (when within a menu already labeled "Agents")
• "{YourAgentName} Powered by Claude" (if you have an existing agent name)
• "Claude Code" or "Claude Code Agent"
• Claude Code-branded ASCII art or visual elements that mimic Claude Code

License and terms

Use of the Claude Agent SDK is governed by Anthropic's Commercial Terms of Service, including when you use it to power products and services that you make available to your own customers and end users, except to the extent a specific component or dependency is covered by a different license as indicated in that component's LICENSE file.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

다음 단계

Build an agent that finds and fixes bugs in minutes

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

실습 체크리스트

1. 공식 문서와 로컬/SDK 버전을 대조합니다.
2. 관련 CLI·SDK 옵션은 공식 페이지와 --help로 교차 확인합니다.
3. Agent SDK 예시는 TypeScript/Python 패키지 최신 API를 우선합니다.
4. 권한·호스팅·보안 설정 변경 후 통합 테스트를 실행합니다.

자주 쓰는 명령·설정 예시

The Agent SDK includes built-in tools for reading files, running commands, and editing code, so your agent can start working immediately without you implementing tool execution. Dive into the quickstart or explore real agents built with the SDK:

  

    Build a bug-fixing agent in minutes
  

  

    Email assistant, research agent, and more
  

## Get started

Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.is) runs TypeScript files directly. In an existing CommonJS project, skip the first two commands and name your script `agent.mts` instead of `agent.ts`.
      

      

        [uv](https://docs.astral.sh/uv/) is a fast Python package manager that handles virtual environments automatically:

Create and activate a virtual environment, then install the package. Installing into a virtual environment avoids the `error: externally-managed-environment` failure that system Python on recent Debian, Ubuntu, and Homebrew installs returns for `pip install` outside a venv.

        On macOS or Linux:

If PowerShell blocks `Activate.ps1` with an execution policy error, run `Set-ExecutionPolicy -Scope Process RemoteSigned` first.

        The Python package requires Python 3.10 or later. If pip reports `No matching distribution found for claude-agent-sdk`, your interpreter is older than 3.10. Run `python3 --version` on macOS or Linux, or `py --version` on Windows, to check.
      

    

    

      Both the TypeScript and Python SDKs bundle a native Claude Code binary for your platform, so you don't need to install Claude Code separately.
    

  

  

    Get an API key from the [Console](https://platform.claude.com/), then set it as an environment variable.

    On macOS or Linux:

On Windows PowerShell:

The SDK also supports authentication via third-party API providers:

    * **Amazon Bedrock**: set `CLAUDE_CODE_USE_BEDROCK=1` environment variable and configure AWS credentials
    * **Claude Platform on AWS**: set `CLAUDE_CODE_USE_ANTHROPIC_AWS=1` and `ANTHROPIC_AWS_WORKSPACE_ID`, then configure AWS credentials
    * **Google Cloud's Agent Platform**: set `CLAUDE_CODE_USE_VERTEX=1` environment variable and configure Google Cloud credentials
    * **Microsoft Foundry**: set `CLAUDE_CODE_USE_FOUNDRY=1` environment variable and configure Azure credentials

    See the setup guides for [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock), [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws), [Google Cloud's Agent Platform](https://code.claude.com/docs/en/google-vertex-ai), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry) for details.

    

      Unless previously approved, Anthropic does not allow third party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK. Please use the API key authentication methods described in this document instead.
    

  

  

    This example creates an agent that lists files in your current directory using built-in tools.

관련 링크

• Agent SDK Quickstart (로컬)

• 권한 규칙

• 공식 원문: agent-sdk/overview

• 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·API 이름은 설치 버전에 따라 달라질 수 있습니다.