docker-agent-run

Docker Agent：エージェントの実行と運用

概要

このスキルでは、Docker Agent の運用面を扱います。ローカル設定、エイリアス、またはレジストリー参照に対して docker agent run を実行する方法、ツール呼び出しに対してエージェントにどの程度の自律性を与えるか、サンドボックス VM で隔離する方法、実行が失敗する原因の診断方法について説明します。ここでは、agent.yaml がすでに存在することを前提としています。作成方法については「関連スキル」を参照してください。

このスキルを使用する場合

次の場合にこのスキルを有効にしてください。

• ユーザーがエージェントを対話形式またはヘッドレス（--exec）で実行したい場合。
• ユーザーがツール呼び出しに対する --safety、--yolo、または承認動作を選択またはデバッグしている場合。
• ユーザーが --sandbox でエージェントのシェル／ファイルシステムへのアクセスを隔離したい場合、またはサンドボックスのネットワークポリシーエラーが発生した場合。
• ユーザーが再利用可能なショートカット（docker agent alias）、スコープ付きの git ワークツリー（--worktree）を使いたい場合、または認証情報／モデルの利用可否をデバッグしている場合（docker agent doctor）。

このスキルを使用しない場合

次の場合はこのスキルを使用しないでください。

• docker agent run --sandbox ではなく、単独の sbx run/create/stop/rm を使用するタスクの場合は、docker-sandboxes-lifecycle を使用してください。
• 単独の sbx policy または sbx secret の設定タスクの場合は、docker-sandboxes-network-credentials を使用してください。リクエストで「自分のサンドボックス」とだけ述べられている場合は、コマンドを推奨する前に、どの CLI を使っているか確認してください。
• agent.yaml 自体の作成または編集（モデル、ツールセット、sub_agents）の場合は、docker-agent-config を使用してください。
• エージェントをサーバーとして公開する（serve）、レジストリー経由で共有する（share）、または評価する（評価セッション、--baseline 回帰ゲート）場合は、docker-agent-deploy を使用してください。

基本的なガイダンス

安全性モード

• docker agent run は 4 つの --safety モードをサポートします。タスクを完了できる範囲で、最も制限の厳しいモードを選んでください。
  • strict — すべてのツール呼び出しの前に承認を求めます。
  • balanced — 安全と分類された呼び出しは自動承認し、それ以外は承認を求めます。
  • restricted — 安全な呼び出しは自動承認し、それ以外は拒否します。プロンプトに人間が応答できない、無人／CI 実行で使用してください。
  • autonomous — すべてを自動承認します。--yolo と同等です。
• 無人実行（cron、CI、サーバーエンドポイント）を、既定で autonomous／--yolo にしないでください。無人実行では restricted を使用し、予期しないツール呼び出しが未確認のまま実行されるのではなく、安全側に倒れて失敗するようにしてください。autonomous／--yolo は、サンドボックス化された、または完全に信頼できる対話セッションでのみ使用してください。

  # CI-safe: unreviewed tool calls are denied, not silently approved.
  docker agent run --exec --safety restricted ./agent.yaml "Triage the failing test"
  

• 呼び出し元が忘れずに済むよう、エイリアスに安全性の既定値を設定してください。また、docker agent run で明示的に指定した CLI の --safety／--yolo は、引き続きエイリアスより優先されることを明記してください。

  docker agent alias add safe-coder myorg/coder --safety balanced
  

サンドボックスによる隔離

• --sandbox を指定すると、別途前提条件としてインストールと設定が必要な sbx CLI が管理する、隔離されたマイクロ VM 内でエージェントが実行されます。組み込みツールセットが開始するすべてのシェル、ファイルシステム、プロセスのアクティビティは VM 内で実行されます。マウントされるのは作業ディレクトリと、--no-kit を指定しない場合はステージングされたスキル／プロンプトファイルの「キット」のみです。例外： エージェントで宣言されたローカルの stdio MCP サーバーは、サンドボックス VM の外部でホストプロセスとして実行されます。そのような MCP サーバーは、サンドボックス化されているものではなく、信頼されたホスト統合として扱ってください。

  docker agent run --sandbox ./agent.yaml
  

• サンドボックスのネットワークプロキシはデフォルトで拒否します。モデルプロバイダー、models.dev、およびツールセットリゾルバーが推定できるホストのみが許可されます。カスタム MCP サーバーやサードパーティ API では、明示的な許可リスト項目が必要になることがよくあります。実行のたびに再検出せずに済むよう、許可リストに永続的に追加してください。

  docker agent sandbox allow api.example.com
  docker agent sandbox list
  docker agent sandbox deny api.example.com
  

