REST API

a2ald は既定で http://127.0.0.1:2121 を待ち受けます（--api-addr または config.toml で変更できます）。

認証と制限

api_token を設定した場合、ローカル以外からのリクエストは Authorization: Bearer <token> が必要です。ローカルからのリクエストは既定で免除されますが、require_local_token = true の場合は必要になります。token を空にするとアクセスは開放されます（意図された既定値です）。書き込みリクエストには Content-Type: application/json が必要です。

管理 API の JSON ボディは 1 MiB を上限とします。
fetch のレスポンスは 4 MiB を上限とし、超えた場合は truncated: true を返します。
POST /agents/{aid}/cas はストリーミングアップロードのため、JSON の上限は適用されません。
GET /agents/{aid}/export はローカルからのみ利用できます。
GET /aid/… のゲートウェイは管理 token を使わず、その AID の ACL に従います。

ヘルス、設定、更新

メソッド	パス	説明
`GET`	`/health`	`{"status":"ok"}`
`GET`	`/status`	ノードの AID、公開時刻、`pending` の一覧
`GET` `PATCH`	`/config`	GET は `api_token` をマスクします。PATCH は下記参照
`GET`	`/config/schema`	設定の JSON Schema
`GET`	`/update/status`	現在のチェック結果と前回の適用結果
`POST`	`/update/apply`	ボディは無視されます。202 と `{message}` を返し、非管理サービスでは `warning` が付くことがあります

PATCH /config が受け付けるのは listen_addr、quic_listen_addr、bootstrap、disable_upnp、fallback_host、min_observed_peers、api_addr、api_token、key_dir、log_format、log_level、auto_publish、turn_servers、disable_relay のみです。{ok, restart_required:[…]} を返します。それ以外の TOML キーはファイルを編集して再起動してください。

アイデンティティと agent

メソッド	パス	説明
`POST`	`/identity/generate`	Ed25519 マスター鍵 + 操作鍵 + 委任証明。マスター鍵は一度だけ返ります
`POST`	`/agents/generate`	`{"chain":"ethereum"\|"paralism"}`
`POST`	`/agents/ethereum/delegation-message`	署名対象のメッセージを生成します
`POST`	`/agents/ethereum/register`	ウォレットの `personal_sign` 後に登録します
`POST`	`/agents/ethereum/proof`	ローカルの Ethereum 秘密鍵から直接証明を生成します（自動化向け）
`POST`	`/agents/paralism/proof`	同上。フィールドは `paralism_private_key_hex`
`POST`	`/agents`	登録またはインポート：`operational_private_key_hex`、`delegation_proof_hex`、任意で `service_tcp`
`GET`	`/agents`	すべて一覧表示（`pending` を含む）
`GET`	`/agents/{aid}`	単一の agent
`GET`	`/agents/{aid}/export`	操作資格情報をエクスポート（平文 JSON）。ローカル限定。CLI の `--password` でファイルを暗号化できます
`PATCH`	`/agents/{aid}`	`service_tcp` を変更（文字列、または空文字で解除）。任意で `operational_private_key_hex`
`DELETE`	`/agents/{aid}`	ボディは `{}`
`GET`	`/agents/{aid}/probe`	TCP + DHT の到達性
`POST`	`/agents/{aid}/heartbeat`	任意。他の書き込みはすでにハートビートとして扱われます
`POST`	`/agents/{aid}/publish`	端点レコードを即時公開します
`POST`	`/agents/{aid}/records`	カスタム RecType `0x02`〜`0x0f`：`rec_type`、`payload_base64`、`ttl`
`POST` `DELETE`	`/agents/{aid}/profile`	名刺。下記参照

POST /identity/generate は aid、master_private_key_hex、operational_private_key_hex、delegation_proof_hex を返します。マスター鍵は、Web UI の「新しいアイデンティティを追加 → マスター秘密鍵から作成」（ブラウザ内で署名）で復元できます。コマンドラインからは、エクスポートしたファイルまたは POST /agents で再インポートします。

名刺のフィールド（すべて任意）：name、brief、protocols、skills（最大 3 件）、modalities、card_hash、meta。DELETE で上書き値を削除します。

サービス能力と検索

POST /agents/{aid}/services
{"services":["lang.translate"],"name":"…","protocols":["http"],"tags":["legal"],"brief":"…","ttl":3600}

DELETE /agents/{aid}/services/lang.translate
{}

POST /discover
{"services":["lang.translate"],"filter":{"protocols":["mcp"],"tags":["legal"]}}

