תיעוד 147

מעקב אחר עלויות ושימוש

למדו כיצד לעקוב אחר שימוש באסימונים (tokens), להעריך עלויות ולהגדיר שמירה במטמון של הנחיות (prompt caching) באמצעות ה-Claude Agent SDK.

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

לתיעוד ה-API המלא, ראו את TypeScript SDK reference ואת Python SDK reference.

[!WARNING] השדות total_cost_usd ו-costUSD הם הערכות בצד הלקוח, ולא נתוני חיוב מוסמכים. ה-SDK מחשב אותם מקומית מתוך טבלת מחירים המצורפת בזמן הבנייה, אלא אם כן טבלת modelPricing פעילה. הם עשויים לסטות ממה שתחויבו בפועל כאשר:

המחירים משתנים

גרסת ה-SDK המותקנת אינה מזהה מודל מסוים

חלים כללי חיוב שצד הלקוח אינו יכול למדל

כלל חיוב אחד שה-SDK כן ממדל הוא תמחור תושבות נתונים (data residency pricing). כאשר ה-usage של תגובה מדווח על inference_geo: "us", ה-SDK מכפיל את מחיר המחירון של אסימוני אותה תגובה ב-1.1. עמלות לפי בקשה, כגון חיפוש באינטרנט, אינן מוכפלות. נדרש TypeScript Agent SDK גרסה v0.3.239 ומעלה, או Python Agent SDK גרסה v0.2.144 ומעלה.

השתמשו בשדות אלה לתובנות פיתוח ולתקצוב משוער. לחיוב מוסמך, השתמשו ב-Usage and Cost API או בדף ה-Usage ב-Claude Console. אל תחייבו משתמשי קצה ואל תפעילו החלטות פיננסיות בהתבסס על שדות אלה.

#הבנת השימוש באסימונים

ערכות הפיתוח (SDK) של TypeScript ושל Python חושפות את אותם נתוני שימוש בשמות שדות שונים:

TypeScript מספק פירוט אסימונים לפי שלב בכל הודעת עוזר (message.message.id, message.message.usage), עלות לפי מודל באמצעות modelUsage בהודעת התוצאה, וסך הכל מצטבר בהודעת התוצאה.
Python מספק פירוט אסימונים לפי שלב בכל הודעת עוזר בתור message.usage ו-message.message_id, עלות לפי מודל באמצעות model_usage בהודעת התוצאה, ואת הסך הכל המצטבר בהודעת התוצאה בתור total_cost_usd.

שני ה-SDKs משתמשים באותו מודל עלויות בסיסי וחושפים את אותה רמת פירוט. ההבדל הוא בשמות השדות ובמקום שבו הנתונים לפי שלב מקוננים.

מעקב אחר עלויות תלוי בהבנת טווח ההגדרה (scope) של נתוני השימוש ב-SDK:

קריאת query(): הפעלה אחת של הפונקציה query() של ה-SDK. קריאה בודדת יכולה לכלול מספר שלבים: Claude מגיב, משתמש בכלים, מקבל תוצאות ומגיב שוב. כל קריאה מפיקה הודעת result אחת בסופה, למעט ב-streaming input mode, שבו קריאת query() אחת נושאת מספר תורות משתמש וכל תור פולט הודעת result משלו.
שלב (Step): מחזור יחיד של בקשה/תגובה בתוך קריאת query(). כל שלב מפיק הודעות עוזר עם נתוני שימוש באסימונים.
הפעלה (Session): סדרה של קריאות query() המקושרות באמצעות מזהה הפעלה (באמצעות האפשרות resume). כל קריאת query() בתוך הפעלה מדווחת על העלות שלה באופן עצמאי.

התרשים הבא מציג את זרם ההודעות מקריאת query() יחידה, כאשר השימוש באסימונים מדווח בכל שלב וההערכה המצטברת מופיעה בסוף:

תרשים זרם הודעות ושימוש

