Docker Agent入門：YAML設定だけでマルチエージェントAIを構築する方法【MCP対応】

はじめに：AIエージェント開発は「コードを書く時代」から「YAMLを書く時代」へ

AIエージェント開発の世界が、静かに、しかし確実に変わりつつあります。

LangChainでチェーンを組み上げ、CrewAIでエージェントクラスを継承し、数百行のPythonを書いてようやく動く——そんな時代から、YAMLを数十行書くだけでマルチエージェントが動く時代へのシフトが始まっています。

その変化を象徴するのが、Docker Engineeringが2025年にリリースしたDocker Agentです。Hacker Newsで98スコアを獲得し、開発者コミュニティの注目を集めているこのツールは、「コンテナのようにAIエージェントを動かす」というシンプルなコンセプトを実現しています。

この記事で作るもの

この記事では、以下の構成のマルチエージェントパイプラインを実際に動かすところまでを解説します。

ユーザーのリクエスト
        ↓
  root（オーケストレーター）
        ↓
  researcher（Web検索でトピックを調査）
        ↓
  writer（調査結果を記事にまとめる）
        ↓
  完成したMarkdownファイル

所要時間の目安は約30分です。Docker Desktopがインストール済みであれば、環境構築から動作確認まで迷わず進められるよう解説します。

なぜいまDocker Agentが注目されているのか

従来のエージェントフレームワークには、学習コストと配布コストという2つの壁がありました。LangChainはその抽象化層の複雑さゆえに「ドキュメントを読み続けても実装が安定しない」という声が絶えず、CrewAIはPythonの知識が前提となるため、インフラエンジニアやデータアナリストには敷居が高い面がありました。

Docker Agentが選んだアプローチは宣言的設定です。docker-compose.yamlでコンテナ構成を定義するのと同じ感覚で、エージェントの役割・モデル・ツール・委譲先を記述するだけでよい。コードを書かない、ということはレビューしやすく、バージョン管理しやすく、チームで共有しやすいことを意味します。

Apache 2.0ライセンスでOSS公開されていることも重要です。ベンダーロックインを避けながら、必要に応じて拡張や改変ができます。

前提条件と必要な環境

本記事を進めるにあたり、以下の環境が必要です。事前にご準備ください。

Docker Desktop 4.63以降（docker agent サブコマンドが同梱）
OpenAI または Anthropic のAPIキー（どちらか一方でOK）
ターミナルの基本操作（コマンドのコピペができれば十分）

Docker Desktopのインストールがまだの場合は、公式サイトから最新版を入手してください。docker agent サブコマンドはDocker Desktop 4.63で正式導入されたため、それ以前のバージョンでは使用できません。

第1章：Docker Agentとは何か — 3分で理解する基礎

Docker Agentの正体：エージェントビルダー＋ランタイム

Docker Agentは、YAMLファイルで定義されたAIエージェントをビルドして実行するランタイムです。従来のDockerがDockerfileからコンテナイメージをビルドするように、Docker Agentはagent.yamlからエージェントを構築します。

起動コマンドはシンプルです。

docker agent run agent.yaml

これだけでインタラクティブなTUI（テキストユーザーインターフェース）が立ち上がり、エージェントとの対話が始まります。非対話型で使いたい場合は--execフラグを使います。

docker agent run agent.yaml --exec "Dockerの基本概念を3点で説明してください"

LangChain・CrewAIとの決定的な違い

実際の開発現場では、ツール選定で迷うことが多いと思います。下表で主要な違いを整理しましょう。

観点	Docker Agent	LangChain	CrewAI
記述方法	YAML（宣言的）	Python（命令的）	Python（クラス継承）
学習コスト	低い	高い	中程度
配布方法	OCI（DockerHub等）	pip / Gitリポジトリ	pip / Gitリポジトリ
実行環境	Docker Desktop	Python環境	Python環境
コードレス	✅	❌	❌

Docker Agentが特に有利なケース：チームでエージェントを共有したい、インフラコードとしてGit管理したい、Python非専門家もエージェントを定義・修正できるようにしたい。

フレームワークが有利なケース：複雑な条件分岐やカスタムツールをプログラマブルに制御したい、既存のPythonコードベースに統合したい。

対応AIプロバイダー一覧

Docker Agentは主要なAIプロバイダーすべてに対応しています。

