dry_run i Preflight kosztów

Za pomocą dry_run sprawdzasz planowaną pracę, zanim Twój agent ją wykona. Wywołanie waliduje parametry i pokazuje planowane efekty, nie zmieniając stanu, nie księgując zużycia ani nie wywołując skutków zewnętrznych.

Jeśli estimated_cost jest obecne, jednostkę zawsze odczytujesz z estimated_cost.currency. Dla zużycia Gateway jednostką są credits. Agent nie przelicza samodzielnie na euro.

Kiedy dry_run jest obowiązkowy

describe dostarcza dla każdej Capability pole dry_run:

Wartość	Znaczenie
supported	dostępny i użyteczny do sprawdzenia kosztów lub efektów
required	obowiązkowy przed invoke; bez udanego dry_run invoke może zakończyć się błędem dry_run_required
not_applicable	dla tej Capability nie jest przewidziany

Wiążąca reguła: dry_run jest obowiązkowy dokładnie wtedy, gdy describe.dry_run ma wartość required. billing.preflight i billing.cost_class to dodatkowe sygnały planowania dla kosztów i sprawdzenia Guard; nie zmieniają one tej reguły.

Pole	Znaczenie
billing.preflight: "none"	brak wykazanego poziomu kosztowego preflight
billing.preflight: "estimate"	dry_run dostarcza oszacowanie kosztów do sprawdzenia budżetu
billing.preflight: "reserve"	rezerwujący poziom preflight, jeśli Contract go wykazuje
billing.cost_class: "free"	obecnie brak kwoty zużycia
billing.cost_class: "flat"	ryczałtowa kwota Credits za wywołanie
billing.cost_class: "metered"	rozliczenie oparte na zużyciu według Contract/formuły
billing.cost_class: "external_passthrough"	decydujące są koszty zewnętrznego dostawcy lub uwolnienie przez dostawcę

Forma odpowiedzi

{
  "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."
    }
  ]
}

Gdy valid wynosi false, odpowiedź zawiera violations. Każdy element to treść błędu bez dodatkowej otoczki error:

{
  "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 wskazuje na naruszone pole żądania. details może zawierać wiele naruszeń pól. Popraw wszystkie wpisy, zanim ponownie wyślesz dry_run lub invoke.

Reguła dla Twojego agenta

Gdy valid wynosi false, popraw parametry na podstawie violations. Jeśli estimated_cost.currency nie wynosi credits, zatrzymaj się i ponownie odczytaj Contract, zamiast zakładać jednostkę.

W celu sprawdzenia budżetu przekazujesz estimated_cost.amount_max jako liczbę w polu estimated_cost_credits do wallet.agent_budget.guard.check. Pułapka typów: w dry_run pole estimated_cost.amount_max jest ciągiem dziesiętnym; w żądaniu Guard pole estimated_cost_credits musi być liczbą JSON.

Gdy effects pokazują skutek zewnętrzny, usunięcie, archiwizację, płatność lub wysokie koszty, sprawdź uwolnienie, budżet i handover, zanim wyślesz invoke.

Dalej

Handover do ludzi