כל שלב מפיק הודעות עוזר: כאשר Claude מגיב, הוא שולח הודעת עוזר אחת או יותר. ב-TypeScript, כל הודעת עוזר מכילה אובייקט BetaMessage מקונן (הנגיש דרך message.message) עם id ואובייקט usage הכולל ספירת אסימונים (input_tokens, output_tokens). ב-Python, ה-dataclass של AssistantMessage חושף את אותם נתונים ישירות דרך message.usage ו-message.message_id. כאשר Claude משתמש במספר כלים בתור אחד, כל ההודעות באותו תור חולקות את אותו מזהה (ID), לכן בצעו מניעת כפילויות (deduplicate) לפי ID כדי להימנע מספירה כפולה.
הודעת התוצאה מספקת את ההערכה המצטברת: כאשר קריאת query() מסתיימת, ה-SDK פולט הודעת תוצאה עם total_cost_usd ו-usage מצטבר, המוגדרת מטיפוס SDKResultMessage ב-TypeScript ומטיפוס ResultMessage ב-Python. אם אתם מבצעים מספר קריאות query(), למשל בהפעלה מרובת תורות, כל תוצאה משקפת רק את העלות של אותה קריאה בודדת. אם אתם זקוקים רק לסך הכל המשוער, תוכלו להתעלם מהשימוש לפי שלב ולקרוא ערך יחיד זה.

ב-streaming input mode, כל תור פולט הודעת תוצאה משלו. ראו מעקב אחר עלויות ב-streaming input mode כדי לדעת כיצד לקרוא סכומי קריאה במצב זה.

#מעקב אחר עלויות ב-streaming input mode

ב-streaming input mode, קריאת query() אחת נושאת מספר תורות משתמש וכל תור פולט הודעת תוצאה משלו. שדות התוצאה נבדלים בהיקפם:

usage: מכסה רק את אותו תור, ובתוכו רק את לולאת הסוכן הראשית, ללא תתי-סוכנים שהופעלו.
total_cost_usd ו-modelUsage, או model_usage ב-Python: נושאים את הסך הכל המצטבר השוטף עבור הקריאה כולה עד כה.

בקריאה שבה היישום שלכם לעולם אינו שולח /clear, /reset או /new, קראו את התוצאה העדכנית ביותר עבור סכומי הקריאה במקום לסכום את כל התוצאות.

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

התוצאה של תור ה-/clear עצמו: מכסה רק את מה שרץ מאז האיפוס, ונושאת session_id חדש.
כל תוצאה מאוחרת יותר: ממשיכה לספור מאותו איפוס.
התוצאה האחרונה לפני כל /clear: מחזיקה את הסך הכל עבור התורות שמאז האיפוס הקודם.

כדי לסכם את הקריאה כולה, הוסיפו את התוצאה האחרונה מלפני כל /clear אל התוצאה הסופית של הקריאה. כל תוצאה אחרת, כולל זו של תור ה-/clear עצמו, מוחלפת על ידי תוצאה מאוחרת יותר.

ב-TypeScript, ה-SDK פולט גם SDKConversationResetMessage בכל איפוס, כך שתוכלו לזהות איפוסים מתוך הזרם. ב-Python, ה-SDK פולט באופן דומה ConversationResetMessage. לפני Python SDK גרסה v0.2.137, האיטרטור של Python השמיט הודעה זו, ולכן בגרסאות אלו ספרו את האיפוסים בעצמכם מתוך תורות ה-/clear שהיישום שלכם שולח.

השדה maxBudgetUsd, או max_budget_usd ב-Python, מושווה מול אותו סך הכל שוטף, כך ש-/clear מתחיל מחדש גם את התקציב.

#קבלת העלות הכוללת של שאילתה

הודעת התוצאה, מטיפוס SDKResultMessage ב-TypeScript ו-ResultMessage ב-Python, מציינת את סיום לולאת הסוכן עבור קריאת query(). היא כוללת את total_cost_usd, העלות המשוערת המצטברת בכל השלבים באותה קריאה. ב-Python השדה מוגדר כאופציונלי, לכן בדקו שאינו None לפני שאתם קוראים אותו. תוצאות הצלחה ושגיאה נושאות שתיהן שדה זה, אם כי התוצאה הסופית של קריסת הפעלה עשויה לשאת אותו כשהוא מאופס.

אם אתם משתמשים בהפעלות כדי לבצע מספר קריאות query(), כל תוצאה משקפת רק את העלות של אותה קריאה בודדת. ב-streaming input mode, קראו את סכומי הקריאה כפי שמתואר בסעיף מעקב אחר עלויות ב-streaming input mode.

