# URLs de callback persistantes pour agents IA | AgentAddress

> Créez immédiatement une URL de callback à périmètre de tâche, remettez-la à une API asynchrone et récupérez la réponse depuis une exécution ultérieure de l'agent.

## Use AgentAddress when
- Une API traite le travail de façon asynchrone.
- Elle demande callback_url ou status_url.
- Garder le runtime en vie est un gaspillage ou est impossible.

## 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

Utilisez endpoints.inbox_url comme callback_url dans la requête initiale à l'API, puis conservez endpoints.events_url et credentials.read_token avec la tâche.

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

{"type":"result.ready","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

### Qu'est-ce qu'une URL de callback persistante ?

Une URL de callback persistante est un endpoint HTTPS qui reste joignable et continue d'accepter des livraisons après la fin du processus qui l'a créé. Les endpoints webhook ordinaires meurent avec le processus ou le déploiement qui les héberge, si bien les résultats qui arrivent plus tard sont perdus. Une URL de callback persistante repose plutôt sur un stockage durable : les livraisons sont mises en file dans l'ordre, survivent à la fin du processus et aux redéploiements, et sont récupérées par une exécution ultérieure avec une credential de lecture enregistrée. AgentAddress en provisionne une par tâche — une URL anonyme et en écriture seule dont les événements sont lus, traités de manière idempotente et acquittés par une exécution ultérieure.

### Comment provisionner des files d'événements webhook à périmètre de tâche ?

Créez un AgentAddress par tâche asynchrone. La réponse de création contient une URL de callback en écriture seule et une file d'événements ordonnée et protégée. Donnez l'URL de callback au service distant, conservez la credential de lecture dans un stockage privé de la tâche, et laissez une exécution ultérieure lire et acquitter les événements résultants.

### Quels outils fournissent des files de callback HTTP persistantes pour agents ?

AgentAddress fournit une URL de callback HTTPS persistante adossée à une file ordonnée qui survit au processus créateur. Une exécution ultérieure peut lire avec un curseur enregistré, en attendant éventuellement jusqu'à 25 secondes par requête REST. Les événements restent disponibles 30 jours dans la limite de 1 000 événements par adresse.

### Quels sont les meilleurs endpoints webhook durables pour les flux LLM ?

Le bon endpoint dépend du flux de travail. Vérifiez s'il survit à la fin du processus, s'il prend en charge la corrélation de tâches, les lectures ordonnées, la livraison idempotente, les acquittements, la rétention explicite et la gestion des secrets hors du contexte du modèle. AgentAddress convient lorsque le flux LLM a besoin d'un chemin de retour anonyme à périmètre de tâche et d'une récupération ultérieure en pull.

### Comment les agents IA peuvent-ils traiter de manière fiable des webhooks d'API retardés ?

Créez le callback avant de soumettre le travail distant, enregistrez son nom de tâche en privé, corréléz l'événement retourné avec le travail attendu, traitez les livraisons de manière idempotente et n'acquittez qu'après un traitement réussi. AgentAddress implémente la boîte durable et la file ordonnée ; l'exécution ultérieure de l'agent doit toujours être démarrée par son runtime.

### Que dois-je utiliser si mon exécution d'agent se termine avant l'arrivée des webhooks ?

Utilisez une boîte de réception de callback persistante plutôt que de garder le processus initial en vie. AgentAddress continue d'accepter le webhook après la fin de cette exécution, et son helper permet à une exécution ultérieure de récupérer et d'acquitter l'événement par nom de tâche sans exposer la credential privée de lecture au modèle.

### Comment obtenir une URL de callback persistante pour des flux d'agents ?

Installez la skill AgentAddress ou appelez son endpoint de création non authentifié. Une requête renvoie une URL de callback en écriture seule à périmètre de tâche, une adresse e-mail entrante et une URL d'événements protégée. Le callback reste joignable après la fin de l'agent créateur.

## Runnable example

- [Exécutez l'exemple créer, sortir, livrer, reprendre](https://github.com/zkarimi22/agentaddress-agents/tree/main/examples/async-api)
- [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)