AI エージェントを作成して Databricks Apps にデプロイする

AI エージェントを構築し、Databricks Apps を使用してデプロイします。 Databricks Apps を使用すると、エージェントコード、サーバー構成、デプロイワークフローを完全に制御できます。 この方法は、カスタム サーバーの動作、Git ベースのバージョン管理、またはローカル IDE 開発が必要な場合に最適です。

必要条件

ワークスペースで Databricks Apps を有効にします。 Databricks Apps ワークスペースと開発環境を設定するを参照してください。

手順 1. エージェント アプリ テンプレートを複製する

Databricks アプリ テンプレート リポジトリから事前構築済みのエージェント テンプレートを使用して作業を開始します。

このチュートリアルでは、次の agent-openai-agents-sdk テンプレートを使用します。

• OpenAI Agent SDK を使用して作成されたエージェント
• 会話型 REST API と対話型チャット UI を使用したエージェント アプリケーションのスターター コード
• MLflow を使用してエージェントを評価するコード

テンプレートを設定するには、次のいずれかのパスを選択します。

ワークスペース UI

ワークスペース UI を使用してアプリ テンプレートをインストールします。 これにより、アプリがインストールされ、ワークスペース内のコンピューティング リソースにデプロイされます。 その後、アプリケーション ファイルをローカル環境に同期して、さらに開発することができます。

1. Databricks ワークスペースで、[ + 新規>App] をクリックします。

2. [ エージェント>Agent - OpenAI Agents SDK] をクリックします。

3. openai-agents-templateという名前の新しい MLflow 実験を作成し、残りの設定を完了してテンプレートをインストールします。

4. アプリを作成したら、アプリの URL をクリックしてチャット UI を開きます。

アプリを作成したら、ソース コードをローカル コンピューターにダウンロードしてカスタマイズします。

1. Sync the files で最初のコマンドをコピーする

   

2. ローカル ターミナルで、コピーしたコマンドを実行します。

GitHub から複製する

ローカル環境から開始するには、エージェント テンプレート リポジトリを複製し、 agent-openai-agents-sdk ディレクトリを開きます。

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk

ステップ 2. エージェント アプリケーションを理解する

エージェント テンプレートは、これらの主要コンポーネントを使用した運用対応アーキテクチャを示しています。 各コンポーネントの詳細については、次のセクションを開きます。

各コンポーネントの詳細については、次のセクションを開きます。

MLflow AgentServer

組み込みのトレースと可観測性を使用してエージェント要求を処理する非同期 FastAPI サーバー。 AgentServer は、エージェントに対してクエリを実行するための/invocations エンドポイントを提供し、要求ルーティング、ログ記録、およびエラー処理を自動的に管理します。

ResponsesAgent インターフェイス

Databricks では、エージェントを構築するために MLflow ResponsesAgent をお勧めします。 ResponsesAgent を使用すると、任意のサードパーティ フレームワークを使用してエージェントを構築し、それを Databricks AI 機能と統合して、堅牢なログ記録、トレース、評価、デプロイ、監視機能を実現できます。

ResponsesAgentを作成する方法については、MLflow ドキュメントの例である ResponsesAgent for Model Serving を参照してください。

ResponsesAgent には、次の利点があります。

• 高度なエージェント機能

  • マルチエージェントのサポート
  • ストリーミング出力: 出力をより小さなチャンクでストリーミングします。
  • 包括的なツール呼び出しメッセージ履歴: 品質と会話管理を向上させるために、中間ツール呼び出しメッセージを含む複数のメッセージを返します。
  • ツール呼び出しの確認のサポート
  • 実行時間の長いツールのサポート

• 開発、デプロイ、監視の合理化

  • 任意のフレームワークを使用してエージェントを作成する: ResponsesAgent インターフェイスを使用して既存のエージェントをラップして、AI Playground、Agent Evaluation、Agent Monitoring とのすぐに使用できる互換性を実現します。
  • 型指定された作成インターフェイス: IDE とノートブックオートコンプリートの恩恵を受け、型指定された Python クラスを使用してエージェント コードを記述します。
  • 自動トレース: MLflow は、評価と表示を容易にするために、ストリーム応答をトレースに自動的に集計します。
  • OpenAI Responses スキーマと互換性があります。 OpenAI: Responses と ChatCompletion を参照してください。

OpenAI Agents SDK

テンプレートでは、会話管理とツール オーケストレーションのエージェント フレームワークとして OpenAI Agents SDK が使用されます。 任意のフレームワークを使用してエージェントを作成できます。 キーは、MLflow ResponsesAgent インターフェイスでエージェントをラップすることです。

MCP (モデル コンテキスト プロトコル) サーバー

このテンプレートは Databricks MCP サーバーに接続して、エージェントにツールとデータ ソースへのアクセスを許可します。 Databricks のモデル コンテキスト プロトコル (MCP) を参照してください。

AI コーディング アシスタントを使用してエージェントを作成する

Databricks では、Claude、Cursor、Copilot などの AI コーディング アシスタントを使用してエージェントを作成することをお勧めします。 提供されているエージェント スキル ( /.claude/skills) と AGENTS.md ファイルを使用して、AI アシスタントがプロジェクトの構造、使用可能なツール、ベスト プラクティスを理解するのに役立ちます。 エージェントは、これらのファイルを自動的に読み取って、Databricks Apps を開発してデプロイできます。

高度なオーサリングに関するトピック

{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}