שלושת השדות ברמת התוצאה נבדלים במה שהם סופרים כאשר הסוכן מפעיל תתי-סוכנים. השתמשו ב-modelUsage, או ב-model_usage ב-Python, לחישוב אסימונים עבור כל העץ; השדה usage סופר פחות מדי ברגע שמתרחש קינון.

שדה	פעילות תתי-סוכנים
`usage`	לא נכלל. סופר רק את לולאת הסוכן ברמה העליונה, כך שאסימונים שנצרכו בתוך תתי-סוכנים אינם מתווספים
`total_cost_usd`	נכלל. סופר בקשות של תתי-סוכנים לצד הלולאה ברמה העליונה
`modelUsage` / `model_usage`	נכלל. סופר בקשות של תתי-סוכנים לצד הלולאה ברמה העליונה, בחלוקה לפי מודל

ב-single message input mode, כאשר תתי-סוכנים ברקע עדיין פועלים בסיום התור האחרון, Claude Code ממתין להם, עד למגבלה המתוארת ב-משימות רקע ביציאה, לפני פליטת התוצאה. השדות total_cost_usd, duration_api_ms ו-modelUsage, או model_usage ב-Python, של התוצאה כוללים את העבודה שבוצעה במהלך המתנה זו.

הדוגמאות הבאות רצות בלולאה על זרם ההודעות מקריאת query() ומדפיסות את העלות הכוללת כאשר הודעת ה-result מגיעה:

