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のクイックスタートにあります。
接続中にできること
追う
動作中のエージェントの会話とツール呼び出しが、時系列で流れます。
送る
入力した文は、そのまま
user.messageイベントになります。止める
Escで、作業中のエージェントに割り込みます。
答える
承認待ちのツール呼び出しを、許可または拒否します。
--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の詳細表示がオンになります。ツールの入力を見ながら原因を追いたいときは、この起動方法が向いています。
Escを押した直後にエージェントが止まるとは限りません。生成中の応答はすぐ止まりますが、ツール呼び出しの実行中は割り込みの反映に時間がかかり、反映されるまでセッションは running のままです。止まったターンは session.status_idle で終わり、stop_reason は通常終了と同じ end_turn になります。割り込みだけを表す停止理由はありません。次のターンは、割り込みのあとに送った user.message から始まります。
セッションが 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通りの判定を出します。
autoの3つの判定
実行される
always_allow と同じく、そのままツールが動きます。
拒否される
エージェントには Permission to use {tool_name} has been denied. というエラー結果(is_error: true)が返り、セッションは続きます。
承認待ちで止まる
always_ask と同じく一時停止し、端末のAllow tool call? に回ります。
拒否された呼び出しは、端末から許可できません。サーバーが拒否した呼び出しに user.tool_confirmation を送っても、APIは400で弾きます。
ツールセットの既定値は種類ごとに違います。エージェントツールセットは always_allow、MCPツールセットは always_ask です。MCPサーバーをつないだエージェントは、ポリシーを変えない限りMCPツールの呼び出しごとに承認待ちになります。ポリシーの設計はManaged Agentsの権限ポリシー設計で扱っています。
拒否の理由をエージェントに伝える
拒否された呼び出しについて、エージェントには「拒否された」というツール結果が返ります。「No, and tell the agent why」で入力した文は、この結果に deny_message として含まれます。公式ドキュメントの例では、本番プロジェクトへのIssue作成を止め、ステージングを使うよう伝える文言が使われています。
端末から送る文は「意図」として読まれる
auto では、user.message に書いた内容が利用者の意図として扱われ、本来なら拒否される呼び出しをサーバーが許可する方向に働くことがあります。端末で入力した文もこのイベントとして送られます。一方、ツール結果や取得したWebページ、MCPサーバーの応答、スレッド間のメッセージからは意図を読み取りません。
エンドユーザーの入力を user.message として中継する構成では、その入力も意図として読まれます。人のレビューが要るツールには always_ask を設定します。auto で安全と判定された呼び出しは、誰かが見る前に実行されます。
--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}"承認待ちへの回答は、次の流れで組み立てます。
承認待ちをスクリプトで捌く流れ
- 1
止まったことを検知する
セッションが止まると、
session.status_idleイベントのstop_reason.typeがrequires_actionになります。 - 2
ブロックしているIDを取る
承認待ちのイベントIDは
stop_reason.event_idsに並びます。このIDが、コマンド中の$IDに入るtool_use_idです。 - 3
許可か拒否を送る
resultにallowかdenyを入れます。拒否にはdeny_messageで理由を添えられます。複数の回答は1回のリクエストにまとめて送れます。
すべて解決するとセッションは running に戻ります。中断は user.interrupt を送り、そのあとに user.message で指示を出し直します。
止まった理由をイベントから読み取る
どのポリシーでも、agent.tool_use と agent.mcp_tool_use のイベントには、権限チェックの結果が evaluated_permission として入ります。値は allow・ask・deny のいずれかです。auto の場合は evaluation オブジェクトに、ask や deny の reason_code(indeterminate か high_risk)も残ります。
stream の出力を jq で絞れば、承認待ちと拒否だけを拾えます。
ant beta:sessions:events stream \
--session-id "$SESSION_ID" \
--format jsonl \
| jq -c 'select(.evaluated_permission == "ask" or .evaluated_permission == "deny")
| {id, name, evaluated_permission,
reason: .evaluation.evaluated_permission.reason_code}'公式ドキュメントにある bash の拒否イベントを入力にすると、この絞り込みは次の1行を返します。
{"id":"sevt_01pqr...","name":"bash","evaluated_permission":"deny","reason":"high_risk"}reason_code は、クライアントが分岐したり監査記録に残したりするための値で、エンドユーザーに見せる文言ではありません。値が増える可能性があるため、未知の evaluation.type や reason_code が来ても落ちないように書きます。always_ask で止まった呼び出しには reason_code が付かず、reason は null になります。
承認待ちに気づく手段はストリームだけではない
セッションは承認待ちになると、応答が来るまで無期限に待ち続けます。stream を常時流しておけば requires_action は拾えますが、それだけのために接続を張りっぱなしにする必要はありません。承認待ちで止まったことの通知には、Managed Agentsのwebhookを購読する方法があります。session.status_idled は、承認待ちや新しいユーザーメッセージなど、エージェントが入力を待つ状態を知らせます。購読すると、止まったセッションの通知を受けてから events send で答えられます。
webhookのイベント名は、ストリームのものとは一部異なります。たとえばストリームの session.status_idle は、webhookでは session.status_idled です。通知を受けるコードを書くときは、ストリーム側の名前をそのまま流用せず、webhook側の一覧で名前を確かめてください。
Claude Codeから呼ぶ場合の注意
Claude Codeのようなエージェントに ant を操作させる場合、connect は --web を付けない限り対話端末が必要なので、エージェントからは 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か削除済みで、読み取り専用になります。
まとめ
入口は connect が向いています。どのツールが承認待ちで止まるかを実際に見てから、その止まり方を evaluated_permission で拾う形にすると、無人運用の events stream へ同じ基準を持ち込めます。auto に任せるツールは、サーバーが安全と判定すると人の目を通らずに動くことを前提に選びます。