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

このガイドは、DataRobotエージェントテンプレートを使用する際によくある問題の診断と解決に役立ちます。

前提条件とセットアップの問題¶

DataRobotエージェントテンプレートのシステム要件と初期設定に関する一般的な問題。

Windowsとの互換性¶

問題：DataRobotエージェントテンプレートでは、Windowsはサポートされていません。

解決方法：開発にはmacOSまたはLinuxを使用します。

前提条件を満たしていない¶

問題：必要なツールがインストールされていません。

解決方法：前提条件ガイドに従って、不足しているツールをインストールします。

ビルドツールがない¶

問題：使用中のシステムにビルドツールがありません。

解決方法：Xcode Command Line Tools（macOS）または build-essential（Linux）をインストールします。

環境設定の問題¶

環境変数とDataRobotエンドポイント設定の問題。

環境変数がない¶

問題：必要な環境変数が設定されていません。

解決方法：DATAROBOT_API_TOKENとDATAROBOT_ENDPOINTを含む.envファイルを作成します。

無効なエンドポイント設定¶

問題：DataRobotエンドポイントの設定が正しくありません。

解決方法：リージョンに合った正しいエンドポイントを使用するか（クラウドの場合）、サポート（オンプレミス）にお問い合わせください（オンプレミスの場合）。

認証に関する問題¶

API認証と認可コンテキストの設定に関する問題。

APIトークンの認証が失敗した¶

問題：APIトークンが無効か、適切な権限がありません。

解決方法：APIトークンが有効で、適切な権限があるか確認します。

認可コンテキストが設定されていない¶

問題：認可コンテキストがエージェントで初期化されていません。

解決方法：initialize_authorization_context()がエージェントで呼び出されるようにします。

デプロイに関する問題¶

デプロイプロセスやインフラストラクチャの管理で発生した問題。

Pulumiへのログインが必要¶

問題：Pulumiの認証が設定されていません。

