📘 תיעוד 132

שמירת הפעלות באחסון חיצוני

שיקוף תמלילי הפעלות אל S3, Redis, או מערכת אחורית משלכם כדי שמארחים אחרים יוכלו לחדש את ההפעלות שלכם.

כברירת מחדל, ה-SDK כותב תמלילי הפעלות לקובצי JSONL תחת ~/.claude/projects/ במערכת הקבצים המקומית. מתאם SessionStore מאפשר לכם לשקף את התמלילים האלה למערכת אחורית משלכם, כגון S3, Redis, או מסד נתונים, כך שהפעלה שנוצרה במארח אחד תוכל להתחדש במארח אחר שרץ מתוך ספריית עבודה תואמת.

סיבות נפוצות לשימוש באחסון הפעלות:

• פריסות מרובות מארחים. פונקציות Serverless, תהליכי עבודה בהתאמת גודל אוטומטית (autoscaled workers), ומריצי CI אינם חולקים מערכת קבצים. אחסון משותף מאפשר לעותקים לשחזר זה את ההפעלות של זה.
• שרידות. קונטיינרים מקומיים הם זמניים (ephemeral). אחסון המגובה על ידי S3 או מסד נתונים שורד הפעלות מחדש ופריסות מחדש.
• תאימות וביקורת. שמירת תמלילים באחסון שכבר נשלט על ידיכם, עם כללי שימור, הצפנה ובקרות גישה משלכם.

#ממשק ה-SessionStore

SessionStore הוא אובייקט עם שתי מתודות חובה, append ו-load, וארבע מתודות רשות. ה-SDK קורא ל-append כדי לכתוב רשומות תמליל במהלך שאילתה, ול-load כדי לקרוא אותן בחזרה לצורך חידוש.

#TypeScript

// Exported from @anthropic-ai/claude-agent-sdk as
// SessionStore, SessionKey, SessionStoreEntry, SessionSummaryEntry.

type SessionKey = {
  projectKey: string;
  sessionId: string;
  subpath?: string;
};

type SessionStore = {
  // Required
  append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
  load(key: SessionKey): Promise<SessionStoreEntry[] | null>;

  // Optional
  listSessions?(
    projectKey: string,
  ): Promise<Array<{ sessionId: string; mtime: number }>>;
  listSessionSummaries?(projectKey: string): Promise<SessionSummaryEntry[]>;
  delete?(key: SessionKey): Promise<void>;
  listSubkeys?(key: {
    projectKey: string;
    sessionId: string;
  }): Promise<string[]>;
};

type SessionSummaryEntry = {
  sessionId: string;
  mtime: number;
  data: Record<string, unknown>;
};

#Python

# Exported from claude_agent_sdk as
# SessionStore, SessionKey, SessionStoreEntry, SessionSummaryEntry.

class SessionKey(TypedDict):
    project_key: str
    session_id: str
    subpath: NotRequired[str]

class SessionStore(Protocol):
    
# Required
    async def append(
        self, key: SessionKey, entries: list[SessionStoreEntry]
    ) -> None: ...
    async def load(self, key: SessionKey) -> list[SessionStoreEntry] | None: ...

    
# Optional: omit or raise NotImplementedError
    async def list_sessions(
        self, project_key: str
    ) -> list[SessionStoreListEntry]: ...
    async def list_session_summaries(
        self, project_key: str
    ) -> list[SessionSummaryEntry]: ...
    async def delete(self, key: SessionKey) -> None: ...
    async def list_subkeys(self, key: SessionListSubkeysKey) -> list[str]: ...

class SessionSummaryEntry(TypedDict):
    session_id: str
    mtime: int
    data: dict[str, Any]

SessionKey פונה לתמליל אחד. projectKey הוא קידוד יציב ובטוח למערכת הקבצים של ספריית העבודה, sessionId הוא ה-UUID של ההפעלה, ו-subpath מוגדר כאשר הרשומה שייכת לתמליל של סוכן משנה או לקובץ נלווה (sidecar) במקום לשיחה הראשית.

