---
title: "TypeScript SDK V2 Interface (Preview)"
aliases: [typescript-v2, sdk-v2, agent-sdk-v2]
tags: [agent-sdk, typescript, v2, preview, sessions, multi-turn]
sources: [raw/TypeScript SDK V2 interface (preview).md]
created: 2026-04-17
updated: 2026-04-17
---

# TypeScript SDK V2 Interface (Preview)

> **Unstable preview** — APIs may change before becoming stable. Session forking and some advanced streaming patterns remain V1-only.

V2 removes async generators and yield coordination. Each conversation turn is a discrete `send()` / `stream()` cycle — no generator state to manage across turns.

## Installation

```sh
npm install @anthropic-ai/claude-agent-sdk
```

Same package as V1; V2 is additive under `unstable_v2_*` exports.

## Core API Surface

Three concepts cover the full interface:

| Concept | Function | Purpose |
|---------|----------|---------|
| Start session | `unstable_v2_createSession()` | New conversation |
| Resume session | `unstable_v2_resumeSession(id)` | Continue a stored session |
| One-shot | `unstable_v2_prompt()` | Single-turn, no session needed |

### SDKSession Interface

```typescript
interface SDKSession {
  readonly sessionId: string;
  send(message: string | SDKUserMessage): Promise<void>;
  stream(): AsyncGenerator<SDKMessage, void>;
  close(): void;
}
```

`send()` dispatches the message; `stream()` pulls the response. The explicit separation makes it easy to insert logic between turns.

## Usage Patterns

### One-shot prompt

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

const result = await unstable_v2_prompt("What is 2 + 2?", {
  model: "claude-opus-4-7"
});
if (result.subtype === "success") {
  console.log(result.result);
}
```

### Basic session (single turn)

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

await using session = unstable_v2_createSession({ model: "claude-opus-4-7" });

await session.send("Hello!");
for await (const msg of session.stream()) {
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((b) => b.type === "text")
      .map((b) => b.text)
      .join("");
    console.log(text);
  }
}
```

`await using` (TypeScript 5.2+) auto-closes the session when the block exits. Use `session.close()` manually on older TS.

### Multi-turn conversation

Call `send()` again on the same session — Claude retains prior context:

```typescript
await session.send("What is 5 + 3?");
for await (const msg of session.stream()) { /* ... */ }

await session.send("Multiply that by 2");  // references previous answer
for await (const msg of session.stream()) { /* ... */ }
```

### Session resume (across restarts)

Capture `msg.session_id` from any streamed message, close the session, then resume later:

```typescript
// Initial session
const session = unstable_v2_createSession({ model: "claude-opus-4-7" });
await session.send("Remember this number: 42");

let sessionId: string | undefined;
for await (const msg of session.stream()) {
  sessionId = msg.session_id;
}
session.close();

// Resume later
await using resumed = unstable_v2_resumeSession(sessionId!, {
  model: "claude-opus-4-7"
});
await resumed.send("What number did I ask you to remember?");
for await (const msg of resumed.stream()) { /* ... */ }
```

## Cleanup

| Method | When to use |
|--------|------------|
| `await using session = ...` | TypeScript 5.2+ — auto-closes on block exit |
| `session.close()` | Older TS or explicit lifecycle control |

## V1 Features Not Yet in V2

- Session forking (`forkSession` option)
- Some advanced streaming input patterns

Use [[wiki/agent-sdk/typescript-api-reference|typescript-api-reference]] (V1) for these.

## Key Takeaways

- **No generators** — V2 replaces the async generator / yield pattern with explicit `send()` + `stream()` per turn
- **Three exports** cover everything: `unstable_v2_createSession`, `unstable_v2_resumeSession`, `unstable_v2_prompt`
- **Session ID** is available on every `SDKMessage` as `msg.session_id` — capture it to enable resume
- **`await using`** (TS 5.2+) provides automatic resource cleanup; fall back to `.close()` otherwise
- **Unstable prefix** signals the API is a preview — don't ship production code against it without pinning the version
- **Same package** as V1 — no separate install; V1 and V2 coexist

## Related Articles

- [[wiki/agent-sdk/typescript-api-reference|TypeScript V1 API Reference]] — full stable API, session forking, advanced streaming
- [[wiki/agent-sdk/streaming-input|Streaming Input]] — V1 AsyncGenerator vs string input modes
- [[wiki/agent-sdk/streaming-output|Streaming Output]] — StreamEvent structure, text_delta, UI patterns
- [[wiki/agent-sdk/agent-loop|Agent Loop]] — message lifecycle, turns, compaction, sessions

## Sources

- `raw/TypeScript SDK V2 interface (preview).md`