Agent SDK

Antarmuka TypeScript SDK V2 (pratinjau)

Pratinjau SDK Agent TypeScript V2 yang disederhanakan, dengan pola send/receive berbasis sesi untuk percakapan multi-turn.

Antarmuka V2 adalah pratinjau yang tidak stabil. API mungkin berubah berdasarkan umpan balik sebelum menjadi stabil. Beberapa fitur seperti session forking hanya tersedia di SDK V1.

SDK Agent TypeScript Claude V2 menghilangkan kebutuhan untuk async generators dan koordinasi yield. Ini membuat percakapan multi-turn lebih sederhana—alih-alih mengelola status generator di seluruh turn, setiap turn adalah siklus send()/receive() yang terpisah. Permukaan API berkurang menjadi tiga konsep:

createSession() / resumeSession(): Mulai atau lanjutkan percakapan
session.send(): Kirim pesan
session.receive(): Dapatkan respons

Instalasi

Antarmuka V2 disertakan dalam paket SDK yang ada:

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

Mulai cepat

Prompt sekali jalan

Untuk kueri single-turn sederhana di mana Anda tidak perlu mempertahankan sesi, gunakan unstable_v2_prompt(). Contoh ini mengirim pertanyaan matematika dan mencatat jawabannya:

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

const result = await unstable_v2_prompt('What is 2 + 2?', {
  model: 'claude-sonnet-4-5-20250929'
})
console.log(result.result)

Lihat operasi yang sama di V1

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

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

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

Sesi dasar

Untuk interaksi di luar prompt tunggal, buat sesi. V2 memisahkan pengiriman dan penerimaan menjadi langkah-langkah yang berbeda:

send() mengirimkan pesan Anda
receive() mengalirkan respons kembali

Pemisahan eksplisit ini memudahkan untuk menambahkan logika antar turn (seperti memproses respons sebelum mengirim tindak lanjut).

Contoh di bawah membuat sesi, mengirim "Hello!" ke Claude, dan mencetak respons teks. Ini menggunakan await using (TypeScript 5.2+) untuk secara otomatis menutup sesi ketika blok keluar. Anda juga dapat memanggil session.close() secara manual.

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

await using session = unstable_v2_createSession({
  model: 'claude-sonnet-4-5-20250929'
})

await session.send('Hello!')
for await (const msg of session.receive()) {
  // Filter for assistant messages to get human-readable output
  if (msg.type === 'assistant') {
    const text = msg.message.content
      .filter(block => block.type === 'text')
      .map(block => block.text)
      .join('')
    console.log(text)
  }
}

Lihat operasi yang sama di V1

Di V1, aliran input dan output melalui async generator tunggal. Untuk prompt dasar ini terlihat serupa, tetapi menambahkan logika multi-turn memerlukan restrukturisasi untuk menggunakan input generator.

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

const q = query({
  prompt: 'Hello!',
  options: { model: 'claude-sonnet-4-5-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)
  }
}

Percakapan multi-turn

Sesi mempertahankan konteks di seluruh pertukaran ganda. Untuk melanjutkan percakapan, panggil send() lagi pada sesi yang sama. Claude mengingat turn sebelumnya.

Contoh ini menanyakan pertanyaan matematika, kemudian menanyakan tindak lanjut yang mereferensikan jawaban sebelumnya:

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

await using session = unstable_v2_createSession({
  model: 'claude-sonnet-4-5-20250929'
})

// Turn 1
await session.send('What is 5 + 3?')
for await (const msg of session.receive()) {
  // Filter for assistant messages to get human-readable output
  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)
  }
}

Lihat operasi yang sama di V1

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

// Must create an async iterable to feed messages
async function* createInputStream() {
  yield {
    type: 'user',
    session_id: '',
    message: { role: 'user', content: [{ type: 'text', text: 'What is 5 + 3?' }] },
    parent_tool_use_id: null
  }
  // Must coordinate when to yield next message
  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-5-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)
  }
}

Lanjutkan sesi

Jika Anda memiliki ID sesi dari interaksi sebelumnya, Anda dapat melanjutkannya nanti. Ini berguna untuk alur kerja yang berjalan lama atau ketika Anda perlu mempertahankan percakapan di seluruh restart aplikasi.

Contoh ini membuat sesi, menyimpan ID-nya, menutupnya, kemudian melanjutkan percakapan:

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

