Idempotência
Tools que criam um recurso ou enfileiram trabalho aceitam um argumento opcional idempotency_key. Ele é enviado ao endpoint como o header X-Idempotency-Key que a API REST já honra.
{ "name": "inboxes_create",
"arguments": { "label": "Suporte — Triagem", "idempotency_key": "7c4a8d09-ca37-4f21-b1f0-3d2f2b8c9a11" } }
| Formato | String opaca, de 8 a 255 caracteres. Um UUID é a escolha usual. |
| Janela | 24 horas. |
| Replay, mesmo body | Retorna a resposta original, inalterada. |
| Replay, body diferente | 409 conflict. |
Envie uma sempre que um agente possa repetir a chamada: um cliente que estoura o timeout e chama de novo criaria uma segunda inbox, um segundo agente ou um segundo webhook. Tools de leitura, atualizações e exclusões já são naturalmente idempotentes e não recebem chave.
Tools que aceitam
| Recurso | Tools |
|---|---|
| Workspaces | workspaces_create, workspaces_upsert |
| Inboxes | inboxes_create, inboxes_upsert |
| E-mails | emails_reprocess |
| Agentes | agents_create, agents_upsert |
| Webhooks | webhooks_create, webhooks_upsert, webhooks_test, webhooks_regenerate_secret, webhooks_deliveries_replay |
cuidado
webhooks_regenerate_secret rotaciona um segredo devolvido exatamente uma vez. Uma segunda chamada não intencional não é recuperável pela resposta — sempre envie um idempotency_key com ela.