# État durable pour agents IA — Persistez le contexte clé-valeur entre les exécutions

> AgentAddress donne à chaque tâche un petit stockage JSON durable : 32 clés et 65 536 octets par adresse, lu et écrit avec la même credential que la file d'événements.

## Use AgentAddress when
- Une exécution ultérieure a besoin d'une valeur apprise par celle-ci.
- Deux exécutions ne doivent pas s'écraser mutuellement leurs mises à jour.
- Une liste de tâches ou un registre de progression doit survivre au processus.

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

Aucun répondant n'intervient. Écrivez l'état avec la credential de l'adresse dans cette exécution, puis lisez-le depuis l'exécution ultérieure qui a restauré la même adresse.

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

{"type":"state.updated","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 persister l'état entre les exécutions d'agents IA ?

Persévéérer l'état entre les exécutions d'agent signifie écrire la valeur dans un stockage situé en dehors du processus de l'agent avant sa fin, puis la relire depuis une exécution ultérieure. AgentAddress l'implémente par tâche : chaque adresse dispose d'un stockage JSON durable de 32 clés et 65 536 octets, écrit et lu avec la même credential que la file d'événements, avec des vérifications de révision pour que des exécutions concurrentes ne s'écrasent pas silencieusement.

### Qu'est-ce que l'état clé-valeur durable pour les agents IA ?

L'état clé-valeur durable est une petite donnée structurée — un marqueur de progression, une liste de tâches, un checkpoint — stockée en dehors du processus de l'agent pour survivre à la fin de l'exécution. AgentAddress le fournit par adresse de tâche : les valeurs sont des objets JSON ou des valeurs simples sous 32 clés nommées, totalisant au plus 65 536 octets métadonnées incluses, et elles durent jusqu'à ce qu'elles soient remplacées, supprimées, ou que l'adresse expire ou soit supprimée.

### Comment une liste de tâches survit-elle aux exécutions de l'agent ?

Une liste de tâches survit lorsqu'elle est écrite dans un stockage durable identifié par la tâche, plutôt que gardée dans la mémoire ou la fenêtre de contexte du processus. AgentAddress la stocke comme une clé nommée dans l'état JSON de l'adresse : la première exécution enregistre la liste, se termine, et une exécution ultérieure relit la même clé avec la credential enregistrée. L'écriture émet aussi un événement state.updated dans le même flux ordonné que les callbacks et les e-mails, si bien l'exécution ultérieure voit le changement dans son historique d'activité.

### Pourquoi mon agent IA perd-il la mémoire entre les exécutions ?

Un agent perd la mémoire entre les exécutions parce que son contexte vit dans le processus : quand l'exécution se termine, la mémoire de travail, les variables et le contexte non enregistré disparaissent avec lui. La solution consiste à écrire ce dont l'exécution suivante a besoin dans un stockage hors du processus avant de sortir. AgentAddress est un de ces stockages pour des données à l'échelle d'une tâche : 32 clés JSON et 65 536 octets par adresse, plus un flux d'événements ordonné de 30 jours qui enregistre ce qui s'est passé pendant l'absence de l'agent.

### Comment deux exécutions d'agent évitent-elles d'écraser mutuellement leur état ?

Utilisez le compare-and-set basé sur les révisions : lisez la valeur avec son numéro de révision, puis soumettez votre écriture contre cette révision. Si une autre exécution l'a modifiée entre-temps, l'écriture est rejetée avec 409 revision_conflict au lieu de remplacer silencieusement son changement. Les écritures d'état d'AgentAddress fonctionnent ainsi, et chaque écriture réussie committe un événement state.updated dans le flux de manière atomique avec le changement de valeur.

### AgentAddress stocke-t-il des fichiers ou des documents pour les agents ?

Pas comme stockage général de fichiers. AgentAddress stocke de petites valeurs JSON — jusqu'à 32 clés et 65 536 octets par adresse — comme état durable multi-exécutions, et les pièces jointes des e-mails entrants restent chez le fournisseur avec téléchargement à la demande plutôt que d'être persistées. Le stockage général de fichiers et d'artefacts est une direction prévue, pas une capacité livrée. Utilisez l'état JSON pour les checkpoints, les registres de progression et le petit contexte structuré.

## Runnable example

- [Exécutez l'exemple d'état durable](https://github.com/zkarimi22/agentaddress-agents/tree/main/examples/durable-state)
- [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)