// Helper to extract text from assistant messages
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('')
}

// Create initial session and have a conversation
const session = unstable_v2_createSession({
  model: 'claude-sonnet-4-5-20250929'
})

await session.send('Remember this number: 42')

// Get the session ID from any received message
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()

// Later: resume the session using the stored ID
await using resumedSession = unstable_v2_resumeSession(sessionId!, {
  model: 'claude-sonnet-4-5-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)
}

Lihat operasi yang sama di V1

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

// Create initial session
const initialQuery = query({
  prompt: 'Remember this number: 42',
  options: { model: 'claude-sonnet-4-5-20250929' }
})

// Get session ID from any message
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)

// Later: resume the session
const resumedQuery = query({
  prompt: 'What number did I ask you to remember?',
  options: {
    model: 'claude-sonnet-4-5-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)
  }
}

Pembersihan

Sesi dapat ditutup secara manual atau otomatis menggunakan await using, fitur TypeScript 5.2+ untuk pembersihan sumber daya otomatis. Jika Anda menggunakan versi TypeScript yang lebih lama atau mengalami masalah kompatibilitas, gunakan pembersihan manual sebagai gantinya.

Pembersihan otomatis (TypeScript 5.2+):

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

await using session = unstable_v2_createSession({
  model: 'claude-sonnet-4-5-20250929'
})
// Session closes automatically when the block exits

Pembersihan manual:

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

const session = unstable_v2_createSession({
  model: 'claude-sonnet-4-5-20250929'
})
// ... use the session ...
session.close()

Referensi API

`unstable_v2_createSession()`

Membuat sesi baru untuk percakapan multi-turn.

function unstable_v2_createSession(options: {
  model: string;
  // Additional options supported
}): Session

`unstable_v2_resumeSession()`

Melanjutkan sesi yang ada berdasarkan ID.

function unstable_v2_resumeSession(
  sessionId: string,
  options: {
    model: string;
    // Additional options supported
  }
): Session

`unstable_v2_prompt()`

Fungsi kenyamanan sekali jalan untuk kueri single-turn.

function unstable_v2_prompt(
  prompt: string,
  options: {
    model: string;
    // Additional options supported
  }
): Promise<Result>

Antarmuka Sesi

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

Ketersediaan fitur

Tidak semua fitur V1 tersedia di V2 namun. Berikut ini memerlukan penggunaan SDK V1:

Session forking (opsi forkSession)
Beberapa pola input streaming lanjutan

Umpan balik

Bagikan umpan balik Anda tentang antarmuka V2 sebelum menjadi stabil. Laporkan masalah dan saran melalui GitHub Issues.

Lihat juga

Referensi TypeScript SDK (V1) - Dokumentasi SDK V1 lengkap
Gambaran umum SDK - Konsep SDK umum
Contoh V2 di GitHub - Contoh kode yang berfungsi

Agent SDK

Antarmuka TypeScript SDK V2 (pratinjau)

Pratinjau SDK Agent TypeScript V2 yang disederhanakan, dengan pola send/receive berbasis sesi untuk percakapan multi-turn.

Antarmuka V2 adalah pratinjau yang tidak stabil. API mungkin berubah berdasarkan umpan balik sebelum menjadi stabil. Beberapa fitur seperti session forking hanya tersedia di SDK V1.

createSession() / resumeSession(): Mulai atau lanjutkan percakapan
session.send(): Kirim pesan
session.receive(): Dapatkan respons

Instalasi

Antarmuka V2 disertakan dalam paket SDK yang ada:

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

Mulai cepat

Prompt sekali jalan

Untuk kueri single-turn sederhana di mana Anda tidak perlu mempertahankan sesi, gunakan unstable_v2_prompt(). Contoh ini mengirim pertanyaan matematika dan mencatat jawabannya:

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

const result = await unstable_v2_prompt('What is 2 + 2?', {
  model: 'claude-sonnet-4-5-20250929'
})
console.log(result.result)

Lihat operasi yang sama di V1

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

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

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

Sesi dasar

Untuk interaksi di luar prompt tunggal, buat sesi. V2 memisahkan pengiriman dan penerimaan menjadi langkah-langkah yang berbeda:

send() mengirimkan pesan Anda
receive() mengalirkan respons kembali

Pemisahan eksplisit ini memudahkan untuk menambahkan logika antar turn (seperti memproses respons sebelum mengirim tindak lanjut).

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

await using session = unstable_v2_createSession({
  model: 'claude-sonnet-4-5-20250929'
})

await session.send('Hello!')
for await (const msg of session.receive()) {
  // Filter for assistant messages to get human-readable output
  if (msg.type === 'assistant') {
    const text = msg.message.content
      .filter(block => block.type === 'text')
      .map(block => block.text)
      .join('')
    console.log(text)
  }
}

Lihat operasi yang sama di V1

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

const q = query({
  prompt: 'Hello!',
  options: { model: 'claude-sonnet-4-5-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)
  }
}

Percakapan multi-turn

Sesi mempertahankan konteks di seluruh pertukaran ganda. Untuk melanjutkan percakapan, panggil send() lagi pada sesi yang sama. Claude mengingat turn sebelumnya.

Contoh ini menanyakan pertanyaan matematika, kemudian menanyakan tindak lanjut yang mereferensikan jawaban sebelumnya:

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

await using session = unstable_v2_createSession({
  model: 'claude-sonnet-4-5-20250929'
})

// Turn 1
await session.send('What is 5 + 3?')
for await (const msg of session.receive()) {
  // Filter for assistant messages to get human-readable output
  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)
  }
}

