Agent Cost Metering

ممکن است یک agent از نظر فنی کاملاً موفق باشد اما از نظر اقتصادی تصمیم غلطی تولید کند. یک عدد total_tokens به‌تنهایی نمی‌گوید هر request با کدام model یا tier اجرا شده، cached input چه نرخی داشته، ابزار یا retry چه هزینه‌ای اضافه کرده، کدام price snapshot در زمان اجرا معتبر بوده یا هزینه‌ی مشترک workflow با چه قاعده‌ای تخصیص یافته است.

خروجی این درس Agent Usage, Cost & Budget Control Ledger v1 است. هدف این Artifact ساخت invoice واقعی نیست؛ هدف این است که از evidence مصنوعی و قابل مشاهده، یک cost state قابل ممیزی بسازیم و وقتی usage یا price evidence ناقص است، هزینه‌ی دقیق جعل نکنیم.

قاعده‌ی اول: usage evidence با monetary cost یکی نیست.

مسیر یادگیری و مرز مسئولیت

AGN-007 مالک metering، اتصال usage به price snapshot تاریخ‌دار، allocation، unit cost و budget state است. AGN-006 درباره failure/retry reconciliation است و AGN-008 درباره contract suite و scope. این درس هزینه‌ی retry را ثبت می‌کند اما تصمیم نمی‌گیرد که آیا یک action شکست‌خورده باید retry شود یا نه.

مسیر پایه از field map و baseline استفاده می‌کند. فرد باتجربه می‌تواند تعریف‌ها را سریع‌تر رد کند، اما همان gateهای exactness، provenance، allocation و budget را باید پاس کند.

مدل ذهنی: پنج لایه، نه یک عدد کل

پنج لایه را جدا نگه دارید:

1. Measured usage: تعداد request، input/cached/output/reasoning، tool و external usage.
2. Price provenance: model، provider، tier، currency، price snapshot و effective date.
3. Cost calculation: محاسبه‌ی deterministic از unitهای اندازه‌گیری‌شده و unit priceهای تاریخ‌دار.
4. Allocation: قاعده‌ی صریح برای هزینه‌ی مشترک؛ تقسیم پنهانی ممنوع است.
5. Budget control: مصرف قبلی، warning/stop threshold، escalation و audit.

برچسب نهایی نباید از ضعیف‌ترین evidence تعیین‌کننده قوی‌تر باشد. اگر adapter جزئیات usage را نداده، نتیجه می‌تواند estimate/review باشد، نه exact ساختگی.

پایه‌ها: FACT جاری در برابر DESIGN محلی

مستندات فعلی OpenAI Agents SDK برای run، تعداد request و input/output/total tokens و per-request usage entry را گزارش می‌کنند. جزئیات cached token و reasoning token هم قابل نگهداری است و در مواردی که فرق «فیلد حذف‌شده» با «صفر گزارش‌شده» مهم است، حفظ raw provider usage اهمیت پیدا می‌کند.

مستندات فعلی مدل‌های OpenAI قیمت را بر اساس مدل و دسته‌ی token منتشر می‌کنند و بعضی ابزارها واحد billing دیگری دارند. این‌ها FACTهای vendor و متغیرند. اعداد قیمت داخل Lab این درس کاملاً synthetic هستند و قیمت واقعی OpenAI نیستند.

قاعده allocation، warning/stop threshold و escalation در این درس DESIGN محلی MAKNOW است و از vendor docs authority کسب‌وکاری نمی‌گیرد.

توضیح عمیق Ledger

Contract بحرانی ۲۳ بُعد دارد: run_id, request_id, model_id, provider_id, processing_tier, usage_source, input_tokens, output_tokens, total_tokens, price_snapshot_id, price_effective_at, measured_cost, allocation_rule_ref, allocated_cost, unit_of_work, unit_cost, budget_id, budget_limit, budget_consumed, cost_state, missing_usage_state, price_staleness_state, audit_ref.

Lab چند field کمکی قابل مشاهده هم دارد تا محاسبه دقیقاً بازتولید شود. gateهای اصلی:

• total_tokens = input_tokens + output_tokens؛ cached input زیرمجموعه input و reasoning detail زیرمجموعه output است.
• price snapshot باید با model/provider/tier/currency همان usage هم‌خوان و برای زمان run معتبر باشد.
• usage کامل + قیمت جاری می‌تواند EXACT را پشتیبانی کند؛ usage ناقص نمی‌تواند.
• shared cost به rule، weight و denominator صریح نیاز دارد. دو agent بودن به‌خودی‌خود مجوز تقسیم 50/50 نیست.
• اگر retry، tool یا external-provider charge تغییر کند، cost هم باید recompute شود.
• بعد از allocation، budget consumption و warning/stop دوباره محاسبه می‌شوند؛ stop به escalation نیاز دارد.

مثال‌های کارشده

۱) baseline قابل ردیابی

یک run مصنوعی سه request دارد، ۱۲۰هزار input token که ۲۰هزار آن cached است، ۳۰هزار output token، دو tool unit، یک retry charge و یک external charge. price snapshot مصنوعی با model/provider/tier تطبیق دارد. direct cost محاسبه می‌شود، بخشی از shared pool با weight صریح 60/100 تخصیص می‌یابد و unit cost از دو unit کار تکمیل‌شده به‌دست می‌آید. فقط وقتی همه‌ی عددها با recomputation یکی باشند نتیجه review-ready است.

