Model Serving から Databricks Apps へのエージェントの移行

既存の AI エージェントを Model Serving Endpoint から Databricks Apps に移行します。

Databricks は、Model Serving よりも次の利点があるため、Databricks Apps でエージェントを作成することを推奨しています。

• 迅速なイテレーション: ローカルのデバッグ機能、および Logs とエージェントの動作に関する完全な透明性を備え、エージェントのコードとデプロイ構成を数秒で反復します。
• GitベースのバージョニングとCI/CD : モジュール式PythonエージェントコードをGitでパッケージ化およびバージョン管理し、宣言型オートメーションバンドルでデプロイします。
• AIコーディングアシスタントのサポート ：AIコーディングアシスタントを使用して、エージェントをローカルで開発および移行します。
• スケーラブルな非同期エージェント : ネイティブ Python の async パターンを使用して、より高い high concurrency を実現する非同期エージェントを構築します。
• 柔軟なサーバーのカスタマイズ ：任意のフレームワークまたはスタックを使用し、カスタムルートとミドルウェアを追加し、LLM のEndpointとツールに対するユーザーおよびエージェント認証を構成します。
• MLflow tracing : エージェントの動作を監視するために、MLflow の Git ベースの記録済みモデルとリアルタイム トレースを使用します。
• 組み込みチャットUI ：会話型エージェントTemplateには、ストリーミング、認証、永続的な履歴を備えたすぐに使えるチャットインターフェースが含まれています。

要件

• Model Serving Endpointにデプロイされた既存のエージェント。
• Databricks CLI がインストールされ、認証されました。Databricks CLI のインストールまたは更新を参照してください。
• Python 3.11 以降。
• uv パッケージ マネージャー。uv のインストールを参照してください。
• Databricks Apps がワークスペースで有効になっています。Databricks Apps ワークスペースと開発環境をセットアップするをご覧ください。

移行Templateのクローンを作成する

移行Templateは、Databricks Appsでのエージェントの開発とデプロイのための足場と、AIコーディングアシスタントに各移行ステップを実行する方法を教えるエージェントスキルファイルを提供します。

Templateをクローンして、フォルダーに移動します。

Bash

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-migration-from-model-serving

Templateフォルダーに含まれるもの：

• AGENTS.mdAIコーディングアシスタント向けの移行ワークフローを説明する手順です。
• skills/アシスタントが順番に実行する各移行ステップのスキルファイル。
• agent_server/ターゲット Databricks Apps エージェントの足場：@invoke() および @stream() ハンドラー用のプレースホルダーコード
• databricks.yml: 宣言型オートメーションバンドルの構成Templateとプレースホルダーのリソース宣言

AIアシストによる移行 (推奨)

AIを活用した移行は、このTemplateを使用するのに推奨される方法です。AIコーディングアシスタントは、AGENTS.mdとスキルファイルを読み取り、コードと構成の変更を自動的に処理します。

1. Cursor、GitHub Copilot、または Claude などの AI コーディングアシスタントで Template フォルダーを開きます。
2. アシスタントに、Endpoint名を入力して移行を実行するよう依頼してください:

Prompt

"Migrate my Model Serving endpoint `my-agent-endpoint` to a Databricks App"

1. アシスタントは移行計画を生成し、各ステップを実行します。

手動移行

Databricks は、AI コーディングアシスタントを使用して移行することをお勧めします。AIコーディングアシスタントを使用せずに移行する場合は、以下の大まかなステップでプロセスを説明します。

重要

これらのステップは概要であり、ステートフルエージェント、非同期と同期のトレードオフ、Unity Catalog のアーティファクトアクセス、複雑なリソース構成など、すべての移行シナリオを網羅しているわけではありません。

AIコーディングアシスタントを使用して移行を支援するか、詳細についてはTemplateの「migrate-from-model-servingスキル」を参照してください。

ステップ1. エージェントアーティファクトのDownload

1. Endpointからモデル名とバージョンを取得します：

Bash

databricks serving-endpoints get <endpoint-name> --output json

1. served_entities[0].entity_name (モデル名) と entity_version を応答で探し、アーティファクトをダウンロードしてください：

Bash

