古法编程

Appearance

V2 session API 已被移除，不再可用。如果你还在维护基于 Agent SDK 0.2.x 或更早版本的代码，本页可作为迁移参考。V2 中通过 session.send() 和 session.stream() 分离的多轮对话模式，在 V1 中需统一使用 query() API 并传入 AsyncIterable<SDKUserMessage> 实现连续对话，或通过 options.resume 恢复已保存的会话。安装最后兼容的版本需锁定 npm install @anthropic-ai/claude-agent-sdk@0.2。

Claude Code TypeScript SDK V2 会话 API（已移除）迁移参考 ​

V2 session API 不再支持。TypeScript Agent SDK 0.3.142 移除了 unstable_v2_createSession、unstable_v2_resumeSession、unstable_v2_prompt 以及 SDKSession 和 SDKSessionOptions 类型。

迁移方案：改用 query() API 及其支持的 session options。传递 AsyncIterable<SDKUserMessage> 实现多轮对话，或使用 options.resume 恢复已保存的会话。本页保留作为参考，仅适用于维护 Agent SDK 0.2.x 或更早版本的代码。

V2 是实验性会话 API，去除了异步生成器和 yield 协调。每个轮次是独立的 send() / stream() 循环，接口简化为三个概念：

  • createSession() / resumeSession()：开始或继续对话
  • session.send()：发送消息
  • session.stream()：获取响应

安装 ​

Agent SDK 0.2.x 是最后一个包含 V2 接口的版本。包版本从 0.2.x 直接跳到 0.3.142，所以上面的移除版本和下面的安装锁定描述的是同一个边界。要安装最后一个兼容 V2 的版本，锁定主版本和次版本：

bash
npm install @anthropic-ai/claude-agent-sdk@0.2

SDK 会为你的平台打包原生 Claude Code 二进制文件作为可选依赖，因此无需单独安装 Claude Code。

快速开始 ​

一次性提示 ​

对于不需要维护会话的简单单次查询，使用 unstable_v2_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);
}
查看 V1 对应写法
typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

const q = query({
  prompt: "What is 2 + 2?",
  options: { model: "claude-opus-4-7" }
});

for await (const msg of q) {
  if (msg.type === "result" && msg.subtype === "success") {
    console.log(msg.result);
  }
}

基本会话 ​

对于超出单次提示的交互，创建会话。V2 将发送和流式分离为独立步骤：

  • send() 发送你的消息
  • stream() 流式返回响应

这种显式分离使得在轮次之间添加逻辑（如在发送后续问题之前处理响应）更容易。

以下示例创建会话，向 Claude 发送 "Hello!"，并输出文本响应。它使用 await using（TypeScript 5.2+）在块退出时自动关闭会话。你也可手动调用 session.close()。

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()) {
  // 过滤出 assistant 消息以获取可读输出
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log(text);
  }
}
查看 V1 对应写法

在 V1 中，输入和输出都流经同一个异步生成器。对于基本提示，外观类似，但添加多轮逻辑需要重构以使用输入生成器。

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

const q = query({
  prompt: "Hello!",
  options: { model: "claude-opus-4-7" }
});

for await (const msg of q) {
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log(text);
  }
}

多轮对话 ​

会话在多次交互之间保留上下文。要继续对话，在同一会话上再次调用 send()。Claude 会记住之前的轮次。

以下示例先询问数学问题，然后提出引用之前答案的后续问题：

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

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

// 第 1 轮
await session.send("What is 5 + 3?");
for await (const msg of session.stream()) {
  // 过滤出 assistant 消息以获取可读输出
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log(text);
  }
}

// 第 2 轮
await session.send("Multiply that by 2");
for await (const msg of session.stream()) {
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log(text);
  }
}
查看 V1 对应写法
typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

// 需要创建异步可迭代对象来传递消息
async function* createInputStream() {
  yield {
    type: "user",
    session_id: "",
    message: { role: "user", content: [{ type: "text", text: "What is 5 + 3?" }] },
    parent_tool_use_id: null
  };
  // 需要协调何时 yield 下一条消息
  yield {
    type: "user",
    session_id: "",
    message: { role: "user", content: [{ type: "text", text: "Multiply by 2" }] },
    parent_tool_use_id: null
  };
}

const q = query({
  prompt: createInputStream(),
  options: { model: "claude-opus-4-7" }
});

for await (const msg of q) {
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log(text);
  }
}

恢复会话 ​

