תיעוד 188

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

למדו איך לעקוב אחרי שימוש בטוקנים, להעריך עלויות, ולהגדיר prompt caching עם Claude Agent SDK.

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

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

[!WARNING]

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

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

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

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

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

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

#הבנת השימוש בטוקנים

ה-SDK של TypeScript ושל Python חושפים את אותם נתוני שימוש עם שמות שדות שונים:

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

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

מעקב עלויות תלוי בהבנה של האופן שבו ה-SDK קובע את ההיקף של נתוני השימוש:

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

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

תרשים שמראה ש-query מייצר שני שלבים של הודעות. בשלב 1 יש ארבע הודעות assistant שחולקות אותו מזהה ואותו usage (לספור פעם אחת), בשלב 2 יש הודעת assistant אחת עם מזהה חדש, והודעת result הסופית מציגה את total_cost_usd המשוער.

1. כל שלב מייצר הודעות assistant

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

2. הודעת result מספקת את ההערכה המצטברת

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

אם מבצעים כמה קריאות query() עצמאיות, כל result משקף רק את העלות של אותה קריאה בודדת. קריאה שמחדשת סשן סופרת גם את ההוצאה הקודמת של הסשן.

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

#מעקב אחרי עלויות במצב קלט בזרימה

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

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

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

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

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

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

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

maxBudgetUsd (TypeScript) או max_budget_usd (Python) סופר רק את ההוצאה של הקריאה עצמה: סכומים ששוחזרו מסשן שחודש לא נספרים מולו, ו-/clear מתחיל את התקציב מחדש.

#קבלת העלות הכוללת של query

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

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

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

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

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

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

הדוגמאות הבאות עוברות על זרם ההודעות מקריאה ל-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, הגדירו את מגבלות העומק, המקביליות וההוצאה על ה-query.

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

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

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

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

[!WARNING]

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

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

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

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

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

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

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

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 בתוצאות שלה. האופן שבו משלבים את הערכים תלוי בשאלה אם הקריאות חולקות סשן:

קריאות עצמאיות, בלי האפשרות resume או continue: כל תוצאה מכסה רק את הקריאה שלה, ולכן מחברים את הסכומים בעצמכם, כמו בדוגמאות למטה.
קריאות שממשיכות את אותו סשן: Claude Code שומר את סיכומי הסשן בתמליל שלו כשהתהליך יוצא באופן תקין, ומשחזר אותם כשקריאה מאוחרת יותר ממשיכה את הסשן או עושה לו fork. כל תוצאה כבר כוללת את ההוצאה הקודמת של הסשן. קראו את התוצאה האחרונה כדי לקבל את סך הסשן: סיכום התוצאות סופר פעמיים את ההוצאה ששוחזרה. לפני v2.1.277, סשן שחידשתם דרך ה-SDK או claude -p התחיל את הסיכומים שלו באפס, ולכן תוצאות כל קריאה כיסו רק את אותה קריאה.

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

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

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

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

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())

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

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

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

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

ה-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 סופית ויוצא, גם במצב קריאה בודדת וגם במצב קלט בזרימה. התוצאה הזו עשויה לשאת usage, total_cost_usd ו-modelUsage מאופסים, ולכן שחזרו את סיכומי הקריאה ממה שהגיע לפניה. שלב 1 משחזר את הסיכומים המלאים בכל פעם שקיימת תוצאה קודמת. החלופה בשלב 2 משחזרת רק את אסימוני הקלט והמטמון של הלולאה הראשית.

השתמשו בתוצאה של התור שלפני הקריסה. במצב קלט בזרימה, היא מחזיקה את הסך הרץ שמתואר במעקב אחרי עלויות במצב קלט בזרימה. עברו לשלב 2 כשהתוצאה הזו לא יכולה לעזור:
- הקריאה הייתה קריאה בודדת, ולכן אין תוצאה קודמת.
- הקריסה קרתה בתור הראשון.
- התור שלפני הקריסה היה /clear עצמו, ולכן התוצאה שלו מכסה רק את האיפוס.
סכמו את usage שעל הודעות ה-assistant, וספרו כל תשובת API פעם אחת, כמו בדוגמה מעקב אחרי שימוש לכל שלב. במצב קריאה בודדת, סכמו את כולן. במצב קלט בזרימה, סכמו את אלה שהגיעו אחרי התוצאה האחרונה. זה נותן את אסימוני הקלט והמטמון של הלולאה הראשית. שימוש של תת סוכן לא ניתן לשחזור בדרך הזו, וגם לא אסימוני פלט או עלות ב-USD, כי ה-output_tokens לכל שלב הוא מציין מקום.

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

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

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, Agent Platform של Google Cloud, Microsoft Foundry, או Claude Platform on AWS. אם עומס העבודה מריץ הרבה סשנים קצרים מול אותה הנחיית מערכת ואותו הקשר, עם מרווחים ארוכים מ-5 דקות ביניהם, המטמון פג בין הסשנים וכל סשן חדש משלם מחיר קלט מלא.

כדי לבקש TTL של שעה על כתיבות למטמון, הגדירו את משתנה הסביבה ENABLE_PROMPT_CACHING_1H. אפשר לייצא אותו בסביבת המעטפת או הקונטיינר, או להעביר אותו דרך options.env.

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

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())

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: תיעוד API מלא
סקירת SDK: תחילת עבודה עם ה-SDK
הרשאות SDK: ניהול הרשאות כלים