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

このページでは、Databricks にデプロイされた AI エージェントの一般的な問題をデバッグする方法について説明します。

次の場所に移動します:

• ベストプラクティス
• ローカルでの開発
• 構成の問題
• 展開の問題
• Runtimeエラー
• 認証エラー
• メモリとストレージ

このページのほとんどのデバッグ セクションはDatabricks Appsにデプロイされたエージェントに適用されます。 ただし、タブ セレクターを使用して、モデルサービング (レガシー) にデプロイされたエージェントのデバッグ情報を見つけることもできます。

ベストプラクティスを活用した著者エージェント

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

• MLflowトレースを有効にする : AIエージェントを作成してDatabricks Appsにデプロイする のベスト プラクティスに従います。 MLflow トレースの自動ログ記録を有効にすると、エージェントのデバッグが容易になります。

• ツールを明確に文書化する : ツールとパラメーターの説明を明確にすることで、エージェントがツールを理解し、適切に使用できるようになります。明確なドキュメントによるツール呼び出しの改善を参照してください。

• LLM 呼び出しにタイムアウトとトークン制限を追加する : 長時間実行されるステップによって発生する遅延を回避するために、コード内の LLM 呼び出しにタイムアウトとトークン制限を追加します。

  • エージェントがOpenAI クライアントを使用して Databricks LLM サービング エンドポイントをクエリする場合は、必要に応じてサービング エンドポイント呼び出しにカスタム タイムアウトを設定します。

• デプロイ前に構成を検証する : デプロイ前にdatabricks bundle validateを実行して、YAML 構成の問題を早期に発見します。これは、不一致なリソース参照、無効な権限、構文エラーを識別するのに役立ちます。

• 最初にローカルでテストする : デプロイする前にローカル開発を使用して問題を検出します。エージェント サーバーをローカルで起動し、サンプル要求でテストして、 Databricks Appsにデプロイする前にMLflowトレースが正しく表示されることを確認します。

ローカル開発の問題をデバッグする

エージェントを展開前にローカルでテストして問題を特定します。

エージェントをローカルで実行する前に、環境が正しく構成されていることを確認してください。

1. Databricks CLI バージョンを確認します : databricks -vを実行して、バージョン 0.283.0 以降であることを確認します。

2. CLI プロファイルを確認します : 構成された認証プロファイルを表示するには、 databricks auth profilesを実行します。