۲) model جدید با price snapshot قدیمی

model_id را عوض کنید اما model_price_model_id و monetary result قبلی را نگه دارید. نتیجه باید HOLD شود؛ حتی اگر arithmetic از نظر عددی درست به نظر برسد. عدد درست با authority قیمت غلط، exact cost نیست.

۳) transfer با usage ناقص adapter

قیمت provider عوض شده، agent دوم بخشی از workflow را share می‌کند و یک adapter detail کامل usage نمی‌دهد. missing_usage_state=MISSING_PARTIAL را حفظ کنید، state را estimate/review نگه دارید و allocation rule صریح ثبت کنید. exact قبلی یا تقسیم پنهانی بر دو ممنوع است.

failure modeهای مهم

• Token-total shortcut: total token را exact monetary cost فرض کردن.
• Current-price oracle: price امروز را بدون dated basis به run قبلی اعمال کردن.
• Context mismatch: price عددی درست اما برای model/provider/tier اشتباه.
• Zero-versus-omitted: field گزارش‌نشده‌ی provider را صفر واقعی فرض کردن.
• Silent allocation: shared cost را بدون rule به یک owner دادن یا خودکار نصف کردن.
• Retry blindness: retry/tool/external usage تغییر کرده اما cost ثابت مانده است.
• Budget drift: allocated cost جدید ثبت شده اما budget consumed قدیمی مانده است.
• Baseline oracle: بعد از تغییر قیمت یا sharing، exact قبلی دوباره استفاده می‌شود.

گزینه‌ها و trade-offها

Metering می‌تواند در سطح request، run، agent، workflow یا customer allocation انجام شود. granularity بیشتر diagnosis را قوی‌تر می‌کند اما storage و reconciliation overhead را بالا می‌برد. normalized usage بین providerها ساده‌تر است؛ raw usage زمانی مهم‌تر می‌شود که presence یک field provider-specific تعیین‌کننده باشد. در داده ناقص، estimate محافظه‌کارانه بهتر از exact جعلی است.

این درس یک allocation method جهانی تجویز نمی‌کند. direct attribution، weighted activity، equal split صریح یا rule سازمانی دیگری می‌تواند معتبر باشد؛ چیزی که ممنوع است allocation بدون ثبت rule است.

پل برای فرد باتجربه

اگر token accounting را می‌شناسید، مستقیم چهار سؤال را پاسخ دهید:

1. آیا هر chargeable unit به run/request و usage source متصل است؟
2. آیا unit price با model/provider/tier و زمان اجرا تطبیق دارد؟
3. آیا هر shared cost rule و weight قابل بازتولید دارد؟
4. اگر یک retry، tool charge یا usage record تغییر کند، budget state هم recompute می‌شود؟

اگر پاسخ یکی نامعلوم است، EXACT بیش‌ازحد قوی است.

تمرین هدایت‌شده و مستقل

فایل derived_text/tables/AGN-007-T1.csv را ببینید و بعد Lab را اجرا کنید:

python -B lab/AGN-007-LAB1/learner/run_checks.py

برای تمرین مستقل، expected decisionها را کنار بگذارید و یک case جدید بسازید که price provider تغییر کند و adapter دوم یکی از جزئیات usage را ندهد. مقدار ناشناخته را حفظ کنید؛ حدس نزنید.

شواهد قابل بررسی

قبولی با screenshot dashboard ثابت نمی‌شود. Ledger باید token identity، price context، arithmetic، allocation، unit cost و budget state را از fieldهای قابل مشاهده بازتولید کند. Lab باید model/price mismatch، missing usage همراه exact، stale price همراه exact، تغییر retry/tool/external بدون تغییر cost و budget state ناسازگار را رد کند.

hidden reasoning برای بازتولید نتیجه لازم نیست.

ارزیابی و انتقال

ارزیابی شامل retrieval مرز درس، application روی baseline، diagnosis روی mutation و transfer است. در transfer، price provider عوض می‌شود، agent دوم بخشی از workflow را share می‌کند و یک adapter usage detail را حذف می‌کند. price binding، missing-usage state، allocation، unit cost و budget state باید از evidence جدید ساخته شوند.

کپی exact cost baseline مردود است—even اگر عدد نهایی ظاهراً plausible باشد.

منابع و تازگی

• OpenAI Agents SDK — Usage: fieldهای جاری run/per-request و رفتار raw-usage preservation.
• OpenAI API model/pricing documentation: pricing بر اساس model/token category و سایر billing unitها؛ نرخ‌ها متغیرند و در metering واقعی باید snapshot شوند.
• Frozen Lesson Bible lesson://AGN-007: authority محلی MAKNOW برای exactness، allocation و budget state.

مستندات usage/pricing حداکثر تا 2026-10-18 یا زودتر در صورت تغییر معنادار دوباره بررسی می‌شوند. unit priceهای Lab آموزشی و synthetic هستند، نه نرخ واقعی vendor و نه توصیه حسابداری.