dry_run y Preflight de costos

Con dry_run verificas el trabajo planificado antes de que tu Agent lo ejecute. La llamada valida los parámetros y muestra los efectos planificados sin cambiar el estado, registrar uso ni desencadenar efectos externos.

Si estimated_cost está presente, lee siempre la unidad desde estimated_cost.currency. Para el consumo de Gateway, la unidad es credits. El Agent no convierte a euros por sí mismo.

Cuándo dry_run es obligatorio

describe entrega por cada Capability el campo dry_run:

Valor	Significado
supported	disponible y utilizable para verificación de costos o efectos
required	obligatorio antes de invoke; sin un dry_run exitoso el Invoke puede fallar con dry_run_required
not_applicable	no previsto para esta Capability

Regla vinculante: dry_run es obligatorio exactamente cuando describe.dry_run tiene el valor required. billing.preflight y billing.cost_class son señales adicionales de planificación para costos y verificación de Guard; no modifican esta regla.

Campo	Significado
billing.preflight: "none"	ningún nivel de Preflight de costos declarado
billing.preflight: "estimate"	dry_run entrega una estimación de costos para la verificación de presupuesto
billing.preflight: "reserve"	nivel de Preflight con reserva, si un Contract lo declara
billing.cost_class: "free"	actualmente sin importe de consumo
billing.cost_class: "flat"	importe fijo de Credits por llamada
billing.cost_class: "metered"	cálculo basado en consumo según Contract/fórmula
billing.cost_class: "external_passthrough"	costos de proveedor externo o autorización del proveedor determinante

Formato de respuesta

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

Si valid es false, la respuesta contiene violations. Cada elemento es un cuerpo de error sin envoltura error adicional:

{
  "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 señala el campo del Request violado. details puede contener múltiples violaciones de campo. Corrige todas las entradas antes de enviar nuevamente dry_run o invoke.

Regla para tu Agent

Si valid es false, corrige los parámetros según las violations. Si estimated_cost.currency no es credits, detente y lee el Contract nuevamente en lugar de asumir una unidad.

Para una verificación de presupuesto, pasas estimated_cost.amount_max como número en el campo estimated_cost_credits a wallet.agent_budget.guard.check. Trampa de tipo: En el dry_run, estimated_cost.amount_max es un String decimal; en el Request de Guard, estimated_cost_credits debe ser un JSON-Number.

Si effects muestra efectos externos, eliminación, archivo, pago o costos elevados, verifica autorización, presupuesto y Handover antes de enviar invoke.

Continuar

Handover a personas