מכיוון ש-projectKey מקודד את ספריית העבודה, יש לבצע חידוש או המשך מתוך האחסון מתוך ספריית עבודה התואמת לזו של ההרצה המקורית. ב-TypeScript, אם תגדירו את CLAUDE_CODE_PROJECT_DIR_NAME לצד CLAUDE_CONFIG_DIR באפשרות env של השאילתה, ה-SDK ימפתח את הרשומות של אותה שאילתה, ואת בדיקות ה-resume וה-continue שלה, לפי שם זה במקום זאת. מכיוון שפונקציות עזר עצמאיות כגון listSessions ו-deleteSession אינן מקבלות env וקוראות את סביבת התהליך, הגדירו את CLAUDE_CONFIG_DIR ואת אותו השם גם בסביבת תהליך המארח. נדרש Agent SDK בגרסה v0.3.234 ואילך.

התייחסו אל subpath כאל סיומת מפתח אטומה. הוא עוקב אחר המבנה בדיסק, למשל subagents/agent-<id>. כאשר subpath אינו מוגדר, המפתח מתייחס לתמליל הראשי.

ב-SessionSummaryEntry, הערך mtime הוא זמן הכתיבה לאחסון של קובץ ה-sidecar, וחייב לחלוק מקור שעון עם ערכי ה-mtime שמוחזרים מ-listSessions. הערך data הוא מצב אטום בבעלות ה-SDK. שמרו אותו כפי שהוא מבלי לפרש אותו.

בנו את הרשומות על ידי קריאה לפונקציית העזר המיוצאת foldSessionSummary, או fold_session_summary ב-Python, עבור כל אצווה בתוך append. דלגו על אצוות שהמפתח שלהן כולל subpath. תמלילים של סוכני משנה אינם צריכים לתרום לסיכום של ההפעלה הראשית. פונקציית הקיפול לעולם אינה מגדירה את mtime: החתימו אותו בזמן השמירה, דרך ארגומנט options.mtime ב-TypeScript או על ידי דריסת השדה ברשומה המוחזרת ב-Python. קריאות append מקבילות לאותה הפעלה עלולות להתחרות על קובץ ה-sidecar, ולכן יש לסדר את תהליך הקריאה, הקיפול והכתיבה ברצף באמצעות טרנזקציה, compare-and-swap, או נעילה לכל הפעלה. פעולת הקיפול עצמה היא טהורה (pure).

למידע על מה שה-SDK עושה עם התמליל ש-load מחזירה, ראו חידוש מתוך האחסון.

#התחלה מהירה

ה-SDK כולל את InMemorySessionStore לצורכי פיתוח ובדיקות. הדוגמה להלן מריצה שאילתה עם האחסון מחובר, לוכדת את מזהה ההפעלה מהודעת התוצאה, ולאחר מכן מחדשת מתוך האחסון בקריאת query() שנייה. הקריאה השנייה מעבירה את אותו מופע אחסון בתוספת resume, כך שה-SDK טוען את התמליל מהאחסון במקום ממערכת הקבצים המקומית:

#TypeScript

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

const store = new InMemorySessionStore();

