مدیریت هزینه‌های AI Agent روی VPS و جلوگیری از شارژ اضافه

چگونه از افزایش هزینه‌های یک AI agent همیشه فعال جلوگیری کنیم

کنترل هزینه AI agent روی یک VPS (سرور مجازی) به سقف‌هایی بستگی دارد که پیش از شروع کار عامل تعیین می‌کنید، زیرا در حین اجرا کسی کنتور را چک نمی‌کند. هر پاسخ را با max_tokens محدود کنید، تعداد تکرار حلقه‌ها را در کد خود محدود نمایید، بخشی از prompt که تغییر نمی‌کند را کش کنید و میزان مصرف هر پاسخ را لاگ کنید تا متوجه شوید کدام عملیات هزینه ایجاد می‌کند. اجاره سرور یک هزینه ماهانه ثابت است. API مدل بر اساس توکن محاسبه می‌شود و یک حلقه بدون نظارت به‌راحتی می‌تواند توکن‌ها را به‌طور بی‌صدا مصرف کند.

این راهنما فرض می‌کند عاملی دارید که از قبل وجود دارد و از روی سروری که مالک آن هستید، با Messages API تماس می‌گیرد. ساخت یک AI agent با Claude روی یک VPS به جزئیات فنی خودِ این ساختار می‌پردازد.

چرا یک عامل (agent) بدون نظارت، ساختار هزینه‌ای متفاوتی دارد

یک نشست تعاملی دارای یک کاربر انسانی است. زمانی که مدل مسیر اشتباهی را طی می‌کند یا یک لاگ 40,000 خطی را می‌خواند، فرد ناظر آن را متوقف می‌کند. یک عامل بدون نظارت چنین ترمز بازدارنده‌ای ندارد: تا پایان حلقه اجرا می‌شود و سپس یک تایمر، آن را دوباره شروع می‌کند.

تکرار، همان ضریبی است که افراد از آن غافل می‌شوند. کاری که طبق برنامه هر پنج دقیقه اجرا می‌شود، 288 بار در روز و حدود 8,640 بار در ماه اجرا خواهد شد. هزینه هر بار اجرا، عددی است که باید آن را در این تعداد ضرب کنید. بسیاری از عامل‌های «همیشه روشن» نیازی به روشن بودن دائمی ندارند. آن‌ها فقط باید در بازه زمانی مشخصی پاسخ دهند که این خود یک زمان‌بندی است.

یک عامل همچنین هزینه‌هایی را متحمل می‌شود که یک پنجره چت شامل آن‌ها نمی‌شود.

• تعریف ابزارها در هر درخواست همراه هستند. پرامپت سیستمی استفاده از ابزار در Claude Opus 4.8 با tool_choice از auto یا none، معادل 290 توکن و با any یا tool معادل 410 توکن هزینه دارد. ابزار bash نیز 325 توکن دیگر اضافه می‌کند. هر سرور MCP که متصل می‌کنید، شمای خود را به این وزن می‌افزاید؛ MCP همان پروتکل زمینه مدل (Model Context Protocol) است.
• نتایج ابزارها، توکن‌های ورودی محسوب می‌شوند. دستوری که 8,000 خط خروجی چاپ می‌کند، 8,000 خط را به درخواست بعدی و به تمام درخواست‌های پس از آن در همان نوبت وارد می‌کند.
• صفحات دریافت‌شده، توکن‌های ورودی هستند. یک صفحه وب معمولی 10 کیلوبایتی تقریباً 2,500 توکن و یک فایل PDF تحقیقاتی 500 کیلوبایتی تقریباً 125,000 توکن است. max_content_tokens فقط متن‌ها را کوتاه می‌کند، زیرا این قابلیت «برای محتوای متنی اعمال می‌شود، نه محتوای باینری مانند PDFها». برای محدود کردن PDF از max_uses و allowed_domains استفاده کنید.
• جستجوی وب به ازای هر جستجو قیمت‌گذاری می‌شود و هزینه آن 10 دلار به ازای هر 1,000 جستجو است، فارغ از اینکه چه تعداد نتیجه بازگردانده شود. جستجویی که با خطا مواجه شود، مشمول هزینه نخواهد بود.

