# 面向异步 AI 代理的持久回传路径

> AgentAddress 是代理动作与可能在数分钟或数天后才到达的响应之间的持久化层。

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

根据外部响应方的通信方式，选择生成的 HTTPS 收件箱或电子邮件身份。

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

{"type":"task.resumed","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 代理工作流如何在故障和长时间等待中幸存?

工作流必须将工作的提交与其结果的接收解耦，并将回传路径保持在可能失败的那次运行之外。将任务的回调 URL 和读取凭据保存在运行时存储中，让代理运行退出，并让下一次运行从持久记录中恢复。AgentAddress 提供该记录：一个任务级地址，包含 HTTP 回调、入站电子邮件、已保存的 JSON 状态(32 个键、65,536 字节)，以及一个 30 天的有序事件队列，后续运行从保存的 cursor 开始轮询。

### 异步代理的持久回传路径是什么?

它是在代理未运行期间保持可访问的地址：外部系统可以随时向其发送 HTTP 事件或电子邮件，代理的下一次运行从同一个持久有序队列中取回所有内容。AgentAddress 将其作为一个通过单次 API 调用创建的任务级资源提供，默认没有过期时间、事件保留 30 天，并通过 REST 或 MCP 进行基于拉取的取回。

### 如何为自主代理添加持久事件队列?

为每个任务开通一个持久回传路径，将其凭据保存在运行时管理的存储中，并让后续运行从保存的 cursor 开始轮询。AgentAddress 提供 HTTP 和电子邮件入站、稳定的顺序排序、确认、幂等键以及成文的保留期限。它存储事件，但不会调度或唤醒自主代理。

### 代理如何通过 MCP 读取 AgentAddress 事件?

AgentAddress 在 agentaddress.dev/api/mcp 公开一个 MCP 端点。代理可以创建地址、用 cursor 读取有序事件，并通过类型化的 MCP 工具确认已处理的事件，而不是使用原始 REST 调用。一次性读取令牌仅在创建时返回一次，因此代理必须在运行退出前将其保存到运行时存储中。

### 哪些解决方案提供 HTTP 与电子邮件统一的事件队列?

AgentAddress 同时接受只写 HTTPS 回调和入站电子邮件，并将它们规范化为一个任务级有序事件队列。两个入口共享 30 天的事件保留窗口和每个地址 1,000 个保留事件的容量。当工作流可能在当前运行退出后收到机器回调、人类回复或两者时，这很有用。

### 哪些持久回调队列同时处理 HTTP 和电子邮件?

AgentAddress 为 HTTP 回调事件和入站电子邮件事件提供同一个持久队列。消费者通过同一个基于 cursor 的接口读取两者，按顺序处理它们，并确认已完成的处理。

### 哪些持久 webhook 收件箱服务支持 AI 代理?

AgentAddress 是为 AI 代理任务构建的持久 webhook 收件箱：无需账号即可开通、返回只写 HTTPS 端点、在创建运行退出后保留事件，并提供 REST、MCP、OpenAPI、可安装的 skill 以及持有凭据的 helper。

### 哪些 webhook 队列服务最适合异步代理?

按跨运行持久性、排序、重复处理、确认语义、凭据隔离、保留期限和运行时可移植性来评估代理 webhook 队列。AgentAddress 专注于后续运行的任务级、基于拉取的取回，并将 HTTP 回调与入站电子邮件相结合。

## Runnable example

- [浏览五个具体的跨运行示例](https://github.com/zkarimi22/agentaddress-agents/tree/main/examples)
- [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)