Idempotencia
Las tools que crean un recurso o encolan trabajo aceptan un argumento opcional idempotency_key. Se envía al endpoint como el header X-Idempotency-Key que la API REST ya honra.
{ "name": "inboxes_create",
"arguments": { "label": "Soporte — Triaje", "idempotency_key": "7c4a8d09-ca37-4f21-b1f0-3d2f2b8c9a11" } }
| Formato | Cadena opaca, de 8 a 255 caracteres. Un UUID es la elección habitual. |
| Ventana | 24 horas. |
| Repetición, mismo body | Devuelve la respuesta original, sin cambios. |
| Repetición, body distinto | 409 conflict. |
Envía una siempre que un agente pueda reintentar: un cliente que agota el timeout y vuelve a llamar crearía un segundo inbox, un segundo agente o un segundo webhook. Las tools de lectura, las actualizaciones y las eliminaciones ya son naturalmente idempotentes y no llevan clave.
Tools que la aceptan
| Recurso | Tools |
|---|---|
| Workspaces | workspaces_create, workspaces_upsert |
| Inboxes | inboxes_create, inboxes_upsert |
| Correos | emails_reprocess |
| Agentes | agents_create, agents_upsert |
| Webhooks | webhooks_create, webhooks_upsert, webhooks_test, webhooks_regenerate_secret, webhooks_deliveries_replay |
precaución
webhooks_regenerate_secret rota un secreto que se devuelve exactamente una vez. Una segunda llamada no intencionada no se recupera desde la respuesta — envía siempre un idempotency_key con ella.