هیچ‌کدام از این موارد در یک بار اجرا گران نیستند. اما همه آن‌ها در 8,640 بار اجرا، هزینه‌بر خواهند بود.

سقف‌های سخت و سقف‌های نرم مشکلات متفاوتی را حل می‌کنند

max_tokens اعمال می‌شود. این یک سقف سخت برای مجموع خروجی یک درخواست، شامل متن تفکر و متن پاسخ است. Claude هرگز از این حد فراتر نمی‌رود و مدل نمی‌تواند این عدد را ببیند. رسیدن به این سقف منجر به stop_reason: "max_tokens" و پاسخ ناقص می‌شود. نکته برای عامل‌ها (agents): هر درخواست در یک حلقه استفاده از ابزار، max_tokens خاص خود را دارد، بنابراین این محدودیت یک پاسخ را کنترل می‌کند و نه کل وظیفه را. ده فراخوانی ابزار با 4,000 توکن، به معنای سقف 40,000 توکنی برای آن نوبت است.

بودجه وظیفه (Task budget) توصیه‌ای است. task_budget در داخل output_config قرار دارد و به مدل می‌گوید که برای کل حلقه عامل، شامل تفکر، فراخوانی ابزار، نتایج ابزار و خروجی، چه تعداد توکن در اختیار دارد.

resp = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["task-budgets-2026-03-13"],
    output_config={"task_budget": {"type": "tokens", "total": 64000}},
    messages=messages,
)

"بودجه‌های وظیفه یک راهنمایی نرم هستند، نه یک سقف سخت." Claude ممکن است در میانه یک عملیات از آن فراتر رود و محدودیت اعمال‌شده بر خروجی همچنان max_tokens باقی می‌ماند. "شمارش معکوس فقط برای مدل قابل مشاهده است" و پاسخ‌ها فاقد فیلد بودجه باقی‌مانده هستند. حداقل task_budget.total قابل قبول 20,000 توکن است و مقادیر کمتر، خطای 400 برمی‌گردانند. بودجه‌ای که برای کار بسیار کوچک باشد، رفتاری شبیه به امتناع ایجاد می‌کند، بنابراین مدل دامنه وظیفه را محدود کرده یا زودتر متوقف می‌شود.

یک جزئیات به جای صرفه‌جویی در هزینه، باعث افزایش آن می‌شود. اگر کلاینت شما task_budget.remaining را در هر درخواست پیگیری کاهش دهد، مقدار تغییر یافته باعث ابطال هرگونه پیشوند کش‌شده‌ای می‌شود که حاوی آن است. آن را فقط یک بار، در اولین درخواست تنظیم کنید.

بودجه‌های وظیفه در نسخه بتا برای Claude Fable 5، Claude Opus 4.8 و Claude Opus 4.7 در دسترس هستند. Claude Sonnet 5 و Claude Haiku 4.5 به عنوان Not supported فهرست شده‌اند و بودجه‌های وظیفه برای Claude Code اعمال نمی‌شوند، بنابراین یک نشست Claude Code جدا شده در tmux به جای آن به رعایت بهداشت نشست (session hygiene) وابسته است.

سقف سوم در Claude Console قرار دارد: به عامل فضای کاری (workspace) اختصاصی خود را بدهید، سپس یک محدودیت هزینه ماهانه و محدودیت نرخ در دقیقه برای آن تعیین کنید. "شما نمی‌توانید محدودیت‌هایی برای Default Workspace تعیین کنید" و "محدودیت‌های کل سازمان همیشه اعمال می‌شوند، حتی اگر مجموع محدودیت‌های فضاهای کاری بیشتر باشد". اعلان‌های هزینه را اضافه کنید تا یک آستانه پیش از رسیدن به سقف، به شما هشدار دهد.

انتخاب مدل برای هر وظیفه و آنچه واقعاً تلاش را تغییر می‌دهد

