Docker Compose for Agents

Docker Compose for Agents では、Docker Compose と同じ使い慣れた YAML 構文を使って、AI エージェントアーキテクチャを定義・デプロイ・管理できます。AI モデル、ツール、支援サービスを単一の設定ファイルで扱えます。本ガイドでは、SambaCloud 上でホストされる調整役のエージェントと、Compose がローカルで提供するオープンモデルを基盤とする 2 つ目のエージェントが連携して動作するサンプルスタックを実行します。

前提条件

作業を始める前に、以下の環境を準備してください。

有効な API キーを取得済みの SambaCloud アカウント
Docker Desktop 4.43.0 以降、または Docker Engine のインストール
すべてのプラットフォームで Docker Compose v2.38 以降。このサンプルはトップレベル要素の models を使用しており、古いバージョンの Compose では認識されません
オープンモデルをローカルで実行するための GPU 対応マシン (GPU がない場合は Docker Offload を利用できます)

作業を始める前に、Compose のバージョンを確認してください。

docker compose version

プラットフォーム別の要件

Linux (Docker Engine) または Windows (Docker Desktop) の場合: Docker Model Runner の要件を満たしていること。特に、GPU サポートが有効で必要なドライバがインストールされていることを確認してください
Linux (Docker Engine) の場合: Docker Compose バージョン 2.38.1 以降をインストールしてください

セットアップ

リポジトリのクローン

サンプルリポジトリをクローンし、プロジェクトディレクトリに移動します。

git clone https://github.com/sambanova/integrations.git
cd integrations/docker-compose-for-agents

これはデフォルトブランチをクローンするため、サンプルの内容は実行のたびに変わる可能性があります。エージェントイメージは依存関係を agents/requirements.txt で固定しており (google-adk==1.5.0 と litellm==1.73.6)、ローカルモデルも ai/qwen3:8B-Q4_0 タグに固定されているため、再ビルドしても同じスタックが再現されます。固定した開始点を保持したい場合は、クローンしたコミットを記録しておき、後でそこに戻れるようにします。

git rev-parse HEAD          # note this value
git checkout <commit>       # return to it after a later pull

何かを起動する前に、設定が正しくパースできることを確認します。

docker compose config --quiet

ファイルが有効であれば、終了コード 0 で何も出力されません。v2.38 より古い Compose では models 要素が認識されず、4.8 GB のダウンロードの途中ではなく、この時点で問題に気づくことができます。

環境変数の設定

プロジェクトディレクトリに、以下の内容で .env ファイルを作成します。

SAMBANOVA_API_KEY=your_api_key_here
SAMBANOVA_BASE_URL=https://api.sambanova.ai/v1
SAMBANOVA_CHAT_MODEL=gemma-4-31B-it

SAMBANOVA_BASE_URL は /v1 で終わる必要があります。エージェントは OpenAI 互換クライアント経由で SambaNova を呼び出すため、バージョン付きのパスが求められます。現在の SambaCloud モデルには両方のフローに対応できるものがないため、実行したいフローに合わせて SAMBANOVA_CHAT_MODEL を設定してください。

実行したいフロー	設定するモデル	理由
画像をアップロードして説明させる	`gemma-4-31B-it`	画像入力に対応する唯一の現行モデル
SambaNova エージェントから Developer エージェントへのハンドオフ	`Meta-Llama-3.3-70B-Instruct`	ハンドオフにはツール呼び出しが必要で、`gemma-4-31B-it` は非対応

モデルの全一覧と、gemma-4-31B-it に適用されるプレビューモデル (Preview) の指定については、SambaCloud モデルをご参照ください。

ワークフローの例におけるエージェントのハンドオフはツール呼び出しであるため、Function calling に記載のモデルでのみ動作します。gemma-4-31B-it はその対象外です。このモデルを設定した状態で Developer エージェントを呼び出すと、リクエストはルーティングされずに SambaNova エージェントが応答し、ハンドオフが行われなかったことを知らせるエラーも表示されません。