OpenAI（GPT-4o, GPT-5など）
Anthropic（Claude Sonnet, Claude Opus, Claude Haikuなど）
Google Gemini（Gemini 2.5 Proなど）
AWS Bedrock
Mistral
xAI（Grokなど）
Docker Model Runner（Llama, Phi等のローカルLLMをオフラインで実行）

特筆すべきはDocker Model Runnerです。インターネット接続なしで完全オフライン運用が可能になるため、機密情報を扱う社内システムにも適用できます。

第2章：環境構築 — 最初のエージェントを動かす

ステップ1：Docker Desktopのバージョン確認

前提条件のセクションでDocker Desktop 4.63以降をインストール済みであることを確認しました。まずdocker agentサブコマンドが正しく認識されているかチェックしましょう。

# Dockerバージョンの確認
docker --version
# 例: Docker version 27.1.0, build ...

# docker agentサブコマンドの利用可能確認
docker agent --help

docker agentのヘルプが表示されれば準備OKです。'agent' is not a docker command と表示される場合は、Docker Desktopのバージョンが4.63未満である可能性があります。最新版へのアップデートを行ってください。

ステップ2：APIキーの設定

APIキーをYAMLファイルに直書きすることは絶対に避けてください。 Gitにコミットした瞬間にシークレットが漏洩します。正しい方法は環境変数経由での受け渡しです。

# Anthropicを使う場合
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"

# OpenAIを使う場合
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"

.bashrcや.zshrcへの追記ではなく、セッションごとに設定するか、.envファイルを使ってdirenvなどで管理することをベストプラクティスとしておすすめします。

ステップ3：最小構成のagent.yamlを書く

では、最初のエージェントを定義しましょう。以下の内容をagent.yamlという名前で保存してください。

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: "コーディングアシスタント"
    instruction: |
      あなたは専門的なソフトウェア開発者です。
      クリーンで保守性の高いコードを書くことを支援します。
      コード例を示す際は必ず説明を添えてください。

各フィールドの意味を確認しておきましょう。

agents: エージェントの定義をまとめるトップレベルキー
root: エントリーポイントとなるエージェントの名前（変更可だがrootが慣例）
model: プロバイダー名/モデル名の形式で指定
description: 他のエージェントがこのエージェントを参照するときの自己紹介（マルチエージェントで重要）
instruction: エージェントの振る舞いを定義するシステムプロンプト

ステップ4：実行して対話する

docker agent run agent.yaml

TUIが起動したら、テキストを入力してEnterを押すだけで対話できます。Ctrl+Cで終了します。

スクリプトやCIパイプラインから呼び出す場合は--execを使います。

docker agent run agent.yaml --exec "FizzBuzzをPythonで実装してください"

よくあるエラーと対処法：

エラー	原因	対処
`authentication error`	APIキーが未設定または誤り	環境変数を再確認
`model not found`	モデル名のタイポ	プロバイダープレフィックスとモデル名を確認
`yaml: line XX`	YAMLのインデントエラー	スペース数を確認（タブはNG）

第3章：YAML設定を読み解く — 設定リファレンス実践編

`model`：プロバイダープレフィックス形式の書き方

モデル指定はプロバイダー/モデル名の形式です。

model: openai/gpt-4o           # OpenAI GPT-4o
model: anthropic/claude-opus-4  # Anthropic Claude Opus
model: google/gemini-2.5-pro   # Google Gemini 2.5 Pro
model: docker/llama3.2         # Docker Model Runner（ローカル）

技術的に正確な表現をするなら、このプレフィックス形式はルーティングのための名前空間として機能しています。同じYAMLでモデルを差し替えるだけで、動作の違いを比較検証できます。

`instruction`と`description`：役割を正しく伝えるコツ

descriptionは「他のエージェントが見る自己紹介」です。マルチエージェント構成でrootエージェントがどのサブエージェントにタスクを委譲すべきか判断する際に参照されます。

description: "Web検索専門のリサーチエージェント。最新情報の収集と要約が得意。"

instructionのアンチパターンを3つ挙げます。

曖昧な指示：「良いアシスタントになってください」→ 「〇〇の専門家として、△△のフォーマットで回答してください」と具体化する
矛盾した指示：「簡潔に答えて」かつ「詳細に説明して」→ 状況を分けて記述する
役割の混在：1エージェントに「調査」「執筆」「レビュー」を全部担わせる→ サブエージェントに分割する

`toolsets`：標準内蔵7種のツールセット

Docker Agentには7種類のツールセットが標準で用意されています。

