😎

Docker cagent：次世代マルチエージェントAIシステムの完全ガイド

2025/09/23に公開

Docker cagent：次世代マルチエージェントAIシステムの完全ガイド

はじめに

AI開発の世界は急速に進化し、単一のAIモデルでは対応しきれない複雑なタスクが増加しています。そんな中、Dockerが開発したcagentは、複数のAIエージェントを協調させて複雑な問題を解決する革新的なツールとして注目を集めています。

本記事では、cagentの基本概念から実際の活用事例まで、開発者が知っておくべき全てを詳しく解説します。

cagentとは何か？

cagent（Container Agent）は、Dockerが開発したマルチエージェントAIシステムの構築・実行プラットフォームです。特化された知識やツールを持つ複数のAIエージェントを連携させ、複雑なタスクを効率的に解決することができます。

核心的な特徴

🏗️ マルチエージェント・アーキテクチャ

異なる専門分野に特化したエージェントを作成
ルートエージェントが他のエージェントにタスクを委譲
各エージェントは独立したコンテキストで動作

📝 宣言的YAML設定

複雑なコードを書かずにエージェントを定義
設定ファイル一つでエージェントの動作を完全に記述
バージョン管理や共有が容易

🔧 豊富なツールエコシステム

Model Context Protocol（MCP）を通じた外部ツール統合
ファイルシステム、シェルコマンド、Web検索など多様なツール
コンテナ化されたツールによる一貫した実行環境

🌐 マルチプロバイダ対応

OpenAI、Anthropic、Google Gemini/Vertex AI、ローカルモデルをサポート
Docker Model Runner（DMR）によるローカルLLM実行
プロバイダ間でのシームレスな切り替え
Google CloudのVertex AIとの直接統合により、エンタープライズレベルのAI機能を活用可能

MCP（Model Context Protocol）の重要性

cagentの真価を理解するには、MCPの概念が不可欠です。MCPは、AIエージェントと外部ツールやサービスを接続するための標準化されたプロトコルです。

MCPが解決する問題

従来のAI統合では、各データソースやAPIに対して個別のコネクタが必要でした。MCPはこの分断された環境を統一し、以下を実現します：

標準化されたインターフェース：一つのプロトコルで多様なツールに接続
セキュリティの向上：認証情報の安全な管理と伝達
開発効率の向上：再利用可能なコンポーネントによる迅速な開発

Dockerとの統合

DockerのMCP Catalog and Toolkitにより、以下が可能になります：

toolsets:
  - type: mcp
    command: docker
    args: ["mcp", "gateway", "run", "--servers=github,slack,postgres"]

この設定だけで、エージェントがGitHub、Slack、PostgreSQLに同時にアクセスできるようになります。

インストールと初期設定

バイナリのダウンロードとインストール

最新のバイナリはGitHubリリースページからダウンロードできます：

# Linux AMD64の場合
wget https://github.com/docker/cagent/releases/download/v0.x.x/cagent-linux-amd64
chmod +x cagent-linux-amd64
sudo mv cagent-linux-amd64 /usr/local/bin/cagent

# macOS Intel/Apple Siliconの場合
wget https://github.com/docker/cagent/releases/download/v0.x.x/cagent-darwin-amd64
chmod +x cagent-darwin-amd64
sudo mv cagent-darwin-amd64 /usr/local/bin/cagent

環境変数の設定

使用するAIプロバイダに応じて、APIキーを設定します：

# OpenAI
export OPENAI_API_KEY="your_api_key_here"

# Anthropic
export ANTHROPIC_API_KEY="your_api_key_here"  

# Google Gemini / Vertex AI
export GOOGLE_API_KEY="your_api_key_here"

# Vertex AI（Google Cloud統合）
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
# または
export GOOGLE_CLOUD_ACCESS_TOKEN="$(gcloud auth print-access-token)"

# Azure OpenAI（カスタム設定の場合）
export AZURE_OPENAI_API_KEY="your_api_key_here"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"