DATABRICKS_CONFIG_PROFILE=<profile> uv run --no-project \
  --with "mlflow[databricks]>=2.15.0" \
  python3 << 'EOF'
import mlflow
mlflow.set_tracking_uri("databricks")
mlflow.artifacts.download_artifacts(
    artifact_uri="models:/<model-name>/<version>",
    dst_path="./original_mlflow_model"
)
EOF

ダウンロードしたフォルダーの内容：

• MLmodel 元のエージェントのリソース宣言。
• code/ エージェントの Python ソースファイル
• artifacts/ オプションの構成ファイルとプロンプト
• input_example.json テスト用のサンプルリクエスト

ステップ 2. エージェントコードの移行

code/のすべてのPythonファイルをagent_server/に、およびartifacts/の任意のアーティファクトをagent_server/artifacts/にコピーします。

ファイルを移動した後、新しいフォルダー構造を反映するように、関連するインポートとハードコードされたファイルパスを更新してください。次に、ステップ 3 に示すパターンを使用するように agent_server/agent.py を書き換えます。

ステップ 3: エージェントコードを変換する

Model Serving では、エージェントは predict() と predict_stream() メソッドを持つクラスベースの ResponsesAgent を使用します。Databricks Apps では、MLflow AgentServer が @invoke() と @stream() で装飾されたモジュールレベルの関数を提供します。

移行する際は、以下のパターンのいずれかを選択してください。

• 非同期 (推奨) ：Python async defとawaitを使用して、複数のリクエストを同時に処理します。あるリクエストがLLMの応答を待っている間、サーバーは他のリクエストを処理します。
• **同期**: Model Servingエージェントの同期Pythonパターンを保持します。最小限の移行の場合、またはコードが同期専用のライブラリに依存している場合は、これを選択してください。

Model Serving (before)

元のクラスベースのエージェント構造です。

Python

from mlflow.pyfunc import ResponsesAgent, ResponsesAgentRequest, ResponsesAgentResponse

class MyAgent(ResponsesAgent):
  def predict(self, request: ResponsesAgentRequest, params=None) -> ResponsesAgentResponse:
    # Synchronous implementation
    ...
    return ResponsesAgentResponse(output=outputs)

  def predict_stream(self, request: ResponsesAgentRequest, params=None):
    # Synchronous generator
    for chunk in ...:
      yield ResponsesAgentStreamEvent(...)

Apps — async (recommended)

プライマリエージェントロジックはstreaming()にあります。non_streaming()関数は、その出力を収集し、単一の応答として返します。

Python

from mlflow.genai.agent_server import invoke, stream
from mlflow.types.responses import (
  ResponsesAgentRequest,
  ResponsesAgentResponse,
  ResponsesAgentStreamEvent,
)

@invoke()
async def non_streaming(request: ResponsesAgentRequest) -> ResponsesAgentResponse:
  # Async implementation - typically calls streaming() and collects results
  outputs = [
    event.item
    async for event in streaming(request)
    if event.type == "response.output_item.done"
  ]
  return ResponsesAgentResponse(output=outputs)

@stream()
async def streaming(request: ResponsesAgentRequest) -> AsyncGenerator[ResponsesAgentStreamEvent, None]:
  # Async generator
  async for event in ...:
    yield event

Apps — sync

クラスメソッドを装飾されたモジュールレベルの関数に、最小限の構造変更で抽出します。

Python

from mlflow.genai.agent_server import invoke, stream
from mlflow.types.responses import (
  ResponsesAgentRequest,
  ResponsesAgentResponse,
  ResponsesAgentStreamEvent,
)

@invoke()
def non_streaming(request: ResponsesAgentRequest) -> ResponsesAgentResponse:
  # Same sync logic from original predict(), extracted from the class
  ...
  return ResponsesAgentResponse(output=outputs)

@stream()
def streaming(request: ResponsesAgentRequest):
  # Same sync generator from original predict_stream(), extracted from the class
  for chunk in ...:
    yield ResponsesAgentStreamEvent(...)

ステップ 4: アプリを設定する

1. 依存関係をインストールします。これにより、pyproject.tomlの依存関係が解決され、再現性のあるインストールができるように、それらをピン留めするuv.lockファイルが作成されます。

   Bash

   uv sync