let sessionId: string | undefined;
try {
  for await (const message of query({
    prompt: "List the TypeScript files under src/",
    options: { sessionStore: store },
  })) {
    if (message.type === "result") {
      sessionId = message.session_id;
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, sessionId was already captured by the loop
  // above; connection or process failures yield no result message.
  console.error(`Session ended with an error: ${error}`);
}

// Resume from the store. The agent has full context from the first call.
for await (const message of query({
  prompt: "Summarize what those files do",
  options: { sessionStore: store, resume: sessionId },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

#Python

import asyncio
from claude_agent_sdk import (
    ClaudeAgentOptions,
    InMemorySessionStore,
    ResultMessage,
    query,
)

store = InMemorySessionStore()


async def main():
    session_id = None
    try:
        async for message in query(
            prompt="List the Python files under src/",
            options=ClaudeAgentOptions(session_store=store),
        ):
            if isinstance(message, ResultMessage):
                session_id = message.session_id
    except Exception as error:
        
# A single-shot query() raises after yielding an error result. If the
        
# failure was an error result, session_id was already captured by the
        
# loop above; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")

    
# Resume from the store. The agent has full context from the first call.
    async for message in query(
        prompt="Summarize what those files do",
        options=ClaudeAgentOptions(session_store=store, resume=session_id),
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

השאילתה השנייה מדפיסה סיכום של הקבצים מהשאילתה הראשונה, מה שמראה שהסוכן התחדש עם הקשר מלא מתוך האחסון.

#כתיבת מתאם משלכם

ממשו את append ואת load מול המערכת האחורית שלכם. הוסיפו את listSessions, listSessionSummaries, delete ו-listSubkeys אם אתם רוצים ש-listSessions(), קריאות מטא נתונים בקריאה אחת, deleteSession() וחידוש סוכני משנה יעבדו מול האחסון.

רשומות המועברות אל append מוגדרות כטיפוס SessionStoreEntry (אובייקט של { type: string; ... }). התייחסו אליהן כאל ערכים אטומים ובטוחים ל-JSON: שימרו אותן לפי הסדר והחזירו אותן מ-load באותו הסדר. המתודה load חייבת להחזיר רשומות בעלות שוויון עמוק (deep-equal) למה שצורף. אין דרישה לסריאליזציה זהה ברמת הבייטים, ולכן מערכות אחוריות כמו jsonb ב-Postgres שמשנות את סדר המפתחות באובייקט מתאימות לחלוטין.

#מימושי ייחוס

מאגר ה-SDK של TypeScript כולל מתאמי ייחוס שניתנים להרצה עבור S3, Redis ו-Postgres תחת examples/session-stores/. הם אינם מפורסמים ב-npm. העתיקו את קובץ ה-src/ הדרוש לכם לתוך הפרויקט שלכם והתקינו את לקוח המערכת האחורית המתאים.

כל מתאם מקבל מופע לקוח שהוגדר מראש, כך שאתם שולטים באישורי גישה, ב-TLS, באזור ובניהול מאגר חיבורים (pooling). לדוגמה, עם S3:

import { query } from "@anthropic-ai/claude-agent-sdk";
import { S3Client } from "@aws-sdk/client-s3";
import { S3SessionStore } from "./S3SessionStore"; // copied from examples/session-stores/s3

const store = new S3SessionStore({
  bucket: "my-claude-sessions",
  prefix: "transcripts",
  client: new S3Client({ region: "us-east-1" }),
});

for await (const message of query({
  prompt: "Hello!",
  options: { sessionStore: store },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

// Later, possibly on a different host:
for await (const message of query({
  prompt: "Continue where we left off",
  options: { sessionStore: store, resume: "previous-session-id" },
})) {
  // ...
}

#אימות המתאם שלכם

שני ה-SDKs מגיעים עם חבילת בדיקות תאימות שמוודאת את החוזה ההתנהגותי ש-append, load והמתודות האופציונליות חייבות לקיים. בדיקות עבור מתודות אופציונליות מדולגות אוטומטית כאשר מתודות אלו אינן ממומשות.

ב-TypeScript, העתיקו את shared/conformance.ts מספריית הדוגמאות לתוך מערך הבדיקות שלכם. ב-Python, חבילת הבדיקות מגיעה בתוך החבילה עצמה. כדי להריץ אותה עם pytest, שאינו תלות של ה-SDK, התקינו קודם את pytest:

pip install pytest

לאחר מכן העבירו את המתאם שלכם לחבילת הבדיקות בקובץ בדיקה בתור מפעל ללא ארגומנטים (zero-argument factory), שבו run_session_store_conformance קורא פעם אחת לכל חוזה כדי לבנות אחסון חדש:

import pytest
from claude_agent_sdk.testing import run_session_store_conformance


@pytest.mark.anyio
async def test_my_store_conformance():
    await run_session_store_conformance(MyRedisStore)

העברת המחלקה MyRedisStore עצמה, כפי שנעשה בדוגמה זו, עובדת כאשר הבנאי אינו מקבל ארגומנטים. עבור מתאם שמקבל לקוח שהוגדר מראש, העבירו במקום זאת פונקציית lambda שבונה את האחסון. מכיוון שהחוזים משתמשים שוב באותם מפתחות הפעלה, כל אחסון שהמפעל מחזיר חייב להתחיל עם שטח אחסון ריק, ולכן ודאו שפונקציית ה-lambda מקצה אחסון גיבוי מבודד לכל קריאה, כגון רכיב דמה חדש בזיכרון, קידומת מפתח ייחודית, או מסד נתונים חדש לבדיקות.

#הערות התנהגות

#ארכיטקטורת כתיבה כפולה

תהליך המשנה של Claude Code תמיד כותב כל אצווה של רשומות תמליל לדיסק המקומי תחילה, ולאחר מכן ה-SDK מעביר את אותה אצווה ל-append() של האחסון שלכם, כך שהאחסון הוא שיקוף של התמליל המקומי ולא תחליף עבורו. איזה עותק ישרוד מעבר להרצה תלוי באופן שבו ההרצה החלה:

• הפעלה חדשה, או חידוש כאשר באחסון אין דבר עבור ההפעלה: התמליל המקומי תחת ספריית ההגדרות שלכם שורד מעבר להרצה, והאחסון מקבל עותק.
• הרצה שחודשה מתוך האחסון: העותק המקומי נמחק בסיום ההרצה, כך שהאחסון מחזיק בעותק העמיד היחיד.

אם אינכם רוצים שהפעלה חדשה תשאיר תמליל בדיסק המקומי, הגדירו את CLAUDE_CONFIG_DIR לספרייה זמנית ב-options.env. הרצה שחודשה מתוך האחסון כבר מוחקת את העותק המקומי שלה, ולכן אינה זקוקה להגדרה כזו. ב-TypeScript, פירסו (spread) גם את process.env לתוך env, מכיוון שהאפשרות env מחליפה את סביבת תהליך המשנה.

אם האפליקציה שלכם מתחברת באמצעות קבצים בספריית ההגדרות, כגון אישורי OAuth או apiKeyHelper בקובץ settings.json של המשתמש, העתיקו קבצים אלה לספרייה הזמנית תחילה, או הגדירו את ANTHROPIC_API_KEY ב-env במקום זאת. אחרת ההרצה תיכשל עם Not logged in.

שתי אפשרויות מתנגשות עם השיקוף, וה-SDK זורק שגיאה בעת ההפעלה אם תשלבו אחת מהן עם אחסון:

• persistSession: false ב-TypeScript: מכבה את הכתיבות המקומיות שמהן נבנה השיקוף. ל-SDK של Python אין אפשרות מקבילה.
• נקודות ביקורת לקבצים (File checkpointing), המוגדרות כ-enableFileCheckpointing ב-TypeScript או enable_file_checkpointing ב-Python: כותבות את גיבויי הקבצים ישירות לדיסק המקומי, וה-SDK אינו משקף אותם לאחסון.

#חידוש מתוך האחסון

כאשר אתם מעבירים resume, או continue: true ב-TypeScript או continue_conversation=True ב-Python, יחד עם אחסון, ה-SDK מבקש מהאחסון תמליל לפני שהוא מייצר את תהליך המשנה:

• resume: ה-SDK מבקש את ההפעלה שהמזהה שלה הועבר.
• continue: true או continue_conversation=True: ה-SDK מבקש את ההפעלה החדשה ביותר באחסון.

כאשר האחסון מחזיר את התמליל, ה-SDK כותב אותו לתוך ספריית הגדרות זמנית, מריץ את תהליך המשנה כאשר CLAUDE_CONFIG_DIR מצביע לשם, ומוחק את הספרייה בסיום ההרצה. התמליל המקומי שנכתב בהרצה זו נמחק יחד איתה, וזו הסיבה לכך שהאחסון מחזיק בעותק העמיד היחיד בנתיב זה.

ה-SDK גם מאכלס מראש את הספרייה הזמנית בקבצים מספריית ההגדרות האמיתית שלכם. מה שמועתק שונה בין השפות:

• TypeScript: אישורי גישה, הקובץ .claude.json, וקובץ settings.json של המשתמש. מתוך settings.json מוסרים המפתחות שאינם מתנהגים כראוי תחת ספריית הגדרות זמנית: enabledPlugins, extraKnownMarketplaces, הכינוי הנוסף שלו additionalMarketplaces, וכל הגדרת CLAUDE_CONFIG_DIR בבלוק ה-env של הקובץ. לפני Agent SDK v0.3.232, ה-SDK לא הסיר את הכינוי. אימות המוגדר בהגדרות, כגון apiKeyHelper, עובד בעת חידוש מתוך האחסון. לפני Agent SDK v0.3.222, ה-SDK של TypeScript העתיק רק אישורי גישה ואת .claude.json.
• Python: אישורי גישה ו-.claude.json בלבד, ולכן אפליקציה שמבצעת אימות באמצעות apiKeyHelper בקובץ settings.json של המשתמש תיכשל עם Not logged in בעת חידוש מתוך אחסון. מנגנון apiKeyHelper בהגדרות מנוהלות או בהגדרות פרויקט עדיין עובד, מכיוון ש-Claude Code קורא קבצים אלה ממיקומים ש-CLAUDE_CONFIG_DIR אינו משפיע עליהם.

כאשר באחסון אין דבר עבור ההפעלה, ה-SDK רץ תחת ספריית ההגדרות האמיתית שלכם במקום זאת, והתוצאה תלויה באפשרות שהועברה:

• resume: שני ה-SDKs מעבירים את המזהה לתהליך המשנה, שמחדש את התמליל המקומי בדיוק כפי ש-resume עושה ללא אחסון.
• continue: true ב-TypeScript: ה-SDK מתחיל הפעלה חדשה.
• continue_conversation=True ב-Python: ה-SDK ממשיך מההפעלה המקומית החדשה ביותר.

#כתיבות שיקוף הן בשיטת מאמץ מרבי

אם append() נכשל, ה-SDK מנסה שוב לשלוח את האצווה עד פעמיים נוספות עם השהיה קצרה, כלומר לכל היותר שלושה ניסיונות בסך הכל. קריאה שחורגת ממגבלת הזמן אינה מנוסה שוב, מכיוון שהקריאה המקורית עדיין עשויה להיקלט. אם האצווה עדיין נכשלת, ה-SDK רושם את השגיאה ביומן, פולט הודעת { type: "system", subtype: "mirror_error" } לתוך האיטרטור, משמיט את האצווה וממשיך בשאילתה. מכיוון שאצווה שנוסתה שוב עשויה למסור מחדש רשומות שכבר נקלטו, בצעו מניעת כפילויות לפי entry.uuid במימוש ה-append() שלכם.

השבתה באחסון אינה קוטעת את פעולת הסוכן, מכיוון שתהליך המשנה כותב מקומית תחילה. נטרו הודעות mirror_error אם עליכם לזהות אובדן נתונים באחסון. בהרצה שחודשה מתוך האחסון, לאצווה שהושמטה אין עותק ששורד לאחר סיום ההרצה.

#הפונקציה getSessionMessages מחזירה את שרשרת ההודעות שלאחר דחיסה

הקריאה getSessionMessages({ sessionStore }) מחזירה את שרשרת ההודעות המקושרת שהסוכן היה רואה בעת חידוש. לאחר דחיסה אוטומטית (auto-compaction), תורות מוקדמים מוחלפים בסיכום, ולכן הפעלה שהאחסון שלה מחזיק ב-503 רשומות גולמיות עשויה להחזיר 18 הודעות מ-getSessionMessages. לקבלת ההיסטוריה הגולמית המלאה, כולל תורות מלפני הדחיסה ורשומות מטא נתונים, קראו ישירות ל-store.load(key).

#הפונקציה forkSession אינה העתקת בייטים

הקריאה forkSession({ sessionStore }) קוראת את רשומות המקור, משכתבת כל שדה sessionId, ממפה מחדש את ה-UUIDs של ההודעות, ואז מצרפת את הרשומות שעברו המרה תחת מפתח חדש. העתקה ברמת המתאם או קיצור דרך של CopyObject ייצרו תמליל שעדיין מפנה למזהה ההפעלה הישן, ולכן ה-SDK אינו משתמש בהם.

#תמלילי סוכני משנה

תמלילי סוכני משנה משוקפים תחת subpath: "subagents/agent-<id>". הקריאה listSubagents({ sessionStore }) דורשת מהמתאם לממש את listSubkeys. הקריאה getSubagentMessages({ sessionStore }) משתמשת בו כאשר הוא זמין, אך נסוגה לנתיב המשנה הישיר כאשר אינו מוגדר. פעולת החידוש קוראת גם ל-listSubkeys כדי לשחזר קובצי סוכני משנה. בלעדיה, רק התמליל הראשי משוחזר.

#שימור נתונים

ה-SDK לעולם אינו מוחק נתונים מהאחסון שלכם מיוזמתו. שימור נתונים הוא באחריות המתאם: ממשו TTLs, מדיניות מחזור חיים של S3, או ניקוי מתוזמן בהתאם לדרישות התאימות שלכם.

תמלילים מקומיים תחת CLAUDE_CONFIG_DIR מנוקים באופן עצמאי על ידי ההגדרה cleanupPeriodDays, בהתאם לכללי סריקת השימור. הרצה שחודשה מתוך האחסון אינה משאירה תמליל מקומי, ולכן עבור הרצות אלו השימור של האחסון שלכם הוא השימור היחיד שקיים.

#נתמך ב

הפונקציות הבאות ב-SDK של TypeScript מקבלות את האפשרות sessionStore ופועלות מול האחסון במקום מול מערכת הקבצים המקומית כאשר היא מסופקת:

• query()
• startup()
• listSessions()
• getSessionInfo()
• getSessionMessages()
• renameSession()
• tagSession()
• deleteSession()
• forkSession()
• listSubagents()
• getSubagentMessages()

ב-SDK של Python, הגדירו את session_store בתוך ClaudeAgentOptions כדי להריץ את query() מול אחסון. לכל אחת משאר הפעולות קיימת פונקציית Python המגובה באחסון ומקבלת את האחסון כארגומנט: list_sessions_from_store(), get_session_info_from_store(), get_session_messages_from_store(), list_subagents_from_store(), get_subagent_messages_from_store(), rename_session_via_store(), tag_session_via_store(), delete_session_via_store() ו-fork_session_via_store(). ל-startup() אין מקבילה ב-Python. הפונקציות העצמאיות המתועדות במדריך ה-SDK של Python, כגון list_sessions(), קוראות קובצי הפעלה מקומיים.

#משאבים קשורים

• עבודה עם הפעלות: המשך, חידוש ופיצול ללא אחסון מותאם אישית (לפי התיעוד הרשמי מתאריך ספטמבר 2026, המשפט במקור נחתך במילים "custom sto" שמשמעותן "custom store").