Vertex AI使用時の推奨設定：

Google Cloudプロジェクトでの認証が必要な場合：

# Google Cloud CLIで認証
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID

# アクセストークンを取得（一時的）
export GOOGLE_CLOUD_ACCESS_TOKEN=$(gcloud auth print-access-token)

より簡単にGemini APIを使用する場合：

# Google AI Studioでキーを取得：https://aistudio.google.com/apikey
export GOOGLE_API_KEY="your_gemini_api_key"

基本的な使い方

シンプルなエージェントの作成

まずは基本的なアシスタントエージェントを作成してみましょう：

# basic_agent.yaml
agents:
  root:
    model: openai/gpt-4o
    description: "役立つAIアシスタント"
    instruction: |
      あなたは様々なタスクでユーザーを支援する知識豊富なアシスタントです。
      役立ち、正確で、簡潔な回答を提供してください。

実行コマンド：

cagent run basic_agent.yaml

ツールを統合したエージェント

Web検索とファイル操作ができるエージェントを作成：

# enhanced_agent.yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: "Web検索とファイル操作ができるアシスタント"
    instruction: |
      あなたは以下の機能を持つ高度なアシスタントです：
      1. Web検索による最新情報の取得
      2. ファイルの読み書き
      3. 検索結果のファイル保存
      
      タスクに応じて適切なツールを使い分けてください。
    toolsets:
      - type: mcp
        command: docker
        args: ["mcp", "gateway", "run", "--servers=duckduckgo"]
      - type: mcp
        command: rust-mcp-filesystem
        args: ["--allow-write", "."]
        tools: ["read_file", "write_file"]
        env:
          - "RUST_LOG=debug"

Vertex AIを活用した高度なエージェント

Google Cloudサービスとの統合を前提としたエージェント：

# vertex_ai_agent.yaml
agents:
  root:
    model: vertex-gemini-flash
    description: "Vertex AI搭載のクラウド統合エージェント"
    instruction: |
      あなたはGoogle CloudのVertex AIを活用する高度なAIエージェントです。
      以下の特徴を持ちます：
      
      - 高度な推論能力による複雑な問題解決
      - Google Cloudサービスとの自然な連携
      - エンタープライズレベルのセキュリティと可用性
      - 大規模データ処理への対応
      
      ユーザーの要求を理解し、最適なソリューションを提供してください。
    toolsets:
      - type: mcp
        command: docker
        args: ["mcp", "gateway", "run", "--servers=gcp,bigquery"]
      - type: think
      - type: memory

models:
  vertex-gemini-flash:
    provider: openai
    model: "gemini-2.0-flash"
    base_url: "https://generativelanguage.googleapis.com/v1beta/openai/"
    token_key: "GOOGLE_API_KEY"
    max_tokens: 8000
    temperature: 0.3

実行例：

# Vertex AIエージェントの実行
export GOOGLE_API_KEY="your_gemini_api_key"
cagent run vertex_ai_agent.yaml

実践的な活用事例

1. GitHubイシュー管理エージェント

開発チームのイシュー管理を自動化するエージェントの例：

# github_todo_agent.yaml
#!/usr/bin/env cagent run
version: "2"

agents:
  root:
    model: openai/gpt-4o
    description: "GitHubイシュー管理専門エージェント"
    instruction: |
      あなたはGitHubイシューの管理を専門とするエージェントです。
      以下の操作が可能です：
      
      - 新しいイシューの作成
      - 既存イシューの一覧表示
      - イシューの詳細確認
      - イシューのクローズ
      - ラベルの管理
      - マイルストーンの設定
      
      ユーザーの要求に応じて適切な操作を実行してください。
    toolsets:
      - type: mcp
        command: docker
        args: ["mcp", "gateway", "run", "--servers=github"]

models:
  openai/gpt-4o:
    provider: openai
    model: gpt-4o
    max_tokens: 4000

使用例:

# エージェントを実行
cagent run github_todo_agent.yaml

