# 面向 AI 代理的持久状态 — 在运行之间保存键值上下文

> AgentAddress 为每个任务提供一个小型持久 JSON 存储：每个地址 32 个键和 65,536 字节，使用与事件队列相同的凭据读写。

## Use AgentAddress when
- 后续运行需要本次运行学到的某个值。
- 两次运行不得相互覆盖对方的更新。
- 待办事项或进度记录必须比进程活得更久。

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

不涉及响应方。在本运行中使用地址凭据写入状态，然后从恢复了同一地址的后续运行中读取。

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

### 如何在 AI 代理运行之间持久化状态?

在代理运行之间持久化状态，是指在代理进程退出之前将该值写入进程之外的存储，并由后续运行读取回来。AgentAddress 按任务实现这一点：每个地址拥有一个包含 32 个键和 65,536 字节的持久 JSON 存储，使用与事件队列相同的凭据读写，并带有修订检查，使并发运行不会静默地相互覆盖。

### 面向 AI 代理的持久键值状态是什么?

持久键值状态是小的结构化数据——进度标记、待办事项列表、checkpoint——存储在代理进程之外，因此能在运行退出后存续。AgentAddress 按任务地址提供：值是 32 个命名键之下的 JSON 对象或简单值，含元数据总计最多 65,536 字节，在被替换、删除，或地址过期或被删除之前一直保留。

### 待办事项列表如何在代理运行之间幸存?

待办事项列表在写入以任务为键的持久存储时才能幸存，而不是保存在进程的内存或上下文窗口中。AgentAddress 将其存储为地址 JSON 状态中的一个命名键：第一次运行保存列表并退出，后续运行使用保存的凭据读取同一个键。写入操作还会向与回调和电子邮件相同的有序 feed 发出 state.updated 事件，因此后续运行能在其活动历史中看到该变更。

### 为什么我的 AI 代理会在运行之间丢失记忆?

代理在运行之间丢失记忆，是因为其上下文存在于进程内：运行退出时，工作记忆、变量和未保存的上下文随之中止。解决办法是在退出前将下一次运行所需的内容写入进程之外的存储。AgentAddress 是适用于任务规模数据的此类存储之一：每个地址 32 个 JSON 键和 65,536 字节，外加一个记录代理缺席期间发生了什么的 30 天有序事件 feed。

### 两次代理运行如何避免相互覆盖对方的状态?

使用基于修订的 compare-and-set：连同修订号一起读取值，然后针对该修订提交写入。如果另一个运行先修改了它，写入会以 409 revision_conflict 被拒绝，而不是静默替换对方的更改。AgentAddress 的状态写入以这种方式工作，且每次成功的写入都会随值变更原子性地向 feed 提交一个 state.updated 事件。

### AgentAddress 会为代理存储文件或文档吗?

不作为通用文件存储。AgentAddress 将小的 JSON 值——每个地址最多 32 个键和 65,536 字节——存储为持久的跨运行状态，入站电子邮件附件则保留在提供方处，按需下载而不是持久化。通用文件和制品存储是规划方向，不是已交付的能力。请将 JSON 状态用于 checkpoint、进度记录和小型结构化上下文。

## Runnable example

- [运行持久状态示例](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)