انتخاب مدل تصمیمی است که برای هر وظیفه به‌صورت جداگانه گرفته می‌شود. تا ژوئیه 2026، هزینه به ازای هر میلیون توکن (ورودی و سپس خروجی) به این شرح است: Claude Fable 5 با قیمت 10 دلار و 50 دلار، Claude Opus 4.8 و Opus 4.7 با قیمت 5 دلار و 25 دلار، Claude Sonnet 5 با قیمت 3 دلار و 15 دلار، و Claude Haiku 4.5 با قیمت 1 دلار و 5 دلار. مدل Sonnet 5 در حال حاضر پایین‌تر از قیمت درج‌شده‌اش عرضه می‌شود، زیرا «قیمت‌گذاری مقدماتی 2 دلار برای ورودی و 10 دلار برای خروجی به ازای هر میلیون توکن تا 31 اوت 2026 معتبر است». مرحله‌ای که فقط خطوط لاگ را دسته‌بندی می‌کند، نیازی به Opus ندارد. همچنین هیچ سهمیه رایگانی برای پوشش برنامه‌های کاری شلوغ وجود ندارد، زیرا Claude API هیچ سطح رایگانی ندارد و تنها اعتبار اندکی هنگام ثبت‌نام ارائه می‌شود.

تلاش (effort) اهرم دوم است. output_config.effort مقادیر low، medium، high، xhigh و max را می‌پذیرد و مقدار پیش‌فرض high است؛ بنابراین تنظیم صریح high تفاوتی با حذف آن ندارد. تلاش کمتر، فراتر از کاهش طول استدلال، تأثیرگذار است: مستندات بیان می‌کنند که این کار باعث می‌شود Claude از فراخوانی‌های ابزار (tool calls) کمتری استفاده کند و عملیات‌ها را در یک مرحله ترکیب نماید. در یک عامل (agent)، این صرفه‌جویی بزرگ‌تری است، زیرا یک فراخوانی ابزارِ حذف‌شده، به معنای یک درخواست کامل است که هرگز ارسال نمی‌شود.

دام اینجاست که تلاش با کش (cache) تداخل دارد. تغییر این مقدار بین درخواست‌ها، prompt caching را باطل می‌کند. در مثال مستندشده، درخواست 2 مقدار cache_read_input_tokens: 3546 را گزارش کرد؛ درخواست 3، با تغییر تلاش از زیاد به متوسط، مقدار cache_creation_input_tokens از 3546 و cache_read_input_tokens از 0 را گزارش کرد. بنابراین، تلاش را در بارهای کاری مختلف تغییر دهید، اما هرگز در یک مکالمه کش‌شده این کار را نکنید. برای هدایت عمق پاسخ بدون شکستن کش، این کار را در prompt انجام دهید: جمله‌ای مانند «بدون تأمل، مستقیماً پاسخ بده» در جدیدترین پیام کاربر، نقاط شکست قبلی را دست‌نخورده باقی می‌گذارد.

توکن‌های تفکر (thinking tokens) با نرخ خروجی محاسبه می‌شوند و در max_tokens لحاظ می‌گردند؛ به همین دلیل است که پاسخ ناقص اغلب به این معناست که بخش تفکر، بودجه را مصرف کرده است. برای مشاهده تعداد، usage.output_tokens_details.thinking_tokens را بخوانید. چه چیزی واقعاً صورت‌حساب توکن Claude را پر می‌کند این متریک را کالبدشکافی می‌کند.

پیشوند پایدار را کش کنید و از شکستن تصادفی آن جلوگیری کنید

هزینه نوشتن در کش برای کش 5 دقیقه‌ای 1.25 برابر قیمت ورودی پایه و برای کش 1 ساعته 2 برابر است. هزینه خواندن از کش 0.1 برابر است، بنابراین «کش کردن تنها پس از یک بار خواندن برای مدت 5 دقیقه (1.25 برابر هزینه نوشتن) یا پس از دو بار خواندن برای مدت 1 ساعت (2 برابر هزینه نوشتن) صرفه اقتصادی دارد».

