dry_run & Kosten-Preflight

dry_run 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.

Agent-Regel

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