TypeScript:

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

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "result") {
      console.log(`Total cost: $${message.total_cost_usd}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, it still carried total_cost_usd and the
  // branch above has already run; connection or process failures yield
  // no result message.
  console.error(`Session ended with an error: ${error}`);
}

Python:

from claude_agent_sdk import query, ResultMessage
import asyncio


async def main():
    try:
        async for message in query(prompt="Summarize this project"):
            if isinstance(message, ResultMessage):
                print(f"Total cost: ${message.total_cost_usd or 0}")
    except Exception as error:
        
# A single-shot query() raises after yielding an error result. If the
        
# failure was an error result, the branch above has already run;
        
# connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

כדי להגביל כמה תתי-סוכנים יכולים להוסיף ל-total_cost_usd, הגדירו את מגבלות העומק, המקביליות וההוצאה בשאילתה.

#מעקב אחר שימוש לפי שלב ולפי מודל

הדוגמאות בסעיף זה משתמשות בשמות השדות של TypeScript. ב-Python, השדות המקבילים הם AssistantMessage.usage ו-AssistantMessage.message_id עבור שימוש לפי שלב, ו-ResultMessage.model_usage עבור פירוט לפי מודל.

#מעקב אחר שימוש לפי שלב

כל הודעת עוזר מכילה אובייקט BetaMessage מקונן (הנגיש דרך message.message) עם id ואובייקט usage הכולל ספירת אסימונים. כאשר Claude משתמש בכלים במקביל, מספר הודעות חולקות את אותו id עם נתוני שימוש זהים. עקבו אחר המזהים שכבר ספרתם ודלגו על כפילויות כדי להימנע מסכומים מנופחים.

[!WARNING] הערכים לאחר מניעת כפילויות לפי שלב מדויקים עבור אסימוני קלט ואסימוני מטמון. הערך של output_tokens לפי שלב הוא שומר מקום (placeholder), לכן קראו אסימוני פלט מהודעת התוצאה.

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

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

const seenIds = new Set<string>();
let totalInputTokens = 0;
let resultOutputTokens = 0;

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "assistant" && !message.parent_tool_use_id) {
      const msgId = message.message.id;

      // Parallel tool calls share the same ID, only count once
      if (!seenIds.has(msgId)) {
        seenIds.add(msgId);
        totalInputTokens += message.message.usage.input_tokens;
      }
    }
    if (message.type === "result") {
      // Per-step output_tokens is a placeholder; the result message
      // carries the accumulated output total.
      resultOutputTokens = message.usage.output_tokens;
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result, so the
  // input total below still reflects the steps that ran before the failure.
  console.error(`Session ended with an error: ${error}`);
}

console.log(`Steps: ${seenIds.size}`);
console.log(`Input tokens: ${totalInputTokens}`);
console.log(`Output tokens: ${resultOutputTokens}`);

#פירוט שימוש לפי מודל

הודעת התוצאה כוללת את modelUsage, מפה של שם המודל לספירת אסימונים ועלות לפי מודל. דבר זה שימושי כאשר מפעילים מספר מודלים (למשל, Haiku עבור תתי-סוכנים ו-Opus עבור הסוכן הראשי) ורוצים לראות לאן מגיעים האסימונים.

השדה costBasis בכל רשומה מציין איזו טבלת מחירים תמחרה את הבקשה האחרונה של אותו מודל: list למחיר מחירון, managed לטבלת modelPricing, או unknown כאשר אף אחת מהן לא התאימה למזהה המודל. שדה זה דורש את Claude Code גרסה v2.1.246 ומעלה.

הדוגמה הבאה מריצה שאילתה ומדפיסה את פירוט העלויות והאסימונים עבור כל מודל שהיה בשימוש:

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

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type !== "result") continue;

    for (const [modelName, usage] of Object.entries(message.modelUsage)) {
      console.log(`${modelName}: $${usage.costUSD.toFixed(4)}`);
      console.log(`  Input tokens: ${usage.inputTokens}`);
      console.log(`  Output tokens: ${usage.outputTokens}`);
      console.log(`  Cache read: ${usage.cacheReadInputTokens}`);
      console.log(`  Cache creation: ${usage.cacheCreationInputTokens}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the per-model breakdown above has already
  // printed; connection or process failures yield no result message.
  console.error(`Session ended with an error: ${error}`);
}

#צבירת עלויות על פני מספר קריאות

כל קריאת query() מחזירה total_cost_usd משלה. ה-SDK אינו מספק סך הכל ברמת ההפעלה, כך שאם היישום שלכם מבצע מספר קריאות query(), למשל בהפעלה מרובת תורות או בין משתמשים שונים, צברו את הסכומים בעצמכם. ב-streaming input mode, קראו את הסך הכל של כל קריאה כפי שמתואר בסעיף מעקב אחר עלויות ב-streaming input mode. עבור קריאה שהסתיימה בקריסה, ראו התאוששות של סכומים לאחר קריסת הפעלה.

הדוגמאות הבאות מריצות שתי קריאות query() באופן סדרתי, מוסיפות את ה-total_cost_usd של כל קריאה לסך הכל שוטף, ומדפיסות הן את העלות לכל קריאה והן את העלות המשולבת:

TypeScript:

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

// Track cumulative cost across multiple query() calls
let totalSpend = 0;

const prompts = [
  "Read the files in src/ and summarize the architecture",
  "List all exported functions in src/auth.ts"
];

for (const prompt of prompts) {
  try {
    for await (const message of query({ prompt })) {
      if (message.type === "result") {
        totalSpend += message.total_cost_usd;
        console.log(`This call: $${message.total_cost_usd}`);
      }
    }
  } catch (error) {
    // A single-shot query() throws after yielding an error result. If the
    // failure was an error result, this call's cost was already counted;
    // connection or process failures yield no result message. Continue
    // with the next prompt.
    console.error(`Call failed: ${error}`);
  }
}

console.log(`Total spend: $${totalSpend.toFixed(4)}`);

Python:

from claude_agent_sdk import query, ResultMessage
import asyncio


async def main():
    
# Track cumulative cost across multiple query() calls
    total_spend = 0.0

    prompts = [
        "Read the files in src/ and summarize the architecture",
        "List all exported functions in src/auth.ts",
    ]

    for prompt in prompts:
        try:
            async for message in query(prompt=prompt):
                if isinstance(message, ResultMessage):
                    cost = message.total_cost_usd or 0
                    total_spend += cost
                    print(f"This call: ${cost}")
        except Exception as error:
            
# A single-shot query() raises after yielding an error result. If
            
# the failure was an error result, this call's cost was already
            
# counted; connection or process failures yield no result message.
            
# Continue with the next prompt.
            print(f"Call failed: {error}")

    print(f"Total spend: ${total_spend:.4f}")


asyncio.run(main())

#טיפול בשגיאות, שמירה במטמון וספירת אסימוני פלט

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

#קריאת אסימוני פלט מהודעת התוצאה

Claude Code בונה כל הודעת עוזר מתוך נתוני השימוש שה-API דיווח כאשר התגובה החלה, כך שה-output_tokens של ההודעה הוא רק המספר שה-API דיווח ב-message_start, לפני שהתגובה נוצרה. תגובת API אחת יכולה להפיק מספר הודעות עוזר, וכל אחת מהן נושאת את אותו שומר מקום בדיוק.

ה-API מדווח על ספירת הפלט האמיתית בסיום התגובה, ו-Claude Code מוסיף אותה להודעת התוצאה. קראו אסימוני פלט מתוך ה-usage של התוצאה, או מתוך modelUsage עבור פירוט לפי מודל.

כדי לעקוב אחר גידול ספירת הפלט של תגובה בזמן שהיא מוזרמת, הגדירו את includePartialMessages, או include_partial_messages ב-Python, וקראו את usage מכל אירוע זרם של message_delta, המוגדר מטיפוס SDKPartialAssistantMessage ב-TypeScript ומטיפוס StreamEvent ב-Python.

#מעקב אחר עלויות בשיחות שנכשלו

הודעות תוצאה של הצלחה ושל שגיאה כוללות שתיהן את usage ואת total_cost_usd; ב-Python שני השדות מוגדרים כאופציונליים, לכן בדקו שאינם None לפני שאתם קוראים אותם.

אם שיחה נכשלת באמצע, עדיין נצרכו אסימונים עד לנקודת הכישלון. קראו נתוני עלות מכל הודעת תוצאה, בין אם ה-subtype שלה הוא success ובין אם הוא אחד מסוגי המשנה של שגיאה. בחלק מתוצאות השגיאה, usage מדווח על פחות ממה שהקריאה הוציאה בפועל:

error_during_execution לאחר קריסת הפעלה: כל שדה עלות עשוי להיות מאופס.
error_max_budget_usd: השדה usage משמיט את התגובה שחרגה מהתקציב, בעוד ש-total_cost_usd ו-modelUsage כוללים אותה.

היכן שיש לכם בחירה, חשבו מתוך total_cost_usd או modelUsage ולא מתוך usage.

#התאוששות של סכומים לאחר קריסת הפעלה

כאשר תהליך Claude Code קורס, הוא פולט תוצאת error_during_execution סופית ויוצא, הן במצב single-shot והן ב-streaming input mode. תוצאה זו עשויה לשאת ערכים מאופסים ב-usage, ב-total_cost_usd וב-modelUsage, לכן שחזרו את סכומי הקריאה מתוך מה שהגיע לפניה. צעד 1 משחזר את הסכומים המלאים בכל פעם שקיימת תוצאה מוקדמת יותר; אפשרות הגיבוי בצעד 2 משחזרת רק את אסימוני הקלט והמטמון של הלולאה הראשית.

השתמשו בתוצאה של התור שלפני הקריסה. ב-streaming input mode, היא מחזיקה את הסך הכל השוטף מתחילת הקריאה או מאז ה-/clear האחרון. עברו לצעד 2 במקום זאת כאשר תוצאה זו אינה יכולה לעזור לכם:
- הקריאה הייתה single-shot, ולכן לא קיימת תוצאה מוקדמת יותר.
- הקריסה התרחשה בתור הראשון.
- התור שלפני הקריסה היה ה-/clear עצמו, כך שהתוצאה שלו מכסה רק את האיפוס.
סכמו במקום זאת את ה-usage בהודעות העוזר, כאשר סופרים כל תגובת API פעם אחת, כפי שעושה הדוגמה מעקב אחר שימוש לפי שלב. במצב single-shot, סכמו את כולן; ב-streaming input mode, סכמו את אלו שהגיעו לאחר התוצאה האחרונה. פעולה זו מעניקה לכם את אסימוני הקלט והמטמון של הלולאה הראשית. לא ניתן לשחזר שימוש של תתי-סוכנים בדרך זו, וגם לא אסימוני פלט או עלות בדולר (USD), מכיוון ש-output_tokens לפי שלב הוא שומר מקום.

#מעקב אחר אסימוני מטמון

ה-Agent SDK משתמש באופן אוטומטי ב-prompt caching כדי להפחית עלויות על תוכן שחוזר על עצמו. אין צורך להגדיר שמירה במטמון בעצמכם. אובייקט ה-usage כולל שני שדות נוספים למעקב אחר המטמון:

cache_creation_input_tokens: אסימונים ששימשו ליצירת רשומות מטמון חדשות (מחויבים בתעריף גבוה יותר מאשר אסימוני קלט רגילים).
cache_read_input_tokens: אסימונים שנקראו מרשומות מטמון קיימות (מחויבים בתעריף מופחת).

עקבו אחריהם בנפרד מ-input_tokens כדי להבין את החיסכון בשמירה במטמון. ב-TypeScript, שדות אלו מוגדרים על אובייקט ה-Usage. ב-Python, הם מופיעים כמפתחות במילון ResultMessage.usage (לדוגמה, message.usage.get("cache_read_input_tokens", 0)).

#הארכת ה-TTL של מטמון ההנחיות לשעה אחת

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

רשומות מטמון עבור התורות שלכם משתמשות כברירת מחדל ב-TTL של 5 דקות כאשר אתם מזדהים באמצעות מפתח API או רצים ב-Amazon Bedrock, ב-Google Cloud's Agent Platform, ב-Microsoft Foundry, או ב-Claude Platform on AWS. אם עומס העבודה שלכם מריץ הפעלות קצרות רבות מול אותה הנחיית מערכת ואותו הקשר עם מרווחים של יותר מ-5 דקות ביניהן, תוקף המטמון יפוג בין הפעלה להפעלה וכל הפעלה חדשה תשלם מחיר קלט מלא.

כדי לבקש TTL של שעה אחת בכתיבה למטמון, הגדירו את משתנה הסביבה ENABLE_PROMPT_CACHING_1H. ניתן לייצא אותו בסביבת ה-shell או המכולה (container) שלכם, או להעביר אותו דרך options.env.

הדוגמה הבאה מאפשרת TTL של שעה אחת עבור סוכן שרץ ב-Amazon Bedrock. מכיוון שהיא מגדירה את CLAUDE_CODE_USE_BEDROCK, היא דורשת אישורי AWS תקינים עבור Amazon Bedrock; בלעדיהם השאילתה תיכשל.

Python:

from claude_agent_sdk import ClaudeAgentOptions, query
import asyncio


async def main():
    options = ClaudeAgentOptions(
        env={
            "CLAUDE_CODE_USE_BEDROCK": "1",
            "ENABLE_PROMPT_CACHING_1H": "1",
        },
    )

    async for message in query(prompt="Summarize this project", options=options):
        print(message)


asyncio.run(main())

TypeScript:

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

const options = {
  env: {
    ...process.env,
    CLAUDE_CODE_USE_BEDROCK: "1",
    ENABLE_PROMPT_CACHING_1H: "1",
  },
};

for await (const message of query({ prompt: "Summarize this project", options })) {
  console.log(message);
}

כתיבות למטמון עם TTL של שעה אחת מחויבות בתעריף גבוה יותר מכתיבות של 5 דקות, לכן הפעלת אפשרות זו מחליפה עלות כתיבה גבוהה יותר ביותר קריאות מטמון. ראו תמחור שמירה במטמון של הנחיות לפרטים. במסגרת מנוי Claude ובתחום השימוש הכלול בתוכנית שלכם, אתם מקבלים את ה-TTL של שעה אחת בתורות שלכם וכן בחלק מבקשות העזר ש-Claude Code מבצע לצידן, מבלי להגדיר משתנה זה, ו-Claude Code מוריד תורות אלה ל-TTL של 5 דקות ברגע שאתם משתמשים ב-קרדיטים לשימוש.

המשתנה ENABLE_PROMPT_CACHING_1H מבקש TTL של שעה אחת בכל בקשה בשני הדליים. כדי לבחור TTL לכל דלי בנפרד, השתמשו בבקרים הבאים במקום זאת. כל אחד מהם מקבל 5m או 1h וקודם ל-ENABLE_PROMPT_CACHING_1H:

שיחה ראשית: משתנה הסביבה CLAUDE_CODE_PROMPT_CACHE_TTL, או ההגדרה promptCacheTtl
כל השאר: משתנה הסביבה CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, או ההגדרה subagentPromptCacheTtl

הגדרת promptCacheTtl ל-1h שומרת על מטמון של שעה אחת בשיחה הראשית בזמן שאתם משתמשים בקרדיטים לשימוש. לסדר הקדימויות המלא, ראו בחירת ה-TTL בעצמכם.

#תיעוד קשור

TypeScript SDK Reference: תיעוד API מלא
SDK Overview: תחילת העבודה עם ה-SDK
SDK Permissions: ניהול הרשאות כלים