その他の設定オプションについては、リポジトリ内の .env.example ファイルをご参照ください。ただし、このファイルには現在、SambaCloud で提供終了となったモデルが設定されているため、そのままコピーせず、上の表の値を使用してください。

エージェントプロンプトの定義

すべてのエージェントプロンプトは compose.yml ファイルで定義されています。この設定ファイル内のプロンプトを変更することで、エージェントの動作・役割・機能をユースケースに合わせてカスタマイズできます。このファイルは 2 つの部分で構成されます。トップレベル要素の models は、Compose がローカルで提供するオープンモデルを宣言します。サービスレベルの models ブロックは、コンテナがそのモデルに到達できるよう、どの環境変数を注入するかを Compose に指示します。

services:
  main-agent:
    build:
      context: ./agents
      dockerfile: Dockerfile
    models:
      qwen3:
        endpoint_var: MODEL_RUNNER_URL
        model_var: MODEL_RUNNER_MODEL
    ports:
      - 8000:8000
    environment:
      PORT: 8000
      SAMBANOVA_BASE_URL: ${SAMBANOVA_BASE_URL}
      SAMBANOVA_CHAT_MODEL: ${SAMBANOVA_CHAT_MODEL}
      SAMBANOVA_API_KEY: ${SAMBANOVA_API_KEY}
      SAMBANOVA_AGENT_NAME: sambanova_agent
      SAMBANOVA_AGENT_INSTRUCTION: |
        You are SambaNova. ...
      DEVELOPER_AGENT_NAME: developer_agent
      DEVELOPER_AGENT_INSTRUCTION: |
        You are developer. ...

models:
  qwen3:
    model: ai/qwen3:8B-Q4_0

3 つの ${...} の値は、.env で設定したものです。MODEL_RUNNER_URL と MODEL_RUNNER_MODEL は Compose が models 要素から生成するため、自分で設定しないでください。

SambaCloud 上で動作するのは SambaNova エージェントのみです。Developer エージェントは、ローカルで提供される ai/qwen3:8B-Q4_0 モデル上で動作します。GPU と Docker Model Runner が前提条件に含まれるのはこのためです。

サービスの起動

Docker Compose スタックを起動します。

docker compose up

初回の実行では、エージェントの起動前に約 4.8 GB の ai/qwen3:8B-Q4_0 モデルをダウンロードします。10〜15 分ほど見込んでください。2 回目以降はキャッシュ済みのモデルを再利用するため、数秒で起動します。

コードや設定を更新した場合は、コンテナを再ビルドします。

docker compose up --build

アプリケーションには http://localhost:8000 からアクセスできます。スタックが起動したことを確認するには、実行中のサービスを一覧表示します。

docker compose ps

main-agent サービスが、STATUS に Up、PORTS に 0.0.0.0:8000->8000/tcp と表示されるはずです。ヘッダー行しか表示されない場合は、何も実行されていません。

NAME      IMAGE     COMMAND   SERVICE   CREATED   STATUS    PORTS

これは、スタックが起動に失敗したのではなく起動中に終了したことを意味するため、原因はログに残っています。docker compose logs を確認し、トラブルシューティングをご参照ください。

利用方法

エージェントには、Web インターフェースと API エンドポイントの両方からアクセスできます。

ワークフローの例

リアルタイムに応答を受け取るために Token Streaming を有効にした上で、以下の手順を実行します。

このワークフローは 2 つのモデル能力にまたがります。ステップ 1 には画像入力が、ステップ 3 にはツール呼び出しが必要です。ステップ 1 と 2 は SAMBANOVA_CHAT_MODEL=gemma-4-31B-it で実行し、その後 Meta-Llama-3.3-70B-Instruct などのツール呼び出し対応モデルに切り替えてスタックを再起動し、ステップ 3 を実行してください。コンテナは起動時に環境変数を読み込むため、.env を変更した場合は docker compose down に続けて docker compose up を実行する必要があります。

画像のアップロード

アプリケーションのアーキテクチャ図、システム設計図、ワークフローの可視化画像などを、Web インターフェースからアップロードします。

SambaNova エージェントとの対話

