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

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

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

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)

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:

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:

// 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 (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

wiki/agent-sdk/typescript-api-reference — full stable API, session forking, advanced streaming
wiki/agent-sdk/streaming-input — V1 AsyncGenerator vs string input modes
wiki/agent-sdk/streaming-output — StreamEvent structure, text_delta, UI patterns
wiki/agent-sdk/agent-loop — message lifecycle, turns, compaction, sessions

Sources

raw/TypeScript SDK V2 interface (preview).md

4.8 KiB Raw Permalink Blame History