Idempotência

As tools que alteram dados — todas, menos as de leitura e as de exclusão — aceitam um argumento opcional idempotency_key. Ele é enviado à rota como o cabeçalho X-Idempotency-Key que a API v1 já honra, e as regras são as dela (veja Idempotência da API).

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

Formato	Texto opaco, de 1 a 255 caracteres.
Validade	24 horas, dentro da organização.
Repetição com os mesmos argumentos	Devolve a resposta original, sem rodar a operação de novo.
Repetição com argumentos diferentes	isError com IDEMPOTENCY_KEY_REUSED.
Repetição enquanto a primeira ainda roda	isError com IDEMPOTENCY_REQUEST_IN_PROGRESS; tente de novo em alguns segundos, com a mesma chave.

A repetição devolve o mesmo corpo que a primeira chamada. O cabeçalho X-Idempotent-Replay da API não chega ao resultado da tool, que traz só o corpo. Um segredo mostrado uma vez só — o segredo de assinatura de kadu_webhooks_create e de kadu_webhooks_rotate_secret — volta null na repetição.

Por que um agente precisa disto mais que o seu backend

Um cliente MCP que dá timeout e tenta de novo, ou um modelo que decide "não tenho certeza se aquilo funcionou, vou refazer", é exatamente o padrão que põe a segunda execução na fila, reenvia a mesma entrega duas vezes ou cria o segundo agendamento. Seu backend tem um laço de retry que você escreveu; o agente tem um julgamento.

Gere uma chave por operação de negócio (por exemplo, disparo-<data>-<tarefa>), e não por tentativa: é a mesma chave em todos os retries que torna o retry seguro.

Tools que aceitam

Família	Tools
Organização e estrutura	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
Execuções	kadu_tasks_run, kadu_executions_cancel, kadu_executions_continue, kadu_todos_update
Memórias	kadu_memories_create, kadu_memories_update
Configuração	kadu_environments_create, kadu_environments_update, kadu_secrets_create, kadu_secrets_update, kadu_schedules_create, kadu_schedules_update
Arquivos e 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
Papéis	kadu_roles_create

As tools de exclusão não aceitam: excluir de novo o mesmo registro já responde NOT_FOUND, sem efeito nenhum.

:::caution As que rodam o agente kadu_tasks_run e kadu_executions_continue põem uma execução na fila, e o agente age nos sistemas da tarefa — banco, ERP, notas fiscais — com efeitos que nenhuma exclusão desfaz. kadu_webhook_deliveries_replay entrega de novo ao sistema de quem recebe. Mande idempotency_key nessas mesmo quando você acha que não vai repetir. :::

Idempotência e confirmação

Cada chamada de uma tool destrutiva pede a sua confirmação de novo: um cliente que repete a chamada depois de um timeout gera uma segunda pergunta, ou um segundo link de aprovação. Com a mesma idempotency_key nas duas, confirmar as duas não dispara a tarefa duas vezes — a segunda devolve a resposta da primeira.