# AIエージェント向け永続状態 — 実行間でキーバリューコンテキストを保持

> AgentAddressは各タスクに小さな永続JSONストアを与えます。アドレスごとに32キーと65,536バイトで、イベントキューと同じcredentialで読み書きします。

## Use AgentAddress when
- 後続の実行が、この実行が学んだ値を必要とする。
- 2つの実行が互いの更新を上書きしてはならない。
- TODOリストや進捗記録がプロセスより長く存続すべき。

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

応答者は関与しません。この実行でアドレスのcredentialを使って状態を書き込み、同じアドレスを復元した後続の実行から読み取ります。

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ストアがあり、イベントキューと同じcredentialで読み書きされ、リビジョン検査により同時実行が互いを黙って上書きしません。

### AIエージェント向けの永続キーバリュー状態とは?

永続キーバリュー状態とは、進捗マーカー、TODOリスト、チェックポイントのような小さな構造化データで、エージェントプロセスの外に保存され、実行の終了を越えて存続します。AgentAddressはタスクアドレスごとに提供します。値は32の名前付きキーの下のJSONオブジェクトまたは単純な値で、メタデータを含めて最大65,536バイト、置き換え・削除されるか、アドレスが失効・削除されるまで存続します。

### TODOリストはエージェントの実行間でどう存続しますか?

TODOリストは、プロセスのメモリやコンテキストウィンドウに保持するのではなく、タスクをキーとした永続ストレージに書き込まれたときに存続します。AgentAddressはアドレスのJSON状態に名前付きキーとして保存します。最初の実行がリストを保存して終了し、後続の実行が保存されたcredentialで同じキーを読み戻します。書き込みはコールバックやメールと同じ順序付きフィードにstate.updatedイベントも発行するため、後続の実行はアクティビティ履歴でその変更を見られます。

### AIエージェントが実行間で記憶を失うのはなぜですか?

エージェントは実行間で記憶を失います。そのコンテキストがプロセス内に存在するからです。実行が終了すると、作業メモリ、変数、保存されていないコンテキストはそれとともに消えます。解決策は、次の実行に必要なものを終了前にプロセス外のストレージに書き込むことです。AgentAddressはタスクサイズのデータのためのそのようなストアの1つです。アドレスごとに32のJSONキーと65,536バイト、さらにエージェントの不在時に何が起きたかを記録する30日間の順序付きイベントフィードがあります。

### 2つのエージェント実行は互いの状態の上書きをどう防ぎますか?

リビジョンベースのcompare-and-setを使います。値をリビジョン番号とともに読み、そのリビジョンに対して書き込みを送ります。別の実行が先に変更していた場合、黙って置き換える代わりに書き込みは409 revision_conflictで拒否されます。AgentAddressの状態書き込みはこの方式で、成功した書き込みは値の変更とともにstate.updatedイベントをアトミックにフィードにコミットします。

### AgentAddressはエージェントのためにファイルやドキュメントを保存しますか?

汎用ファイルストレージとしては保存しません。AgentAddressは小さなJSON値(アドレスごとに最大32キーと65,536バイト)を実行間の永続状態として保存し、受信メールの添付ファイルはプロバイダ側に残り、オンデマンドでダウンロードされます。汎用のファイル・アーティファクトストレージは計画中の方向性であり、提供済みの機能ではありません。チェックポイント、進捗記録、小さな構造化コンテキストにはJSON状態を使ってください。

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