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

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

エージェントチャットUIプレビュー

すべての会話エージェントテンプレートには、追加の設定を必要としない組み込みのチャット UI (上記に表示) が含まれています。チャット UI は、ストリーミング応答、マークダウンレンダリング、Databricks 認証、オプションの永続的なチャット履歴をサポートします。

必要条件

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

ステップ 1. エージェントアプリテンプレートのクローンを作成します

Databricks アプリテンプレートリポジトリから事前に構築されたエージェントテンプレートを使用して開始します。

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

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

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

Workspace UI
Clone from GitHub

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

Databricks ワークスペースで、 [+ 新規] > [アプリ] をクリックします。
[エージェント] > [エージェント - OpenAI エージェント SDK] をクリックします。
openai-agents-templateという名前で新しいMLflowエクスペリメントを作成し、残りのセットアップを完了してテンプレートをインストールします。
アプリを作成したら、アプリの URL をクリックしてチャット UI を開きます。

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

ファイルの同期 の最初のコマンドをコピーします
ローカルターミナルで、コピーしたコマンドを実行します。

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

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

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

エージェントテンプレートは、これらの主要なコンポーネントを備えた本番運用対応のアーキテクチャを示しています。各コンポーネントの詳細については、次のセクションを参照してください。

アプリ上のエージェントの簡単な図

各コンポーネントの詳細については、次のセクションを参照してください。

MLflow エージェントサーバー

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

ResponsesAgentインターフェース

Databricks では、エージェントの構築に MLflow ResponsesAgentを推奨しています。ResponsesAgent使用すると、任意のサードパーティフレームワークを使用してエージェントを構築し、それをDatabricks AI機能と統合して、強力なログ記録、トレース、評価、展開、モニタリング機能を実現できます。

ResponsesAgent は、Databricks との互換性のために既存のエージェントを簡単にラップします。

ResponsesAgent作成方法については、 MLflowドキュメントの例 (ResponsesAgent for モデルサービング)を参照してください。

ResponsesAgent 次の利点があります。

高度なエージェント機能
- マルチエージェントのサポート
- ストリーミング出力 : 出力を小さなチャンクでストリームします。
- 包括的なツール呼び出しメッセージ履歴 : 中間ツール呼び出しメッセージを含む複数のメッセージを返し、品質と会話管理を向上させます。
- ツールコール確認支援
- 長期実行ツールのサポート
開発、デプロイ、モニタリングの効率化
- 任意のフレームワークを使用してエージェントを作成する : ResponsesAgent インターフェイスを使用して既存のエージェントをラップし、 AI Playground、エージェント評価、エージェントモニタリングとのすぐに使用できる互換性を実現します。
- 型付きオーサリングインターフェイス :型付きPythonクラスを使用してエージェントコードを記述し、IDEとノートブックのオートコンプリートの恩恵を受けます。
- 自動トレース : MLflow は、ストリームされた応答をトレースに自動的に集約し、評価と表示を容易にします。
- OpenAI Responsesスキーマと互換性があります 。OpenAI : Responses vs. ChatCompletion を参照してください。

OpenAI エージェント SDK

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

MCP（モデルコンテキストプロトコル）サーバー

テンプレートはDatabricks MCP サーバーに接続し、エージェントがツールやデータソースにアクセスできるようにします。 Databricks のモデルコンテキストプロトコル (MCP) を参照してください。

AIコーディングアシスタントを活用したエージェントの開発

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

高度なオーサリングトピック

ストリーミング応答

ストリーミングを使用すると、エージェントは完全な応答を待つ代わりに、リアルタイムのチャンクで応答を送信できます。ResponsesAgentを使用してストリーミングを実装するには、一連のデルタイベントとそれに続く最終完了イベントを発行します。

デルタイベントを出力する : 同じitem_idで複数のoutput_text.deltaイベントを送信して、ストリームテキストチャンクリアルタイム。
完了イベントで終了 : 完全な最終出力テキストを含むデルタイベントと同じitem_idで最終response.output_item.doneイベントを送信します。

各デルタイベントは、テキストのチャンクをクライアントにストリームします。最終的な done イベントには完全な応答テキストが含まれ、Databricks に次の操作を行うように通知します。

MLflow トレースを使用してエージェントの出力をトレースする
AI Gateway推論テーブルでのストリームレスポンスの集計
AI Playground UI で完全な出力を表示する

ストリーミングエラーの伝播

Mosaic AI は、ストリーミング中に発生したエラーを databricks_output.errorの下の最後のトークンで伝播します。このエラーを適切に処理して表示するのは、呼び出し元のクライアント次第です。

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

カスタム入力と出力

一部のシナリオでは、 client_type や session_idなどの追加のエージェント入力や、将来の対話のためにチャット履歴に含めるべきではない取得ソースリンクなどの出力が必要になる場合があります。

これらのシナリオでは、MLflow ResponsesAgentはフィールドcustom_inputsとcustom_outputsをネイティブにサポートします。上記のフレームワークの例では、 request.custom_inputsを介してカスタム入力にアクセスできます。