3. 環境構成を検証します : .envファイルに必要な変数 (特にMLFLOW_TRACKING_URIが含まれていることを確認します。CLI プロファイルを含めるには、 databricks://PROFILE_NAME形式を使用する必要があります。

よくあるローカル開発エラー

エラー	原因	ソリューション
The provided MLFLOW_EXPERIMENT_ID does not exist	トラッキング URI 形式が間違っているか、エクスペリメントが削除されました	MLFLOW_TRACKING_URIが CLI プロファイル名でdatabricks://PROFILE_NAME形式を使用していることを確認してください
Module not found	依存関係がインストールされていません	依存関係をインストールするには、 uv syncを実行します。
Port already in use	ポートを使用している別のプロセス	別のポートを指定するには、 --portフラグを使用します (例: uv run start-app --port 8001 )
ローカル実行時の認証エラー	環境が設定されていません	クイックスタート スクリプトを実行するか、CLI プロファイルを使用して.envファイルを手動で構成します

エージェントをローカルでテストする

エージェントを展開前にテストするには:

1. エージェント サーバーをローカルで起動します。

   Bash

   uv run start-app

2. 別のターミナルで、テストリクエストを送信します。

   Bash

   curl -X POST http://localhost:8000/invocations \
     -H "Content-Type: application/json" \
     -d '{"input": [{"role": "user", "content": "hello"}]}'

3. Databricks UI で MLflow トレースを表示して、エージェントがトレースを正しく記録していることを確認します。

デバッグ構成の問題

databricks.ymlとapp.yamlの構成エラーは、デプロイメント失敗の一般的な原因です。

Databricks アセットバンドルの構成を検証する

アプリをデプロイする前に、Databricks アセット バンドルの構成を検証します。

Bash

databricks bundle validate

このコマンドは、次の構成をチェックします。

• YAML構文エラー
• 必須フィールドがありません
• 有効なリソース参照ではありません
• 権限設定の問題

一般的な構成の不一致

構成ポイント	ルール	デバッグ方法
valueFrom 参照先 app.yaml	リソースnameと完全に一致する必要があります databricks.yml	両方のファイルで正確な文字列を検索して、一致していることを確認します。
アプリ名	agent-プレフィックスで始まる必要があります (例: agent-data-analyst )	resources.appsのnameフィールドを確認してください databricks.yml
GenieスペースID	Genie URL の 32 文字の 16 進文字列である必要があります	URL パスから抽出: https://workspace.cloud.databricks.com/genie/rooms/{SPACE_ID}
Unity Catalog関数リファレンス	フォーマットを使用する必要があります catalog.schema.function_name	関数が存在することを確認するには databricks unity-catalog functions list
Lakebaseインスタンスリファレンス	app.yamlファイルではvalue ( valueFromではない) を使用する必要があります	インスタンス名はリテラル文字列であり、リソース参照ではありません

デプロイメントの問題をデバッグする

Agents deployed to Apps

アプリが既に存在するエラー

アプリが既に存在するエラー

Error: failed to create app - An app with the same name already existsが表示された場合、次の 2 つのオプションがあります。

オプション 1: 既存のアプリにバインドする (推奨)

Bash

# Get existing app configuration
databricks apps get <app-name> --output json

# Sync the configuration to your databricks.yml, then bind
databricks bundle deployment bind <bundle-name> <app-name> --auto-approve

# Deploy
databricks bundle deploy
databricks bundle run <bundle-name>

オプション2: 削除して再作成

Bash

databricks apps delete <app-name>
databricks bundle deploy
databricks bundle run <bundle-name>

デプロイ後にアプリが更新されない

デプロイ後にアプリが更新されない

databricks bundle deploy ワークスペースにファイルをアップロードするだけです。新しいコードでアプリを再起動するには、 databricks bundle run <bundle-name>を実行する必要もあります。

常に両方のコマンドを使用してデプロイします。

Bash

databricks bundle deploy && databricks bundle run <bundle-name>

展開ステータスとログを表示する

展開ステータスとログを表示する

アプリのデプロイメント ステータスを確認するには:

Bash

databricks apps get <app-name>

アプリのログをリアルタイムで表示するには:

Bash

databricks apps logs <app-name> --follow

Agents on Model Serving (legacy)

agents.deploy()を使用してエージェントをモデルサービング エンドポイントにデプロイした場合は、デプロイメント固有の問題についてモデルサービングのデバッグ ガイドを確認してください。

遅いリクエストや失敗するリクエストなどのランタイムの問題をデバッグするには、 「ランタイム エラーのデバッグ」を参照してください。

ランタイムエラーをデバッグする

Agents deployed to Apps

アプリ ログとリクエスト テストを使用して、展開されたエージェントの問題を特定します。

アプリログを分析する

デプロイされたアプリからのリアルタイム ログを表示します。

Bash

databricks apps logs <app-name> --follow

探す：

• コードエラーを示すスタックトレース
• リソースのアクセス拒否メッセージ
• 外部サービスへの接続エラー
• タイムアウトメッセージ

一般的なランタイムエラー

エラー	原因	ソリューション
アプリをクエリする際の302リダイレクト	OAuthの代わりに個人アクセストークンを使用する	OAuthセキュリティを取得するには databricks auth token
エージェントが利用可能なツールを使用していない	MCP クライアントからツールが返されない	MCPサーバーのURLが正しいこと、リソースに適切な権限があることを確認してください。 databricks.yml
ストリーミング応答が途中で途切れる	接続タイムアウト	CHAT_PROXY_TIMEOUT_SECONDS環境変数を増やしてください app.yaml
エージェントが「メモリが利用できません」を返す	リクエストにuser_idがありません	リクエストペイロードにcustom_inputs.user_id渡します
200 ステータスにもかかわらず、空またはエラーの応答	ストリーム応答内でエラーが発生しました	HTTPステータスコードだけでなく、実際のストリームコンテンツとアプリのログを確認してください。

Agents on Model Serving (legacy)

推論テーブルとMLflowトレースを使用して、モデルサービング エンドポイントにデプロイされたエージェントの問題を特定します。

問題のあるリクエストを特定する

エージェントの作成中にMLflow トレースの自動ログ記録を有効にした場合、トレースは推論テーブルに自動的に記録されます。これらのトレースを使用して、速度が遅い、または障害が発生しているエージェント コンポーネントを識別します。

1. ワークスペースで、 サービング タブに移動し、デプロイ名を選択します。

2. [ 推論テーブル ] セクションで、推論テーブルの完全修飾名を見つけます。たとえば、 my-catalog.my-schema.my-table.

3. Databricks ノートブックで次のコマンドを実行します。

   Python

   %sql
   SELECT * FROM my-catalog.my-schema.my-table

4. レスポンス 列で詳細なトレース情報を確認します。

5. request_time、databricks_request_id、またはstatus_codeでフィルタリングして、結果を絞り込みます。

   Python

   %sql
   SELECT * FROM my-catalog.my-schema.my-table
   WHERE status_code != 200

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

失敗したリクエストや遅いリクエストを特定したら、 mlflow.models.validate_serving_inputを使用します。失敗した入力要求に対してエージェントを呼び出すための API。結果のトレースを表示し、失敗した応答の根本原因分析を実行します。

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

認証エラーをデバッグする

Agents deployed to Apps

OAuth認証が必要です

OAuth認証が必要です

アプリにデプロイされたエージェントをクエリするには、Databricks OAuth トークンを使用する必要があります。パーソナル アクセス ウイルス (PAT) を使用すると、302 リダイレクト エラーが発生します。

OAuth トークンを取得するには:

Bash

databricks auth token

デプロイされたアプリへのリクエストでトークンを使用します。

Bash

TOKEN=$(databricks auth token | jq -r '.access_token')
curl -X POST <app-url>/invocations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "hello"}]}'