ツールセット	用途	主な使いどころ
`filesystem`	ファイル読み書き	ドキュメント生成、コード出力
`shell`	コマンド実行	ビルド、テスト、スクリプト実行
`think`	内部推論の強化	複雑な判断が必要なタスク
`todo`	タスク管理	複数ステップのタスクの進捗管理
`memory`	セッション間の記憶	ユーザー設定や過去の対話の保持
`fetch`	HTTP取得	Webページ・API呼び出し
`script`	スクリプト実行	Python・Node.js等の実行

shellツールを使う際の注意点：shellはホスト環境に直接アクセスできる強力なツールです。実際の開発現場では、shellツールは必要最小限の権限を持つDockerコンテナ内で実行するか、MCPのコンテナ隔離を活用することをベストプラクティスとして強く推奨します。

toolsets:
  - type: filesystem
    paths: ["./output"]   # アクセス可能なパスを限定
  - type: think

第4章：マルチエージェント構成を組む — AIオーケストレーションの実装

マルチエージェントが必要になる瞬間

単一エージェントが破綻する典型的なパターンがあります。「最新のDockerのベストプラクティスを調査して、1000字の解説記事を書いて、レビューもして」という複合タスクを1つのエージェントに任せると、どうなるか。

コンテキストウィンドウが圧迫されます。「調査」「執筆」「レビュー」という互いに干渉する役割が混在すると、モデルは最適な振る舞いを見つけられません。そして最も根本的な問題として、調査の質が低いまま執筆が始まってしまいます。

「調べる人」と「書く人」を分けると精度が上がる理由は明快です。各エージェントが自分の役割に特化したコンテキストを持てるからです。

Coordinator + Specialistパターンの全体像

Docker Agentの推奨アーキテクチャはrootエージェントをオーケストレーターとして機能させ、特定のタスクを専門エージェントに委譲するパターンです。

root（オーケストレーター）
├── researcher（Web検索・情報収集）
└── writer（記事執筆・ファイル出力）

このパターンの利点は3つあります。

役割の明確化：各エージェントのシステムプロンプトが短く明快になり、モデルが迷いにくい
コンテキストの独立：researcherの検索履歴がwriterのコンテキストを汚染しない
保守性の向上：一方のエージェントを改修しても他方に影響を与えない

researcher + writerパイプラインの完全なYAML

では実際にマルチエージェントを定義しましょう。以下の内容をpipeline.yamlとして保存してください。

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: "リサーチ・ライティングパイプラインのオーケストレーター"
    instruction: |
      あなたはタスクを適切なサブエージェントに委譲するオーケストレーターです。
      ユーザーからテーマを受け取ったら、以下の手順で処理してください。

      1. researcherエージェントに「{テーマ}について最新情報を5点に絞って調査してください」と依頼する
      2. 調査結果を受け取ったら、writerエージェントに「以下の調査結果を基に800字程度の解説記事を書いてください」と依頼する
      3. 完成した記事をユーザーに提示する

      常に日本語で回答し、各ステップの進捗をユーザーに簡潔に報告してください。
    sub_agents:
      - researcher
      - writer

  researcher:
    model: anthropic/claude-sonnet-4-5
    description: "Web検索専門のリサーチエージェント。最新情報の収集と要約が得意。"
    instruction: |
      あなたはWeb検索の専門家です。
      与えられたテーマについて、fetchツールを使って最新情報を収集し、
      重要なポイントを箇条書きで整理して報告してください。

      - 情報源のURLは必ず記録すること
      - 不確かな情報には「要確認」と明記すること
      - 回答は日本語でまとめること
    toolsets:
      - type: fetch
      - type: think

  writer:
    model: anthropic/claude-sonnet-4-5
    description: "技術解説記事を執筆するライティングエージェント。Markdown形式での出力が得意。"
    instruction: |
      あなたは技術ライターの専門家です。
      提供された調査情報を基に、読者にわかりやすい解説記事を執筆してください。

      記事の要件：
      - Markdown形式で出力すること
      - 見出し（##）・本文・コード例（必要な場合）の構成で書くこと
      - 専門用語は初出時に平易な言葉で補足すること
      - 完成した記事は output/article.md に保存すること
    toolsets:
      - type: filesystem
        paths:
          - "./output"
      - type: think

YAML構造のポイント解説

上記のYAMLで特に重要な部分を段階的に理解していきましょう。

sub_agentsフィールド