Lihat operasi yang sama di V1

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

// Must create an async iterable to feed messages
async function* createInputStream() {
  yield {
    type: 'user',
    session_id: '',
    message: { role: 'user', content: [{ type: 'text', text: 'What is 5 + 3?' }] },
    parent_tool_use_id: null
  }
  // Must coordinate when to yield next message
  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-5-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)
  }
}

Lanjutkan sesi

Contoh ini membuat sesi, menyimpan ID-nya, menutupnya, kemudian melanjutkan percakapan:

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

// Helper to extract text from assistant messages
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('')
}

// Create initial session and have a conversation
const session = unstable_v2_createSession({
  model: 'claude-sonnet-4-5-20250929'
})

await session.send('Remember this number: 42')

// Get the session ID from any received message
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()

// Later: resume the session using the stored ID
await using resumedSession = unstable_v2_resumeSession(sessionId!, {
  model: 'claude-sonnet-4-5-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)
}

Lihat operasi yang sama di V1

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

// Create initial session
const initialQuery = query({
  prompt: 'Remember this number: 42',
  options: { model: 'claude-sonnet-4-5-20250929' }
})

// Get session ID from any message
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)

// Later: resume the session
const resumedQuery = query({
  prompt: 'What number did I ask you to remember?',
  options: {
    model: 'claude-sonnet-4-5-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)
  }
}

Pembersihan

Pembersihan otomatis (TypeScript 5.2+):

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

await using session = unstable_v2_createSession({
  model: 'claude-sonnet-4-5-20250929'
})
// Session closes automatically when the block exits

Pembersihan manual:

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

const session = unstable_v2_createSession({
  model: 'claude-sonnet-4-5-20250929'
})
// ... use the session ...
session.close()

Referensi API

`unstable_v2_createSession()`

Membuat sesi baru untuk percakapan multi-turn.

function unstable_v2_createSession(options: {
  model: string;
  // Additional options supported
}): Session

`unstable_v2_resumeSession()`

Melanjutkan sesi yang ada berdasarkan ID.

function unstable_v2_resumeSession(
  sessionId: string,
  options: {
    model: string;
    // Additional options supported
  }
): Session

`unstable_v2_prompt()`

Fungsi kenyamanan sekali jalan untuk kueri single-turn.

function unstable_v2_prompt(
  prompt: string,
  options: {
    model: string;
    // Additional options supported
  }
): Promise<Result>

Antarmuka Sesi

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

Ketersediaan fitur

Tidak semua fitur V1 tersedia di V2 namun. Berikut ini memerlukan penggunaan SDK V1:

Session forking (opsi forkSession)
Beberapa pola input streaming lanjutan

Umpan balik

Bagikan umpan balik Anda tentang antarmuka V2 sebelum menjadi stabil. Laporkan masalah dan saran melalui GitHub Issues.

Lihat juga

Referensi TypeScript SDK (V1) - Dokumentasi SDK V1 lengkap
Gambaran umum SDK - Konsep SDK umum
Contoh V2 di GitHub - Contoh kode yang berfungsi