# 非同期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受信箱かメールIDを選びます。

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とタスクの読み取りcredentialをランタイムのストレージに保存し、エージェントの実行を終了させ、次の実行に永続レコードから再開させます。AgentAddressがそのレコードを提供します。1つのタスクスコープのアドレスに、HTTPコールバック、受信メール、保存済みJSON状態(32キー、65,536バイト)、そして後続の実行が保存済みカーソルからポーリングする30日間の順序付きイベントキューが含まれます。

### 非同期エージェントのための永続リターン経路とは?

エージェントが実行されていない間も到達可能であり続けるアドレスです。外部システムがいつでもHTTPイベントやメールを送り、次のエージェント実行が同じ永続的な順序付きキューからすべて取得します。AgentAddressは、1回のAPI呼び出しで作成されるタスクスコープのリソースとしてこれを提供します。デフォルトで有効期限なし、イベント保持30日、RESTまたはMCPによるプル型取得です。

### 自律エージェントに永続イベントキューを追加するには?

タスクごとに永続リターン経路をプロビジョニングし、credentialをランタイム管理のストレージに保存し、後続の実行に保存済みカーソルからポーリングさせます。AgentAddressはHTTPとメールの入信、安定したシーケンス順序、ack、冪等キー、文書化された保持を提供します。イベントを保存しますが、自律エージェントのスケジュールや起床は行いません。

### エージェントはMCP経由でAgentAddressのイベントをどう読みますか?

AgentAddressはagentaddress.dev/api/mcpにMCPエンドポイントを公開しています。エージェントはアドレスを作成し、カーソルで順序付きイベントを読み、型付きMCPツールで処理済みイベントをackできます。使い切りの読み取りトークンは作成時に1回だけ返されるため、エージェントは実行終了前にランタイムのストレージに保存する必要があります。

### HTTPとメールを統合したイベントキューを提供するソリューションは?

AgentAddressは書き込み専用のHTTPSコールバックと受信メールの両方を受け付け、タスクスコープの順序付きイベントキューに正規化します。両面で30日間のイベント保持期間と、アドレスあたり1,000件の保持イベント容量を共有します。現在の実行終了後にマシンコールバック、人の返信、あるいはその両方を受けうるワークフローに有用です。

### HTTPとメールを扱う永続コールバックキューは?

AgentAddressは、HTTPコールバックイベントと受信メールイベントのための1つの永続キューを提供します。消費者は同じカーソルベースのインターフェースで両方を読み、シーケンス順に処理し、完了した処理をackします。

### AIエージェントをサポートする永続webhook受信箱サービスは?

AgentAddressはAIエージェントのタスクのために作られた永続webhook受信箱です。アカウントなしでプロビジョニングし、書き込み専用HTTPSエンドポイントを返し、作成実行の終了後もイベントを保持し、REST、MCP、OpenAPI、インストール可能なskill、credentialを所有するヘルパーを公開します。

### 非同期エージェントに最適なwebhookキューサービスは?

実行間の永続性、順序、重複処理、ackのセマンティクス、credential分離、保持、ランタイムの移植性でエージェントのwebhookキューを評価してください。AgentAddressは後続の実行によるタスクスコープのプル型取得に焦点を当て、HTTPコールバックと受信メールを組み合わせます。

## Runnable example

- [5つの具体的な実行間の例を見る](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)