# 対話例
User: "新しいバグレポートのイシューを作成して"
Agent: GitHubAPIを使用してイシューを作成し、issue番号と詳細を報告

User: "オープン中のイシューを全て表示して"
Agent: 現在のオープンイシューを整理して表示

2. 技術ブログ執筆チーム

複数エージェントが協力してブログ記事を作成するシステム：

# blog_team.yaml
#!/usr/bin/env cagent run
version: "2"

agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: "技術ブログ執筆チームのリーダー"
    instruction: |
      あなたは技術ブログ執筆ワークフローのチームリーダーです。
      
      チームメンバー：
      - research_agent: Web調査専門
      - writer_agent: 記事執筆専門
      - reviewer_agent: 記事レビュー専門
      
      ワークフロー：
      1. トピックに関する情報収集をresearch_agentに依頼
      2. 収集した情報を基にwriter_agentが記事作成
      3. reviewer_agentが記事を品質チェック
      4. 必要に応じて修正指示
    sub_agents: ["research_agent", "writer_agent", "reviewer_agent"]
    toolsets:
      - type: think

  research_agent:
    model: openai/gpt-4o
    description: "技術調査専門エージェント"
    instruction: |
      あなたは技術的なトピックの調査を専門とします。
      最新の情報、技術トレンド、実例を収集し、
      信頼性の高い情報源を特定してください。
    toolsets:
      - type: mcp
        command: docker
        args: ["mcp", "gateway", "run", "--servers=duckduckgo"]

  writer_agent:
    model: anthropic/claude-sonnet-4-0
    description: "技術記事執筆専門エージェント"
    instruction: |
      収集された情報を基に、750-1000語の技術記事を執筆します。
      - 明確な構造（導入、本文、結論）
      - 実践的なコード例の含有
      - 技術用語の適切な説明
      - 読者にとって価値のある内容
    toolsets:
      - type: filesystem
      - type: think

  reviewer_agent:
    model: openai/gpt-4o
    description: "記事品質チェック専門エージェント"
    instruction: |
      技術記事の品質をチェックし、以下を評価します：
      - 技術的正確性
      - 文章の明確性
      - 構造の論理性
      - コード例の動作確認
      - SEOの観点
      
      改善点があれば具体的な修正提案を行います。
    toolsets:
      - type: filesystem

models:
  openai/gpt-4o:
    provider: openai
    model: gpt-4o
    max_tokens: 4000
  
  anthropic/claude-sonnet-4-0:
    provider: anthropic
    model: claude-sonnet-4-0
    max_tokens: 8000

3. DevOpsオートメーション・エージェント

システム監視とトラブルシューティングを行うエージェント：

# devops_agent.yaml
#!/usr/bin/env cagent run
version: "2"

agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: "DevOps自動化エージェント"
    instruction: |
      あなたはDevOpsタスクの自動化を専門とします。
      
      主な機能：
      - システム監視とヘルスチェック
      - ログ分析とエラー検出
      - 自動デプロイメント
      - インフラストラクチャの状態確認
      - トラブルシューティング
      
      問題を検出した場合は即座に報告し、
      可能な範囲で自動修復を試みます。
    toolsets:
      - type: shell
      - type: filesystem
      - type: mcp
        command: docker
        args: ["mcp", "gateway", "run", "--servers=docker,kubernetes"]
      - type: todo
      - type: memory

models:
  anthropic/claude-sonnet-4-0:
    provider: anthropic
    model: claude-sonnet-4-0
    max_tokens: 8000

4. Google Cloud統合エージェント（Vertex AI活用）

Vertex AIのOpenAI互換エンドポイントを使用したクラウドリソース管理エージェント：

# gcp_vertex_agent.yaml
#!/usr/bin/env cagent run
version: "2"