SambaNova エージェントに、アップロードした内容の分析と説明を依頼します。

Sambanova, describe this app
Explain the info and the stack required to develop this app

プロンプト例の日本語訳

Sambanova、このアプリについて説明してください / このアプリの開発に必要な情報と技術スタックを説明してください

このエージェントからの応答は SAMBANOVA_AGENT SPEAKING: で始まります。これは compose.yml 内のプロンプトで設定されているもので、どのエージェントが応答したかを手早く確認する手段になります。

コード生成の依頼

Developer エージェントを使って、分析結果に基づいたコードを生成します。

Developer, can you create code from this description using Python?

プロンプト例の日本語訳

Developer、この説明をもとに Python でコードを作成してもらえますか？

このステップはハンドオフであるため、ツール呼び出しに対応したモデルが必要です。Developer エージェントは SambaCloud ではなくローカルの ai/qwen3:8B-Q4_0 モデル上で動作するため、そのエージェントから応答が返ってくれば、ハンドオフは成功しています。代わりに SambaNova エージェントが応答した場合、ハンドオフは行われていません。トラブルシューティングをご参照ください。

マルチエージェントコラボレーション

この Docker Compose 構成では、複数の専門エージェントが連携して動作します。

SambaNova Agent: 画像やドキュメントを分析し、アーキテクチャに関する知見を提供します
Developer Agent: 仕様や要件に基づいてコードを生成します
カスタムエージェント: 固有の役割と機能を持つ独自のエージェントを定義できます

アーキテクチャ

Docker Compose for Agents では、以下を定義できます。

AI モデル: 通常の推論や reasoning を担う SambaNova モデル
エージェントサービス: それぞれ固有の役割とプロンプトを持つ専門エージェント
支援サービス: データベース、メッセージキュー、ストレージなどのインフラストラクチャ
ツール連携: エージェントと外部 API・データベース・サービスとの接続

すべてのコンポーネントは単一の compose.yml ファイルでオーケストレーションされるため、以下が容易になります。

エージェントアーキテクチャ全体のバージョン管理
サービスごとの独立したスケーリング
環境をまたいだ一貫性のあるデプロイ
チーム内での構成の共有

主なメリット

Docker Compose for Agents と SambaNova を組み合わせることで、コンテナ化のベストプラクティスと高性能な AI 推論を両立し、以下を実現できます。

使い慣れたワークフロー: すでに知っている Docker Compose の構文をそのまま利用できます
デプロイの簡素化: 複雑なマルチエージェントシステムを単一の YAML ファイルで定義できます
ローカル開発: ローカルマシンで素早くテストと反復を行えます
本番対応: 同じ構成のまま本番環境にデプロイできます
柔軟なアーキテクチャ: エージェントやサービスの追加・削除・変更が容易です
高性能な推論: SambaNova の最適化されたモデルにより高速な応答を実現します

トラブルシューティング

SambaNova エージェントで認証エラーが発生する

Compose は値をプロジェクトディレクトリの .env ファイルから読み込むため、そこで SAMBANOVA_API_KEY が設定されていることを確認してください。
空の値は、未設定と同じではありません。Compose は未設定の変数を空文字列に置き換えてそのまま起動するため、エージェントは認証情報なしで立ち上がり、起動時ではなく最初のリクエストで失敗します。
SambaCloud ポータルでキーを再生成してください。
コンテナは起動時に環境変数を読み込むため、.env を編集した後は docker compose down に続けて docker compose up を実行して変更を適用してください。

エラーに OPENAI_API_KEY や api.openai.com が含まれる

これは SambaNova のキーではなく、Developer エージェントに起因します。このエージェントは、openai プレフィックス付きのクライアントを通じてローカルで提供されるモデルと通信します。その接続先アドレスは、Compose が models 要素から生成する MODEL_RUNNER_URL から取得されます。
このアドレスが空の場合、クライアントは OpenAI の公開エンドポイントにフォールバックし、OpenAI 由来のエラーが発生します。これは Docker Model Runner がモデルを提供できていないことを示すシグナルとして扱ってください。
v2.38 より古いバージョンは models 要素を無視して変数を注入しないため、Compose のバージョンが v2.38 以降であることを確認してください。
Docker Model Runner が GPU サポート付きで有効になっていることを確認してください。

