エージェントをモデルサービングからDatabricks Appsに移行する

既存のAIエージェントをモデルサービングエンドポイントからDatabricks Appsに移行します。

Databricks 、モデルサービングに比べて次の利点があるため、 Databricks Appsでエージェントを作成することをお勧めします。

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

要件

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

移行テンプレートを複製する

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

テンプレートを複製し、次のフォルダに移動します。

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

テンプレートフォルダーには次のものが含まれます。

AGENTS.md: 移行ワークフローを説明する AI コーディングアシスタント向けの手順
skills/: アシスタントによって順番に実行される各移行ステップのスキルファイル
agent_server/: @invoke()および@stream()ハンドラーのプレースホルダーコードを含むターゲット Databricks Apps エージェントのスキャフォールディング
databricks.yml: プレースホルダーリソース宣言を含む宣言型自動化バンドル構成テンプレート

AI支援による移行（推奨）

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

Cursor、GitHub Copilot、Claude などの AI コーディングアシスタントでテンプレートフォルダーを開きます。
エンドポイント名を指定して、アシスタントに移行を実行するように依頼します。

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

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

エージェントをモデルサービングからDatabricks Appsに移行するためのステップバイステップの TODO リストを表示するAIコーディングアシスタントのスクリーンショット。

手動移行

Databricks では、移行を実行するために AI コーディングアシスタントを使用することを推奨しています。AIコーディングアシスタントを使用せずに移行する場合は、次の概要でプロセスについて説明します。

重要

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

移行を支援する AI コーディングアシスタントを使用するか、テンプレートのmigrate-from-model-servingスキルで詳細情報を確認してください。

ステップ 1. エージェントアーティファクトをダウンロードする

エンドポイントからモデル名とバージョンを取得します。

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

応答で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. エージェントコードを移行する

すべてのPythonファイルをcode/からagent_server/にコピーし、アーティファクトをartifacts/からagent_server/artifacts/にコピーします。

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

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

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

移行するときは、次のいずれかのパターンを選択します。

非同期 (推奨) : Python async defとawaitを使用して複数のリクエストを同時に処理します。1 つの要求が LLM 応答を待機している間に、サーバーは他の要求を処理します。
同期 : モデルサービングエージェントからの同期Pythonパターンを保持します。最小限の移行の場合、またはコードが同期のみのライブラリに依存している場合は、これを選択します。

Model Serving (before)
Apps — async (recommended)
Apps — sync

オリジナルのクラスベースのエージェント構造。

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(...)

主なエージェントロジックは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

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

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. アプリをセットアップする

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

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

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

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

ステップ 6. リソースを設定する

モデルサービングエージェントは、 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` (セキュリティ保護可能なタイプ: `TABLE` )	`SELECT`
`function`	`uc_securable` (セキュリティ保護可能なタイプ: `FUNCTION` )	`EXECUTE`
`table`	`uc_securable` (セキュリティ保護可能なタイプ: `TABLE` )	`SELECT` または `MODIFY`
`uc_connection`	`uc_securable` (セキュリティ保護可能なタイプ: `CONNECTION` )	`USE_CONNECTION`
`sql_warehouse`	`sql_warehouse`	`CAN_USE`
`genie_space`	`genie_space`	`CAN_RUN`

ステップ 7. 宣言型自動化バンドルを使用してエージェントをデプロイする

宣言型自動化バンドルを使用して、 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
    ├── requirements.txt
    └── ...

注記

Databricks Apps pyproject.tomlから依存関係をインストールできるように、アプリフォルダー内のrequirements.txtファイルにはuvが含まれている必要があります。

バンドル構成を検証します。
Bash
```
databricks bundle validate
```
バンドルをワークスペースにデプロイします ( bundle deployファイルをアップロードしますが、アプリは起動しません)。
Bash
```
databricks bundle deploy
```

アプリを起動：

Bash
databricks bundle run <app-resource-name>

次のステップ

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

要件​

移行テンプレートを複製する​

AI支援による移行（推奨）​

手動移行​

ステップ 1. エージェント アーティファクトをダウンロードする​

ステップ 2. エージェント コードを移行する​

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

ステップ 4. アプリをセットアップする​

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

ステップ 6. リソースを設定する​

ステップ 7. 宣言型自動化バンドルを使用してエージェントをデプロイする​

次のステップ​

要件