dry_run & Maliyet Ön Kontrolü

dry_run ile agent’ınız işi gerçekleştirmeden önce planlanan çalışmayı kontrol edersiniz. Çağrı parametreleri doğrular ve planlanan etkileri gösterir, ancak durum değiştirmez, kullanım kaydetmez veya harici etki tetiklemez.

estimated_cost mevcut olduğunda, birimi her zaman estimated_cost.currency alanından okursunuz. Gateway tüketimi için birim credits şeklindedir. Agent kendisi Euro’ya çevrim yapmaz.

dry_run Zorunlu Olduğu Durumlar

describe her Capability için dry_run bilgisi sağlar:

Değer	Anlamı
supported	mevcut ve maliyet veya etki kontrolü için kullanılabilir
required	invoke öncesinde zorunlu; başarılı bir dry_run olmadan Invoke dry_run_required hatasıyla başarısız olabilir
not_applicable	bu Capability için öngörülmemiş

Bağlayıcı kural: dry_run tam olarak describe.dry_run değeri required olduğunda zorunludur. billing.preflight ve billing.cost_class maliyet ve Guard kontrolü için ek planlama sinyalleridir; bu kuralı değiştirmezler.

Alan	Anlamı
billing.preflight: "none"	belirtilmiş bir maliyet ön kontrol aşaması yok
billing.preflight: "estimate"	dry_run bütçe kontrolü için bir maliyet tahmini sağlar
billing.preflight: "reserve"	bir Contract’ın belirttiği durumlarda rezerve edici ön kontrol aşaması
billing.cost_class: "free"	şu anda tüketim tutarı yok
billing.cost_class: "flat"	çağrı başına sabit Credit tutarı
billing.cost_class: "metered"	Contract/formüle göre tüketime dayalı hesaplama
billing.cost_class: "external_passthrough"	harici sağlayıcı maliyetleri veya sağlayıcı onayı belirleyici

Yanıt Formatı

{
  "interface_version": "1.0",
  "valid": true,
  "capability_id": "documents.document.upload",
  "resolved_version": "1.0.0",
  "audit_id": "audit_123",
  "would_require_approval": false,
  "estimated_cost": {
    "amount_min": "0.09",
    "amount_max": "0.09",
    "currency": "credits"
  },
  "effects": [
    {
      "kind": "create",
      "resource": "document",
      "description": "Would upload and process one document."
    }
  ]
}

valid değeri false olduğunda, yanıt violations içerir. Her öğe ek error zarfı olmadan bir hata gövdesidir:

{
  "valid": false,
  "violations": [
    {
      "code": "validation_error",
      "message": "Field 'mime_type' is invalid.",
      "hint": "Call describe(id) and resend params that match input_schema.",
      "retryable": false,
      "schema_pointer": "/params/mime_type",
      "details": [
        {
          "schema_pointer": "/params/mime_type",
          "message": "Value must be one of the documented enum values."
        }
      ],
      "audit_id": "audit_123"
    }
  ],
  "effects": []
}

schema_pointer ihlal edilen Request alanını gösterir. details birden fazla alan ihlali içerebilir. Tekrar dry_run veya invoke göndermeden önce tüm girişleri düzeltin.

Agent’ınız İçin Kural

valid false ise, violations temelinde parametreleri düzeltin. estimated_cost.currency değeri credits değilse, bir birim varsaymak yerine durdurun ve Contract’ı yeniden okuyun.

Bütçe kontrolü için estimated_cost.amount_max değerini sayı olarak estimated_cost_credits çağrısındaki wallet.agent_budget.guard.check alanına aktarırsınız. Tür tuzağı: dry_run içinde estimated_cost.amount_max bir ondalık String’dir; Guard Request’inde estimated_cost_credits bir JSON-Number olmalıdır.

effects harici etki, silme, arşivleme, ödeme veya yüksek maliyet gösteriyorsa, invoke göndermeden önce onay, bütçe ve Handover’ı kontrol edin.

Devamı

İnsanlara Handover