import mlflow
# Define the retriever's schema by providing your column names
# For example, the following call specifies the schema of a retriever that returns a list of objects like
# [
#     {
#         'document_id': '9a8292da3a9d4005a988bf0bfdd0024c',
#         'chunk_text': 'MLflow is an open-source platform, purpose-built to assist machine learning practitioners...',
#         'doc_uri': 'https://mlflow.org/docs/latest/index.html',
#         'title': 'MLflow: A Tool for Managing the Machine Learning Lifecycle'
#     },
#     {
#         'document_id': '7537fe93c97f4fdb9867412e9c1f9e5b',
#         'chunk_text': 'A great way to get started with MLflow is to use the autologging feature. Autologging automatically logs your model...',
#         'doc_uri': 'https://mlflow.org/docs/latest/getting-started/',
#         'title': 'Getting Started with MLflow'
#     },
# ...
# ]
mlflow.models.set_retriever_schema(
    # Specify the name of your retriever span
    name="mlflow_docs_vector_search",
    # Specify the output column name to treat as the primary key (ID) of each retrieved document
    primary_key="document_id",
    # Specify the output column name to treat as the text content (page content) of each retrieved document
    text_column="chunk_text",
    # Specify the output column name to treat as the document URI of each retrieved document
    doc_uri="doc_uri",
    # Specify any other columns returned by the retriever
    other_columns=["title"],
)

手順 3. エージェント アプリをローカルで実行する

ローカル環境を設定します。

1. uv (Python パッケージ マネージャー)、nvm (ノード バージョン マネージャー)、および Databricks CLI をインストールします。

   • uv インストール
   • nvm インストール
   • ノード 20 LTS を使用するには、次を実行します。

     nvm use 20
     

   • databricks CLI インストール

2. ディレクトリを agent-openai-agents-sdk フォルダーに変更します。

3. 提供されているクイック スタート スクリプトを実行して依存関係をインストールし、環境を設定して、アプリを起動します。

   uv run quickstart
   uv run start-app
   

ブラウザーで、 http://localhost:8000 に移動してエージェントとのチャットを開始します。

手順 4. 認証を構成する

エージェントは、Databricks リソースにアクセスするための認証を必要とします。 Databricks Apps には、次の 2 つの認証方法が用意されています。

アプリの承認 (既定)

アプリの承認では、Azure Databricks によってアプリ用に自動的に作成されるサービス プリンシパルが使用されます。 すべてのユーザーが同じアクセス許可を共有します。

MLflow 実験にアクセス許可を付与します。

1. アプリのホーム ページで [ 編集] をクリックします。
2. [構成] ステップに移動します。
3. [ アプリ リソース ] セクションで、 Can Edit アクセス許可を持つ MLflow 実験リソースを追加します。

その他のリソース (Vector Search、Genie スペース、サービス エンドポイント) については、[ アプリ リソース ] セクションで同じ方法で追加します。

詳細については、 アプリの承認 に関するページを参照してください。

ユーザーの承認

ユーザー承認を使用すると、エージェントは各ユーザーの個々のアクセス許可を使用して動作できます。 これは、ユーザーごとのアクセス制御または監査証跡が必要な場合に使用します。

エージェントに次のコードを追加します。

from agent_server.utils import get_user_workspace_client

# In your agent code (inside @invoke or @stream)
user_workspace = get_user_workspace_client()

# Access resources with the user's permissions
response = user_workspace.serving_endpoints.query(name="my-endpoint", inputs=inputs)

大事な：アプリの起動時ではなく、get_user_workspace_client()または@invoke関数内の@streamを初期化します。 ユーザー資格情報は、要求を処理するときにのみ存在します。

スコープを構成します。 Databricks Apps UI に承認スコープを追加して、エージェントがユーザーに代わってアクセスできる API を定義します。

完全なセットアップ手順については、 ユーザー承認 を参照してください。

ステップ 5. エージェントを評価する

テンプレートには、エージェント評価コードが含まれています。 詳細については、agent_server/evaluate_agent.py を参照してください。 ターミナルで次を実行して、エージェントの応答の関連性と安全性を評価します。

uv run agent-evaluate

ステップ 6. エージェントを Databricks Apps にデプロイする

認証を構成したら、エージェントを Databricks にデプロイします。 Databricks CLI がインストールされ、構成されていることを確認します。

1. リポジトリをローカルに複製した場合は、デプロイする前に Databricks アプリを作成します。 ワークスペース UI を使用してアプリを作成した場合は、アプリと MLflow の実験が既に構成されているため、この手順をスキップします。

   databricks apps create agent-openai-agents-sdk
   

2. ローカル ファイルをワークスペースに同期します。 「 アプリのデプロイ」を参照してください。

   DATABRICKS_USERNAME=$(databricks current-user me | jq -r .userName)
   databricks sync . "/Users/$DATABRICKS_USERNAME/agent-openai-agents-sdk"
   

3. Databricks アプリをデプロイします。

   databricks apps deploy agent-openai-agents-sdk --source-code-path /Workspace/Users/$DATABRICKS_USERNAME/agent-openai-agents-sdk
   

今後エージェントを更新するには、エージェントを同期して再デプロイします。

ステップ 7. デプロイされたエージェントに対してクエリを実行する

ユーザーは、OAuth トークンを使用して、デプロイされたエージェントに対してクエリを実行します。 Databricks Apps では、個人用アクセス トークン (AT) はサポートされていません。

Databricks CLI を使用して OAuth トークンを生成します。

databricks auth login --host <https://host.databricks.com>
databricks auth token

トークンを使用してエージェントにクエリを実行します。

curl -X POST <app-url.databricksapps.com>/invocations \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

制限事項

中サイズと大きなコンピューティング サイズのみがサポートされます。 Databricks アプリのコンピューティング サイズの構成に関するページを参照してください。