یک جمله دلیل مناسب بودن این روش برای یک ایجنت همیشه فعال را توضیح می‌دهد: «کش هر بار که محتوای کش‌شده استفاده می‌شود، بدون هزینه اضافی به‌روزرسانی می‌شود.» شغلی که هر دو دقیقه یک‌بار روی کش 5 دقیقه‌ای اجرا می‌شود، پیشوند خود را در تمام طول روز تنها با یک بار نوشتن، گرم نگه می‌دارد.

سه روش برای از دست دادن کش بدون اینکه متوجه شوید:

پیشوندی که تغییر می‌کند. «پیشوندهای کش به ترتیب زیر ایجاد می‌شوند: tools، system و سپس messages.» هر تغییری در بایت‌ها در مراحل اولیه این ترتیب، تمام مراحل بعدی را باطل می‌کند و ویرایش تعاریف ابزارها کل کش را از بین می‌برد. اشتباه رایج و خودساخته، قرار دادن یک timestamp یا run id در system prompt است: در این صورت هر درخواست یک پیشوند متفاوت خواهد داشت، یک ورودی جدید با هزینه 1.25 برابر می‌نویسد و هیچ داده‌ای از کش نمی‌خواند. نشانه این وضعیت، مقدار usage.cache_read_input_tokens برابر با 0 در فراخوانی‌هایی است که مشابه به نظر می‌رسند. متن‌های متغیر را به جدیدترین پیام کاربر منتقل کنید.

پیشوندی که بیش از حد کوتاه است. هر مدل حداقل طول قابل کش شدن دارد و در مقادیر کمتر از آن، درخواست بدون کش شدن پردازش می‌شود و «هیچ خطایی بازگردانده نمی‌شود». این مقادیر شامل 1,024 توکن برای Claude Opus 4.8 و Claude Sonnet 5، و 4,096 توکن برای Claude Haiku 4.5 است؛ بنابراین انتقال یک کار از Sonnet به Haiku می‌تواند کش را به‌طور خاموش غیرفعال کند.

مکالمه‌ای که از پنجره نگاه به عقب (lookback) فراتر می‌رود. «پنجره نگاه به عقب 20 بلوک است.» سیستم حداکثر 20 موقعیت را در هر breakpoint بررسی می‌کند و سپس متوقف می‌شود. در مثال مستند، یک نوبت شامل 35 بلوک با یک breakpoint در بلوک 35، بلوک‌های 35 تا 16 را بررسی می‌کند و ورودی نوبت قبلی در بلوک 15 خارج از این پنجره قرار می‌گیرد، بنابراین هیچ hit رخ نمی‌دهد. ایجنتی که در هر نوبت چندین بلوک استفاده از ابزار و نتیجه ابزار اضافه می‌کند، در دو یا سه نوبت از مرز 20 عبور می‌کند. شما در هر درخواست چهار breakpoint دارید، پس یکی را به پیام‌های اخیر اختصاص دهید.

هر کاری که فوریت ندارد را به Batches API بسپارید

«تمام موارد استفاده با 50% قیمت استاندارد API محاسبه می‌شوند»، که این شامل ورودی و خروجی هر دو می‌شود. پردازش دسته‌ای (Batch) به‌صورت غیرهمگام (asynchronous) انجام می‌شود و «بیشتر دسته‌ها در کمتر از 1 ساعت تکمیل می‌شوند». نتایج پس از اتمام تمام درخواست‌ها یا پس از گذشت 24 ساعت، هر کدام که زودتر رخ دهد، در دسترس خواهند بود. این یک وضعیت معمول است، نه یک تضمین.

وضعیت processing_status را تا زمانی که به ended تغییر کند، بررسی (Poll) کنید. درخواست‌هایی که errored، canceled یا expired برمی‌گردانند، مشمول هزینه نمی‌شوند. یک نکته مهم در صورت استفاده از سقف هزینه (spend cap) این است که: «ممکن است دسته‌ها کمی از سقف هزینه تنظیم‌شده برای Workspace شما فراتر بروند.»

