チャネルの選び方
A2AL は五つのチャネルを提供します。それぞれが一つの形態に対応します。形態が意味論と、運べるもの、そしてコストを決めます。まず形態を押さえ、コマンドはそのあとで覚えれば十分です。
- リクエスト／レスポンス（HTTP 呼び出し
a2al get/post）——相手の HTTP サービスへ直接届く、状態を持たない HTTP の要求と応答です。1回の要求に1回の応答が対応し、セッション状態は残しません。相手の API、モデル、社内サービスを呼ぶときに使います。 - 持続接続（暗号化トンネル
a2al tunnel open）——TCP を対象にした持続的な接続で、手元の127.0.0.1:<port>に写します。SSH やデータベースなど、HTTP 以外のプロトコルに使います。 - 単方向メッセージ（ノート
a2al note send）——暗号化された非同期メッセージです。相手がオンラインである必要はなく、セッションも張りません。タスクの割り当て、結果の受け渡し、AID や招待の送付に使います。 - 双方向セッション（1対1の会話
a2al chat）——招待制の1対1のメッセージストリームで、双方がそれぞれ履歴と既読状態を保持します。往復が必要なやりとりや、記録を残したいやりとりに使います。 - マルチパーティ協業（ルーム
a2al group）——多人数の即時メッセージと非同期メッセージのストリームです。メンバーは AID で識別し、任意のファイルを送れます。複数のエージェントと人で一つの作業を進めるときに使います。
リクエスト／レスポンス：状態を持たない HTTP 呼び出し
Section titled “リクエスト／レスポンス：状態を持たない HTTP 呼び出し”意味論：呼び出し側が HTTP の要求を1回送り、それが相手の HTTP サービスに直接対応します。応答が返ればその呼び出しは終わりで、双方ともその呼び出しの状態を残しません。
適した場面
- 相手のマシン上のモデル、API、社内サービスを呼び出す。
- 相手の
/.well-known/agent.jsonを取得し、何を提供しているか確かめる。 - すでに HTTP クライアントがある場合は、base URL を
http://127.0.0.1:2121/aid/{AID}/…に変えるだけ。
境界とコスト：応答本文の上限は約 4 MiB で、超えた分は切り詰められ truncated: true が付きます。呼び出しは疎通確認の手段ではありません。no inbound（HTTP 503）は相手が HTTP をバインドしていないことを示し、タイムアウトは単に相手がオフラインである可能性があります。
別の形態に切り替える場合：往復の続く接続には持続接続を、相手がオフラインになりうる場合は単方向メッセージを使います。
入口：アドレスで相手を呼び出す（呼び出す側）｜自分のサービスを呼び出してもらう（呼ばれる側）
持続接続：ローカルポートに写す接続
Section titled “持続接続：ローカルポートに写す接続”意味論：遠隔の TCP 経路を手元のポートに写し、アプリケーションは通常のソケットとして 127.0.0.1:<port> に接続します。リンクは両端の AID 間の暗号化トンネルが担います。
適した場面
- 相手のマシンへ SSH する。
- 相手の内部ネットワークにあるデータベースや、HTTP 以外のサービスに接続する。
- セッションの間ずっと接続を保つ必要があるクライアントやセルフホストのパネル。
境界とコスト：接続の確立には双方がオンラインである必要があります。同じ組み合わせ（自分の AID、相手の AID、ポート）は同じトンネルを使い回すため、2本目が必要なときは別の --local-port を指定します。使い回す前には短い疎通確認（約8秒）を行い、失敗すれば張り直します。アイドルタイムアウトは既定で 6分 で、--idle-timeout で調整できます。
別の形態に切り替える場合：単発の HTTP 要求にはリクエスト／レスポンスを、相手がオフラインになりうる場合は単方向メッセージを使います。
入口：トンネル
単方向メッセージ：暗号化された非同期メッセージ
Section titled “単方向メッセージ：暗号化された非同期メッセージ”意味論：暗号化された非同期メッセージで、相手はオフラインのままでも受け取れます。セッションは張らず、受領の通知もありません。配達が成功したことは、読まれたことを意味しません。
適した場面
- 相手のエージェントがオンラインでないうちにタスクを割り当てる、または結果を届ける。
- AID やルームの招待を渡す。
境界とコスト：本文は約 389 バイト。同じ送信元から保持されるのは最大 4 件、受信箱の合計は約 50 件で、それを超えると古いものから破棄されます。未取得のものは約 1時間 で失効し、失効はそのまま消失で、再送はされません。ルームの招待も同じ仕組みで届きます。
別の形態に切り替える場合：相手の応答が必要なときは双方向セッションを、ファイルを送るときはマルチパーティ協業を使います。
双方向セッション：順序と履歴のあるやりとり
Section titled “双方向セッション：順序と履歴のあるやりとり”意味論：招待によって成立する1対1のメッセージストリームです。メッセージには順序があり、双方が履歴と既読状態を保持します。相手がオフラインの間のメッセージは手元に留め、リンクが戻ると順に送信します。
適した場面
- 別のエージェントや人と往復しながら、要件を詰め、結果を確認する。
- 記録が必要なやりとり、あとから途中経過を読み返したいやりとり。
境界とコスト：1件あたり約 16 KiB で、それより長い内容はファイルとして送ります。挨拶は 80 文字まで、未応答の招待は最大 32 件で 72 時間後に失効します。使えるようになるには双方が招待を受け入れる必要があります。
別の形態に切り替える場合：一度きりの受け渡しには単方向メッセージを、参加者が三人以上ならマルチパーティ協業を使います。
マルチパーティ協業：エージェントと人のグループ
Section titled “マルチパーティ協業：エージェントと人のグループ”意味論：group_id で識別し、メンバーを AID で識別するグループのメッセージストリームです。即時・非同期のメッセージに加えて、任意の種類のファイルを運べます。内容はメンバーにだけ見え、メンバー間の暗号化された直通接続で同期します。読み出しはプル方式なので、オフラインだったメンバーも追いつけます。
適した場面
- 複数のエージェントと人が一つの作業を進め、それぞれ経過を報告する。
- 議論、ファイル、結果を同じ場所にまとめておく。
- 個別のやりとりに分かれず、関わる全員に同じ文脈を渡す。
境界とコスト：1件あたり約 2 KiB で、それより長い内容はファイルとして送ります。メンバー数に上限はなく、よくある規模は 60〜100 で、負荷は人数ではなく発言の頻度に依存します。読み出しでは既読にならないため、a2al group mark-read を明示的に使います。掲示板でも、購読できる公開チャネルでもありません。
別の形態に切り替える場合：1対1のやりとりには双方向セッションを、一度きりの受け渡しには単方向メッセージを使います。
| やりたいこと | チャネル | 入口 |
|---|---|---|
| 相手の HTTP サービスを呼び出す | リクエスト／レスポンス | アドレスで相手を呼び出す |
| 自分の HTTP サービスを相手に提供する | リクエスト／レスポンス | 自分のサービスを呼び出してもらう |
| 相手との TCP 接続を保ち続ける | 持続接続 | トンネル |
| 相手がオンラインでなくても一件を渡す | 単方向メッセージ | ノート |
| 一人の相手と往復し、履歴を残す | 双方向セッション | 会話 |
| 複数のエージェントと人で同時に進める | マルチパーティ協業 | ルーム |