Idempotencia

Las tools que modifican datos — todas menos las de lectura y las de eliminación — aceptan un argumento opcional idempotency_key. Se envía a la ruta como la cabecera X-Idempotency-Key que la API v1 ya respeta, y las reglas son las de ella (mira Idempotencia de la API).

{ "name": "kadu_tasks_run",
  "arguments": {
    "id": "2f1c…",
    "environment_id": "8a40…",
    "reference_date": "2026-10-30",
    "idempotency_key": "lanzamiento-2026-10-30-baja-boletos"
  } }

Formato	Texto opaco, de 1 a 255 caracteres.
Validez	24 horas, dentro de la organización.
Repetición con los mismos argumentos	Devuelve la respuesta original, sin ejecutar la operación de nuevo.
Repetición con argumentos diferentes	isError con IDEMPOTENCY_KEY_REUSED.
Repetición mientras la primera sigue corriendo	isError con IDEMPOTENCY_REQUEST_IN_PROGRESS; inténtalo de nuevo en unos segundos, con la misma clave.

La repetición devuelve el mismo cuerpo que la primera llamada. La cabecera X-Idempotent-Replay de la API no llega al resultado de la tool, que trae solo el cuerpo. Un secreto que se muestra una sola vez — el secreto de firma de kadu_webhooks_create y de kadu_webhooks_rotate_secret — vuelve null en la repetición.

Por qué un agente lo necesita más que tu backend

Un cliente MCP que agota el tiempo y reintenta, o un modelo que decide "no estoy seguro de que eso funcionó, lo vuelvo a hacer", es exactamente el patrón que pone la segunda ejecución en la cola, reenvía la misma entrega dos veces o crea la segunda programación. Tu backend tiene un bucle de reintentos que tú escribiste; el agente tiene un juicio.

Genera una clave por operación de negocio (por ejemplo, lanzamiento-<fecha>-<tarea>), y no por intento: es la misma clave en todos los reintentos lo que hace seguro el reintento.

Tools que la aceptan

Familia	Tools
Organización y estructura	kadu_organizations_update, kadu_workspaces_create, kadu_workspaces_update, kadu_activities_create, kadu_activities_update, kadu_tasks_create, kadu_tasks_update, kadu_tasks_endpoint_update
Ejecuciones	kadu_tasks_run, kadu_executions_cancel, kadu_executions_continue, kadu_todos_update
Memorias	kadu_memories_create, kadu_memories_update
Configuración	kadu_environments_create, kadu_environments_update, kadu_secrets_create, kadu_secrets_update, kadu_schedules_create, kadu_schedules_update
Archivos y Playbook	kadu_files_create, kadu_files_confirm, kadu_repository_sync
Webhooks	kadu_webhooks_create, kadu_webhooks_update, kadu_webhooks_rotate_secret, kadu_webhook_deliveries_replay
Roles	kadu_roles_create

Las tools de eliminación no la aceptan: eliminar de nuevo el mismo registro ya responde NOT_FOUND, sin ningún efecto.

:::caution Las que ejecutan el agente kadu_tasks_run y kadu_executions_continue ponen una ejecución en la cola, y el agente actúa en los sistemas de la tarea — banco, ERP, facturas — con efectos que ninguna eliminación deshace. kadu_webhook_deliveries_replay entrega de nuevo al sistema de quien recibe. Envía idempotency_key en estas incluso cuando creas que no vas a repetir. :::

Idempotencia y confirmación

Cada llamada de una tool destructiva pide tu confirmación de nuevo: un cliente que repite la llamada después de agotar el tiempo genera una segunda pregunta, o un segundo enlace de aprobación. Con la misma idempotency_key en las dos, confirmar ambas no lanza la tarea dos veces — la segunda devuelve la respuesta de la primera.