agents:
  root:
    model: vertex-gemini
    description: "Google Cloud Platform統合管理エージェント"
    instruction: |
      あなたはGoogle Cloud Platformのリソース管理を専門とするAIエージェントです。
      Vertex AIの高度な推論能力を活用して以下を実行します：
      
      - GCPプロジェクトの状態監視
      - BigQueryでのデータ分析
      - Cloud Storageのファイル管理
      - Compute Engineインスタンスの管理
      - コスト最適化の提案
      - セキュリティ監査レポート作成
      
      問題の検出時は詳細な分析を行い、根本原因を特定します。
    sub_agents: ["bigquery_agent", "storage_agent"]
    toolsets:
      - type: mcp
        command: docker
        args: ["mcp", "gateway", "run", "--servers=gcp,bigquery"]
      - type: shell
      - type: think

  bigquery_agent:
    model: vertex-gemini
    description: "BigQueryデータ分析専門エージェント"
    instruction: |
      BigQueryを使用したデータ分析を専門とします。
      - SQLクエリの生成と最適化
      - データの可視化
      - 異常値検出
      - レポート自動生成
    toolsets:
      - type: mcp
        command: docker
        args: ["mcp", "gateway", "run", "--servers=bigquery"]

  storage_agent:
    model: vertex-gemini
    description: "Cloud Storage管理専門エージェント"
    instruction: |
      Google Cloud Storageの管理を専門とします。
      - ファイルのアップロード・ダウンロード
      - バケット設定の最適化
      - ライフサイクル管理
      - アクセス権限の監査
    toolsets:
      - type: mcp
        command: docker
        args: ["mcp", "gateway", "run", "--servers=gcp"]

models:
  vertex-gemini:
    provider: openai
    model: "google/gemini-2.0-flash-001"
    base_url: "https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/openapi"
    token_key: "GOOGLE_CLOUD_ACCESS_TOKEN"
    max_tokens: 8000
    temperature: 0.2

使用例：

# Google Cloud認証
gcloud auth application-default login
export GOOGLE_CLOUD_ACCESS_TOKEN=$(gcloud auth print-access-token)

# プロジェクトIDを設定
export YOUR_PROJECT_ID="your-gcp-project-id"

# エージェント実行
cagent run gcp_vertex_agent.yaml

# 対話例
User: "BigQueryでユーザー行動データを分析して、異常なパターンを検出して"
Agent: BigQuery専門エージェントがSQLクエリを生成し、データを分析、異常値を特定してレポート作成

User: "今月のGCPコストが予算を超えそう。最適化案を提案して"
Agent: 各サービスのコスト分析を実行し、具体的な削減案を提示

エージェントの配布と共有

Docker Hubへのプッシュ

作成したエージェントはDocker Hubで共有できます：

# エージェントをOCIアーティファクトとしてプッシュ
cagent push ./my_agent.yaml myusername/my-agent

# 他のユーザーがプルして使用
cagent pull myusername/my-agent
cagent run my-agent.yaml

実際の配布例

Docker Hubで公開されている実用的なエージェント：

# 海賊風アシスタント
cagent run creek/pirate

# GitHubタスク管理エージェント  
cagent run docker.io/olegselajev241/github-todo:latest

# 技術文書作成エージェント
cagent run docker.io/examples/tech-writer:latest

新しいエージェントの生成

cagentには組み込みのエージェント生成機能があります：

# インタラクティブなエージェント生成
cagent new

# 特定のモデルを指定
cagent new --model anthropic/claude-sonnet-4-0

# ローカルモデルを使用
cagent new --model dmr/ollama/llama3:8b

実行例：

------- Welcome to cagent! -------
(Ctrl+C to stop the agent or exit)

What should your agent/agent team do? (describe its purpose):
> Kubernetes クラスターの監視とログ分析を行うエージェントチームを作成

[AI が自動的に適切な設定ファイルを生成]

高度な機能

カスタムモデル設定

Azure OpenAI、Vertex AI、その他のプロバイダーを使用する場合：

