# Claude Agent SDK for TypeScript: Your First Agent

> Install @anthropic-ai/claude-agent-sdk, stream an agent that edits real files, gate its tools, and read the final result message.

- Canonical: https://guides-ai.pages.dev/guides/claude-agent-sdk-typescript-quickstart/
- Plate 15.10 · Topic: Building with the API (https://guides-ai.pages.dev/topics/api/)
- Published: 06 Sept 2026 · 4 min read
- Source site: guides-ai — https://guides-ai.pages.dev/

The Claude Agent SDK is the Claude Code harness as a library — the agent loop, built-in
Read/Edit/Bash/Glob/Grep tools, permissions and context management, called from your own
script. It is a different package from the Anthropic API SDK.

## 1. Install

Node.js 18 or later.

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

What it does: `"type": "module"` lets your script use top-level `await`, and `tsx` runs
TypeScript directly with no build step. The SDK ships a native Claude Code binary through
npm optional dependencies — an install that skips them (`npm ci --omit=optional`) gets no
binary, so reinstall without the flag or point `pathToClaudeCodeExecutable` at a native
install. In an existing CommonJS project, name the script `agent.mts` instead.

## 2. Set the key

```bash
export ANTHROPIC_API_KEY=your-api-key
```

```powershell
$env:ANTHROPIC_API_KEY = "your-api-key"
```

What it does: authenticates the agent. The SDK reads the variable from the process
environment and does not load `.env` files on its own.

## 3. Write the agent

`agent.ts`:

```typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review utils.ts for bugs that would cause crashes. Fix any issues you find.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
  },
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
      else if ("name" in block) console.log(`Tool: ${block.name}`);
    }
  } else if (message.type === "result") {
    console.log(`Done: ${message.subtype}`);
  }
}
```

What it does: `query()` returns an async generator of messages, so `for await` streams
Claude's reasoning, each tool call, and finally the outcome. `allowedTools` pre-approves
those three tools; anything else falls through to `permissionMode`.

## 4. Run it

```bash
npx tsx agent.ts
```

What it does: executes the loop against the current directory and its subdirectories. Check
the file on disk afterwards — a changed file is the only proof that matters.

## 5. Read the result

The `result` message is the one to log or persist. On `subtype: "success"` it carries
`result` (the final text), plus `num_turns`, `duration_ms`, `is_error`, `session_id` and
`total_cost_usd`. Treat `total_cost_usd` as a client-side estimate computed from a bundled
price table, not a billing statement.

Other options worth knowing: `systemPrompt`, `maxTurns`, `cwd`, `model`, and `mcpServers`
to hand the agent external tools.

---

Next: [the same agent in Python](/guides/claude-agent-sdk-python-quickstart/) or
[run Claude Code headless in CI](/guides/claude-code-headless-ci/).