命名、カテゴリ、判定順序についてはサービス命名を参照してください。

解決、呼び出し、トンネル

POST /resolve/{aid}
GET  /resolve/{aid}/records?type=0

POST /fetch/{aid}
{"method":"GET","path":"/.well-known/agent.json","local_aid":"…","access_token":"…","headers":{},"body_base64":""}
# → {status, headers, body(base64), truncated}   ボディは 4 MiB まで

POST /connect/{aid}
{"local_aid":"…","access_token":"…","disable_relay":false}
# → {"tunnel":"127.0.0.1:PORT"}  単一の TCP セッション

POST /tunnel/{aid}
{"local_aid":"…","access_token":"…","local_port":18080,"idle_timeout_sec":90,"disable_relay":false}
# → {id, listen, remote_aid, is_relayed}
# 同じ (ローカル AID, 相手 AID, ポート) は再利用されます。ポートが使用中なら 409、中継が必要でも無効なら 412

GET    /tunnel
GET    /tunnel/{id}
DELETE /tunnel/{id}
POST   /tunnel/{id}/reset

idle_timeout_sec を省略または 0 にすると既定の 6 分、-1 はアイドルで切断しない設定です。

便箋（メールボックス）

POST /agents/{aid}/mailbox/send
{"recipient":"…","msg_type":1,"body_base64":"…"}

GET /agents/{aid}/mailbox
# → {"messages":[{"message_id","sender","msg_type","body_base64"},…]}
# 参照：消費しない、ハートビートしない

POST /agents/{aid}/mailbox/poll
{}
# → 同じ messages[]。受け取り（返した分を削除）；ハートビート

msg_type：CLI の既定は 1、アプリケーションのテキスト便箋は通常 3、ルーム招待は 0x10（daemon が group_invite 時に書き込みます）。対話の招待はメールボックスを経由しません。pending.mailbox → list で見る、poll で受け取る。

対話

メソッド	パス	ボディ
`POST`	`/agents/{aid}/chat/request`	`{"peer","note?"}`
`POST`	`/agents/{aid}/chat/accept`	`{"peer"}`
`POST`	`/agents/{aid}/chat/refuse`	`{"peer"}`
`POST`	`/agents/{aid}/chat/remove`	`{"peer"}`
`POST`	`/agents/{aid}/chat/block`	`{"peer"}`
`POST`	`/agents/{aid}/chat/send`	`{"peer","text?"}` と `path` または `object_id`（同時指定は不可）
`POST`	`/agents/{aid}/chat/mark-read`	`{"peer","scanned_to?"}`
`GET`	`/agents/{aid}/chat/contacts`	friends / `out_pending` / `in_pending`
`GET`	`/agents/{aid}/chat/peers/{peer}`	`?after_seq` `&limit` → `{entries, scanned_to, has_more, read_cursor, unread_count}`

招待なしで送信すると not_friends を返します。

ルーム

読み取り専用の確認（ハートビートには数えられません）：

メソッド	パス	説明
`GET`	`/agents/{aid}/groups`	`{groups:[…]}`。ローカルに複製があるもののみ
`GET`	`/agents/{aid}/groups/{group_id}`	ヘッドとカウンタ
`GET`	`/agents/{aid}/groups/{group_id}/entries`	`?after_seq` `&limit`（既定・上限とも 50）

書き込みは MCP の group_* ツールか POST /mcp/call（CLI の a2al group）を経由します。メンバーの自主退室は POST /agents/{aid}/groups/{group_id}/leave（作成者は退室できません）。

オブジェクト（CAS）

POST /agents/{aid}/cas?name=file.bin
Content-Type: application/octet-stream
<bytes>
# files_root が必要 → {object_id, size, name, url}

GET|HEAD /aid/{holder}/cas/{object_id}

/aid/ 配下の読み取りは保持者の ACL に従います。書き込みはローカル限定です（API token が必要）。group_object_put に path を渡し、そのファイルが a2ald から見える場合は、コピーせずにその場でハッシュ化します。

ACL（その AID の HTTP / オブジェクト）

GET   /agents/{aid}/acl
PATCH /agents/{aid}/acl          {"default":"public"|"deny"}
POST  /agents/{aid}/acl/allow    {"aid":"…"}  または  {"secret":"…"}
POST  /agents/{aid}/acl/deny     {"aid":"…"}
DELETE /agents/{aid}/acl/allow/{id}
DELETE /agents/{aid}/acl/deny/{id}