2. クイックスタートスクリプトを実行して、認証を構成し、MLflowエクスペリメントを作成し、.envファイルを生成します。

   Bash

   uv run quickstart

デプロイ時にDatabricks Appsが同じピン留めされた依存関係をインストールするように、生成されたuv.lockファイルをcommitしてください。

ステップ 5: ローカルでテストする

デプロイする前に、アプリサーバーを起動し、エージェントが正しく応答することを確認してください。

curlを使用して元のinput_example.jsonでテストし、エージェントが期待どおりに応答したらデプロイします。

ステップ 6: リソースを設定します。

Model Servingエージェントは、MLmodelファイルでリソースを宣言します。Databricks Appsエージェントは、宣言型オートメーションバンドルを使用してdatabricks.yml構成ファイルでリソースを宣言します。

AI エージェントの認証を参照してください。

リソース宣言を同等の宣言型オートメーションバンドル形式にマップします:

MLmodel リソースタイプ	databricks.yml 同等	権限
serving_endpoint	serving_endpoint	CAN_QUERY
lakebase	database	CAN_CONNECT_AND_CREATE
vector_search_index	uc_securable （securable_type: TABLE）	SELECT
function	uc_securable （securable_type: FUNCTION）	EXECUTE
table	uc_securable （securable_type: TABLE）	SELECT または MODIFY
uc_connection	uc_securable （securable_type: CONNECTION）	USE_CONNECTION
sql_warehouse	sql_warehouse	CAN_USE
genie_space	genie_space	CAN_RUN

MLmodel リソースタイプ	databricks.yml 同等	権限
serving_endpoint	serving_endpoint	CAN_QUERY
lakebase	database	CAN_CONNECT_AND_CREATE
vector_search_index	uc_securable （securable_type: TABLE）	SELECT
function	uc_securable （securable_type: FUNCTION）	EXECUTE
table	uc_securable （securable_type: TABLE）	SELECT または MODIFY
uc_connection	uc_securable （securable_type: CONNECTION）	USE_CONNECTION
sql_warehouse	sql_warehouse	CAN_USE
genie_space	genie_space	CAN_RUN

ステップ7。宣言型オートメーションバンドルを使用してエージェントをデプロイします。

Declarative Automation Bundlesを使用して、エージェントをDatabricks Appsにデプロイします。

デプロイする前に、フォルダ構造が以下のようになっていることを確認してください。

<working-directory>/
├── original_mlflow_model/    # Downloaded artifacts from Model Serving
│   ├── MLmodel
│   ├── code/
│   │   └── agent.py
│   ├── input_example.json
│   └── requirements.txt
│
└── <app-name>/               # New Databricks App (ready to deploy)
    ├── agent_server/
    │   ├── agent.py          # Migrated agent code
    │   └── ...
    ├── app.yaml
    ├── databricks.yml        # Bundle config with resources
    ├── pyproject.toml        # Python dependencies (uv)
    ├── uv.lock               # Pinned dependencies for reproducible installs
    └── ...

注記

Databricks は Python 依存関係管理のために uv (pyproject.toml + uv.lock) を推奨しています。これにより、より高速なインストールと再現可能なビルドが提供されます。アプリにpyproject.tomlとuv.lockが含まれていてrequirements.txtがない場合、Databricks Apps は依存関係をインストールするためにuvを使用します。requirements.txt は引き続きサポートされます。存在する場合、常に優先され、Databricks Apps は代わりに pip を使用します。Databricks Apps のベストプラクティスおよびuv を使用して Python 依存関係を定義するを参照してください。

1. バンドル構成を検証する：

   Bash

   databricks bundle validate

2. バンドルをワークスペースにデプロイします (bundle deploy はファイルを upload しますが、アプリは起動しません)：

   Bash

   databricks bundle deploy

3. アプリを起動：

   Bash

   databricks bundle run <app-resource-name>

その他のリソース

エージェントの移行後、以下を参照してください：

• AIエージェントを作成して Databricks Apps にデプロイする
• カスタムコードエージェントをデバッグします
• AIエージェントの認証
• AIコーディングアシスタントのエージェントスキル
• Databricks Appsのネットワークを構成する