カスタムコードエージェントのデバッグ

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

移動先：

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

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

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

エージェントの作成時には、以下のベストプラクティスを使用してください。

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

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

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

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

• デプロイ前の構成の検証 : デプロイする前に databricks bundle validate を実行し、YAML構成の問題を早期に検出します。これにより、不一致のリソース参照、無効なアクセス許可、構文エラーを特定できます。

• **まずローカルでテストしてください**：デプロイ前に問題を特定するために、ローカル開発を利用してください。エージェントサーバーをローカルで起動し、サンプルリクエストでテストし、MLflow トレースが正しく表示されることを確認してから、Databricks Appsにデプロイしてください。

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

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

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

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

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 ファイルを手動で構成してください。

エラー	原因	ソリューション
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での設定エラーは、デプロイの失敗の一般的な原因です。

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

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

Bash

databricks bundle validate

このコマンドは、以下の構成を確認します：

• YAML構文エラー
• 必須フィールドが見つかりません。
• 無効なリソース参照
• 権限設定の問題

一般的な構成の不一致

構成ポイント	ルール	デバッグする方法
valueFrom における参照 app.yaml	リソース name に完全に一致する必要があります databricks.yml	両方のファイルで正確な文字列を検索して、一致することを確認します。
アプリ名	agent-プレフィックスで始まる必要があります（例：agent-data-analyst）。	resources.apps の下の name フィールドで確認します databricks.yml
Genie Agent 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ではありません）。	インスタンス名はリソース参照ではなく、リテラル文字列です

構成ポイント	ルール	デバッグする方法
valueFrom における参照 app.yaml	リソース name に完全に一致する必要があります databricks.yml	両方のファイルで正確な文字列を検索して、一致することを確認します。
アプリ名	agent-プレフィックスで始まる必要があります（例：agent-data-analyst）。	resources.apps の下の name フィールドで確認します databricks.yml
Genie Agent 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 ワークスペースにはファイルのみをuploadします。新しいコードでアプリを再起動するには、databricks bundle run <bundle-name>も実行する必要があります。

必ず両方のコマンドを使用してデプロイしてください：

Bash

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

デプロイメントステータスとログを表示する

デプロイメントステータスとログを表示する

アプリのデプロイ状況を確認するには：

Bash

databricks apps get <app-name>

アプリのLogsをリアルタイムで表示するには：

Bash

databricks apps logs <app-name> --follow

Agents on Model Serving (legacy)

Model Serving Endpointにagents.deploy()を使用してエージェントをデプロイした場合、デプロイ固有の問題についてはModel Servingのデバッグガイドを参照してください。

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

ランタイムエラーのデバッグ

Agents deployed to Apps

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

Analyze app Logs

デプロイ済みアプリのリアルタイムLogsを表示する：

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ステータスコードだけでなく、実際のストリームコンテンツとアプリのLogsも確認してください。

エラー	原因	ソリューション
アプリのクエリ時の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ステータスコードだけでなく、実際のストリームコンテンツとアプリのLogsも確認してください。

Agents on Model Serving (legacy)

Model Serving Endpointにデプロイされたエージェントの問題を特定するために、推論テーブルとMLflowトレースを使用します。

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

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

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

2. 「Inference tables」セクションで、推論テーブルの完全修飾名を見つけてください。 たとえば、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 Agent	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'

Error	Cause	Solution
Permission denied on Genie Agent	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 Endpointなどのリソースにアクセスしたときに認証エラーが発生した場合は、自動認証パススルーに必要なリソースと共にログに記録されたことを確認します。自動認証パススルーを参照してください。

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

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)

不足しているリソースまたは正しくないリソースを再追加するには、エージェントをlogし、再度デプロイします。

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

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

メモリ ストレージに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を渡してください。

エラー	原因	ソリューション
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())