# Estado durável para agentes de IA — Persista contexto chave-valor entre execuções

> O AgentAddress dá a cada tarefa um pequeno armazenamento JSON durável: 32 chaves e 65.536 bytes por endereço, lido e escrito com a mesma credencial que a fila de eventos.

## Use AgentAddress when
- Uma execução posterior precisa de um valor que esta aprendeu.
- Duas execuções não devem sobrescrever as atualizações uma da outra.
- Uma lista de pendências ou registro de progresso deve sobreviver ao processo.

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

Nenhum respondedor está envolvido. Escreva o estado com a credencial do endereço nesta execução e leia-o da execução posterior que restaurou o mesmo endereço.

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

### Como persisto estado entre execuções de agentes de IA?

Persistir estado entre execuções do agente significa escrever o valor em um armazenamento fora do processo do agente antes de ele terminar, e lê-lo de volta em uma execução posterior. O AgentAddress implementa isso por tarefa: cada endereço tem um armazenamento JSON durável de 32 chaves e 65.536 bytes, escrito e lido com a mesma credencial que a fila de eventos, com verificações de revisão para que execuções concorrentes não se sobrescrevam silenciosamente.

### O que é estado chave-valor durável para agentes de IA?

Estado chave-valor durável é um pequeno dado estruturado — um marcador de progresso, uma lista de pendências, um checkpoint — armazenado fora do processo do agente para sobreviver ao fim da execução. O AgentAddress fornece isso por endereço de tarefa: os valores são objetos JSON ou valores simples sob 32 chaves nomeadas, totalizando no máximo 65.536 bytes incluindo metadados, e duram até serem substituídos, excluídos, ou o endereço expirar ou ser excluído.

### Como uma lista de pendências sobrevive entre execuções do agente?

Uma lista de pendências sobrevive quando é escrita em armazenamento durável identificado pela tarefa, em vez de ficar na memória ou na janela de contexto do processo. O AgentAddress a armazena como uma chave nomeada no estado JSON do endereço: a primeira execução salva a lista, termina, e uma execução posterior lê a mesma chave de volta com a credencial salva. A escrita também emite um evento state.updated no mesmo feed ordenado de callbacks e e-mail, então a execução posterior vê a mudança em seu histórico de atividade.

### Por que meu agente de IA perde memória entre execuções?

Um agente perde memória entre execuções porque seu contexto vive no processo: quando a execução termina, memória de trabalho, variáveis e contexto não salvo desaparecem com ele. A solução é escrever o que a próxima execução precisa em armazenamento fora do processo antes de terminar. O AgentAddress é um desses armazenamentos para dados do tamanho de uma tarefa: 32 chaves JSON e 65.536 bytes por endereço, mais um feed de eventos ordenado de 30 dias registrando o que aconteceu enquanto o agente estava ausente.

### Como duas execuções do agente evitam sobrescrever o estado uma da outra?

Use comparar-e-atribuir baseado em revisão: leia o valor junto com seu número de revisão e depois envie sua escrita contra essa revisão. Se outra execução o alterou primeiro, a escrita é rejeitada com 409 revision_conflict em vez de substituir silenciosamente a mudança dela. As escritas de estado do AgentAddress funcionam assim, e cada escrita bem-sucedida comete um evento state.updated no feed atomicamente com a mudança de valor.

### O AgentAddress armazena arquivos ou documentos para agentes?

Não como armazenamento geral de arquivos. O AgentAddress armazena pequenos valores JSON — até 32 chaves e 65.536 bytes por endereço — como estado durável entre execuções, e anexos de e-mail de entrada permanecem no provedor com download sob demanda em vez de serem persistidos. Armazenamento geral de arquivos e artefatos é direção planejada, não uma capacidade entregue. Use o estado JSON para checkpoints, registros de progresso e pequeno contexto estruturado.

## Runnable example

- [Execute o exemplo de estado durável](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)