Claude Agent SDK V2 预览解析基于 send/receive 会话模式的多轮对话编程【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem本文围绕docs/context/agent-sdk-v2-preview.md预览文档展开讲解 Anthropic Claude Agent SDK 的 V2 TypeScript 接口它用createSession()/resumeSession()send()/receive()取代了 V1 中需要手工协调的异步生成器把多轮对话简化为三个核心概念。读完本文你可以直接用 V2 预览接口编写单发提问、多轮会话、跨进程会话恢复resume等程序并结合 claude-mem 仓库中真实使用 V1 SDK 的源码理解两种模式在会话 ID 捕获与恢复机制上的同源性。V2 接口定位去掉异步生成器保留会话语义V2 是一个不稳定的预览接口API 可能在稳定前根据反馈发生变化部分功能如会话分叉 session forking目前仅 V1 SDK 可用。V2 的核心变化在于去掉了 async generator 与 yield 协调V1 中输入和输出都流经同一个query()返回的异步生成器多轮对话需要构造一个 async iterable 来喂消息并自行协调何时 yield 下一条消息V2 中每一轮对话都是独立的send()/receive()周期API 表面收敛为三个概念createSession()/resumeSession()开始或继续一段对话session.send()发送一条消息session.receive()接收流式响应。这种显式的收发分离让在两轮之间插入自定义逻辑例如先处理上一轮响应再决定追问内容变得自然无需再为生成器状态做结构化改写。安装V2 接口包含在现有的 SDK 包中无需单独安装npm install anthropic-ai/claude-agent-sdkclaude-mem 仓库当前依赖的版本是^0.3.172见 package.json 中的devDependencies说明该包会被 esbuild 内联进 worker/server/npx 产物是构建期依赖。需要注意本仓库自身运行在 V1 接口上V2 预览是为 SDK 使用者提供的简化路径。快速上手1. 单发提问unstable_v2_prompt()对于不需要维持会话的简单单轮查询使用unstable_v2_prompt()。它发送一个数学问题并打印答案import { unstable_v2_prompt } from anthropic-ai/claude-agent-sdk const result await unstable_v2_prompt(What is 2 2?, { model: claude-sonnet-4-6-20250929 }) console.log(result.result)同样的操作在 V1 中需要消费一个异步生成器并等待result类型的消息import { query } from anthropic-ai/claude-agent-sdk const q query({ prompt: What is 2 2?, options: { model: claude-sonnet-4-6-20250929 } }) for await (const msg of q) { if (msg.type result) { console.log(msg.result) } }2. 基础会话send() 与 receive() 分离对于超过单轮提示的交互创建一个 session。V2 把发送与接收拆成两个显式步骤send()派发你的消息receive()流式返回响应。下例创建会话、向 Claude 发送 Hello! 并打印文本响应使用await usingTypeScript 5.2在代码块退出时自动关闭会话也可以手动调用session.close()import { unstable_v2_createSession } from anthropic-ai/claude-agent-sdk await using session unstable_v2_createSession({ model: claude-sonnet-4-6-20250929 }) await session.send(Hello!) for await (const msg of session.receive()) { // 过滤 assistant 消息以获得人类可读输出 if (msg.type assistant) { const text msg.message.content .filter(block block.type text) .map(block block.text) .join() console.log(text) } }V1 中同样的基础提示看起来类似一个for await循环消费query()但一旦要加多轮逻辑就必须重构为输入生成器。3. 多轮对话同一会话反复 send()Session 跨多次交互保持上下文。要继续对话只需在同一个 session 上再次调用send()Claude 会记住之前的轮次。下例先问一个数学问题再追问引用上一轮答案的内容import { unstable_v2_createSession } from anthropic-ai/claude-agent-sdk await using session unstable_v2_createSession({ model: claude-sonnet-4-6-20250929 }) // Turn 1 await session.send(What is 5 3?) for await (const msg of session.receive()) { if (msg.type assistant) { const text msg.message.content .filter(block block.type text) .map(block block.text) .join() console.log(text) } } // Turn 2 await session.send(Multiply that by 2) for await (const msg of session.receive()) { if (msg.type assistant) { const text msg.message.content .filter(block block.type text) .map(block block.text) .join() console.log(text) } }作为对照V1 完成同样多轮对话必须构造一个 async iterable 来逐条 yield 用户消息并手工协调 yield 时机import { query } from anthropic-ai/claude-agent-sdk // 必须创建 async iterable 来喂消息 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-sonnet-4-6-20250929 } }) 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) } }4. 会话恢复session_id 捕获与 resume如果你持有上次交互的 session ID可以稍后恢复它。这对长时工作流或跨应用重启持久化对话很有用。下例创建会话、存储其 ID、关闭会话然后恢复对话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-sonnet-4-6-20250929 }) await session.send(Remember this number: 42) // 从任意收到的消息中获取 session ID let sessionId: string | undefined for await (const msg of session.receive()) { 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-sonnet-4-6-20250929 }) await resumedSession.send(What number did I ask you to remember?) for await (const msg of resumedSession.receive()) { const text getAssistantText(msg) if (text) console.log(Resumed response:, text) }V1 的等价做法是从消息中取session_id再通过options.resume传回一个新的query()import { query } from anthropic-ai/claude-agent-sdk // 创建初始会话 const initialQuery query({ prompt: Remember this number: 42, options: { model: claude-sonnet-4-6-20250929 } }) // 从任意消息中获取 session 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-sonnet-4-6-20250929, 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) } }资源清理自动与手动两种写法会话可以手动关闭也可以使用 TypeScript 5.2 的await using特性自动清理资源如果你使用旧版 TypeScript 或遇到兼容性问题请改用手动清理。自动清理TypeScript 5.2import { unstable_v2_createSession } from anthropic-ai/claude-agent-sdk await using session unstable_v2_createSession({ model: claude-sonnet-4-6-20250929 }) // 代码块退出时会话自动关闭手动清理import { unstable_v2_createSession } from anthropic-ai/claude-agent-sdk const session unstable_v2_createSession({ model: claude-sonnet-4-6-20250929 }) // ... 使用会话 ... session.close()API 参考unstable_v2_createSession()创建用于多轮对话的新会话function unstable_v2_createSession(options: { model: string; // 支持更多选项 }): Sessionunstable_v2_resumeSession()按 ID 恢复已有会话function unstable_v2_resumeSession( sessionId: string, options: { model: string; // 支持更多选项 } ): Sessionunstable_v2_prompt()单轮查询的一次性便捷函数function unstable_v2_prompt( prompt: string, options: { model: string; // 支持更多选项 } ): PromiseResultSession 接口interface Session { send(message: string): Promisevoid; receive(): AsyncGeneratorSDKMessage; close(): void; }从接口签名看receive()本身返回AsyncGeneratorSDKMessage即接收侧仍然以流的形式逐条产出消息V2 消除的只是发送侧的生成器协调负担消息类型SDKMessage与 V1 保持一致session_id字段也继续随消息下发。可运行的官方示例脚本仓库的docs/context/目录下随预览文档附带了一份可直接运行的 V2 示例脚本 agent-sdk-v2-examples.ts覆盖了文档中的全部四个场景通过命令行参数切换npx tsx docs/context/agent-sdk-v2-examples.ts [basic|multi-turn|one-shot|resume]脚本中有几处对预览文档的实操性补充模型别名示例统一使用model: sonnet短别名说明 V2 选项同样接受别名形式而预览文档正文使用完整模型 IDclaude-sonnet-4-6-20250929二者皆可从 system/init 消息取 session_idresume场景中脚本从msg.type system msg.subtype init的消息里读取msg.session_id并打印这是对文档从任意收到的消息中获取 session ID的具体化——init 消息是最稳定的捕获点单发结果的成本字段one-shot场景在result.subtype success时打印result.result与result.total_cost_usd.toFixed(4)说明unstable_v2_prompt()的Result对象携带subtype、result、total_cost_usd等字段可据此做成功判定与成本核算分块隔离的会话生命周期resume 场景用两个独立{ }块分别包两个await using session第一个块退出即关闭首个会话模拟时间流逝后再恢复。功能可用性边界哪些仍需用 V1并非所有 V1 功能在 V2 中可用。以下能力目前仍需使用 V1 SDK会话分叉forkSession选项部分高级流式输入模式。此外unstable_前缀本身表明这是未稳定接口生产代码应评估回退到 V1query()的成本。V2 模式与 claude-mem 的 V1 用法对照claude-mem 是一个捕获 Agent 会话、AI 压缩、回注上下文的持久记忆项目其 worker 内部恰恰是 V1 SDK 的重度使用者因此 V2 预览文档中的 V1 对照代码在仓库里都有真实的对应实现可以印证两种模式的机制同源性架构定位docs/public/architecture/overview.mdx 在技术栈表将 AI SDK 一栏标注为anthropic-ai/claude-agent-sdk (or Gemini / OpenRouter)多轮喂入与流式消费src/services/worker/ClaudeProvider.ts 中startSession()以query({ prompt: messageGenerator, options: ... })启动会话约 L274随后for await (const message of queryResult)逐条消费——这正是 V2 用send()/receive()简化掉的输入生成器 输出消费双生成器结构session_id 捕获与 resumeClaudeProvider 在消费循环中检测message.session_id与本地memorySessionId比对后更新并落库ensureMemorySessionIdRegistered约 L334-L356下一轮再通过options.resume传回这与预览文档 resume 章节从消息捕获 ID、恢复时回传 ID的流程完全一致。源码中的注释也点明了原因每次query()启动一个全新的 SDK 进程捕获的 ID 才能安全地喂回后续进程的resume知识库问答的 resumesrc/services/worker/knowledge/KnowledgeAgent.ts 中query()调用携带resume: corpus.session_id并在正则匹配到session|resume|expired|invalid.*session|not found类错误消息时判定会话已失效——这是对 resume 语义边界会话可能过期/失效的工程化处理。这些实现细节说明V2 的send()/receive()只是把 V1 中输入生成器协调 输出流消费 session_id 捕获/resume这套机制内化到了 Session 对象里会话上下文的持久化语义跨进程靠 session_id 恢复在两个版本中是同一套。对熟悉 claude-mem 源码的读者而言迁移心智成本主要集中在不再自己 yield 用户消息这一点上。适用前提与限制小结V2 为不稳定预览API 在稳定前可能变化会话分叉等能力暂缺需要这些功能时请使用 V1query()await using自动清理要求 TypeScript 5.2旧版本请显式调用session.close()model选项既接受完整模型 ID如claude-sonnet-4-6-20250929仓库示例中也使用sonnet别名本仓库claude-mem的运行时路径构建在 V1 SDK^0.3.172之上本文的 V2 内容基于仓库内预览文档与示例脚本供 SDK 使用者参考不代表仓库内部已切换 V2。【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考