dry_run et estimation des coûts

Avec dry_run, vous vérifiez le travail prévu avant son exécution par votre agent. L’appel valide les paramètres et présente les effets attendus sans modifier l’état, comptabiliser une consommation ou déclencher un effet externe.

Si estimated_cost est présent, lisez toujours l’unité dans estimated_cost.currency. Pour la consommation de la passerelle, l’unité est credits. L’agent ne convertit pas lui-même les montants en euros.

Quand dry_run est obligatoire

Pour chaque capacité, describe fournit le champ dry_run :

Valeur	Signification
supported	Disponible pour vérifier les coûts ou les effets
required	Obligatoire avant invoke ; sans dry_run réussi, l’appel peut échouer avec dry_run_required
not_applicable	Non prévu pour cette capacité

La règle est précise : dry_run est obligatoire lorsque describe.dry_run vaut required. billing.preflight et billing.cost_class donnent des informations supplémentaires pour planifier les coûts et le contrôle budgétaire ; ils ne changent pas cette règle.

Champ	Signification
billing.preflight: "none"	Aucune étape d’estimation préalable des coûts indiquée
billing.preflight: "estimate"	dry_run fournit une estimation pour la vérification budgétaire
billing.preflight: "reserve"	Étape préalable avec réservation, si le contrat la prévoit
billing.cost_class: "free"	Aucun montant de consommation actuellement
billing.cost_class: "flat"	Montant forfaitaire en Credits par appel
billing.cost_class: "metered"	Calcul à l’usage selon le contrat ou la formule
billing.cost_class: "external_passthrough"	Coûts ou autorisation du prestataire externe déterminants

Format de la réponse

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

Lorsque valid vaut false, la réponse contient violations. Chaque élément est un corps d’erreur sans enveloppe error supplémentaire :

{
  "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 désigne le champ de requête qui ne respecte pas le schéma. details peut contenir plusieurs erreurs de champs. Corrigez-les toutes avant de renvoyer dry_run ou invoke.

Règle pour votre agent

Si valid vaut false, corrigez les paramètres à partir de violations. Si estimated_cost.currency ne vaut pas credits, arrêtez-vous et relisez le contrat au lieu de supposer l’unité.

Pour vérifier le budget, transmettez estimated_cost.amount_max comme nombre dans le champ estimated_cost_credits à wallet.agent_budget.guard.check. Attention au type : estimated_cost.amount_max est une chaîne décimale dans dry_run, mais estimated_cost_credits doit être un nombre JSON dans la requête de contrôle.

Si effects annonce une action externe, une suppression, un archivage, un paiement ou des coûts élevés, vérifiez les validations, le budget et le passage de relais avant d’envoyer invoke.

Pour continuer

Passage de relais à une personne