docker-agent-config

Docker Agent の設定

概要

Docker Agent（CLI は docker agent、オープンソースプロジェクトは cagent） は、アプリケーションコードではなく YAML ファイルで宣言された AI エージェントを実行します。この スキルでは agent.yaml アーティファクトを扱います。具体的には、agents セクション（各エントリの model、instruction、および固有の toolsets／sub_agents）、エージェントから参照されるトップレベルの models／providers セクション、そしてエージェントが use_commands で利用できるトップレベルの commands グループです。CLI の呼び出しや設定の提供・共有は対象外です。関連する スキルを参照してください。

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

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

• ユーザーが agent.yaml／agent.yml／agent.hcl ファイルを作成、編集、またはレビューしている場合。
• ユーザーがエージェント設定にツール／ツールセット、MCP サーバー、またはサブエージェントを追加したい場合。
• ユーザーがエージェント用のモデル／プロバイダー（OpenAI、Anthropic、Google、Bedrock、Docker Model Runner、カスタムエンドポイント）を選択または設定したい場合。
• ユーザーが、コーディネーターがスペシャリストにタスクを委任するマルチエージェントの「チーム」を作りたい場合。

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

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

• CLI の実行（docker agent run のフラグ、--safety、--sandbox、エイリアス、ワークツリー）に関するタスクの場合は、docker-agent-run を使用してください。
• エージェントをサーバーとして公開（serve mcp/api/a2a/acp/chat）する、配布（share push/pull）する、または評価（評価セッション、--baseline 回帰ゲート）するタスクの場合は、docker-agent-deploy を使用してください。
• Docker Agent と関係のない一般的な Dockerfile や Compose サービスのタスクの場合は、docker-build-strategies または docker-compose-patterns を使用してください。

基本的な指針

ファイル構造

• すべての設定には、トップレベルの agents: の下に少なくとも 1 つのエージェントが必要です。名前が root のエージェント、または最初に定義されたエージェントが、ユーザーメッセージを受け取る エントリーポイントです。

  agents:
    root:
      model: anthropic/claude-sonnet-4-5
      description: A coding assistant
      instruction: |
        You are an expert developer. Help users write clean,
        efficient code. Explain your reasoning step by step.
      toolsets:
        - type: filesystem
        - type: shell
        - type: think
  

• 必須のエージェントプロパティ：model、description、instruction（または instruction_file）。description は単なる飾りではありません。他のエージェントはこれを読んで このエージェントに委任するかどうかを判断するため、正確に保ってください。
• 長いプロンプトでは、インラインの instruction の代わりに instruction_file（相対パス。.. は不可）を使用してください。これにより、 YAML のエスケープではなく動作に関する変更に差分を絞れます。instruction と instruction_file は相互に排他的です。 OCI リファレンスまたは URL から読み込まれたエージェントでは instruction_file はサポートされません。その場合はインラインの instruction を使用してください。

モデルとプロバイダー

• モデルの設定方法は 2 つあります。インラインの provider/model 省略表記を使う方法と、トップレベルの models: の下に provider を参照する名前付きエントリを定義する方法です。temperature、max_tokens、thinking_budget が必要な場合や、 複数のエージェントで再利用する場合は、名前付きの形式を使用してください。

  models:
    claude:
      provider: anthropic
      model: claude-sonnet-4-5
      max_tokens: 64000
  
  agents:
    root:
      model: claude
  

• 組み込みのプロバイダーキー：openai、anthropic、google、amazon-bedrock、 dmr（Docker Model Runner、ローカル、API キー不要）、ollama（ローカル）。ほかにも数十種類の 組み込みエイリアス（mistral、groq、xai、together、 azure、github-copilot、openrouter など）があり、それぞれに <PROVIDER>_API_KEY 形式の環境変数が必要です。解決可能なものを確認するには docker agent models --all を実行してください。また、環境変数を手動編集する代わりに、対話形式で認証情報を登録するには docker agent setup を実行してください。
• agent.yaml に API キーを直接記述しないでください。プロバイダーの認証情報は、環境変数（カスタムプロバイダーでは token_key）または docker agent setup が作成する ~/.config/cagent/.env から取得します。
• オフラインでの実行が必要なエージェントや、サードパーティにデータを送信してはならないエージェントには、dmr/<model> を優先してください。費用がかからず、認証情報も必要ありません。タスク上必要な場合に限り、有料のクラウドプロバイダーを使用してください。
• プロバイダーの停止やレート制限によって実行が止まらないよう、耐障害性が重要なエージェントには fallback を設定してください。

  agents:
    root:
      model: anthropic/claude-sonnet-4-5
      fallback:
        models: [openai/gpt-5, google/gemini-3.5-flash]
        retries: 2      # per model, for 5xx errors
        cooldown: 1m    # stick with fallback after a 429
  

