dry_run & Kosten-Preflight

Mit dry_run prüfst du geplante Arbeit, bevor dein Agent sie ausführt. Der Aufruf validiert Parameter und zeigt geplante Effekte, ohne Zustand zu ändern, Nutzung zu buchen oder externe Wirkung auszulösen.

Wenn estimated_cost vorhanden ist, liest du die Einheit immer aus estimated_cost.currency. Für Gateway-Verbrauch ist die Einheit credits. Der Agent rechnet nicht selbst in Euro um.

Wann dry_run Pflicht ist

describe liefert je Capability dry_run:

Wert	Bedeutung
supported	verfügbar und für Kosten- oder Effektprüfung nutzbar
required	vor invoke zwingend nötig; ohne erfolgreichen dry_run kann der Invoke mit dry_run_required scheitern
not_applicable	für diese Capability nicht vorgesehen

Verbindliche Regel: dry_run ist Pflicht genau dann, wenn describe.dry_run den Wert required hat. billing.preflight und billing.cost_class sind zusätzliche Planungssignale für Kosten und Guard-Prüfung; sie ändern diese Regel nicht.

Feld	Bedeutung
billing.preflight: "none"	keine ausgewiesene Kosten-Preflight-Stufe
billing.preflight: "estimate"	dry_run liefert eine Kostenschätzung für die Budgetprüfung
billing.preflight: "reserve"	reservierende Preflight-Stufe, falls ein Contract sie ausweist
billing.cost_class: "free"	aktuell kein Verbrauchsbetrag
billing.cost_class: "flat"	pauschaler Credit-Betrag pro Aufruf
billing.cost_class: "metered"	verbrauchsbasierte Berechnung nach Contract/Formel
billing.cost_class: "external_passthrough"	externe Providerkosten oder Provider-Freigabe maßgeblich

Antwortform

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

Wenn valid false ist, enthält die Antwort violations. Jedes Element ist ein Fehlerkörper ohne zusätzliche error-Hülle:

{
  "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 zeigt auf das verletzte Request-Feld. details kann mehrere Feldverletzungen enthalten. Korrigiere alle Einträge, bevor du erneut dry_run oder invoke sendest.

Regel für deinen Agenten

Wenn valid false ist, korrigiere die Parameter anhand der violations. Wenn estimated_cost.currency nicht credits ist, stoppe und lies den Contract erneut, statt eine Einheit anzunehmen.

Für eine Budgetprüfung übergibst du estimated_cost.amount_max als Zahl im Feld estimated_cost_credits an wallet.agent_budget.guard.check. Typfalle: Im dry_run ist estimated_cost.amount_max ein Dezimal-String; im Guard-Request muss estimated_cost_credits eine JSON-Number sein.

Wenn effects Außenwirkung, Löschung, Archivierung, Zahlung oder hohe Kosten zeigen, prüfe Freigabe, Budget und Handover, bevor du invoke sendest.

Weiter

Handover an Menschen