エージェント評価レビューアプリは、追加の入力フィールドを持つエージェントのレンダリングトレースをサポートしていません。

AI Playgroundとレビューアプリでcustom_inputsを提供します

エージェントが custom_inputs フィールドを使用して追加の入力を受け入れる場合は、 AI Playground とレビューアプリの両方でこれらの入力を手動で提供できます。

AI Playground または Agent Review App で、歯車アイコンを選択します。
custom_inputs を有効にします。
エージェントの定義済み入力スキーマに一致するJSONオブジェクトを提供します。

カスタムリトリーバースキーマ

AI エージェントは通常、リトリーバーを使用して、ベクトル検索インデックスから非構造化データを検索およびクエリします。サンプルリトリーバーツールについては、「エージェントを非構造化データに接続する」を参照してください。

MLflow RETRIEVER スパンを使用してエージェント内でこれらのレトリーバーをトレースし、次のような Databricks 製品の機能を有効にします。

取得したソースドキュメントへのリンクを AI Playground UI に自動的に表示する
Agent Evaluation で自動的に実行される検索の根拠と関連性のジャッジ

注記

Databricks recommends using retriever tools provided by Databricks AI Bridge packages like databricks_langchain.VectorSearchRetrieverTool and databricks_openai.VectorSearchRetrieverTool because they already conform to the MLflow retriever schema. See Locally develop Vector Search retriever tools with AI Bridge.

エージェントにカスタムスキーマのレトリーバースパンが含まれている場合は、コードでエージェントを定義するときに mlflow.models.set_retriever_schema を呼び出します。これにより、レトリーバーの出力列が MLflow の予期されるフィールド (primary_key、 text_column、 doc_uri) にマップされます。

Python
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"],
)

注記

The doc_uri column is especially important when evaluating the retriever's performance. doc_uri is the main identifier for documents returned by the retriever, allowing you to compare them against ground truth evaluation sets. See Evaluation sets (MLflow 2).

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

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

uv (Python パッケージマネージャー)、 nvm (Node バージョンマネージャー)、および Databricks CLI をインストールします。
- uv インストール
- nvm インストール
- Node 20 LTS を使用するには、以下を実行します。
  Bash
```
nvm use 20
```
- databricks CLI インストール
ディレクトリをagent-openai-agents-sdkフォルダーに変更します。
提供されているクイックスタートスクリプトを実行して依存関係をインストールし、環境をセットアップしてアプリを起動します。
Bash
```
uv run quickstart
uv run start-app
```

ブラウザでhttp://localhost:8000にアクセスし、組み込みのチャット UI を開いてエージェントとのチャットを開始します。

ステップ 4. 認証を構成する

エージェントが Databricks リソースにアクセスするには認証が必要です。Databricks Apps 、次の 2 つの認証方法が提供されます。

App authorization (default)
User authorization

アプリの承認では、 Databricksアプリ用に自動的に作成するサービスプリンシパルを使用します。すべてのユーザーは同じ権限を共有します。

MLflowエクスペリメントにアクセス許可を付与します。

アプリのホームページで 「編集」を クリックします。
構成ステップに移動します。
[アプリリソース] セクションで、 Can Edit権限を持つMLflowエクスペリメントリソースを追加します。

他のリソース (「検索」、 Genie spaces 、「サービス提供エンドポイント」) についても、同様に 「アプリリソース」 セクションに追加します。

詳細については、アプリの承認を参照してください。

ユーザー認証により、エージェントは各ユーザーの個別の権限で動作できるようになります。ユーザーごとのアクセス制御や監査証跡が必要な場合に使用します。

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

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

重要: アプリの起動時ではなく、 @invokeまたは@stream関数内でget_user_workspace_client()初期化してください。ユーザー資格情報はリクエストを処理するときにのみ存在します。

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

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

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

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

Bash
uv run agent-evaluate

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

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

リポジトリをローカルに複製した場合は、デプロイする前に Databricks アプリを作成します。ワークスペース UI を通じてアプリを作成した場合は、アプリとMLflowエクスペリメントがすでに構成されているため、このステップをスキップしてください。
Bash
```
databricks apps create agent-openai-agents-sdk
```

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

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

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

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

以降のエージェントの更新については、エージェントを同期して再デプロイしてください。

ステップ 7. デプロイされたエージェントをクエリする

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

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

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

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

Bash
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アプリのコンピュートサイズを構成するを参照してください。
MLflow Review App Chat UI は現在、 Databricks Appsにデプロイされたエージェントをサポートしていません。既存のトレースを評価するには、展開方法に関係なく機能するラベル付けセッションを使用します。Databricks は、チャットボットテンプレートにレビューとフィードバックのサポートを直接組み込んでいます。

必要条件​

ステップ 1. エージェント アプリ テンプレートのクローンを作成します​

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

AIコーディングアシスタントを活用したエージェントの開発​

高度なオーサリングトピック​

ストリーミング応答​

カスタム入力と出力​

カスタム リトリーバー スキーマ​

ステップ 3. エージェント アプリをローカルで実行する​

ステップ 4. 認証を構成する​

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

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

ステップ 7. デプロイされたエージェントをクエリする​

制限事項​