models:
  # Azure OpenAI
  custom-gpt4:
    provider: openai
    model: gpt-4
    base_url: "https://your-resource.openai.azure.com/"
    azure_api_version: "2024-02-15-preview" 
    token_key: "AZURE_OPENAI_API_KEY"
    max_tokens: 4000
    temperature: 0.1

  # Vertex AI (OpenAI互換エンドポイント)
  vertex-gemini:
    provider: openai
    model: "google/gemini-2.0-flash-001"
    base_url: "https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/endpoints/openapi"
    token_key: "GOOGLE_CLOUD_ACCESS_TOKEN"
    max_tokens: 8000
    temperature: 0.2

  # Gemini API (OpenAI互換エンドポイント) - より簡単な方法
  gemini-direct:
    provider: openai
    model: "gemini-2.0-flash"
    base_url: "https://generativelanguage.googleapis.com/v1beta/openai/"
    token_key: "GOOGLE_API_KEY"
    max_tokens: 8000
    temperature: 0.3

  # ローカルモデル
  local-llama:
    provider: dmr
    model: "ollama/llama3:70b"
    max_tokens: 8000
    temperature: 0.7

Vertex AI用の環境変数設定

# 方法1: Vertex AI (Google Cloud認証が必要)
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
export GOOGLE_CLOUD_ACCESS_TOKEN=$(gcloud auth print-access-token)

# 方法2: Gemini API (より簡単)
export GOOGLE_API_KEY="your_gemini_api_key_here"

メモリとコンテキスト管理

長期的なタスクで状態を維持：

agents:
  persistent_agent:
    model: anthropic/claude-sonnet-4-0
    description: "長期プロジェクト管理エージェント"
    instruction: |
      プロジェクトの進行状況を記録し、
      前回の作業内容を踏まえて継続的に作業します。
    toolsets:
      - type: memory  # 長期記憶機能
      - type: todo    # タスク管理
      - type: filesystem

条件分岐とエラーハンドリング

agents:
  robust_agent:
    model: openai/gpt-4o
    description: "堅牢なエラーハンドリングを持つエージェント"
    instruction: |
      タスク実行時には以下を遵守：
      1. 操作前に前提条件を確認
      2. エラーが発生した場合は3回まで再試行
      3. 失敗した場合は詳細なエラーレポートを作成
      4. 代替手段があれば提案
    toolsets:
      - type: shell
      - type: filesystem
      - type: think

トラブルシューティング

一般的な問題と解決方法

1. APIキーの認証エラー

# 環境変数が正しく設定されているか確認
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY
echo $GOOGLE_API_KEY

# キーが正しく読み込まれているか確認
cagent run --verbose your-agent.yaml

2. MCP接続エラー

# Docker MCP Gatewayの状態確認
docker ps | grep mcp-gateway

# MCPサーバーの手動テスト
docker run -i --rm mcp/duckduckgo

3. Vertex AI / Google Cloud認証エラー

# Google Cloud CLIの認証状態確認
gcloud auth list
gcloud config get-value project

# 認証情報の再設定
gcloud auth application-default login
export GOOGLE_CLOUD_ACCESS_TOKEN=$(gcloud auth print-access-token)

# プロジェクト権限の確認
gcloud projects get-iam-policy YOUR_PROJECT_ID

4. Google API配額制限エラー

# 現在の使用量確認
gcloud logging read "resource.type=api" --limit=10 --format="table(timestamp,severity,jsonPayload.request)"

# 配額制限の確認
gcloud services list --enabled | grep generativelanguage

5. メモリ不足エラー

models:
  efficient-model:
    provider: openai
    model: gpt-4o-mini  # より軽量なモデルを使用
    max_tokens: 2000    # トークン数を制限
    
  # Vertex AI軽量版
  vertex-efficient:
    provider: openai
    model: "gemini-2.0-flash"  # Flash版は高速・軽量
    base_url: "https://generativelanguage.googleapis.com/v1beta/openai/"
    token_key: "GOOGLE_API_KEY"
    max_tokens: 4000
    temperature: 0.1

デバッグ方法

# 詳細ログを有効化
cagent run --verbose --debug your-agent.yaml

# 特定のエージェントから開始
cagent run your-agent.yaml -a specific_agent

