次の方法で共有

デプロイされた AI エージェントをデバッグする

このページでは、Mosaic AI Agent Framework の agents.deploy() API を使用して AI エージェントをデプロイするときの一般的な問題をデバッグする方法について説明します。

Agent Framework は Model Serving エンドポイントにデプロイされるため、このページのエージェント デバッグ手順に加えて 、モデル サービス のデバッグ ガイドを確認する必要があります。

ベスト プラクティスを使用してエージェントを作成する

エージェントを作成するときは、次のベスト プラクティスを使用します。

  • 推奨されるエージェント作成インターフェイスと MLflow トレースを使用してデバッグを改善する: MLflow トレースの自動ログ記録を有効にしてエージェントをデバッグしやすくするなど、コード内の AI エージェントの作成に関するページのベスト プラクティスに従います。
  • ドキュメント ツールが明確: ツールとパラメーターの説明を明確にすることで、エージェントがツールを理解し、適切に使用できるようにします。 明確なドキュメントを使用したツール呼び出しの向上を参照してください。
  • LLM 呼び出しにタイムアウトとトークン制限を追加する: コード内の LLM 呼び出しにタイムアウトとトークン制限を追加して、実行時間の長い手順による遅延を回避します。
    • エージェントが OpenAI クライアント を使用して Databricks LLM サービス エンドポイントのクエリを実行する場合は、必要に応じてエンドポイント呼び出しを提供するカスタム タイムアウトを設定します。

デプロイされたエージェントに対する低速または失敗した要求をデバッグする

エージェントの作成中に MLflow トレースの自動ログ記録 を有効にした場合、トレースは推論テーブルに自動的に記録されます。 これらのトレースは、低速または失敗しているエージェント コンポーネントを識別するのに役立ちます。

問題のある要求を特定する

問題のある要求を見つけるには、次の手順に従います。

  1. ワークスペースで、[ サービス ] タブに移動し、デプロイ名を選択します。
  2. [ 推論テーブル ] セクションで、推論テーブルの完全修飾名を見つけます。 たとえば、my-catalog.my-schema.my-table のようにします。
  3. Databricks ノートブックで次を実行します。 
    %sql
SELECT * FROM my-catalog.my-schema.my-table
  4. [応答] 列で詳細なトレース情報を調べます。
  5. request_time、databricks_request_id、またはstatus_codeでフィルター処理して、結果を絞り込みます。 
    %sql
SELECT * FROM my-catalog.my-schema.my-table
WHERE status_code != 200

根本原因の問題を分析する

失敗した要求または低速な要求を特定した後、 mlflow.models.validate_serving_input API を使用して、失敗した入力要求に対してエージェントを呼び出します。 次に、結果のトレースを表示し、失敗した応答に対して根本原因分析を実行します。

開発ループを高速化するために、エージェント コードを直接更新し、失敗した入力例に対してエージェントを呼び出して反復処理できます。

認証エラーのデバッグ

デプロイされたエージェントがベクター検索インデックスや LLM エンドポイントなどのリソースにアクセスしているときに認証エラーが発生した場合は、自動認証パススルーに必要なリソースでログに記録されたことを確認します。 自動認証パススルーを参照してください。

ログに記録されたリソースを調べるには、ノートブックで次を実行します。

%pip install -U mlflow[databricks]
%restart_python

import mlflow
mlflow.set_registry_uri("databricks-uc")

# Replace with the model name and version of your deployed agent
agent_registered_model_name = ...
agent_model_version = ...

model_uri = f"models:/{agent_registered_model_name}/{agent_model_version}"
agent_info = mlflow.models.Model.load(model_uri)
print(f"Resources logged for agent model {model_uri}:", agent_info.resources)

不足しているリソースまたは正しくないリソースを再追加するには、エージェントをログに記録して、もう一度デプロイする必要があります。

リソースに手動認証を使用している場合は、環境変数が正しく設定されていることを確認します。 手動設定は、自動認証構成をオーバーライドします。 「手動認証」を参照してください。