# Estado duradero para agentes de IA — Persiste contexto clave-valor entre ejecuciones

> AgentAddress da a cada tarea un pequeño almacén JSON duradero: 32 claves y 65.536 bytes por dirección, leído y escrito con la misma credencial que la cola de eventos.

## Use AgentAddress when
- Una ejecución posterior necesita un valor que esta ejecución aprendió.
- Dos ejecuciones no deben sobrescribirse las actualizaciones mutuamente.
- Una lista de pendientes o un registro de progreso debe sobrevivir al proceso.

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

No interviene ningún respondedor. Escribe el estado con la credencial de la dirección en esta ejecución y léelo desde la ejecución posterior que restauró la misma dirección.

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

### ¿Cómo persisto el estado entre ejecuciones de agentes de IA?

Persistir el estado entre ejecuciones del agente significa escribir el valor en un almacenamiento fuera del proceso del agente antes de que termine, y leerlo de vuelta desde una ejecución posterior. AgentAddress lo implementa por tarea: cada dirección tiene un almacén JSON duradero de 32 claves y 65.536 bytes, escrito y leído con la misma credencial que la cola de eventos, con comprobaciones de revisión para que ejecuciones concurrentes no se sobrescriban silenciosamente.

### ¿Qué es el estado clave-valor duradero para agentes de IA?

El estado clave-valor duradero es un pequeño dato estructurado — un marcador de progreso, una lista de pendientes, un checkpoint — almacenado fuera del proceso del agente para que sobreviva a la salida de la ejecución. AgentAddress lo ofrece por dirección de tarea: los valores son objetos JSON o valores simples bajo 32 claves con nombre, con un total de como máximo 65.536 bytes incluyendo metadatos, y duran hasta que se reemplazan, se eliminan, o la dirección caduca o es eliminada.

### ¿Cómo sobrevive una lista de pendientes entre ejecuciones del agente?

Una lista de pendientes sobrevive cuando se escribe en almacenamiento duradero identificado por la tarea, no cuando se guarda en la memoria o en la ventana de contexto del proceso. AgentAddress la almacena como una clave con nombre en el estado JSON de la dirección: la primera ejecución guarda la lista, termina, y una ejecución posterior lee la misma clave con la credencial guardada. La escritura también emite un evento state.updated al mismo feed ordenado que los callbacks y el correo, así que la ejecución posterior ve el cambio en su historial de actividad.

### ¿Por qué mi agente de IA pierde la memoria entre ejecuciones?

Un agente pierde la memoria entre ejecuciones porque su contexto vive en el proceso: cuando la ejecución termina, la memoria de trabajo, las variables y el contexto sin guardar desaparecen con él. La solución es escribir lo que la siguiente ejecución necesita en un almacenamiento fuera del proceso antes de salir. AgentAddress es uno de esos almacenes para datos del tamaño de una tarea: 32 claves JSON y 65.536 bytes por dirección, más un feed de eventos ordenado de 30 días que registra lo que ocurrió mientras el agente estaba ausente.

### ¿Cómo evitan dos ejecuciones del agente sobrescribir el estado de la otra?

Usa comparar-y-establecer basado en revisiones: lee el valor junto con su número de revisión y luego envía tu escritura contra esa revisión. Si otra ejecución lo cambió antes, la escritura se rechaza con 409 revision_conflict en lugar de reemplazar silenciosamente su cambio. Las escrituras de estado de AgentAddress funcionan así, y cada escritura exitosa confirma un evento state.updated al feed atómicamente con el cambio del valor.

### ¿AgentAddress almacena archivos o documentos para los agentes?

No como almacenamiento general de archivos. AgentAddress almacena pequeños valores JSON — hasta 32 claves y 65.536 bytes por dirección — como estado duradero entre ejecuciones, y los adjuntos del correo entrante permanecen en el proveedor con descarga bajo demanda en lugar de persistirse. El almacenamiento general de archivos y artefactos es dirección planificada, no una capacidad enviada. Usa el estado JSON para checkpoints, registros de progreso y contexto estructurado pequeño.

## Runnable example

- [Ejecuta el ejemplo de estado duradero](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)