Quickstart

Quickstart 문서는 Claude Code 공식 문서(agent-sdk/quickstart)를 한국어로 정리한 가이드입니다. Get started with the Python or TypeScript Agent SDK to build AI agents that work autonomously 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치 버전과 공식 원문을 확인하세요.

핵심 요약

Get started with the Python or TypeScript Agent SDK to build AI agents that work autonomously

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

문서 구성

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

Quickstart
사전 요구사항
설정
Create a buggy file
Build an agent that finds and fixes bugs
Run your agent
Try other prompts
Customize your agent
Key concepts
다음 단계

상세 내용

Quickstart

사전 요구사항

주요 항목:

Node.js 18+ or Python 3.10+
An Anthropic account (sign up here)

설정

Create a new directory for this quickstart:

주요 항목:

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

For your own projects, you can run the SDK from any folder; it will have access to files in that directory and its subdirectories by default.
  

  

    Install the Agent SDK package for your language:

Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.is) runs TypeScript files directly. npm prints `added N packages` when the install succeeds.

[tsx](https://tsx.is) runs TypeScript files directly. If your project uses CommonJS, name your agent script `agent.mts` instead of `agent.ts`. The `.mts` extension makes tsx treat the file as an ES module, so top-level `await` works without converting your whole project to ES modules. Use `agent.mts` in place of `agent.ts` in the create and run steps later in this quickstart.
      

      

        [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.

        On macOS or Linux:

On Windows:

Create a buggy file

This quickstart walks you through building an agent that can find and fix bugs in code. First, you need a file with some intentional bugs for the agent to fix. Create utils.py in the my-agent directory and paste the following code:

Build an agent that finds and fixes bugs

Create agent.py if you're using the Python SDK, or agent.ts for TypeScript. Use agent.mts instead if your existing project uses CommonJS:

Run your agent

Your agent is ready. Run it with the following command:

If you named your script `agent.mts`, run `npx tsx agent.mts` instead.

With your virtual environment still activated:

Try other prompts

Now that your agent is set up, try some different prompts:

주요 항목:

"Add docstrings to all functions in utils.py"
"Add type hints to all functions in utils.py"
"Create a README.md documenting the functions in utils.py"

Customize your agent

You can modify your agent's behavior by changing the options. Here are a few examples:

**Give Claude a custom system prompt:**

**Run commands in the terminal:**

Key concepts

The example above uses acceptEdits mode, which auto-approves file operations so the agent can run without interactive prompts. If you want to prompt users for approval, use default mode and provide a canUseTool callback that collects user input. For more control, see Permissions.

Tools	What the agent can do
`Read`, `Glob`, `Grep`	Read-only analysis
`Read`, `Edit`, `Glob`	Analyze and modify code
`Read`, `Edit`, `Bash`, `Glob`, `Grep`	Full automation

Mode	Behavior	Use case
`acceptEdits`	Auto-approves file edits and common filesystem commands, asks for other actions	Trusted development workflows
`plan`	Runs read-only tools; file edits are never auto-approved and reach your `canUseTool` callback	Scoping a task before approving execution
`dontAsk`	Denies anything not in `allowedTools`; connector tools your organization set to `ask` and tools that require user interaction are denied even if you've listed them	Locked-down headless agents
`auto`	A model classifier approves or denies permission prompts	Autonomous agents with safety guardrails
`bypassPermissions`	Runs every tool without prompting, except tools matched by an explicit `ask` rule, connector tools your organization set to `ask`, and tools that require user interaction. In the TypeScript SDK, also requires `allowDangerouslySkipPermissions: true` in `options`	Sandboxed CI, fully trusted environments
`default`	Requires a `canUseTool` callback to handle approval	Custom approval flows

다음 단계

Now that you've created your first agent, learn how to extend its capabilities and tailor it to your use case:

주요 항목:

Permissions: control what your agent can do and when it needs approval
Hooks: run custom code before or after tool calls
Sessions: build multi-turn agents that maintain context
MCP servers: connect to databases, browsers, APIs, and other external systems
Hosting: deploy agents to Docker, cloud, and CI/CD
Example agents: see complete examples: email assistant, research agent, and more

실습 체크리스트

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

자주 쓰는 명령·설정 예시

For your own projects, you can run the SDK from any folder; it will have access to files in that directory and its subdirectories by default.
  

  

    Install the Agent SDK package for your language:

Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.is) runs TypeScript files directly. npm prints `added N packages` when the install succeeds.

[tsx](https://tsx.is) runs TypeScript files directly. If your project uses CommonJS, name your agent script `agent.mts` instead of `agent.ts`. The `.mts` extension makes tsx treat the file as an ES module, so top-level `await` works without converting your whole project to ES modules. Use `agent.mts` in place of `agent.ts` in the create and run steps later in this quickstart.
      

      

        [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.

        On macOS or Linux:

On Windows:

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

    

    

      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 [Claude Console](https://platform.claude.com/), then set it as an environment variable in the shell where you'll run your agent:

The SDK reads the key from the environment of the process that runs your agent; it doesn't load `.env` files automatically. If you keep the key in a `.env` file, load it yourself, for example with the `dotenv` package, before calling the SDK.

    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](/docs/en/amazon-bedrock), [Claude Platform on AWS](/docs/en/claude-platform-on-aws), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), or [Microsoft Foundry](/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.
    

  

## Create a buggy file

This quickstart walks you through building an agent that can find and fix bugs in code. First, you need a file with some intentional bugs for the agent to fix. Create `utils.py` in the `my-agent` directory and paste the following code:

Quickstart

핵심 요약

Get started with the Python or TypeScript Agent SDK to build AI agents that work autonomously

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

문서 구성

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

Quickstart
사전 요구사항
설정
Create a buggy file
Build an agent that finds and fixes bugs
Run your agent
Try other prompts
Customize your agent
Key concepts
다음 단계

상세 내용

Quickstart

사전 요구사항

주요 항목:

Node.js 18+ or Python 3.10+
An Anthropic account (sign up here)

설정

Create a new directory for this quickstart:

주요 항목:

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

For your own projects, you can run the SDK from any folder; it will have access to files in that directory and its subdirectories by default.
  

  

    Install the Agent SDK package for your language:

Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.is) runs TypeScript files directly. npm prints `added N packages` when the install succeeds.

[tsx](https://tsx.is) runs TypeScript files directly. If your project uses CommonJS, name your agent script `agent.mts` instead of `agent.ts`. The `.mts` extension makes tsx treat the file as an ES module, so top-level `await` works without converting your whole project to ES modules. Use `agent.mts` in place of `agent.ts` in the create and run steps later in this quickstart.
      

      

        [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.

        On macOS or Linux:

On Windows:

Create a buggy file

Build an agent that finds and fixes bugs

Create agent.py if you're using the Python SDK, or agent.ts for TypeScript. Use agent.mts instead if your existing project uses CommonJS:

Run your agent

Your agent is ready. Run it with the following command:

If you named your script `agent.mts`, run `npx tsx agent.mts` instead.

With your virtual environment still activated:

Try other prompts

Now that your agent is set up, try some different prompts:

주요 항목:

"Add docstrings to all functions in utils.py"
"Add type hints to all functions in utils.py"
"Create a README.md documenting the functions in utils.py"

Customize your agent

You can modify your agent's behavior by changing the options. Here are a few examples:

**Give Claude a custom system prompt:**

**Run commands in the terminal:**

Key concepts

Tools	What the agent can do
`Read`, `Glob`, `Grep`	Read-only analysis
`Read`, `Edit`, `Glob`	Analyze and modify code
`Read`, `Edit`, `Bash`, `Glob`, `Grep`	Full automation

Mode	Behavior	Use case
`acceptEdits`	Auto-approves file edits and common filesystem commands, asks for other actions	Trusted development workflows
`plan`	Runs read-only tools; file edits are never auto-approved and reach your `canUseTool` callback	Scoping a task before approving execution
`dontAsk`	Denies anything not in `allowedTools`; connector tools your organization set to `ask` and tools that require user interaction are denied even if you've listed them	Locked-down headless agents
`auto`	A model classifier approves or denies permission prompts	Autonomous agents with safety guardrails
`bypassPermissions`	Runs every tool without prompting, except tools matched by an explicit `ask` rule, connector tools your organization set to `ask`, and tools that require user interaction. In the TypeScript SDK, also requires `allowDangerouslySkipPermissions: true` in `options`	Sandboxed CI, fully trusted environments
`default`	Requires a `canUseTool` callback to handle approval	Custom approval flows

다음 단계

Now that you've created your first agent, learn how to extend its capabilities and tailor it to your use case:

주요 항목:

Permissions: control what your agent can do and when it needs approval
Hooks: run custom code before or after tool calls
Sessions: build multi-turn agents that maintain context
MCP servers: connect to databases, browsers, APIs, and other external systems
Hosting: deploy agents to Docker, cloud, and CI/CD
Example agents: see complete examples: email assistant, research agent, and more

실습 체크리스트

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

자주 쓰는 명령·설정 예시

For your own projects, you can run the SDK from any folder; it will have access to files in that directory and its subdirectories by default.
  

  

    Install the Agent SDK package for your language:

Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.is) runs TypeScript files directly. npm prints `added N packages` when the install succeeds.

[tsx](https://tsx.is) runs TypeScript files directly. If your project uses CommonJS, name your agent script `agent.mts` instead of `agent.ts`. The `.mts` extension makes tsx treat the file as an ES module, so top-level `await` works without converting your whole project to ES modules. Use `agent.mts` in place of `agent.ts` in the create and run steps later in this quickstart.
      

      

        [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.

        On macOS or Linux:

On Windows:

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

    

    

      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 [Claude Console](https://platform.claude.com/), then set it as an environment variable in the shell where you'll run your agent:

The SDK reads the key from the environment of the process that runs your agent; it doesn't load `.env` files automatically. If you keep the key in a `.env` file, load it yourself, for example with the `dotenv` package, before calling the SDK.

    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](/docs/en/amazon-bedrock), [Claude Platform on AWS](/docs/en/claude-platform-on-aws), [Google Cloud's Agent Platform](/docs/en/google-vertex-ai), or [Microsoft Foundry](/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.
    

  

## Create a buggy file

This quickstart walks you through building an agent that can find and fix bugs in code. First, you need a file with some intentional bugs for the agent to fix. Create `utils.py` in the `my-agent` directory and paste the following code:

Quickstart

핵심 요약

문서 구성

상세 내용

Quickstart

사전 요구사항

설정

Create a buggy file

Build an agent that finds and fixes bugs

Run your agent

Try other prompts

Customize your agent

Key concepts

다음 단계

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Quickstart

핵심 요약

문서 구성

상세 내용

Quickstart

사전 요구사항

설정

Create a buggy file

Build an agent that finds and fixes bugs

Run your agent

Try other prompts

Customize your agent

Key concepts

다음 단계

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드