ant beta:sessions connectでManaged Agentsのセッションを端末から操作する
ant beta:sessions connectで実行中のManaged Agentsセッションを端末で追従し、Escで割り込み、承認待ちの呼び出しに答える手順と、--webやスクリプトとの使い分けをまとめます。
ant beta:sessions connect は、動いているManaged Agentsのセッションに端末をつなぐコマンドです。会話の履歴を読み込み、エージェントの作業をリアルタイムで追いかけられます。メッセージの送信、作業の中断、承認待ちのツール呼び出しへの回答もその場でできます。
ブラウザで見たいときは --web を付けます。スクリプトからは使えず、代わりに events stream と events send を使います。この3つの使い分けが、このコマンドで迷いやすい部分です。
ant beta:sessions connectは何をするコマンドか
connect は、既存のセッションに端末を接続して、トランスクリプト(会話とツール呼び出しの記録)を表示し続けるコマンドです。セッションを新しく作るコマンドではありません。作成は ant beta:sessions create の役割で、手順はManaged Agentsのクイックスタートにあります。
接続中にできることは4つです。
- 動作中のエージェントの会話とツール呼び出しを追う
- メッセージを送る
- 作業中のエージェントを止める
- 承認待ちのツール呼び出しを許可または拒否する
--web を付けると、端末ではなくClaude Consoleのセッションビューアーがブラウザで開きます。Consoleでの可視化そのものはManaged AgentsをConsoleで可視化・デバッグする方法で扱っています。
接続の手順と前提
前提はCLIのバージョンです。connect は1.32.0以降で使えます。
ant --version古い場合は、ant CLIのインストール方法にあるHomebrewなどの手順で更新します。認証もそちらの記事の範囲です。
接続には、ワークスペース内のセッションIDを渡します。IDは、セッション作成時のレスポンス、ant beta:sessions list、Consoleのどれかで確認できます。
# 一覧から ID を探す
ant beta:sessions list
# 接続する
ant beta:sessions connect sesn_011CZkZAtmR3yMPDzynEDxu7--web なしの connect は、対話できる端末が必要です。パイプの先やCIのジョブなど、端末でない場所では動きません。
Ctrl+C で切り離せます。切り離してもセッションは止まらず、動き続けます。もう一度 connect すれば、全履歴が読み込まれます。「席を外している間にエージェントが進めた作業」を後から見に行く使い方ができます。
端末画面で何が見えて、どのキーが効くか
画面には、メッセージとツール呼び出しが時系列で流れます。ツール呼び出しごとに、所要時間と結果も出ます。下部のステータスバーには、セッションが実行中(running)か、待機中(idle)か、承認待ちかが表示されます。
マルチエージェントのセッションでは、端末ビューは主スレッドを追います。コーディネーターが委任先のエージェントとやり取りしたメッセージも、そこに含まれます。
操作キーは次の表のとおりです。
| キー | 動作 |
|---|---|
| Enter | 動作入力を user.message イベントとして送信。Alt+EnterかCtrl+Jで改行 |
| Esc | 動作実行中のエージェントを中断(user.interrupt) |
| Ctrl+O | 動作ツールの入出力・トークン使用量・ステータスイベントの表示切り替え |
| Page Up / Page Down | 動作トランスクリプトのスクロール。上に送ると追従が止まり、Endで再開 |
| Ctrl+C | 動作切り離し。入力行が空ならCtrl+Dでも切り離せる |
--verbose(-v)を付けて接続すると、最初からCtrl+Oの詳細表示がオンになります。ツールの入力が見えない状態で原因を追うときは、この起動方法が手早いです。
セッションが terminated になっているか削除済みの場合、画面は読み取り専用になります。終了後のセッションの扱いはManaged Agentsのセッション操作にまとめています。
承認待ちの呼び出しにはどう答えるか
ツール呼び出しが承認待ちになると、入力行がAllow tool call? に切り替わります。選択肢は3つです。
- Yes: 呼び出しを許可する
- No: 呼び出しを拒否する
- No, and tell the agent why: 拒否して、理由を入力してエージェントに伝える
CLIは、この選択を user.tool_confirmation イベントとして送ります。理由を入力した場合は、deny_message として渡されます。
承認待ちが起きる条件
承認待ちになるのは2つの場合です。1つは権限ポリシーが always_ask のとき。もう1つは auto のときに、サーバーが判定を出さなかったときです。
auto の挙動は、判定が3通りに分かれます。安全と判断された呼び出しはそのまま実行され、高リスクと判断された呼び出しは拒否されます。判定が出ない呼び出しだけが、承認待ちで止まります。
拒否された呼び出しは、端末から許可できません。エージェントには Permission to use {tool_name} has been denied. というエラーの結果が返り、セッションは続きます。サーバーが拒否した呼び出しに user.tool_confirmation を送っても、APIは400で弾きます。
なお、ツールセットの既定値は種類ごとに違います。エージェントツールセットは always_allow、MCPツールセットは always_ask です。MCPサーバーをつないだエージェントで承認待ちが頻発するのは、この既定値によるものです。ポリシーの設計はManaged Agentsの権限ポリシー設計で扱っています。
拒否の理由をエージェントに伝える
「No, and tell the agent why」で入力した文は、エージェントへのツール結果に含まれます。エージェントはそれを読んで方針を変えます。公式ドキュメントの例では、本番プロジェクトへのIssue作成を止め、ステージングを使うよう伝える文言が使われています。
拒否だけでは、エージェントは理由を知らないまま次の手を探します。代替の指示を添えると、その指示を踏まえた結果が返ります。
--webでブラウザに表示するには
ブラウザで見たいときは、--web を付けます。
ant beta:sessions connect sesn_011CZkZAtmR3yMPDzynEDxu7 --webこのコマンドは 127.0.0.1 上にローカルサーバーを立て、Consoleのセッションビューアーを配信します。URLが表示され、ブラウザが自動で開きます。ブラウザを開きたくない場合は --no-browser を足します。
ブラウザ側でも、メッセージの送信、中断、ツール呼び出しの許可・拒否ができます。端末ビューとの違いは、マルチエージェントのセッションで全スレッドを追える点です。端末ビューは主スレッドだけを追います。
URLの有効期限とセキュリティ
URLは、表示から2分以内に1回だけ開けます。同じタブのリロードは効きますが、別のブラウザや別のマシンで開くには、コマンドを実行し直す必要があります。
認証情報はCLIの外に出ません。ページが送るリクエストの宛先はローカルの ant プロセスだけで、APIへのリクエストはそのプロセスが代行します。サーバーは Ctrl+C を押すまで動き続けます。
スクリプトやCIでは何を使うか
connect は対話用です。スクリプトでは、次の2つを使います。
ant beta:sessions:events stream: イベントを届いた順に出力するant beta:sessions:events send: イベントを送る
stream は、--format を付けずに端末で実行すると、インタラクティブなエクスプローラーが開きます。パイプやログ保存に使うなら --format jsonl を指定します。
# イベントを 1 行 1 JSON で流す
ant beta:sessions:events stream \
--session-id "$SESSION_ID" \
--format jsonl承認待ちへの回答も、events send で送れます。connect の「Yes」に当たる操作は、次のコマンドです。
ant beta:sessions:events send \
--session-id "$SESSION_ID" \
--event "{type: user.tool_confirmation, tool_use_id: $ID, result: allow}"tool_use_id(コマンド中の $ID)には、承認待ちを起こした agent.tool_use などのイベントIDを入れます。セッションが止まったときの session.status_idle イベントには stop_reason.type が requires_action として入り、ブロックしているイベントのIDは stop_reason.event_ids に並びます。
中断も同じ仕組みです。user.interrupt を送ってから、user.message で指示を出し直します。
承認待ちに気づく手段はストリームだけではない
セッションは承認待ちになると、応答が来るまで無期限に待ち続けます。stream を常時流しておけば requires_action は拾えますが、それだけのために接続を張りっぱなしにする必要はありません。承認待ちで止まったことの通知には、Managed Agentsのwebhookを購読する方法があります。ポーリングも常時接続も要らず、通知を受けてから events send で答えられます。
webhookのイベント名は、ストリームのものとは一部異なります。たとえばストリームの session.status_idle は、webhookでは session.status_idled です。通知を受けるコードを書くときは、ストリーム側の名前をそのまま流用せず、webhook側の一覧で名前を確かめてください。
Claude Codeから呼ぶ場合の注意
Claude Codeのようなエージェントに ant を操作させる場合、connect は向きません。対話端末を前提とするためです。stream と send を使わせます。CLI全般のスクリプト化はant CLIでAPIリソースをスクリプトで自動化するにまとめています。
使い分けの早見表
| 状況 | 使うもの | 理由 |
|---|---|---|
| 手元でエージェントの作業を見守り、必要なら止めたい | 使うものconnect | 理由履歴の読み込み、追従、中断、承認が1画面で完結する |
| マルチエージェントの全スレッドを見たい | 使うものconnect --web | 理由端末ビューは主スレッドだけを追う |
| 承認待ちに答えたいが、端末ではなくブラウザが良い | 使うものconnect --web | 理由ブラウザからも許可・拒否できる |
| CI・バッチ・別プロセスから監視する | 使うものevents stream --format jsonl | 理由端末不要で機械処理しやすい |
| 承認待ちを自動で捌く仕組みを作る | 使うものevents send(user.tool_confirmation) | 理由ID指定で複数回答をスクリプト化できる |
つまずきやすい点
connectが動かない: CLIが1.32.0未満か、対話できない端末で実行している可能性があります。ant --versionを確認し、端末でないなら--webかスクリプト用コマンドへ切り替えます。- Ctrl+Cでセッションが止まると思っている: 止まりません。切り離すだけです。作業そのものを止めたいなら、Escで中断します。
- 承認画面が出ないのに作業が止まっている: ステータスバーで状態を確認します。
autoでサーバーが拒否した場合は、承認待ちにならず、エラー結果を受けたエージェントが作業を続けます。 --webのURLが開けない: 2分以内に1回だけ有効です。開き直すときは、コマンドを再実行して新しいURLを取ります。- 画面が読み取り専用になった: セッションが
terminatedか削除済みです。新しいセッションを作ります。
まとめ
ant beta:sessions connect は、動いているManaged Agentsのセッションを端末で見守り、必要なときだけ介入するためのコマンドです。追従、Escでの中断、承認待ちへの回答が1つの画面に集まっています。Ctrl+C で切り離してもセッションは続き、再接続すれば全履歴を読み込めます。
ブラウザで全スレッドを見るなら --web、自動化するなら events stream と events send。この線引きさえ押さえれば、承認待ちで止まったセッションに気づいて対応する流れを、手動でもスクリプトでも組めます。