Quickstart

Setup

Create a project folder

Create a new directory for this quickstart:

mkdir my-agent
cd my-agent

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 SDK

Install the Agent SDK package for your language:

TypeScript (new project)
TypeScript (existing project)
Python (uv)
Python (pip)

npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

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

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

tsx 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 is a fast Python package manager that handles virtual environments automatically:

uv init
uv add claude-agent-sdk

Create and activate a virtual environment, then install the package.On macOS or Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

On Windows:

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

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, so most installs need no separate Claude Code install. Some installs have no bundled binary:

If pip installs the Python SDK’s source distribution instead of a platform wheel, for example on ARM64 Windows, no binary is bundled. Install Claude Code natively. The Python SDK finds it on your PATH.
The TypeScript SDK installs its binary through npm optional dependencies, so an install that skips them, for example npm ci --omit=optional, gets no binary even on a supported platform. Reinstall without skipping optional dependencies, or install Claude Code natively and set pathToClaudeCodeExecutable to its path.

Set your API key

Get an API key from the Claude Console, then set it as an environment variable in the shell where you’ll run your agent:

macOS / Linux
Windows (PowerShell)

Agent SDK

Build agents

Core concepts

Input and output

Extend with tools

Customize behavior

Control and observability

Deployment

SDK references

Prerequisites

Setup

​Prerequisites

​Setup

Prerequisites

Setup