تخفیف‌ها با هم جمع می‌شوند و از آنجا که یک دسته ممکن است بیش از 5 دقیقه طول بکشد، مستندات توصیه می‌کنند برای دسته‌هایی که محتوای مشترک دارند، از کش یک‌ساعته استفاده کنید. بنابراین کار را تفکیک کنید: هر چیزی که یک کاربر یا یک webhook منتظر آن است را در مسیر زنده (live path) نگه دارید و پردازش‌هایی مانند گزارش‌های شبانه یا طبقه‌بندی لاگ‌های دیروز را با نصف قیمت به یک دسته (batch) بسپارید.

ثبت فیلدهای مصرف هر پاسخ در ذخیره‌ساز اختصاصی خود

شما نمی‌توانید هزینه‌ای را که ثبت نکرده‌اید، تخصیص دهید. هر پاسخ به شما می‌گوید که چه هزینه‌ای داشته است.

u = resp.usage
row = {
    "job": job_name,
    "model": resp.model,
    "uncached_input": u.input_tokens,
    "cache_write": u.cache_creation_input_tokens,
    "cache_read": u.cache_read_input_tokens,
    "output": u.output_tokens,
    "stop_reason": resp.stop_reason,
}

به ازای هر فراخوانی API، یک ردیف به فایل JSON-lines اضافه کنید و آن را با نام job خود برچسب‌گذاری کنید. یک هفته بعد می‌توانید بگویید کدام job هزینه ایجاد کرده و کدام فقط مشغول به نظر می‌رسیده است. cache_read را زیر نظر داشته باشید: ستونی از صفرها، رایج‌ترین باگ هزینه در یک agent خودمیزبان (self-hosted) است.

یک فیلد به راحتی ممکن است اشتباه تفسیر شود. input_tokens فقط توکن‌های بعد از آخرین نقطه شکست کش (cache breakpoint) را می‌شمارد، بنابراین اندازه واقعی prompt برابر با total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens است. agentای که برای یک prompt بزرگ، input_tokens: 400 گزارش می‌دهد، ارزان نیست: بقیه آن از کش آمده است.

پیش از ارسال، شمارش کنید. شمارش توکن رایگان است و محدودیت‌های نرخ (rate limits) آن از ایجاد پیام جداست، بنابراین از count_tokens استفاده کنید تا به جای پرداخت هزینه برای کشف یک فایل پیوست بیش از حد بزرگ، از پذیرش آن خودداری کنید. نتیجه یک تخمین است، بنابراین برای هر مدل دوباره اندازه‌گیری کنید و هرگز شمارش انجام‌شده توسط tokenizer یک فروشنده دیگر را مجدداً استفاده نکنید. مدل‌های Claude Opus 4.7 و نسخه‌های بعدی Opus، و همچنین Claude Fable 5 و Claude Sonnet 5 از tokenizer جدیدتری استفاده می‌کنند که «برای متن یکسان، تقریباً 30 درصد توکن بیشتری تولید می‌کند». مدل‌های Claude Sonnet 4.6 و قدیمی‌تر، از جمله Claude Haiku 4.5، از tokenizer قبلی استفاده می‌کنند.

برای مشاهده دقیق و رسمی، Admin API میزان مصرف را در https://api.anthropic.com/v1/organizations/usage_report/messages و هزینه را در https://api.anthropic.com/v1/organizations/cost_report گزارش می‌دهد. هر دو به یک کلید مدیریتی (sk-ant-admin01-...) به عنوان x-api-key: $ANTHROPIC_ADMIN_KEY با anthropic-version: 2023-06-01 نیاز دارند و bucket_width=1d، group_by[]=model و api_key_ids[]= را می‌پذیرند. یک محدودیت وجود دارد: «Admin API برای حساب‌های شخصی در دسترس نیست.»