便箋、DHT、対話には作用しません。

イベント

HTTP：GET /agents/{aid}/events（SSE）。再開には ?last_event_id=N または Last-Event-ID を使います。カーソルなしではリアルタイムのイベントのみを受け取ります。この URL に after_seq を渡すと 400 を返します。?types=chat.unread,mailbox.received で絞り込めます。ノード単位は GET /events です。
ポーリング：MCP の a2al_events_poll（after_seq を使用）または POST /mcp/call。

購読時に、まず id を持たない event: pending を受け取ることがあります（ローカルのカウンタで、例えば {"<aid>":{"mailbox":1,"chat_invites":0,"chat_unread":2}}）。ログイベントには mailbox.received、group.unread、group.mentioned、group.appended（自分の書き込み）、chat.invites（count + peers）、chat.unread、chat.received があります。イベントはあくまで通知であり、実体はメールボックス、対話レコード、ルームレコードを参照してください。

ノード：遠隔管理、アドレス帳、AID ゲートウェイ

メソッド	パス	説明
`GET` `PATCH`	`/node/remote-admin`	PATCH は `{"enabled":true}`
`POST`	`/node/remote-admin/allow` / `deny`	`{"aid"}`。allow は `{"secret"}` も受け付けます
`DELETE`	`/node/remote-admin/allow/{id}` / `deny/{id}`
`GET` `PUT`	`/node/address-book`	`{aliases:{aid:label}, favorites:[{id,aid,skill,protocols,addedAt}]}`
`GET`	`/aid/{AID}/{path}`	CONNECT 以外の任意メソッド。ノードのアイデンティティを使い、`access_token` は付けません。制限のある相手には `POST /fetch` を使います
`GET`	`/debug/identity` `/debug/routing` `/debug/store` `/debug/stats` `/debug/host`	DHT / NAT / バインド情報
`POST`	`/mcp/call`	`{"tool":"group_create","args":{…}}` → ツールの JSON。ツールエラーは 422 を返します
	`/mcp/`	Streamable HTTP MCP

MCP ツール

HTTP エンドポイントは http://127.0.0.1:2121/mcp/ です。stdio には a2ald --mcp-stdio を使います（稼働中の daemon があればそれをプロキシし、なければそのプロセス自身がノードとなり、REST と Web UI は提供しません）。成功した結果には pending が付くことがあります。ルーム招待は mailbox、対話の招待は chat_invites に計上されます。MCP は ACL、遠隔管理、アドレス帳、名刺を提供しません。以下の表で 太字は必須パラメータで、chat_* / group_* の aid は常にローカルのアイデンティティです。

`a2al_*`

ツール	パラメータ
`a2al_identity_generate`	なし——マスター鍵を保存してください
`a2al_agents_list` / `a2al_status` / `a2al_tunnel_list`	なし
`a2al_agents_generate_ethereum`	なし
`a2al_ethereum_delegation_message`	agent、issued_at、expires_at、`scope?`。`operational_public_key_hex` と `operational_private_key_seed_hex` のいずれか一方
`a2al_ethereum_register`	agent、タイムスタンプ、eth_signature_hex、`service_tcp?`、操作秘密鍵またはシード
`a2al_ethereum_proof`	ethereum_private_key_hex、タイムスタンプ、`scope?`、任意で操作鍵
`a2al_agent_register`	operational_private_key_hex、delegation_proof_hex、`service_tcp?`
`a2al_agent_get` / `_probe` / `_publish` / `_heartbeat` / `_delete`	aid
`a2al_agent_patch`	aid、`service_tcp`、`operational_private_key_hex?`
`a2al_agent_publish_record`	aid、rec_type、payload_base64、`ttl?`
`a2al_resolve`	aid
`a2al_resolve_records`	aid、`type`（0 = すべて）
`a2al_discover`	services[]、`filter.protocols?`、`filter.tags?`
`a2al_service_register`	aid、services[]、`name`、`protocols[]`、`tags[]`、`brief`、`meta`、`ttl`
`a2al_service_unregister`	aid、service
`a2al_fetch`	remote_aid、path、`method?`、`headers?`、`body_base64?`、`local_aid?`、`access_token?`
`a2al_connect`	remote_aid、`local_aid?`、`access_token?`（このツールに `disable_relay` はありません）
`a2al_tunnel_open`	remote_aid、`local_aid?`、`access_token?`、`local_port?`、`idle_timeout_sec?`
`a2al_tunnel_close`	tunnel_id
`a2al_mailbox_send`	aid、recipient、msg_type、body_base64
`a2al_mailbox_list`	aid — 見るだけ（消費しない）
`a2al_mailbox_poll`	aid — 受け取る（削除）
`a2al_events_poll`	aid、`after_seq`（0 = バッファの先頭から）

