> ## Documentation Index > Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Docker Compose for Agents Docker Compose for Agents では、Docker Compose と同じ使い慣れた YAML 構文を使って、AI エージェントアーキテクチャを定義・デプロイ・管理できます。AI モデル、ツール、支援サービスを単一の設定ファイルで扱えます。 本ガイドでは、SambaCloud 上でホストされる調整役のエージェントと、Compose がローカルで提供するオープンモデルを基盤とする 2 つ目のエージェントが連携して動作するサンプルスタックを実行します。 ## 前提条件 作業を始める前に、以下の環境を準備してください。 * 有効な API キーを取得済みの [SambaCloud](https://cloud.sambanova.ai/?utm_source=docker\&utm_medium=external\&utm_campaign=cloud_signup) アカウント * [Docker Desktop](https://www.docker.com/products/docker-desktop/) 4.43.0 以降、または [Docker Engine](https://docs.docker.com/engine/) のインストール * すべてのプラットフォームで [Docker Compose](https://github.com/docker/compose) v2.38 以降。このサンプルはトップレベル要素の `models` を使用しており、古いバージョンの Compose では認識されません * オープンモデルをローカルで実行するための GPU 対応マシン (GPU がない場合は [Docker Offload](https://www.docker.com/products/docker-offload/) を利用できます) 作業を始める前に、Compose のバージョンを確認してください。 ```bash theme={} docker compose version ``` ### プラットフォーム別の要件 * **Linux (Docker Engine) または Windows (Docker Desktop) の場合:** [Docker Model Runner の要件](https://docs.docker.com/ai/model-runner/)を満たしていること。特に、GPU サポートが有効で必要なドライバがインストールされていることを確認してください * **Linux (Docker Engine) の場合:** [Docker Compose](https://github.com/docker/compose) バージョン 2.38.1 以降をインストールしてください ## セットアップ サンプルリポジトリをクローンし、プロジェクトディレクトリに移動します。 ```bash theme={} 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` タグに固定されているため、再ビルドしても同じスタックが再現されます。 固定した開始点を保持したい場合は、クローンしたコミットを記録しておき、後でそこに戻れるようにします。 ```bash theme={} git rev-parse HEAD # note this value git checkout # return to it after a later pull ``` 何かを起動する前に、設定が正しくパースできることを確認します。 ```bash theme={} docker compose config --quiet ``` ファイルが有効であれば、終了コード `0` で何も出力されません。v2.38 より古い Compose では `models` 要素が認識されず、4.8 GB のダウンロードの途中ではなく、この時点で問題に気づくことができます。 プロジェクトディレクトリに、以下の内容で `.env` ファイルを作成します。 ```bash theme={} 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 モデル](/docs/ja/models/sambacloud-models)をご参照ください。 [ワークフローの例](#ワークフローの例)におけるエージェントのハンドオフはツール呼び出しであるため、[Function calling](/docs/ja/features/function-calling) に記載のモデルでのみ動作します。`gemma-4-31B-it` はその対象外です。このモデルを設定した状態で Developer エージェントを呼び出すと、リクエストはルーティングされずに SambaNova エージェントが応答し、ハンドオフが行われなかったことを知らせるエラーも表示されません。 その他の設定オプションについては、リポジトリ内の `.env.example` ファイルをご参照ください。ただし、このファイルには現在、SambaCloud で提供終了となったモデルが設定されているため、そのままコピーせず、上の表の値を使用してください。 すべてのエージェントプロンプトは `compose.yml` ファイルで定義されています。この設定ファイル内のプロンプトを変更することで、エージェントの動作・役割・機能をユースケースに合わせてカスタマイズできます。 このファイルは 2 つの部分で構成されます。トップレベル要素の `models` は、Compose がローカルで提供するオープンモデルを宣言します。サービスレベルの `models` ブロックは、コンテナがそのモデルに到達できるよう、どの環境変数を注入するかを Compose に指示します。 ```yaml theme={} 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 スタックを起動します。 ```bash theme={} docker compose up ``` 初回の実行では、エージェントの起動前に約 4.8 GB の `ai/qwen3:8B-Q4_0` モデルをダウンロードします。10〜15 分ほど見込んでください。2 回目以降はキャッシュ済みのモデルを再利用するため、数秒で起動します。 コードや設定を更新した場合は、コンテナを再ビルドします。 ```bash theme={} docker compose up --build ``` アプリケーションには [http://localhost:8000](http://localhost:8000) からアクセスできます。 スタックが起動したことを確認するには、実行中のサービスを一覧表示します。 ```bash theme={} docker compose ps ``` `main-agent` サービスが、`STATUS` に `Up`、`PORTS` に `0.0.0.0:8000->8000/tcp` と表示されるはずです。ヘッダー行しか表示されない場合は、何も実行されていません。 ```text theme={} 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 エージェントに、アップロードした内容の分析と説明を依頼します。 ```text theme={} Sambanova, describe this app Explain the info and the stack required to develop this app ``` Sambanova、このアプリについて説明してください / このアプリの開発に必要な情報と技術スタックを説明してください このエージェントからの応答は `SAMBANOVA_AGENT SPEAKING:` で始まります。これは `compose.yml` 内のプロンプトで設定されているもので、どのエージェントが応答したかを手早く確認する手段になります。 Developer エージェントを使って、分析結果に基づいたコードを生成します。 ```text theme={} 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 の最適化されたモデルにより高速な応答を実現します ## トラブルシューティング * Compose は値をプロジェクトディレクトリの `.env` ファイルから読み込むため、そこで `SAMBANOVA_API_KEY` が設定されていることを確認してください。 * 空の値は、未設定と同じではありません。Compose は未設定の変数を空文字列に置き換えてそのまま起動するため、エージェントは認証情報なしで立ち上がり、起動時ではなく最初のリクエストで失敗します。 * [SambaCloud ポータル](https://cloud.sambanova.ai/apis)でキーを再生成してください。 * コンテナは起動時に環境変数を読み込むため、`.env` を編集した後は `docker compose down` に続けて `docker compose up` を実行して変更を適用してください。 * これは SambaNova のキーではなく、Developer エージェントに起因します。このエージェントは、`openai` プレフィックス付きのクライアントを通じてローカルで提供されるモデルと通信します。その接続先アドレスは、Compose が `models` 要素から生成する `MODEL_RUNNER_URL` から取得されます。 * このアドレスが空の場合、クライアントは OpenAI の公開エンドポイントにフォールバックし、OpenAI 由来のエラーが発生します。これは Docker Model Runner がモデルを提供できていないことを示すシグナルとして扱ってください。 * v2.38 より古いバージョンは `models` 要素を無視して変数を注入しないため、Compose のバージョンが v2.38 以降であることを確認してください。 * [Docker Model Runner](https://docs.docker.com/ai/model-runner/) が GPU サポート付きで有効になっていることを確認してください。 * 初回の `docker compose up` は、エージェントの起動前に約 4.8 GB の `ai/qwen3:8B-Q4_0` モデルをダウンロードします。10〜15 分ほど見込んでください。 * `docker compose logs -f` で進行状況を確認できます。 * このスタックはオープンモデルをローカルで実行するため、GPU サポートが有効な [Docker Model Runner](https://docs.docker.com/ai/model-runner/) が必要です。 * Linux (Docker Engine) または Windows (Docker Desktop) では、Model Runner の要件を満たし、必要なドライバがインストールされていることを確認してください。 * GPU がない場合は、代わりに [Docker Offload](https://www.docker.com/products/docker-offload/) を使用してください。 * `docker compose ps` を実行して以前の実行が残っていないか確認し、残っている場合は `docker compose down` で停止してください。 * それ以外の場合は、`compose.yml` の `ports` マッピングでホスト側のポートを変更してください。 * `SAMBANOVA_CHAT_MODEL` には、SambaCloud で提供中のモデル ID を設定してください。最新の一覧は [SambaCloud モデル](/docs/ja/models/sambacloud-models)をご参照ください。`.env.example` から値をコピーした場合、それは提供終了したモデルを指しています。 * 画像を使うステップでは `gemma-4-31B-it` を使用してください。他の現行モデルはテキストのみに対応しており、画像を添付した時点で失敗するため、それらに切り替えても、このエラーがよりわかりにくいエラーに置き換わるだけです。 * `sambanova/` プレフィックスを付けず、モデル ID のみを指定してください。エージェント自身がプロバイダープレフィックスを追加するため、プレフィックス付きの値は `sambanova/sambanova/...` に解決されて失敗します。 * Developer エージェントの呼び出しはハンドオフであり、調整役のエージェントがツール呼び出しで実行します。`SAMBANOVA_CHAT_MODEL` にツール呼び出し非対応のモデルを指定すると、この呼び出しは破棄され、SambaNova エージェント自身がリクエストに応答します。ログにもエラーは記録されません。 * `gemma-4-31B-it` はツール呼び出しに対応していません。`SAMBANOVA_CHAT_MODEL` に [Function calling](/docs/ja/features/function-calling) に記載のモデル (例: `Meta-Llama-3.3-70B-Instruct`) を設定し、`docker compose down` に続けて `docker compose up` を実行してください。 * このモデルはテキストのみに対応しているため、画像のアップロードではなくテキストの説明でハンドオフを試してください。 * 警告の全文は `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 の公式ドキュメント](https://docs.docker.com/guides/agentic-ai/) をご参照ください。