آن پارامتر آخر، یک ترفند ارزان برای تخصیص هزینه است: به هر job کلید API اختصاصی خود را بدهید، با api_key_ids[] فیلتر کنید و گزارش را با group_by[]=api_key_id بر اساس کلید تفکیک کنید. فیلتر به صورت جمع است، اما بعد گروه‌بندی به صورت مفرد است. کلیدها را به جای کد، در محیط (environment) نگهداری کنید، همان‌طور که اولین برنامه Claude API روی یک VPS با آن‌ها برخورد می‌کند.

محدود کردن حلقه، زیرا هیچ‌چیز دیگری این کار را انجام نمی‌دهد

تعداد تکرار محدود در اینجا اختیاری نیست. حلقه متعلق به شماست، بنابراین شمارنده نیز متعلق به شماست:

for step in range(MAX_STEPS):          # MAX_STEPS = 12, never "while True"
    resp = client.messages.create(...)
    if resp.stop_reason != "tool_use":
        break
else:
    log.warning("job %s hit MAX_STEPS=%d, giving up", job_name, MAX_STEPS)

هیچ‌کدام از سقف‌های تعیین‌شده در بالا این کار را برای شما انجام نمی‌دهند: max_tokens تنها یک پاسخ را محدود می‌کند و به مدل فقط در مورد بودجهٔ وظیفه هشدار داده می‌شود. یک محصول میزبانی‌شده در اینجا جلوی شما را می‌گیرد، همان‌طور که محدودیت Claude بر فراخوانی ابزارها در یک نوبت جلسه‌ای را که تعداد زیادی از آن‌ها را انجام داده است متوقف می‌کند، اما حلقه‌ای که خودتان نوشته‌اید بدون چنین محافظی عرضه می‌شود مگر اینکه خودتان آن را اضافه کنید.

یک ترمز دوم خارج از فرآیند قرار دهید. کار را به‌جای یک فرآیند دائمی، از طریق یک systemd timer اجرا کنید و RuntimeMaxSec= را در unit سرویس آن تنظیم نمایید. با RuntimeMaxSec=600، یک اجرای معلق پس از 10 دقیقه کشته می‌شود، به‌جای اینکه تا زمانی که متوجه شوید به چرخش ادامه دهد. اجرای یک برنامه به عنوان سرویس و تایمر systemd فایل‌های unit را پوشش می‌دهد. عملکرد یک اجرا را با journalctl -u triage-agent.service --since "1 hour ago" بررسی کنید.

تعداد تلاش‌های مجدد (retries) را نیز محدود کنید، زیرا هندلری که برای همیشه تلاش مجدد می‌کند، هزینهٔ تمام تلاش‌ها را محاسبه می‌کند. خطای 429 یا 500 مستحق چند بار تلاش مجدد با backoff است. خطای 400 مستحق هیچ تلاشی نیست، زیرا همان درخواست به همان شکل شکست می‌خورد.

کنترل هزینه عامل‌های هوش مصنوعی با بررسی اعداد خودتان آغاز می‌شود

هیچ‌کس نمی‌تواند به شما بگوید هزینه یک عامل همیشه فعال چقدر است، زیرا هزینه برابر است با تعداد توکن در هر اجرا ضرب‌در تعداد اجرا در روز، و هر دو بخش این معادله متعلق به شماست. آن را یک‌بار اجرا کنید، ردیف مصرفی که ثبت کرده‌اید را بخوانید و در برنامه زمانی خود ضرب کنید. دو روز بعد، گزارش هزینه را با این محاسبات تطبیق دهید. زمانی که این دو با هم همخوانی ندارند، شکاف موجود تقریباً همیشه ناشی از خرابی کش یا حلقه‌ای است که طولانی‌تر از حد تصور شما اجرا شده است.

این موضوع فرض را بر استفاده از API key می‌گذارد، زیرا عامل، برنامه شخصی شماست که Messages API را فراخوانی می‌کند. برای کارهای تعاملی شخصی خود، کدام طرح Claude با نحوه کار شما متناسب است بخش اشتراک را پوشش می‌دهد. تمام قیمت‌ها و محدودیت‌های ذکر شده در اینجا در ژوئیه 2026 با مستندات Anthropic مطابقت داده شده‌اند، بنابراین پیش از تدوین بودجه، صفحه قیمت‌گذاری را دوباره مطالعه کنید.