リソース権限エラー

リソース権限エラー

エージェントがワークスペース リソースにアクセスできない場合は、リソースがdatabricks.ymlで適切に構成されていることを確認してください。 各リソース タイプには特定の権限が必要です。

Error	Cause	Solution
Permission denied on Genie space	Missing genie_space resource	Add a genie_space resource with permission: 'CAN_RUN'
Vector search index not accessible	Missing uc_securable resource for the index	Add a uc_securable resource with securable_type: 'TABLE' and permission: 'SELECT'
Unity Catalog function execution denied	Missing uc_securable resource for the function	Add a uc_securable resource with securable_type: 'FUNCTION' and permission: 'EXECUTE'
Serving endpoint access denied	Missing serving_endpoint resource	Add a serving_endpoint resource with permission: 'CAN_QUERY'
SQL warehouse access denied	Missing sql_warehouse resource	Add a sql_warehouse resource with permission: 'CAN_USE'

databricks.ymlのリソース構成の例:

YAML

resources:
  apps:
    my_agent:
      name: 'agent-my-app'
      resources:
        - name: 'my_genie_space'
          genie_space:
            space_id: '01234567890abcdef01234567890abcd'
            permission: 'CAN_RUN'
        - name: 'my_vector_index'
          uc_securable:
            securable_full_name: 'catalog.schema.index_name'
            securable_type: 'TABLE'
            permission: 'SELECT'

カスタム MCP サーバー権限

カスタム MCP サーバー権限

エージェントが Databricks アプリとして実行されているカスタム MCP サーバーに接続する場合、アプリはまだdatabricks.ymlリソース依存関係としてサポートされていないため、手動で権限を付与する必要があります。

Bash

# Get your agent app's service principal
AGENT_SP=$(databricks apps get <agent-app-name> --output json | jq -r '.service_principal_name')

# Grant permission on the MCP server app
databricks apps update-permissions <mcp-server-app-name> \
  --json "{\"access_control_list\": [{\"service_principal_name\": \"$AGENT_SP\", \"permission_level\": \"CAN_USE\"}]}"

Agents on Model Serving (legacy)

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

ログに記録されたリソースを検査するには、ノートブックで次のコマンドを実行します。

Python

%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)

不足しているリソースや間違ったリソースを再度追加するには、エージェントをログに記録して再度デプロイします。

リソースに対して手動認証を使用する場合は、環境変数が正しく設定されていることを確認してください。手動設定は自動認証構成よりも優先されます。手動認証を参照してください。

メモリとストレージの問題をデバッグする

メモリ ストレージに Lakebase を使用するエージェントの場合、次のような問題がよく発生します。

エラー	原因	ソリューション
relation 'store' does not exist	メモリテーブルが初期化されていません	必要なテーブルを作成するには、デプロイする前にローカルでawait store.setup()を実行してください
Unable to resolve :re[LKB] instance	インスタンス名が間違っているか、構成が正しくありません	LAKEBASE_INSTANCE_NAME app.yamlでvalue ( valueFromではない) を使用しており、 instance_nameと一致していることを確認します。 databricks.yml
permission denied for table store	Lakebase の権限がありません	databricks.ymlにdatabaseリソースを追加します permission: 'CAN_CONNECT_AND_CREATE'
会話を通じて記憶が持続しない	リクエストごとに異なるuser_id	各ユーザーに対して、 custom_inputsに一貫したuser_idを渡すようにしてください。

Lakebase リソース構成の例:

YAML

resources:
  apps:
    my_agent:
      resources:
        - name: 'memory_database'
          database:
            instance_name: '<lakebase-instance-name>'
            database_name: 'postgres'
            permission: 'CAN_CONNECT_AND_CREATE'

メモリ付きのエージェントを展開する前に、テーブルをローカルで初期化します。

Python

import asyncio
from databricks_langchain import AsyncDatabricksStore

async def setup_memory():
    async with AsyncDatabricksStore(
        instance_name='your-lakebase-instance',
        embedding_endpoint='databricks-gte-large-en',
        embedding_dims=1024,
    ) as store:
        await store.setup()

asyncio.run(setup_memory())