Quickstart changedagent-sdk/quickstart
Nearest release: v2.1.312, published 2 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 27 Oct 2026 20:44 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 30 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+82added
Lines−82removed
From line
32
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits13to this page, all time
The whole hunk
from line 32, old and new numbered
/
from line 32
3232
3333Install the Agent SDK package for your language:
3434
35**TypeScript (new project)**
35> [tab] TypeScript (new project)
36>
37> ```bash theme={null}
38> npm init -y
39> npm pkg set type=module
40> npm install @anthropic-ai/claude-agent-sdk
41> npm install --save-dev tsx
42> ```
43>
44> Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.hirok.io) runs TypeScript files directly. npm prints `added N packages` when the install succeeds.
3645
37```bash theme={null}
38npm init -y
39npm pkg set type=module
40npm install @anthropic-ai/claude-agent-sdk
41npm install --save-dev tsx
42```
46> [tab] TypeScript (existing project)
47>
48> ```bash theme={null}
49> npm install @anthropic-ai/claude-agent-sdk
50> npm install --save-dev tsx
51> ```
52>
53> [tsx](https://tsx.hirok.io) 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.
4354
44Setting `"type": "module"` in `package.json` lets your agent script use top-level `await`, and [tsx](https://tsx.hirok.io) runs TypeScript files directly. npm prints `added N packages` when the install succeeds.
55> [tab] Python (uv)
56>
57> [Install uv](https://docs.astral.sh/uv/), a fast Python package manager that handles virtual environments automatically. Then initialize a project and add the SDK:
58>
59> ```bash theme={null}
60> uv init
61> uv add claude-agent-sdk
62> ```
4563
46**TypeScript (existing project)**
64> [tab] Python (pip)
65>
66> Create and activate a virtual environment, then install the package.
67>
68> On macOS or Linux:
69>
70> ```bash theme={null}
71> python3 -m venv .venv
72> source .venv/bin/activate
73> pip install claude-agent-sdk
74> ```
75>
76> On Windows:
77>
78> ```powershell theme={null}
79> py -m venv .venv
80> .venv\Scripts\Activate.ps1
81> pip install claude-agent-sdk
82> ```
83>
84> If PowerShell blocks `Activate.ps1` with an execution policy error, run `Set-ExecutionPolicy -Scope Process RemoteSigned` first.
4785
48```bash theme={null}
49npm install @anthropic-ai/claude-agent-sdk
50npm install --save-dev tsx
51```
52
53[tsx](https://tsx.hirok.io) 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.
54
55**Python (uv)**
56
57[Install uv](https://docs.astral.sh/uv/), a fast Python package manager that handles virtual environments automatically. Then initialize a project and add the SDK:
58
59```bash theme={null}
60uv init
61uv add claude-agent-sdk
62```
63
64**Python (pip)**
65
66Create and activate a virtual environment, then install the package.
67
68On macOS or Linux:
69
70```bash theme={null}
71python3 -m venv .venv
72source .venv/bin/activate
73pip install claude-agent-sdk
74```
75
76On Windows:
77
78```powershell theme={null}
79py -m venv .venv
80.venv\Scripts\Activate.ps1
81pip install claude-agent-sdk
82```
83
84If PowerShell blocks `Activate.ps1` with an execution policy error, run `Set-ExecutionPolicy -Scope Process RemoteSigned` first.
85
8686> [!NOTE]
8787>
8888> 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:
from line 94
9494
9595Get 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:
9696
97**macOS / Linux**
97> [tab] macOS / Linux
98>
99> ```bash theme={null}
100> export ANTHROPIC_API_KEY=your-api-key
101> ```
98102
99```bash theme={null}
100export ANTHROPIC_API_KEY=your-api-key
101```
103> [tab] Windows (PowerShell)
104>
105> ```powershell theme={null}
106> $env:ANTHROPIC_API_KEY = "your-api-key"
107> ```
102108
103**Windows (PowerShell)**
104
105```powershell theme={null}
106$env:ANTHROPIC_API_KEY = "your-api-key"
107```
108
109109The 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.
110110
111111The SDK also supports authentication via third-party API providers:
from line 220
220220
221221Your agent is ready. Run it with the following command:
222222
223**TypeScript**
223> [tab] TypeScript
224>
225> ```bash theme={null}
226> npx tsx agent.ts
227> ```
228>
229> If you named your script `agent.mts`, run `npx tsx agent.mts` instead.
224230
225```bash theme={null}
226npx tsx agent.ts
227```
231> [tab] Python (uv)
232>
233> ```bash theme={null}
234> uv run agent.py
235> ```
228236
229If you named your script `agent.mts`, run `npx tsx agent.mts` instead.
230
231**Python (uv)**
232
233```bash theme={null}
234uv run agent.py
235```
236
237**Python (pip)**
238
239With your virtual environment still activated:
240
241```bash theme={null}
242python agent.py
243```
237> [tab] Python (pip)
238>
239> With your virtual environment still activated:
240>
241> ```bash theme={null}
242> python agent.py
243> ```
244244
245245As it works, the agent prints its reasoning and each tool it calls, ending with `Done: success`. After running, check `utils.py`. You'll see defensive code handling empty lists and null users. Your agent autonomously:
246246
No line in this hunk matches that.