dry_run & Cost Preflight

With dry_run you check planned work before your agent executes it. The call validates parameters and shows planned effects without changing state, recording usage, or triggering external impact.

When estimated_cost is present, always read the unit from estimated_cost.currency. For gateway consumption the unit is credits. The agent does not convert to Euro on its own.

When dry_run Is Required

describe returns dry_run for each capability:

Value	Meaning
supported	available and usable for cost or effect checking
required	mandatory before invoke; without a successful dry_run invoke may fail with dry_run_required
not_applicable	not applicable for this capability

Binding rule: dry_run is required if and only if describe.dry_run has the value required. billing.preflight and billing.cost_class are additional planning signals for cost and guard checks; they do not change this rule.

Field	Meaning
billing.preflight: "none"	no designated cost preflight level
billing.preflight: "estimate"	dry_run provides a cost estimate for budget checking
billing.preflight: "reserve"	reserving preflight level, if a contract specifies it
billing.cost_class: "free"	currently no consumption charge
billing.cost_class: "flat"	flat credit amount per call
billing.cost_class: "metered"	consumption-based calculation per contract/formula
billing.cost_class: "external_passthrough"	external provider costs or provider approval governs

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

When valid is false, the response contains violations. Each element is an error body without an additional error wrapper:

{
  "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 points to the violated request field. details may contain multiple field violations. Correct all entries before sending dry_run or invoke again.

Rule for Your Agent

When valid is false, correct the parameters based on the violations. If estimated_cost.currency is not credits, stop and read the contract again instead of assuming a unit.

For a budget check, pass estimated_cost.amount_max as a number in the field estimated_cost_credits to wallet.agent_budget.guard.check. Type trap: In dry_run, estimated_cost.amount_max is a decimal string; in the guard request, estimated_cost_credits must be a JSON number.

When effects show external impact, deletion, archiving, payment, or high costs, check approval, budget, and handover before sending invoke.

Next

Handover to Humans