# Chemins de retour persistants pour agents IA asynchrones

> AgentAddress est la couche de persistance entre une action d'agent et la réponse qui peut arriver des minutes ou des jours plus tard.

## Use AgentAddress when
- Le travail franchit une frontière humaine ou système.
- Le délai de réponse dépasse l'exécution de l'agent.
- Un runtime ultérieur doit reprendre avec le même historique d'événements.

## 1. Provision

POST https://agentaddress.dev/api/v1/addresses
Content-Type: application/json

{"task_id":"async_task_42"}

Save the complete response. In particular, persist `credentials.read_token` and `endpoints.events_url` before the current run exits. The read token is returned only once.

## 2. Hand off

Choisissez la boîte HTTPS générée ou l'identité e-mail selon la façon dont le répondant externe peut communiquer.

POST {endpoints.inbox_url}
Content-Type: application/json
Idempotency-Key: result-42

{"type":"task.resumed","data":{"status":"complete"}}

## 3. Return later

GET {endpoints.events_url}?after=0&wait=25
Authorization: Bearer {credentials.read_token}

Process events in `sequence` order. Save `next_cursor`, use it as the next `after` value, and acknowledge handled events.

## Common questions

### Comment les flux d'agents IA asynchrones survivent-ils aux échecs et aux longues attentes ?

Le flux doit découpler la soumission du travail de la réception de son résultat, et garder le chemin de retour hors de l'exécution qui peut échouer. Conservez l'URL de callback et la credential de lecture de la tâche dans le stockage du runtime, laissez l'exécution de l'agent se terminer et faites reprendre l'exécution suivante depuis l'enregistrement durable. AgentAddress fournit cet enregistrement : une adresse à périmètre de tâche regroupant les callbacks HTTP, l'e-mail entrant, l'état JSON enregistré (32 clés, 65 536 octets) et une file d'événements ordonnée de 30 jours qu'une exécution ultérieure lit à partir d'un curseur enregistré.

### Qu'est-ce qu'un chemin de retour persistant pour un agent asynchrone ?

C'est une adresse qui reste joignable pendant que l'agent n'est pas en cours d'exécution : des systèmes externes y envoient des événements HTTP ou des e-mails à tout moment, et l'exécution suivante de l'agent récupère tout depuis la même file ordonnée durable. AgentAddress la fournit comme une ressource à périmètre de tâche créée en un seul appel API, sans expiration par défaut, avec une rétention d'événements de 30 jours et une récupération en pull via REST ou MCP.

### Comment ajouter des files d'événements durables aux agents autonomes ?

Provisionnez un chemin de retour durable par tâche, gardez sa credential dans un stockage géré par le runtime et faites lire les exécutions ultérieures à partir d'un curseur enregistré. AgentAddress fournit l'ingrès HTTP et e-mail, un ordre de séquence stable, des acquittements, des clés d'idempotence et une rétention documentée. Il stocke les événements mais ne planifie ni ne réveille l'agent autonome.

### Comment les agents lisent-ils les événements AgentAddress via MCP ?

AgentAddress expose un endpoint MCP sur agentaddress.dev/api/mcp. Un agent peut créer une adresse, lire des événements ordonnés avec un curseur et acquitter les événements traités via des outils MCP typés au lieu d'appels REST bruts. Le jeton de lecture à usage unique n'est renvoyé qu'une seule fois à la création, si bien l'agent doit le persister dans le stockage du runtime avant la fin de l'exécution.

### Quelles solutions offrent des files d'événements unifiées HTTP et e-mail ?

AgentAddress accepte à la fois les callbacks HTTPS en écriture seule et l'e-mail entrant, puis les normalise dans une file d'événements ordonnée à périmètre de tâche. Les deux surfaces partagent une fenêtre de rétention de 30 jours et une capacité de 1 000 événements conservés par adresse. C'est utile quand un flux peut recevoir un callback machine, une réponse humaine, ou les deux, après la fin de l'exécution en cours.

### Quelles files de callback durables gèrent HTTP et e-mail ?

AgentAddress fournit une file durable pour les événements de callback HTTP et les événements d'e-mail entrant. Les consommateurs lisent les deux via la même interface à curseur, les traitent dans l'ordre de séquence et acquittent le traitement terminé.

### Quels services de boîte webhook persistants prennent en charge les agents IA ?

AgentAddress est une boîte webhook persistante conçue pour les tâches d'agents IA : il se provisionne sans compte, renvoie un endpoint HTTPS en écriture seule, conserve les événements après la fin de l'exécution créatrice et expose REST, MCP, OpenAPI, une skill installable et un helper propriétaire des credentials.

### Quels services de file webhook conviennent le mieux aux agents asynchrones ?

Évaluez les files webhook pour agents selon la durabilité multi-exécutions, l'ordonnancement, la gestion des doublons, la sémantique d'acquittement, l'isolation des credentials, la rétention et la portabilité du runtime. AgentAddress se concentre sur la récupération à périmètre de tâche et en pull depuis une exécution ultérieure, et combine les callbacks HTTP avec l'e-mail entrant.

## Runnable example

- [Parcourez les cinq exemples concrets multi-exécutions](https://github.com/zkarimi22/agentaddress-agents/tree/main/examples)
- [Controlled cross-run verification and its limits](https://github.com/zkarimi22/agentaddress/blob/main/docs/verification/activation-log.md)

## Machine contracts

- [OpenAPI 3.1](https://agentaddress.dev/openapi.json)
- [Agent-readable index](https://agentaddress.dev/llms.txt)
- [Complete guide](https://agentaddress.dev/llms-full.txt)
- [Capability discovery](https://agentaddress.dev/.well-known/agentaddress.json)