前提条件
-
SambaCloud の API キー
SambaCloud アカウント を作成し、「API Keys」 タブから API キーを生成して取得してください。 -
Python 3.10 〜 3.14。
camel-aiは Python 3.9 以前と Python 3.15 以降をサポートしていません。 -
API キーを
SAMBA_API_KEYとしてエクスポートしておくこと:
CAMEL-AI は
SAMBANOVA_API_KEY ではなく SAMBA_API_KEY からキーを読み取ります。他の SambaNova 連携ガイドの手順に従ったことがある場合は、ここでは変数名が異なる点にご注意ください。インストールとセットアップ
-
仮想環境を作成します。
-
環境がサポート対象のバージョンを使用していることを確認します。
-
必要なライブラリをインストールします。
"camel-ai[all]~=0.2.90"は必ず引用符で囲んでください。macOS のデフォルトシェルである zsh は角括弧をファイル名パターンとして解釈するため、pip が実行される前にno matches foundで失敗します。この extra は大きな依存関係ツリーを取得し、完了まで数分かかることがあるため、時間に余裕を持って実行してください。 -
インストールを確認します。エージェント API が壊れていても
import camelは成功するため、トップレベルのパッケージではなくChatAgentをインポートして確認します。このコマンドが、トレースバックなしで正確に以下を出力すれば成功です。
クイックスタート
大きなコードを書き始める前に、1 回のチャット補完でセットアップをエンドツーエンドで確認しましょう。以下をquickstart.py として保存し、python quickstart.py で実行します。
SAMBA_API_KEY を読み取り、数秒でレスポンスを返します。応答が表示されれば環境とキーは正常に動作しており、以降の失敗はセットアップではなくご自身のコードに起因すると判断できます。model_type には SambaCloud モデル にある現行のモデル ID を指定できます。Meta-Llama-3.3-70B-Instruct は、最初の実行に適した高速で低コストな選択肢です。
2 つのエージェントの連携
CAMEL-AI はマルチエージェントでの利用を想定して設計されているため、単一エージェントではその真価はあまり見えません。以下の例では、2 つのエージェントに異なるシステムメッセージを与え、一方の出力を他方に渡します。プランナーが計画を起草し、レビュアーがそれを批評し、プランナーが修正します。各ChatAgent は独自の会話履歴を保持しているため、プランナーは 2 回目のターンで、自分が書いた計画をすでに把握しています。
以下を two_agents.py として保存し、python two_agents.py で実行します。
model オブジェクトを共有するため、スクリプトが開くクライアントは 1 つで、課金対象は 3 回の補完です。ロールごとに異なるモデルを使いたい場合は、エージェントごとに ModelFactory.create() を呼び出してください。
サンプルノートブック
CAMEL-AI、SambaCloud が提供するモデル、Firecrawl、Qdrant を使用してカスタマーサービス用の Discord ボットを構築する方法を示したサンプルノートブックをご覧いただけます。
FIRECRAWL_API_KEY用の Firecrawl アカウント。ナレッジソースのクロールに使用します。DISCORD_BOT_TOKEN用に、Discord Developer Portal で登録したボット。- GPU ランタイム。ノートブックはオープンソースの Embedding モデルをローカルで実行し、そのステップには GPU 対応の Google Colab ランタイム (Tesla T4) を推奨しています。代わりに、CAMEL-AI がサポートする別の Embedding モデルを使用することもできます。
data/vectordb/ に書き込みます。
トラブルシューティング
zsh: no matches found: camel-ai[all]
zsh: no matches found: camel-ai[all]
macOS のデフォルトシェルである zsh は角括弧をファイル名パターンとして展開するため、pip が実行される前にインストールコマンドが失敗します。引数全体を引用符で囲んでください:
pip install "camel-ai[all]~=0.2.90"。bash では引用符は不要ですが、付けても問題ありません。ImportError: cannot import name 'FastMCP' from 'mcp.server'
ImportError: cannot import name 'FastMCP' from 'mcp.server'
mcp 2.0.0 がインストールされています。camel-ai は上限なしで mcp>=1.3.0 を要求しますが、2.0.0 では camel.toolkits がインポートする FastMCP が削除されました。その結果、ノートブックの最初のセルを含め、camel.agents 配下のすべてのインポートが失敗します。なお import camel は成功するため、トップレベルのインポート確認ではこの問題は検出できません。pip install "mcp<2" で修正してください。ModuleNotFoundError: No module named 'camel'
ModuleNotFoundError: No module named 'camel'
仮想環境が有効になっていません。もう一度
source .venv/bin/activate を実行し、プロンプトに (.venv) が表示されることを確認してから、インストールコマンドを再実行してください。python -c "import camel; print('Camel-AI ready')" で確認できます。インストールに時間がかかる、または途中で失敗する
インストールに時間がかかる、または途中で失敗する
camel-ai[all] はすべてのオプション依存関係をインストールするため、ダウンロードサイズが大きく、回線速度によっては数分かかることがあります。途中で失敗した場合は、まず pip install "camel-ai~=0.2.90" でベースパッケージをインストールし、その後 extra を追加してください。サンプルノートブックには extra が必要なため、恒久的に省略しないでください。アップグレード後に camel から ImportError や TypeError が発生する
アップグレード後に camel から ImportError や TypeError が発生する
新しい
camel-ai により、本ページが依存する API が変更されています。camel-ai は 1.0 未満であり、公開 API はリリース間で変わる可能性があります。pip install "camel-ai[all]~=0.2.90" で検証済みバージョンを再インストールし、pip show camel-ai で現在のバージョンを確認した上で、制約を緩める前に CAMEL-AI ドキュメント で最新のシグネチャを確認してください。ノートブックのモデルが model_not_found を返す
ノートブックのモデルが model_not_found を返す
サンプルノートブックは
model_type="QwQ-32B" を設定していますが、このモデルは SambaCloud で 2025年6月25日に提供終了 となっており、すでに提供されていません。MiniMax-M2.7 か、SambaCloud モデル にある他の現行モデル ID に置き換えてください。なお、ノートブックの検索対象コーパス自体が Qwen モデルに関する内容のため、モデルと合わせてプロンプトの調整も検討してください。ValueError: DISCORD_BOT_TOKEN not found
ValueError: DISCORD_BOT_TOKEN not found
リンク先のノートブックは
DISCORD_TOKEN を設定するよう指示していますが、CAMEL-AI のコードが読み取るのは DISCORD_BOT_TOKEN です。CAMEL-AI 自体の docstring も古い名前のままであり、ノートブックの指示は本ページの誤りではなく、アップストリーム側の更新漏れです。DISCORD_TOKEN ではなく DISCORD_BOT_TOKEN を設定してください。ValueError: Missing or empty required API keys in environment variables: SAMBA_API_KEY
ValueError: Missing or empty required API keys in environment variables: SAMBA_API_KEY
多くの SambaNova 連携とは異なり、CAMEL-AI は
SAMBA_API_KEY を必要とします。SAMBANOVA_API_KEY を設定しても効果はありません。CAMEL-AI はリクエスト送信前の ModelFactory.create() の時点でこのエラーを送出するため、トレースバックは API 呼び出しではなくモデルのセットアップ箇所を指します。SAMBA_API_KEY をエクスポートしてください。スクリプトが応答しない、またはリクエストがタイムアウトする
スクリプトが応答しない、またはリクエストがタイムアウトする
CAMEL-AI のデフォルトは、リクエストごとに 180 秒のタイムアウトと、失敗した呼び出しの 3 回の再試行です。試行錯誤している間は、
ModelFactory.create() に timeout=30 を渡すか、環境変数 MODEL_TIMEOUT を設定してタイムアウトを短くすると、フィードバックを早く得られます。すべての呼び出しがタイムアウトする場合は、エンドポイントに到達できることを確認してください: curl -H "Authorization: Bearer $SAMBA_API_KEY" https://api.sambanova.ai/v1/modelsノートブック用のサードパーティ認証情報が不足している
ノートブック用のサードパーティ認証情報が不足している
サンプルノートブックには、SambaCloud のキーに加えて、Firecrawl の API キー、Discord のボットトークン、GPU ランタイムが必要です。完全な一覧と各項目の入手先は サンプルノートブック をご参照ください。クイックスタートと 2 つのエージェントの例には、いずれも不要です。
参考情報
- CAMEL-AI ドキュメント – フレームワークの完全なリファレンス。
- CAMEL-AI societies – 上記の 2 エージェントの例より高度な
RolePlayingとWorkforceのパターン。 - camel-ai (GitHub) – ソースでシグネチャを確認したり、アップストリームに Issue を報告したりする場合。
- SambaCloud モデル – 現行のモデル ID とコンテキスト長。