• エージェントを実行するたびに --sandbox を忘れずに指定する代わりに、エージェント自身の agent.yaml に runtime: {sandbox: true} を設定しておくことを推奨します。CLI で明示的に --sandbox=false を指定すれば、1 回のデバッグ実行に限り、引き続き設定の既定値を上書きできます。
• サンドボックスは同じワークスペースからの実行間で保持され、再利用されます。セッション終了時に破棄されるわけではありません。実行のたびにクリーンな VM が用意されるとは考えないでください。新しい VM が必要な場合は、マウントセット（たとえば新しいキット）を変更して再作成を促してください。

エイリアスとデフォルトエージェント

• ショートカットを一度登録すれば、パスの代わりに名前で実行できます。

  docker agent alias add code myorg/notion-expert
  docker agent run code
  

• エージェント引数を指定せずローカルで実行すると、docker agent run は現在のディレクトリで docker-agent.yaml、次に docker-agent.yml、次に docker-agent.hcl を検索します （最初に見つかったものが使用されます）。いずれも存在しない場合に限り、 default エイリアスを解決し、該当するものがなければ組み込みのデフォルトエージェントを使用します。 これらのスキルにある agent.yaml の例ではファイル名を明示的に指定しています。 agent.yaml は自動検出の対象名ではありません。
• プロジェクト設定のないディレクトリでのフォールバックを設定するには、 default エイリアスを使います。プロジェクト設定が存在する場合でもこれを選択するには、 default を明示的に指定します。

  docker agent alias add default ./my-agent.yaml
  docker agent run default
  

• docker agent run <alias> の CLI フラグは、エイリアスに保存されたオプションよりも常に優先されます （例：docker agent run yolo-coder --yolo=false）。

ワークツリー

• --worktree（-w）を使うと、新しい Git ワークツリー内でエージェントを実行し、 現在のチェックアウトからエージェントによるファイル編集を分離できます。 対話型セッションでは、未コミットの変更、未追跡ファイル、新しいコミットがないクリーンなワークツリーは、 セッション終了時に自動的に削除されます。変更がある場合は、保持するか削除するかを尋ねられます。 ヘッドレス実行（--exec）では、状態にかかわらずワークツリーは自動削除されず、 確認できるようそのまま残されます。

  docker agent run ./agent.yaml --worktree=auth-refactor --worktree-base origin/main
  

• --worktree は --remote や --sandbox と併用できません。ワークツリーでの実行を再開するには、 --session -1（またはセッション ID）を指定します。ワークツリーはすでに存在するためエラーになるので、 --worktree を再度指定しないでください。

トラブルシューティング

• 「No model is currently available」または「model ... is not pulled」は、 エージェントのプロバイダーに使用可能な認証情報がないか（dmr/ の場合は）モデルがプルされていないことを意味します。 YAML を変更する前に、まず docker agent doctor ./agent.yaml を実行してください。 解決されたモデル／プロバイダーと、認証情報が見つかったかどうかが報告されます。 認証情報がない場合は、プロバイダーの API キーを環境変数に設定してください。 DMR モデルがない場合は、docker model pull <model> を実行してください。 タスクを再試行する前に、もう一度 doctor を実行してください。
• 計画を説明するだけで実行しないエージェントは、たいてい必要なツールが不足しています （agent.yaml に type: shell または type: todo を追加してください）。 モデルの障害ではありません。この場合は docker-agent-config に引き継いでください。
• サンドボックス実行中の 403 Blocked by network policy エラーは、 接続先が許可リストに登録されていないことを意味します。docker agent sandbox allow <host> を使用してください。

関連スキル

• sbx の単独のライフサイクルコマンドについては、docker-sandboxes-lifecycle を使用してください。
• sbx policy と sbx secret の単独の操作については、docker-sandboxes-network-credentials を使用してください。
• 基盤となる agent.yaml（モデル、ツールセット、sub_agents）の作成や変更については、docker-agent-config を使用してください。
• エージェントの提供、共有、評価については、docker-agent-deploy を使用してください。

参考資料

• references/safety-and-sandbox.md — セーフティモードとフラグの相互作用をまとめた表、およびサンドボックスの信頼境界の詳細。
• references/sources.md — このスキル内の各ルールの出典。

アセット

• なし。

チェック

• checks/verification.md — docker agent run の呼び出しを検証する手順書。