如果你有上一次交互的会话 ID，可以稍后恢复。这对于长时间运行的工作流或在应用重启后需要保留对话的场景很有用。

以下示例创建会话、存储 ID、关闭、然后恢复对话：

typescript
import {
  unstable_v2_createSession,
  unstable_v2_resumeSession,
  type SDKMessage
} from "@anthropic-ai/claude-agent-sdk";

// 辅助函数：从 assistant 消息中提取文本
function getAssistantText(msg: SDKMessage): string | null {
  if (msg.type !== "assistant") return null;
  return msg.message.content
    .filter((block) => block.type === "text")
    .map((block) => block.text)
    .join("");
}

// 创建初始会话并进行对话
const session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});

await session.send("Remember this number: 42");

// 从任何接收到的消息中获取会话 ID
let sessionId: string | undefined;
for await (const msg of session.stream()) {
  sessionId = msg.session_id;
  const text = getAssistantText(msg);
  if (text) console.log("Initial response:", text);
}

console.log("Session ID:", sessionId);
session.close();

// 稍后：使用存储的 ID 恢复会话
await using resumedSession = unstable_v2_resumeSession(sessionId!, {
  model: "claude-opus-4-7"
});

await resumedSession.send("What number did I ask you to remember?");
for await (const msg of resumedSession.stream()) {
  const text = getAssistantText(msg);
  if (text) console.log("Resumed response:", text);
}
查看 V1 对应写法
typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

// 创建初始会话
const initialQuery = query({
  prompt: "Remember this number: 42",
  options: { model: "claude-opus-4-7" }
});

// 从任何消息中获取会话 ID
let sessionId: string | undefined;
for await (const msg of initialQuery) {
  sessionId = msg.session_id;
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log("Initial response:", text);
  }
}

console.log("Session ID:", sessionId);

// 稍后：恢复会话
const resumedQuery = query({
  prompt: "What number did I ask you to remember?",
  options: {
    model: "claude-opus-4-7",
    resume: sessionId
  }
});

for await (const msg of resumedQuery) {
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log("Resumed response:", text);
  }
}

清理 ​

会话可以手动关闭，或使用 await using（TypeScript 5.2+ 自动资源清理特性）自动关闭。如果你使用较旧 TypeScript 版本或遇到兼容性问题，请改用手动清理。

自动清理（TypeScript 5.2+）：

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

await using session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});
// 块退出时自动关闭会话

手动清理：

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

const session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});
// ... 使用会话 ...
session.close();

API 参考 ​

unstable_v2_createSession() ​

创建用于多轮对话的新会话。

typescript
function unstable_v2_createSession(options: {
  model: string;
  // 额外选项支持
}): SDKSession;

unstable_v2_resumeSession() ​

通过 ID 恢复现有会话。

typescript
function unstable_v2_resumeSession(
  sessionId: string,
  options: {
    model: string;
    // 额外选项支持
  }
): SDKSession;

unstable_v2_prompt() ​

用于单次查询的便捷函数。

typescript
function unstable_v2_prompt(
  prompt: string,
  options: {
    model: string;
    // 额外选项支持
  }
): Promise<SDKResultMessage>;

SDKSession 接口 ​

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

功能可用性 ​

V2 会话 API 不支持所有 V1 功能。以下功能需要使用 V1 SDK：

  • 会话分叉（forkSession 选项）
  • 某些高级流输入模式

常见问题 ​

V2 session API 为什么被移除？ ​

V2 是实验性 API，其设计被证明与新一代 Agent SDK 的架构不一致。从 0.3.142 版本起，V2 接口被完全移除，统一为基于 query() API 和 session options 的 V1 模式。

如何从 V2 迁移到 V1？ ​

将 unstable_v2_createSession + send/stream 替换为 query() API。多轮对话需传入 AsyncIterable<SDKUserMessage>，恢复会话使用 options.resume。详见 TypeScript SDK 参考 和 sessions 文档。

V2 的 send/stream 在 V1 中怎么替代？ ​

V1 没有分离的 send 和 stream；所有输入输出通过 query() 返回的单个 AsyncGenerator 处理。要模拟多轮，你需要手动构建一个异步生成器函数 createInputStream() 并在其中 yield 用户消息，然后将该生成器作为 prompt 参数传入。V2 中的 send() 相当于在生成器内 yield 一条新消息，stream() 对应 for await...of 循环处理生成器输出。

参见 ​

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策