sub_agents:
  - researcher
  - writer

rootエージェントが呼び出せるサブエージェントをここで宣言します。列挙した名前がagentsキー配下に定義されていることを確認してください。この宣言があることで、rootはresearcherとwriterを「ツール」として認識し、適切なタイミングで自律的に委譲を行えるようになります。

ツールのスコープ限定

toolsets:
  - type: filesystem
    paths:
      - "./output"

pathsでアクセス可能なディレクトリを限定することが、セキュリティ上のベストプラクティスです。./outputのみを指定すれば、writerエージェントはそのディレクトリ以外のファイルを読み書きできません。最小権限の原則はエージェント設計においても同様に重要です。

thinkツールの活用

thinkツールセットは、エージェントが回答を生成する前に内部的な推論ステップを踏めるようにします。複雑な判断やフォーマットの整形が求められるエージェントに付与しておくことで、出力の一貫性が向上します。

実行と動作確認

事前に出力ディレクトリを作成してから実行します。

mkdir -p output
docker agent run pipeline.yaml

TUIが起動したら、以下のように入力してみてください。

「Dockerのマルチステージビルド」について調査して記事にしてください

正常に動作すると、rootエージェントがresearcherとwriterを順番に呼び出し、最終的にoutput/article.mdが生成されます。非対話型で実行する場合は--execフラグを使います。

docker agent run pipeline.yaml --exec "「Kubernetes入門」について調査して記事にしてください"

詳細なログを確認したい場合は--verboseフラグを付与します。各エージェントへのタスク委譲・ツール呼び出し・モデルへの入出力が逐次表示されるため、デバッグや動作確認に非常に有効です。

docker agent run pipeline.yaml --verbose

MCPツールによる拡張

Docker AgentはMCP（Model Context Protocol）をサポートしており、外部ツールをエージェントに組み込めます。mcp_serversフィールドにサーバーの起動コマンドと環境変数を記述するだけで、エージェントの能力を大幅に拡張できます。

たとえば、GitHub MCPサーバーを追加することでエージェントがリポジトリ操作を行えるようになります。

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: "GitHubと連携するコードレビューエージェント"
    instruction: |
      あなたはコードレビューの専門家です。
      指定されたGitHubリポジトリのPull Requestを確認し、
      改善提案をレビューコメントとして投稿してください。
    mcp_servers:
      - name: github
        command: ["npx", "-y", "@modelcontextprotocol/server-github"]
        env:
          GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

MCPのコンテナ隔離機能を活用すると、外部ツールをホスト環境から分離して実行できます。セキュリティ要件が厳しい社内環境への適用を検討している場合は、この機能を積極的に活用することをベストプラクティスとして推奨します。

まとめ：YAMLで始めるマルチエージェント開発

この記事では、Docker AgentのYAML設定を使ってマルチエージェントパイプラインを構築する方法を段階的に解説しました。要点を振り返りましょう。

学んだこと

Docker Agentの基礎：docker agent run agent.yamlの1コマンドで起動し、YAMLで宣言的にエージェントを定義できる
環境構築：Docker Desktop 4.63以降があればすぐに使え、APIキーは環境変数で安全に管理する
YAML設定リファレンス：model・instruction・description・toolsetsの各フィールドの意味と使い方
マルチエージェント設計：sub_agentsでエージェントを委譲し、Coordinator + Specialistパターンで役割を分担する
MCPによる拡張：mcp_serversフィールドで外部ツールをエージェントに統合し、能力を拡張する

次のステップ

Docker Agentの理解を深めるために、以下の発展的なテーマに挑戦してみてください。

Docker Hubへのエージェント公開：作成したエージェントをOCIイメージとしてプッシュし、チームと共有する
Docker Model Runnerの活用：ローカルLLM（Llama、Phi等）を使ってオフライン環境でエージェントを動かす
CIパイプラインへの組み込み：--execフラグを使ってGitHub ActionsやJenkinsとDocker Agentを連携させる
メモリとセッション管理：memoryツールセットを使って複数セッションをまたぐ状態を保持する

YAMLによる宣言的なエージェント定義は、インフラコードとしてのAI開発という新しいパラダイムを開きます。まずはこの記事のpipeline.yamlを手元で動かし、instructionやtoolsetsを少しずつ変えながら、自分のユースケースに合わせてカスタマイズしていきましょう。

Docker Agentの最新情報はDocker公式ドキュメントで随時更新されています。