解決方法：pulumi login --localまたはpulumi login`を実行します。

デプロイIDが見つからない¶

問題：デプロイ後にデプロイIDが見つかりません。

解決方法：ターミナル出力または DataRobot UI → コンソール → デプロイを確認します。

CLIとテストに関する問題¶

コマンドラインインターフェイスの使用とエージェントのローカルテストに関する問題。

CLIコマンドが見つからない¶

問題：CLIコマンドがありません。

Solution: Run dr start to select framework.

ローカルテストが失敗¶

問題：開発中にエージェントを実行しようとすると、ローカルテストでエラーが発生します。

解決方法：CLIコマンドを使用して、エージェントをローカルでテストします。 これにより、DataRobotにデプロイすることなく、エージェントコードを実行してデバッグすることができます。 executeコマンドを実行するには、開発サーバーが稼働している必要があります。 task agent:devを使用して手動で起動したり（継続的に実行されるため、別のターミナルを使用してください）、START_DEV=1を使用して自動的に起動および停止したりできます。

• 基本的なテキストクエリーでテストする：task agent:cli START_DEV=1 -- execute --user_prompt "Hello"（または、最初にtask agent:devを起動してから、task agent:cli--execute--user_prompt"Hello"を実行）
• JSON入力でテストする：task agent:cli START_DEV=1 -- execute --user_prompt '{"topic": "Artificial Intelligence"}'
• 出力JSONファイルでテストする：task agent:cli START_DEV=1 -- execute --completion_json example-completion.json
• 冗長ログを有効にする：補完JSONのextra_bodyフィールドに"verbose": trueを追加します。

よくある問題としては、環境変数（DATAROBOT_API_TOKEN、DATAROBOT_ENDPOINT）の欠落、agent.pyでのインポート問題（インポートの問題を参照）、pyproject.tomlでの依存関係の欠落などがあります。

インフラストラクチャに関する問題¶

コンテナ化、構築プロセス、インフラストラクチャの状態管理に関する問題。

Dockerの構築が失敗する¶

問題：Dockerコンテナの構築でエラーが発生します。

解決方法：ローカルでテストし、pyproject.tomlの依存関係をチェックします。

Pulumiの状態に関する問題¶

問題：Pulumiの状態が同期していません。

解決方法：task infra:refreshを実行して状態を同期します。

agent.pyにおけるインポートの問題¶

問題：agent.pyで同じフォルダー内のファイルにインポートすると、DRUMでサイレントエラーが発生します。

解決方法：パッケージインポートではなく、相対インポート利用します。

LLM Gatewayに関する問題¶

LLM Gatewayの接続、モデルへのアクセス、および設定に関する問題。

モデルアクセスエラー¶

問題：LLM Gatewayがモデルに接続できないか、「モデルへのアクセス権がない」というエラーで失敗します。

解決方法：モデルにアクセスできるようにします。 アクセス権のないモデル（またはサポートが終了したモデル）を指定した場合、ゲートウェイへの接続は可能ですが、アクションは「モデルにアクセスできない」エラーで失敗します。

LLM Gatewayの設定¶

問題：LLM Gatewayが正しく設定されていません。

解決方法：所属する組織がLLM Gatewayにアクセスできることと、model-metadata.yamlファイルにENABLE_LLM_GATEWAY_INFERENCEランタイムパラメーターを指定し、trueに設定していることを確認します。

Gateway以外のモデルのデプロイ¶

問題：Gateway以外のモデルのデプロイが失敗します。

解決方法：Gatewayモデルを使用していない場合は、LLMデプロイの実行に失敗しても、task deployを1回実行します。

リクエストヘッダーへのアクセス¶

エージェントがデプロイされると、認証、追跡、またはカスタムメタデータのために、HTTPリクエストヘッダーにアクセスする必要があるかもしれません。 DataRobot はchat()関数の**kwargsパラメーターを通して、エージェントコードからヘッダーを利用できるようにします。

X-Untrusted-*ヘッダーの抽出¶

X-Untrusted-*プレフィックスを持つヘッダーは、元のリクエストから渡され、kwargsディクショナリで使用できます。

import asyncio
from concurrent.futures import ThreadPoolExecutor
from typing import Any, Iterator, Union
from openai.types.chat import CompletionCreateParams
from openai.types.chat.completion_create_params import (
    CompletionCreateParamsNonStreaming,
    CompletionCreateParamsStreaming,
)

def chat(
    completion_create_params: CompletionCreateParams
    | CompletionCreateParamsNonStreaming
    | CompletionCreateParamsStreaming,
    load_model_result: tuple[ThreadPoolExecutor, asyncio.AbstractEventLoop],
    **kwargs: Any,
) -> Union[CustomModelChatResponse, Iterator[CustomModelStreamingResponse]]:
    # Extract all headers from kwargs
    headers = kwargs.get("headers", {})

    # Access specific X-Untrusted-* headers
    authorization_header = headers.get("X-Untrusted-Authorization")
    custom_header = headers.get("X-Untrusted-Custom-Metadata")

    # Use headers in your agent logic
    if authorization_header:
        # Pass to downstream services, tools, etc.
        print(f"Authorization header: {authorization_header}") 

一般的なユースケース¶

外部サービスに認証を渡す：

headers = kwargs.get("headers", {})
auth_token = headers.get("X-Untrusted-Authorization")

# Use the token to authenticate with external APIs
tool_client = MyTool(auth_token=auth_token) 

リクエストメタデータの追跡：

headers = kwargs.get("headers", {})
request_id = headers.get("X-Untrusted-Request-ID")
user_id = headers.get("X-Untrusted-User-ID")

# Log metadata for debugging or analytics
logging.info(f"Processing request {request_id} for user {user_id}") 

条件付きのエージェントの動作：

headers = kwargs.get("headers", {})
region = headers.get("X-Untrusted-Region")

# Adjust agent behavior based on request context
if region == "EU":
    agent = MyAgent(enable_gdpr_mode=True) 

重要な注意事項¶

• X-Untrusted-*プレフィックスを持つヘッダーのみが、エージェントコードに渡されます。
• ディクショナリからヘッダーにアクセスする場合、英大文字と英小文字は区別されます。
• 存在しない可能性のあるヘッダーにアクセスする場合、常にデフォルト値を指定するか、「なし」をチェックします。
• ヘッダーは、ストリーミングと非ストリーミングの両方のチャット回答で使用できます。

デバッグのヒント¶

エージェントの問題のトラブルシューティングとデバッグに役立つテクニックとコマンド。

冗長ログを有効にする¶

agent = MyAgent(verbose=True) 

認証のテスト¶

from datarobot_genai.core.cli import AgentEnvironment

env = AgentEnvironment() 

環境変数のチェック¶

echo $DATAROBOT_API_TOKEN
echo $DATAROBOT_ENDPOINT 

デバッグのためリクエストヘッダーのログを取る¶

import asyncio
import logging
from concurrent.futures import ThreadPoolExecutor
from typing import Any

def chat(completion_create_params, load_model_result: tuple[ThreadPoolExecutor, asyncio.AbstractEventLoop], **kwargs: Any):
    headers = kwargs.get("headers", {})

    # Log all headers to inspect what's available
    if headers:
        logging.warning(f"All headers: {dict(headers)}")

    # Continue with agent logic... 

サポートについて¶

追加のサポートが必要な場合は：

• 選択したエージェントフレームワークのドキュメントを確認します。
• DataRobotに問い合わせます。
• GitHubリポジトリで案件を公開します。
• フレームワークについてのドキュメント：
  • CrewAI
  • LangGraph
  • LlamaIndex
  • NVIDIA NeMo Agent Toolkit