初回の実行がハングしているように見える

初回の docker compose up は、エージェントの起動前に約 4.8 GB の ai/qwen3:8B-Q4_0 モデルをダウンロードします。10〜15 分ほど見込んでください。
docker compose logs -f で進行状況を確認できます。

GPU または Docker Model Runner のエラー

このスタックはオープンモデルをローカルで実行するため、GPU サポートが有効な Docker Model Runner が必要です。
Linux (Docker Engine) または Windows (Docker Desktop) では、Model Runner の要件を満たし、必要なドライバがインストールされていることを確認してください。
GPU がない場合は、代わりに Docker Offload を使用してください。

ポート 8000 がすでに使用されている

docker compose ps を実行して以前の実行が残っていないか確認し、残っている場合は docker compose down で停止してください。
それ以外の場合は、compose.yml の ports マッピングでホスト側のポートを変更してください。

モデルが見つからない

SAMBANOVA_CHAT_MODEL には、SambaCloud で提供中のモデル ID を設定してください。最新の一覧は SambaCloud モデルをご参照ください。.env.example から値をコピーした場合、それは提供終了したモデルを指しています。
画像を使うステップでは gemma-4-31B-it を使用してください。他の現行モデルはテキストのみに対応しており、画像を添付した時点で失敗するため、それらに切り替えても、このエラーがよりわかりにくいエラーに置き換わるだけです。
sambanova/ プレフィックスを付けず、モデル ID のみを指定してください。エージェント自身がプロバイダープレフィックスを追加するため、プレフィックス付きの値は sambanova/sambanova/... に解決されて失敗します。

Developer エージェントに切り替わらない

Developer エージェントの呼び出しはハンドオフであり、調整役のエージェントがツール呼び出しで実行します。SAMBANOVA_CHAT_MODEL にツール呼び出し非対応のモデルを指定すると、この呼び出しは破棄され、SambaNova エージェント自身がリクエストに応答します。ログにもエラーは記録されません。
gemma-4-31B-it はツール呼び出しに対応していません。SAMBANOVA_CHAT_MODEL に Function calling に記載のモデル (例: Meta-Llama-3.3-70B-Instruct) を設定し、docker compose down に続けて docker compose up を実行してください。
このモデルはテキストのみに対応しているため、画像のアップロードではなくテキストの説明でハンドオフを試してください。

The SAMBANOVA_API_KEY variable is not set という警告が表示される

警告の全文は warning msg="The \"SAMBANOVA_API_KEY\" variable is not set. Defaulting to a blank string." で、Compose は未設定の変数ごとに 1 行ずつ出力します。各変数を空文字列にデフォルト設定して続行するため、エージェントは即座に失敗するのではなく、認証情報なしで起動します。
.env ファイルは、docker compose up を実行するディレクトリ、つまり integrations/docker-compose-for-agents に置く必要があります。Compose は親ディレクトリを検索しません。
.env は通常の ls では表示されないため、ls -a でファイルの存在を確認してください。

参考情報

Docker Compose によるエージェント型 AI アプリケーション構築の包括的なガイドについては、Docker Compose for Agents の公式ドキュメントをご参照ください。

概要

開発者ツール

フレームワーク

インターフェースとローコード

データとインフラ

マルチモーダル

評価とモニタリング

前提条件

プラットフォーム別の要件

セットアップ

利用方法

ワークフローの例

マルチエージェントコラボレーション

アーキテクチャ

主なメリット

トラブルシューティング

参考情報

​前提条件

​プラットフォーム別の要件

​セットアップ

​利用方法

​ワークフローの例

​マルチエージェントコラボレーション

​アーキテクチャ

​主なメリット

​トラブルシューティング

​参考情報

前提条件

プラットフォーム別の要件

セットアップ

利用方法

ワークフローの例

マルチエージェントコラボレーション

アーキテクチャ

主なメリット

トラブルシューティング

参考情報