Agent SDK

TypeScript SDK V2 接口（预览版）

简化的 V2 TypeScript Agent SDK 预览版，采用基于会话的 send/stream 模式进行多轮对话。

V2 接口是一个不稳定的预览版。API 可能会根据反馈在稳定之前进行更改。某些功能（如会话分叉）仅在 V1 SDK 中可用。

V2 Claude Agent TypeScript SDK 消除了对异步生成器和 yield 协调的需求。这使得多轮对话更加简单，无需跨轮次管理生成器状态，每一轮都是一个独立的 send()/stream() 周期。API 接口简化为三个概念：

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

安装

V2 接口包含在现有的 SDK 包中：

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

快速开始

一次性提示

对于不需要维护会话的简单单轮查询，使用 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-opus-4-6'
})
console.log(result.result)

查看 V1 中的相同操作

import { query } from '@anthropic-ai/claude-agent-sdk'

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

for await (const msg of q) {
  if (msg.type === 'result') {
    console.log(msg.result)
  }
}

基本会话

对于超出单个提示的交互，请创建一个会话。V2 将发送和流式传输分为不同的步骤：

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

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

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

import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'

await using session = unstable_v2_createSession({
  model: 'claude-opus-4-6'
})

await session.send('Hello!')
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 中的相同操作

在 V1 中，输入和输出都通过单个异步生成器流动。对于基本提示，这看起来类似，但添加多轮逻辑需要重构以使用输入生成器。

import { query } from '@anthropic-ai/claude-agent-sdk'

const q = query({
  prompt: 'Hello!',
  options: { model: 'claude-opus-4-6' }
})

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 会记住之前的轮次。

此示例提出一个数学问题，然后提出一个引用先前答案的后续问题：

import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'

await using session = unstable_v2_createSession({
  model: 'claude-opus-4-6'
})

// 第 1 轮
await session.send('What is 5 + 3?')
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)
  }
}

// 第 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 中的相同操作

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-6' }
})

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，关闭它，然后恢复对话：

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

// 从助手消息中提取文本的辅助函数
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-6'
})

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-6'
})

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 中的相同操作

import { query } from '@anthropic-ai/claude-agent-sdk'

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

// 从任何消息中获取会话 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-6',
    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+）：

import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'

await using session = unstable_v2_createSession({
  model: 'claude-opus-4-6'
})
// 当代码块退出时会话自动关闭

手动清理：

import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'

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

API 参考

`unstable_v2_createSession()`

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

function unstable_v2_createSession(options: {
  model: string;
  // 支持其他选项
}): Session

`unstable_v2_resumeSession()`

通过 ID 恢复现有会话。

function unstable_v2_resumeSession(
  sessionId: string,
  options: {
    model: string;
    // 支持其他选项
  }
): Session

`unstable_v2_prompt()`

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

function unstable_v2_prompt(
  prompt: string,
  options: {
    model: string;
    // 支持其他选项
  }
): Promise<Result>

Session 接口

interface Session {
  send(message: string): Promise<void>;
  stream(): AsyncGenerator<SDKMessage>;
  close(): void;
}

功能可用性

并非所有 V1 功能都已在 V2 中可用。以下功能需要使用 V1 SDK：

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

反馈

在 V2 接口稳定之前，请分享您的反馈。通过 GitHub Issues 报告问题和建议。

另请参阅

TypeScript SDK 参考（V1） - 完整的 V1 SDK 文档
SDK 概述 - 通用 SDK 概念
GitHub 上的 V2 示例 - 可运行的代码示例

Was this page helpful?

Agent SDK

TypeScript SDK V2 接口（预览版）

简化的 V2 TypeScript Agent SDK 预览版，采用基于会话的 send/stream 模式进行多轮对话。

V2 接口是一个不稳定的预览版。API 可能会根据反馈在稳定之前进行更改。某些功能（如会话分叉）仅在 V1 SDK 中可用。

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

安装

V2 接口包含在现有的 SDK 包中：

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

快速开始

一次性提示

对于不需要维护会话的简单单轮查询，使用 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-opus-4-6'
})
console.log(result.result)

查看 V1 中的相同操作

import { query } from '@anthropic-ai/claude-agent-sdk'

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

for await (const msg of q) {
  if (msg.type === 'result') {
    console.log(msg.result)
  }
}

基本会话

对于超出单个提示的交互，请创建一个会话。V2 将发送和流式传输分为不同的步骤：

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

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

import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'

await using session = unstable_v2_createSession({
  model: 'claude-opus-4-6'
})

await session.send('Hello!')
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 中的相同操作

在 V1 中，输入和输出都通过单个异步生成器流动。对于基本提示，这看起来类似，但添加多轮逻辑需要重构以使用输入生成器。

import { query } from '@anthropic-ai/claude-agent-sdk'

const q = query({
  prompt: 'Hello!',
  options: { model: 'claude-opus-4-6' }
})

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 会记住之前的轮次。

此示例提出一个数学问题，然后提出一个引用先前答案的后续问题：

import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'

await using session = unstable_v2_createSession({
  model: 'claude-opus-4-6'
})

// 第 1 轮
await session.send('What is 5 + 3?')
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)
  }
}

// 第 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 中的相同操作

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-6' }
})

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，关闭它，然后恢复对话：

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

// 从助手消息中提取文本的辅助函数
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-6'
})

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-6'
})

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 中的相同操作

import { query } from '@anthropic-ai/claude-agent-sdk'

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

// 从任何消息中获取会话 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-6',
    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+）：

import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'

await using session = unstable_v2_createSession({
  model: 'claude-opus-4-6'
})
// 当代码块退出时会话自动关闭

手动清理：

import { unstable_v2_createSession } from '@anthropic-ai/claude-agent-sdk'

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

API 参考

`unstable_v2_createSession()`

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

function unstable_v2_createSession(options: {
  model: string;
  // 支持其他选项
}): Session

`unstable_v2_resumeSession()`

通过 ID 恢复现有会话。

function unstable_v2_resumeSession(
  sessionId: string,
  options: {
    model: string;
    // 支持其他选项
  }
): Session

`unstable_v2_prompt()`

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

function unstable_v2_prompt(
  prompt: string,
  options: {
    model: string;
    // 支持其他选项
  }
): Promise<Result>

Session 接口

interface Session {
  send(message: string): Promise<void>;
  stream(): AsyncGenerator<SDKMessage>;
  close(): void;
}

功能可用性

并非所有 V1 功能都已在 V2 中可用。以下功能需要使用 V1 SDK：

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

反馈

在 V2 接口稳定之前，请分享您的反馈。通过 GitHub Issues 报告问题和建议。

另请参阅

TypeScript SDK 参考（V1） - 完整的 V1 SDK 文档
SDK 概述 - 通用 SDK 概念
GitHub 上的 V2 示例 - 可运行的代码示例

Was this page helpful?