• セルフホスト型／OpenAI 互換のエンドポイント（vLLM、LiteLLM、社内ゲートウェイ）では、URL を各モデルにインラインで記述するのではなく、base_url と token_key を含む providers: エントリを定義してください。

  providers:
    my_gateway:
      base_url: https://api.example.com/v1
      token_key: MY_API_KEY
  models:
    my_model:
      provider: my_gateway
      model: gpt-4o
  

ツールセット

• 組み込みツールセットは外部依存関係が不要です：filesystem、shell、 think、todo、tasks、memory、fetch、background-jobs、script、 lsp、api。リストの項目ごとに1つ追加します：

  toolsets:
    - type: filesystem
    - type: shell
  

• エージェントが計画を説明するだけで実行しない場合は、type: todo （または shell）を追加します。これはモデルの問題ではなく、エージェントに 実行に必要なツールが不足している場合によく見られる症状です。
• 外部ツールには、独自の統合よりも Docker の MCP カタログにある MCP サーバーを 優先してください。コンテナとして実行され、複数のエージェントで再利用できます：

  toolsets:
    - type: mcp
      ref: docker:duckduckgo
  

  ローカルの stdio とリモート HTTP/SSE MCP サーバーにも対応しています。 references/toolsets-and-providers.md を参照してください。
• ツールセット（MCP かどうかは問いません）に defer: true を指定すると、 起動時ではなく必要に応じてツールを読み込めます。エージェントが多数の ツールセットを持ち、起動時の遅延が問題になる場合に使用してください。
• エージェントに readonly: true を設定すると、使用するすべてのツールセットを 読み取り専用ツールに制限できます。何も変更してはならないレビュー／分析 エージェントに使用してください。

マルチエージェントチーム

• コーディネーターは sub_agents: [name, ...] で委任します。サブエージェントを 一覧にすると、親エージェントで transfer_task ツールが自動的に有効になります。

  # Fragment: coder and reviewer are defined separately in the full asset.
  agents:
    root:
      sub_agents: [coder, reviewer]
  

  レビュアーの readonly: true 制限も含め、実行可能なチーム全体には assets/team-agent.yaml を使用してください。テンプレートを応用する際も この制限を維持してください。ファイルシステムのツールセットだけでも書き込みが 可能になるためです。
• sub_agents は外部 OCI 参照（myorg/agent:tag）も受け付けます。 本番環境の設定では、タグによって実行ごとに発生するレジストリ検索を省略するため、 外部参照をダイジェスト（name@sha256:...）に固定してください。
• クリーンで分離された結果を得る委任には、transfer_task（sub_agents 経由）を 使用してください。ユーザーにセッションの残りの間そのエージェントに なってもらう 場合に限り、agent: フィールドを含む commands: エントリーを 使用してください。

安全性と衛生管理

• 信頼できない入力に対して shell/fetch ツールを実行するエージェントには、 redact_secrets: true を設定してください。ツール引数、送信メッセージ、 ツール出力から、認識されたシークレットのパターンを除去します。これは 多層防御であり、保証ではありません。任意のパスワード、トークン、 顧客データは検出されない場合があります。
• 自律的にループするエージェントには max_iterations を設定してください （デフォルトは無制限です）。コストを抑え、ループが止まらなくなるのを防ぎます。 max_consecutive_tool_calls（デフォルトは5）でも、同一呼び出しのループを すでに防止しています。
• リテラル値か展開値かにかかわらず、認証情報、トークン、機密性の高い顧客データを instruction、instruction_file、コマンドプロンプトに含めないでください。 ${env.VAR} は値をモデルに送信されるプロンプトテキストに展開します。値を 環境変数ファイルに保存しても、この情報漏えいは防げません。展開は機密情報でない コンテキストにのみ使用してください。
• プロバイダーの認証情報は docker agent setup またはプロバイダーがサポートする 環境変数を通じて渡してください。カスタムプロバイダーでは、token_key: MY_API_KEY は値ではなく環境変数名を指定します。展開しないでください。 ツール／MCP の認証情報は、プロンプトやモデルが指定するツール引数ではなく、 その統合の認証メカニズムを通じて設定してください。プロンプトでは、シークレットを 含めずに認証済みの機能を説明してください。認証を確認するために、エージェントに 認証情報ファイルや環境変数の値を読み取ったり、表示したりするよう求めないでください。

関連スキル

• エージェントの実行（docker agent run、安全モード、サンドボックス、エイリアス）については、docker-agent-run を使用してください。
• エージェントの提供、共有、評価については、docker-agent-deploy を使用してください。

リファレンス

• references/toolsets-and-providers.md — 組み込みツールセットの全一覧、MCP 接続モード、プロバイダー／環境変数の表。
• references/sources.md — このスキルの各ルールの出典。

アセット

• assets/team-agent.yaml — 実行可能なマルチエージェントチームのテンプレート（コーディネーター＋コーダー＋レビュアー）。

チェック

• エージェントを実行する前に、checks/verification.md に従って解決済みの設定、 公開されているツール、プロバイダーへの接続を確認し、スモークテストを実施してください。