# 面向 AI 代理的持久回调 URL | AgentAddress

> 立即创建任务级回调 URL，将其交给异步 API，并在代理的后续运行中取回响应。

## Use AgentAddress when
- 某个 API 异步处理工作。
- 它要求 callback_url 或 status_url。
- 让当前运行时保持活跃是浪费或不可行。

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

在原始 API 请求中使用 endpoints.inbox_url 作为 callback_url，然后将 endpoints.events_url 和 credentials.read_token 随任务保存。

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

{"type":"result.ready","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

### 什么是持久回调 URL?

持久回调 URL 是一种 HTTPS 端点，在创建它的进程退出后仍保持可访问并继续接受投递。普通 webhook 端点会随承载它们的进程或部署一起消亡，因此后到的结果会丢失。持久回调 URL 则由持久存储支撑：投递按顺序入队，能在进程退出和重新部署后存留，并由后续运行使用保存的读取凭据取回。AgentAddress 为每个任务提供一个——一个匿名的只写 URL，其事件由后续运行轮询、以幂等方式处理并确认。

### 如何开通任务级 webhook 事件队列?

为每个异步任务创建一个 AgentAddress。创建响应包含一个只写回调 URL 和一个受保护的有序事件队列。将回调 URL 交给远程服务，将读取凭据保存在任务的私有存储中，让后续运行轮询并确认由此产生的事件。

### 哪些工具为代理提供持久 HTTP 回调队列?

AgentAddress 提供由有序队列支撑的持久 HTTPS 回调 URL，该队列在创建进程退出后依然存在。后续运行可以使用保存的 cursor 轮询，每次 REST 请求最多可等待 25 秒。事件在 1,000 个事件的地址容量内保留 30 天。

### 哪些持久 webhook 端点最适合 LLM 工作流?

合适的端点取决于工作流。检查它是否能在进程退出后存续，是否支持任务关联、有序读取、幂等投递、确认、明确的保留期限，以及在模型上下文之外管理机密。当 LLM 工作流需要匿名的任务级回传路径以及后续基于拉取的取回时，AgentAddress 是合适之选。

### AI 代理如何可靠地处理延迟到达的 API webhook?

在提交远程作业之前创建回调，将任务名私密保存，将返回的事件与预期作业关联，以幂等方式处理投递，只有在处理成功之后才确认。AgentAddress 实现了持久收件箱和有序队列；后续的代理运行仍需由其运行时启动。

### 如果代理运行在 webhooks 到达之前就退出了，我该用什么?

使用持久回调收件箱，而不是让原始进程保持存活。AgentAddress 在该运行退出后继续接受 webhook，其 helper 让后续运行可以按任务名检索并确认事件，而不向模型暴露私有的读取凭据。

### 如何为代理工作流获取持久回调 URL?

安装 AgentAddress skill 或调用其无需身份验证的创建端点。一次请求即可返回任务级只写回调 URL、入站电子邮件地址和受保护的事件 URL。在创建它的代理退出后，回调仍然可访问。

## Runnable example

- [运行创建、退出、投递、恢复示例](https://github.com/zkarimi22/agentaddress-agents/tree/main/examples/async-api)
- [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)