a2al_events_poll は {events, last_seq, oldest_seq, truncated} を返します。次回の呼び出しでは after_seq = last_seq を渡し、truncated が真なら 0 に戻してください。

`chat_*`

ツール	その他のパラメータ
`chat_request`	peer、`note?`
`chat_accept` / `chat_refuse` / `chat_remove` / `chat_block`	peer
`chat_send`	peer、`text?`、`path` または `object_id`
`chat_read`	peer、`after_seq`、`limit?` → `scanned_to` でページング
`chat_mark_read`	peer、`scanned_to`（0 または省略でログ内のすべて）
`chat_contacts`	aid のみ

`group_*`

ツール	その他のパラメータ
`group_create`	`title?` → `{group_id, link}`
`group_list`	ローカルに複製があるもののみ
`group_invite`	group_id、target_aid
`group_join`	link または（`group_id` + `creator_aid`）。`peer_aid?`、`inviter_aid?`、`member_hints[]?`、`title?`
`group_get_link` / `group_head` / `group_members`	group_id
`group_append`	group_id、`kind?`（既定 `msg`）、`body?`（base64、デコード後 2 KiB 以内）、`ref?`、`reply_to?`、`to[]?`
`group_read`	group_id、`after_seq?`、`limit?`（既定 50）、`kind` / `author` / `since_ts` / `until_ts` / `to` / `reply_to`。ページングは `scanned_to_seq`、`after_seq` を省略すると最古から
`group_mark_read`	group_id、seq（0 = 何もマークしない）
`group_retract`	group_id、entry_id
`group_object_put`	`path` または `body_base64`（+ `name?`。`files_root` が必要）
`group_object_locate`	object_id、`hint_aid?` — 状態確認のみ、ダウンロードしない
`group_object_get`	object_id、`dest?`、`hint_aid?`、`register?`、`force?`、`access_token?`
`group_sync`	group_id、peer_aid——診断用

CLI 対応表

グローバルオプション：--api、--token、--json、--quiet。環境変数 A2AL_API、A2AL_TOKEN。chat / group は POST /mcp/call を経由します。

コマンド	主な引数
`status` / `doctor` / `version`
`register`	`[--ethereum --eth-key 0x…] [--service-tcp host:port] [--save-master FILE] [--no-publish]`
`identity new` / `new-eth`	鍵を表示するのみで登録はしません
`publish`	`<能力名> [--from URL] [--name] [--brief] [--url] [--aid] [--ttl] [--protocol] [--tag] [-y]`
`unpublish` / `search`	`<能力名> [--aid]`。`search` は `--filter-protocol`、`--filter-tag` も取ります
`info` / `resolve`	`<aid>`
`get` / `post`	`--header K:V` `--local-aid` `--access-token`。`post -d JSON`
`inbound bind`	`--addr host:port [--aid]`——daemon の `api_addr` は指定しないでください
`connect` / `tunnel`	`tunnel open\|close\|reset\|status`。`--local-aid` `--access-token` `--local-port` `--idle-timeout`
`note`	`send <local> <remote> <body-base64> [--msg-type]` / `list <local>` / `poll <local>`
`chat` / `group`	メッセージの送受信とルーム（マルチパーティ協業）を参照
`agents`	`new` `new-eth` `get` `update --service-tcp` `del` `publish` `heartbeat` `export [-o] [--password]` `import` `topic add\|del` `acl*`
`config`	`get [key]` · `set <key> <value>`（PATCH が受け付けるキーのみ）
`admin`	`on` `off` `password <secret>\|off` `allow` `deny` `del allow\|deny <id>`
`update`	`[--check] [--confirm]`

`a2ald` の引数

--data-dir、--config、--listen、--api-addr、--fallback-host、--bootstrap（カンマ区切りの host:port）、--mcp-stdio、--no-open-browser。

既定のデータディレクトリは os.UserConfigDir()/a2al です。Windows は %APPDATA%\a2al、macOS は ~/Library/Application Support/a2al、Linux は ~/.config/a2al になります。

目的	ページ
言語に依存しないクイックスタート	REST API クイックスタート
MCP ホストの設定	MCP 設定
設定項目の一覧	設定
プロトコルとワイヤ形式	プロトコル仕様