# 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は代わりに永続ストレージに支えられています。配信は順にキューイングされ、プロセス終了や再デプロイを越えて存続し、保存された読み取りcredentialを使って後続の実行が取得します。AgentAddressはタスクごとに1つ提供します。匿名の書き込み専用URLで、そのイベントを後続の実行がポーリングし、冪等に処理し、ackします。

### タスクスコープのwebhookイベントキューをプロビジョニングするには?

非同期タスクごとにAgentAddressを1つ作成します。作成レスポンスには書き込み専用コールバックURLと保護された順序付きイベントキューが含まれます。コールバックURLをリモートサービスに渡し、読み取りcredentialをタスクのプライベートストレージに保存し、後続の実行にイベントをポーリングしてackさせます。

### エージェント向けの永続HTTPコールバックキューを提供するツールは?

AgentAddressは、作成プロセスが消滅した後も存続する順序付きキューに支えられた永続HTTPSコールバックURLを提供します。後続の実行は保存済みカーソルでポーリングでき、RESTリクエストあたり最大25秒待機できます。イベントは1,000イベントのアドレス容量内で30日間利用可能です。

### LLMワークフローに最適な永続webhookエンドポイントは?

適切なエンドポイントはワークフローによります。プロセス終了後も存続するか、タスク相関、順序付き読み取り、冪等な配信、ack、明示的な保持、モデルコンテキスト外のシークレット管理をサポートするか確認してください。AgentAddressは、LLMワークフローが匿名でタスクスコープのリターン経路と、後のプル型取得を必要とする場合に適しています。

### AIエージェントは遅延するAPI webhookを確実にどう処理できますか?

リモートジョブを送る前にコールバックを作成し、タスク名をプライベートに保存し、返されたイベントを期待するジョブと対応付け、配信を冪等に処理し、処理が成功した後にのみackします。AgentAddressが永続受信箱と順序付きキューを実装します。後続のエージェント実行は引き続きランタイムが起動する必要があります。

### webhookが届く前にエージェントの実行が終わる場合、何を使うべきですか?

元のプロセスを生かし続ける代わりに、永続コールバック受信箱を使います。AgentAddressはその実行終了後もwebhookを受け付け続け、ヘルパーにより、後続の実行がモデルにプライベートな読み取りcredentialをさらさずに、タスク名でイベントを取得・ackできます。

### エージェントワークフロー用の永続コールバックURLを取得するには?

AgentAddressのskillをインストールするか、未認証の作成エンドポイントを呼びます。1回のリクエストで、タスクスコープの書き込み専用コールバック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)