# ドライランモード（実際の操作を行わず設定をテスト）
cagent run --dry-run your-agent.yaml

パフォーマンス最適化

モデル選択の指針

タスクの複雑さ別推奨モデル：

シンプルなタスク: gpt-4o-mini, claude-haiku, gemini-2.0-flash
標準的なタスク: gpt-4o, claude-sonnet-4-0, google/gemini-2.0-flash-001 (Vertex AI)
複雑なタスク: gpt-4o, claude-opus-4, google/gemini-2.5-flash-preview-04-17 (Vertex AI)
ローカル実行: ollama/llama3:8b, ollama/mistral:7b
Google Cloud統合: Vertex AI Geminiモデル（GCPサービスとの連携に最適）

リソース使用量の最適化

# 同時実行エージェント数の制限
agents:
  root:
    model: openai/gpt-4o
    max_concurrent_agents: 2  # 同時実行を制限
    toolsets:
      - type: rate_limit
        requests_per_minute: 60  # API呼び出し制限

セキュリティのベストプラクティス

機密情報の管理

# 環境変数ファイルを使用
echo "OPENAI_API_KEY=your_key_here" > .env
echo "DATABASE_URL=your_db_url" >> .env

# cagent実行時に読み込み
cagent run --env-file .env your-agent.yaml

権限の最小化

agents:
  limited_agent:
    model: openai/gpt-4o
    description: "制限された権限のエージェント"
    toolsets:
      - type: filesystem
        read_only: true          # 読み取り専用
        allowed_paths: ["/tmp"]  # 特定ディレクトリのみ
      - type: shell
        allowed_commands: ["ls", "cat", "grep"]  # 許可コマンドのみ

まとめ

Docker cagentは、マルチエージェントAIシステムの構築を劇的に簡素化する革新的なツールです。YAML設定による宣言的なエージェント定義、MCP統合による豊富なツールエコシステム、Docker Hubでの簡単な配布機能により、個人開発者から企業まで幅広く活用できます。

cagentを選ぶべき理由:

開発効率: 複雑なコードなしでエージェントを作成
拡張性: MCPを通じた無限のツール統合可能性
移植性: Dockerベースの一貫した実行環境
プロバイダー対応: OpenAI、Anthropic、Google Gemini、Vertex AIなど主要プロバイダーをサポート
コミュニティ: 活発な開発とサポート体制

AIエージェントシステムの構築を検討している開発者にとって、cagentは現時点で最も実用的で将来性のある選択肢の一つです。特に、Vertex AIとの統合により、Google Cloudエコシステムを活用した高度なエージェントシステムも構築可能になりました。オープンソースプロジェクトとして継続的に進化するcagentの動向に、今後も注目していく価値があるでしょう。

参考リンク:

執筆日: 2025年9月23日
バージョン: cagent v0.2.x対応

Docker cagent：次世代マルチエージェントAIシステムの完全ガイド

はじめに

cagentとは何か？

核心的な特徴

MCP（Model Context Protocol）の重要性

MCPが解決する問題

Dockerとの統合

インストールと初期設定

バイナリのダウンロードとインストール

環境変数の設定

基本的な使い方

シンプルなエージェントの作成

ツールを統合したエージェント

Vertex AIを活用した高度なエージェント

実践的な活用事例

1. GitHubイシュー管理エージェント

2. 技術ブログ執筆チーム

3. DevOpsオートメーション・エージェント

4. Google Cloud統合エージェント（Vertex AI活用）

エージェントの配布と共有

Docker Hubへのプッシュ

実際の配布例

新しいエージェントの生成

高度な機能

カスタムモデル設定

Vertex AI用の環境変数設定

メモリとコンテキスト管理

条件分岐とエラーハンドリング

トラブルシューティング

一般的な問題と解決方法

デバッグ方法

パフォーマンス最適化

モデル選択の指針

リソース使用量の最適化

セキュリティのベストプラクティス

機密情報の管理

権限の最小化

まとめ

Discussion