カスタムコードエージェントをデバッグします

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

移動先：

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

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

ベストプラクティスを活用したエージェントの開発

エージェント作成時には、次のベストプラクティスに従ってください。

• **MLflow トレースの有効化**：AIエージェントを作成してDatabricks Appsにデプロイする のベストプラクティスに従ってください。エージェントのデバッグを容易にするために、MLflow トレースの自動ログ記録を有効にしてください。

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

• LLM呼び出しにタイムアウトとトークン制限を追加する ：長時間実行されるステップによって引き起こされる遅延を避けるために、コード内のLLM呼び出しにタイムアウトとトークン制限を追加してください。

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

• デプロイ前の構成の検証 ：YAML構成の問題を早期に検出するために、デプロイする前にdatabricks bundle validateを実行してください。これにより、不一致のリソース参照、無効な権限、および構文エラーの特定に役立ちます。

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

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

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

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

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

2. CLI プロファイルの検証 ：設定済みの認証プロファイルを表示するには、databricks auth profilesを実行します。

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

一般的なローカル開発エラー

エラー	原因	ソリューション
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）を指定します。
ローカル実行時の認証エラー	環境が設定されていません。	クイックスタートスクリプトを実行するか、.envファイルをCLIプロファイルで手動で設定します。

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

エージェントをデプロイ前にテストするには:

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の構成エラーは、デプロイメントの失敗の一般的な原因です。

宣言型オートメーションバンドルの構成を検証します

アプリをデプロイする前に、宣言型オートメーションバンドルの設定を検証します：

Bash

databricks bundle validate

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

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

一般的な構成の不一致

構成ポイント	ルール	デバッグ方法
valueFrom リファレンス内 app.yaml	リソースnameと完全に一致する必要があります。 databricks.yml	両方のファイルで正確な文字列を検索して、一致することを確認します。
アプリ名	agent-プレフィックスで開始する必要があります（例：agent-data-analyst）。	〜にあるresources.appsの下のnameフィールドを確認します databricks.yml
Genie Space 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()を使用して Model Serving エンドポイントにエージェントをデプロイした場合は、デプロイ固有の問題についてModel Serving のデバッグガイドを確認してください。

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

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

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
「Memory not available」を返すエージェント	リクエストで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'
AI 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)

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

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

Python

%pip install -U mlflow[databricks]==2.20.2
%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	インスタンス名が間違っているか、設定が正しくありません。	app.yamlでLAKEBASE_INSTANCE_NAMEが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())