FAQ

هزینه اجرای یک AI agent که همیشه فعال است روی یک VPS چقدر است؟

دو نوع هزینه وجود دارد که فقط یکی از آن‌ها قابل پیش‌بینی است. هزینه سرور ماهانه ثابت است. هزینه API مدل بر اساس تعداد توکن محاسبه می‌شود، بنابراین هزینه نهایی برابر است با حاصل‌ضرب مصرف یک اجرا در تعداد دفعات اجرای آن. Anthropic هیچ رقمی برای یک agent خودمیزبان (self-hosted) که همیشه فعال است ارائه نمی‌دهد، بنابراین هر عددی که به شما گفته می‌شود را صرفاً یک حدس در نظر بگیرید. لاگ usage را از یک اجرای واقعی استخراج کنید و آن را در برنامه زمان‌بندی خود ضرب کنید.

تفاوت بین max_tokens و بودجه وظیفه (task budget) چیست؟

max_tokens توسط سیستم اعمال می‌شود و برای مدل نامرئی است. این پارامتر خروجی یک درخواست را، شامل بخش تفکر (thinking)، محدود می‌کند و در صورت رسیدن به این حد، خطای stop_reason: "max_tokens" دریافت می‌کنید. بودجه وظیفه برعکس است: این عدد به مدل اعلام می‌شود و مدل حلقه عاملیت (agentic loop) خود را بر اساس آن تنظیم می‌کند، اما «بودجه‌های وظیفه یک راهنمای نرم هستند، نه یک محدودیت سخت» و محدودیت اعمال‌شده توسط سیستم همچنان همان max_tokens است.

چرا مقدار cache_read_input_tokens برای agent من همیشه صفر است؟

به این دلیل که پیشوند (prefix) بین فراخوانی‌ها تغییر می‌کند یا برای کش شدن بیش از حد کوتاه است. دلیل معمول این اتفاق، وجود یک timestamp یا run id است که در system prompt جای‌گذاری می‌شود: کش بر اساس پیشوند کلیدگذاری می‌شود، بنابراین تغییر حتی یک بایت، تمام محتوای پس از آن را نامعتبر می‌کند. تغییر تعاریف ابزارها یا مقدار effort نیز همین نتیجه را دارد. در غیر این صورت، دلیل آن اندازه است، زیرا promptهای کوتاه‌تر کش نمی‌شوند و هیچ خطایی هم بازگردانده نمی‌شود.

چگونه از حلقه بی‌نهایت یک AI agent جلوگیری کنم؟

تعداد تکرارها را در کد حلقه خود بشمارید و در یک حداکثر مقدار ثابت متوقف شوید، زیرا max_tokens فقط یک پاسخ را محدود می‌کند و یک agent ممکن است پاسخ‌های متعددی تولید کند. یک محدودیت زمانی (wall-clock limit) خارج از پردازش اضافه کنید: کار را از طریق یک systemd timer با تنظیم RuntimeMaxSec= شروع کنید تا اجرای گیرکرده در زمان مقرر کشته شود. تعداد تلاش‌های مجدد (retries) را نیز محدود کنید، زیرا در یک حلقه تلاش مجدد، هزینه تمام دفعات محاسبه می‌شود.

آیا می‌توانم برای یک کلید API خاص Claude محدودیت هزینه تعیین کنم؟

محدودیت هزینه مستندشده، مربوط به کل workspace است نه هر کلید به صورت جداگانه؛ بنابراین یک workspace اختصاصی برای agent ایجاد کنید و هزینه ماهانه آن را در همان‌جا محدود کنید. «شما نمی‌توانید برای Default Workspace محدودیت تعیین کنید». اعلان‌های هزینه (spend notifications) را فعال کنید تا با رسیدن به یک آستانه، به شما هشدار داده شود. برای تفکیک هزینه‌ها، برای هر کار یک کلید جداگانه صادر کنید و سپس گزارش استفاده را با group_by[]=api_key_id گروه‌بندی کنید.