実践レシピ

いずれも具体的な状況から始まり、自分で確かめられる結果で終わります。オプションとコマンドの全体は REST API と各トピックのページにあります。

1. ローカルサービスをどこからでも呼び出せるようにする

状況：手元のマシンでモデルサービス、ワークフロー、社内 API が動いており、別のエージェント、別のマシン、あるいは同僚から呼び出せるようにしたい。ポートは開けず、ドメインも設定しない。

a2al register                                     # 1. アイデンティティの作成（あれば省略可）
a2al inbound bind --addr 127.0.0.1:8080 --aid <あなたのAID>   # 2. サービスが実際に待ち受けるポートをバインド
a2al publish lang.translate --aid <あなたのAID>       # 3. 任意：検索用に能力名を公開

--addr にはサービスが実際に待ち受けているアドレスを指定し、2121 は使いません（daemon の管理ポートです）。

相手からの呼び出し

a2al get <あなたのAID> /your/api/path     # AID が分かっている場合
a2al search lang.translate                # AID が不明な場合は能力名で検索してから呼び出す

成功の目印：相手が a2al get <あなたのAID> /.well-known/agent.json を実行し、あなたのサービスの JSON を受け取ります。相手の IP、ネットワーク、NAT の構成は結果に影響しません。

利用可能なまま保つ：バインドはアイデンティティとともにデータディレクトリに保存され、再起動後に自動で復元されます。公開記録は daemon の停止から約1時間で失効します。長期に検索可能にしたい場合は daemon を常駐させてください（Windows / macOS：a2ald service install、Linux：systemd での運用）。呼び出せる相手の制限はセキュリティ実践にあります。

2. 相手の NAT の内側のエージェントへ直接届く

状況：同僚のノート PC、遠隔のワークステーション、自宅のマシンでエージェントが動いています。手元にあるのは AID だけで、VPN も公衆 IP も、失効するトンネルアドレスも使いたくない。

前提：両方のマシンで a2ald が動作していること。相手が AID を登録して公開している（またはレシピ1でサービスをバインドしている）こと。

# 一度きりの HTTP 呼び出し
a2al get <相手のAID> /.well-known/agent.json

# 長期に保つ TCP 接続（SSH、データベース、gRPC）
a2al tunnel open <相手のAID> --local-port 2222
# Tunnel:  127.0.0.1:2222
ssh -p 2222 user@127.0.0.1

成功の目印：呼び出しが完了します。相手のマシンに到達可能な公衆アドレスがまったくなくても構いません。NAT 越えは a2ald が透過的に処理します。

相手がオンラインでない場合：まずノートでタスクを渡し、相手が起動してから受け取ってもらいます。

a2al note send <あなたのAID> <相手のAID> "$(printf '%s' 'タスク X を実行' | base64 -w0)"

3. ローカルサービスを AI アシスタントに組み込む

状況：Claude や Cursor などの MCP ホストを使っていて、手元のモデル、内製ツール、社内 API を呼び出させたい。ただしサービスはインターネットに出したくない。

npx -y a2ald mcp add          # 1. MCP に接続（ホストはツールが見えるまで再読み込みが必要）

2 はホスト側かコマンドラインで行います。

a2al register                              # AID を作成
a2al inbound bind --addr 127.0.0.1:11434   # 例として Ollama

アシスタントに直接「新しいアイデンティティを登録し、このマシンの 127.0.0.1:11434 の Ollama をバインドして」と伝えても構いません。その場合 a2al_agent_register と a2al_agent_patch を呼び出します。

3（マシンをまたぐ場合）：AID を相手に渡し、相手は a2al resolve <AID> のあと必要なパスを a2al_fetch で取得します。呼び出しは端末間で暗号化され、途中のサーバーを通りません。

4. 手元のマシン群にプライベート（セルフホスト）ネットワークを組む

状況：自宅に数台、チームに数台のサーバー、あるいは隔離した検証環境があります。互いを見つけて接続できればよいが、トラフィックは公共ディレクトリに出入りさせたくない。

最初の1台（シードノード）：

a2ald --listen :4121 --data-dir /var/lib/a2al/node-a

アドレスを控えます。たとえば 192.168.1.10 です。

残りのマシン：

a2ald --bootstrap 192.168.1.10:4121 --data-dir /var/lib/a2al/node-b

--bootstrap が空でなければ公共 DNS とビーコンは完全に飛ばされます。古い peers.cache が公共ノードへ接続し続けないよう、新しい --data-dir を使ってください。

1台で2つのノードを動かす（検証用）：

a2ald --data-dir ./node-a --listen :4121 --fallback-host 127.0.0.1

a2ald --data-dir ./node-b --listen :4122 --api-addr 127.0.0.1:2122 \
      --fallback-host 127.0.0.1 --bootstrap 127.0.0.1:4121

a2al --api http://127.0.0.1:2122 resolve <ノードA上のAID>

アイデンティティ、ノート、ルーム、セッションはセルフホストネットワーク上でもまったく同じように動作します。プロトコルは同じで、ディレクトリが自分のものになるだけです。詳細はプライベート（セルフホスト）ネットワークを参照してください。

5. オフラインのマシンにタスクを渡す

状況：別のエージェントやマシンに作業を渡したいが、いまはオンラインではありません。まだ起動していないか、夜間に再起動する予定です。

PAYLOAD=$(printf '%s' '{"job":"process_data","file":"s3://…"}' | base64 -w0)
a2al note send <あなたのAID> <相手のAID> "$PAYLOAD"

相手は戻ってきたときに受け取ります。

a2al note poll <相手のAID>

MCP 経由：a2al_mailbox_send / a2al_mailbox_list / a2al_mailbox_poll。ツールの結果に pending.mailbox: N が現れたら、まず list で見てから poll で受け取る合図です。合図がなければ、毎ターン問い合わせる必要はありません。

ノートは会話ではありません：暗号化された非同期の配達であり、リアルタイムのチャネルでも、配達の受領通知でもありません。往復が必要なら、双方がオンラインになってから会話を使ってください。ファイルを送るならルームです。

目的	ページ
五つのチャネルの選び方	チャネルの選び方
常駐運用とポート	systemd での運用
コマンドとオプションの全体	REST API
よくある問題とエラーの意味	トラブルシューティング