رفتن به محتوا
Claude Code Docs غیر رسمی

مرجع SDK نسخه ۲ تایپ‌اسکریپت برای نشست (حذف‌شده)

V2 یک API نشستِ آزمایشی بود که نیاز به async generatorها و هماهنگیِ yield را حذف می‌کرد. به‌جای مدیریتِ وضعیتِ generator در طولِ مراحل، هر مرحله یک چرخه‌ی جداگانه‌ی send()/stream() بود. سطحِ API به سه مفهوم کاهش یافت:

  • createSession() / resumeSession(): شروع یا ادامه‌ی یک گفتگو
  • session.send(): ارسالِ یک پیام
  • session.stream(): گرفتنِ پاسخ

نصب

Section titled “نصب”

Agent SDK 0.2.x آخرین نسخه‌ای است که رابطِ V2 را در بر دارد. نسخه‌ی پکیج از 0.2.x مستقیماً به 0.3.142 پرید، پس نسخه‌ی حذفِ بالا و پینِ نصبِ پایین، هر دو همان مرز را توصیف می‌کنند. برای نصبِ آخرین نسخه‌ی سازگار با V2، نسخه‌ی major و minor را پین کن:

Terminal window
npm install @anthropic-ai/claude-agent-sdk@0.2

شروعِ سریع

Section titled “شروعِ سریع”

پرامپتِ تک‌مرحله‌ای

Section titled “پرامپتِ تک‌مرحله‌ای”

برای پرس‌وجوهای ساده‌ی تک‌مرحله‌ای که نیازی به نگه‌داشتنِ نشست نداری، از 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-7"
});
if (result.subtype === "success") {
  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-7" }
});


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

نشستِ پایه

Section titled “نشستِ پایه”

برای تعامل‌های فراتر از یک پرامپتِ تکی، یک نشست بساز. V2 ارسال و استریم را به دو گامِ مجزا تفکیک می‌کند:

  • send() پیامت را ارسال می‌کند
  • stream() پاسخ را به‌صورت استریم برمی‌گرداند

این تفکیکِ صریح، افزودنِ منطق بینِ مراحل را آسان‌تر می‌کند (مثل پردازشِ پاسخ‌ها پیش از ارسالِ پیام‌های بعدی).

مثالِ زیر یک نشست می‌سازد، “Hello!” را به Claude می‌فرستد و پاسخِ متنی را چاپ می‌کند. از 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-7"
});


await session.send("Hello!");
for await (const msg of session.stream()) {
  // 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);
  }
}
همان عملیات در V1

در V1، هم ورودی و هم خروجی از یک async generator واحد جریان می‌یابند. برای یک پرامپتِ پایه این شبیه است، اما افزودنِ منطقِ چندمرحله‌ای نیازمندِ بازساختاردهی برای استفاده از یک input generator است.

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);
  }
}

گفتگوی چندمرحله‌ای

Section titled “گفتگوی چندمرحله‌ای”

نشست‌ها کانتکست را در طولِ چند تبادل حفظ می‌کنند. برای ادامه‌ی یک گفتگو، دوباره روی همان نشست send() را صدا بزن. Claude مراحلِ قبلی را به‌خاطر می‌سپارد.

این مثال یک سوالِ ریاضی می‌پرسد، سپس یک پرسشِ پیگیری می‌پرسد که به پاسخِ قبلی ارجاع می‌دهد:

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


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


// Turn 1
await session.send("What is 5 + 3?");
for await (const msg of session.stream()) {
  // 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.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";


// 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-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);
  }
}

ادامه‌ی نشست

Section titled “ادامه‌ی نشست”

اگر شناسه‌ی نشستی از یک تعاملِ قبلی داری، می‌توانی بعداً آن را ادامه بدهی. این برای ورک‌فلوهای طولانی‌مدت یا وقتی نیاز داری گفتگوها در طولِ راه‌اندازی‌های مجددِ برنامه پایدار بمانند مفید است.

این مثال یک نشست می‌سازد، شناسه‌اش را ذخیره می‌کند، آن را می‌بندد، سپس گفتگو را ادامه می‌دهد:

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-opus-4-7"
});


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.stream()) {
  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-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
import { query } from "@anthropic-ai/claude-agent-sdk";


// Create initial session
const initialQuery = query({
  prompt: "Remember this number: 42",
  options: { model: "claude-opus-4-7" }
});


// 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-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);
  }
}

پاک‌سازی

Section titled “پاک‌سازی”

نشست‌ها را می‌توان دستی بست، یا به‌صورت خودکار با 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-7"
});
// Session closes automatically when the block exits

پاک‌سازیِ دستی:

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


const session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});
// ... use the session ...
session.close();

مرجعِ API

Section titled “مرجعِ API”

unstable_v2_createSession()

Section titled “unstable_v2_createSession()”

یک نشستِ جدید برای گفتگوهای چندمرحله‌ای می‌سازد.

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

unstable_v2_resumeSession()

Section titled “unstable_v2_resumeSession()”

یک نشستِ موجود را با شناسه‌اش ادامه می‌دهد.

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

unstable_v2_prompt()

Section titled “unstable_v2_prompt()”

تابعِ سهولتِ تک‌مرحله‌ای برای پرس‌وجوهای تک‌نوبتی.

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

رابطِ SDKSession

Section titled “رابطِ SDKSession”
interface SDKSession {
  readonly sessionId: string;
  send(message: string | SDKUserMessage): Promise<void>;
  stream(): AsyncGenerator<SDKMessage, void>;
  close(): void;
}

در دسترس بودنِ قابلیت‌ها

Section titled “در دسترس بودنِ قابلیت‌ها”

API نشستِ V2 از همه‌ی قابلیت‌های V1 پشتیبانی نمی‌کند. موارد زیر به V1 SDK نیاز دارند:

  • فورک‌کردنِ نشست (گزینه‌ی forkSession)
  • برخی الگوهای پیشرفته‌ی استریمِ ورودی

همچنین ببینید

Section titled “همچنین ببینید”