Databricks Appsでエージェントをデプロイする - モデルサービングとの使い分け

Posted at 2026-02-03

はじめに

Databricks Agent Frameworkでは、AIエージェントをデプロイする方法として2つの選択肢があります。

モデルサービングエンドポイントにデプロイ
Databricks Appsにデプロイ

本記事では、後者のDatabricks Appsへのデプロイ方法と、テンプレートで使われているuv run quickstartコマンドがなぜ動作するのかを解説します。

モデルサービングエンドポイント vs Databricks Apps

エージェントのデプロイ先として、それぞれの特徴を理解しておくことが重要です。

モデルサービングエンドポイント

項目	内容
インフラ管理	Databricksが自動管理
スケーリング	自動スケーリング
カスタマイズ性	限定的
デプロイ方法	`mlflow.models.set_model()` + Unity Catalogへの登録
適したユースケース	標準的なエージェントを素早くデプロイしたい場合

Databricks Apps

項目	内容
インフラ管理	開発者がコントロール可能
スケーリング	手動設定(中/大サイズのみ)
カスタマイズ性	高い(サーバー構成、UIなど自由)
デプロイ方法	Databricks CLIでソースコードをデプロイ
適したユースケース	カスタムUI、Git連携、ローカル開発が必要な場合

Databricks Appsを選ぶべきケース:

カスタムのチャットUIを提供したい
Gitベースのバージョン管理でCI/CDを構築したい
ローカルIDEで開発・デバッグしたい
サーバーの動作を細かくカスタマイズしたい

uv run quickstart が動く仕組み

テンプレートをクローンしてuv run quickstartを実行すると、環境構築からアプリの初期設定まで一発で完了します。これがなぜ動くのか見ていきましょう。

uvとは

uvはRust製の高速なPythonパッケージマネージャーです。pipやPoetryの代替として、10〜100倍高速な依存関係解決とインストールを実現します。

pyproject.tomlのscriptsセクション

秘密はpyproject.tomlの[project.scripts]セクションにあります:

[project.scripts]
quickstart = "scripts.quickstart:main"
start-app = "scripts.start_app:main"
start-server = "agent_server.start_server:main"
agent-evaluate = "agent_server.evaluate_agent:evaluate"
discover-tools = "scripts.discover_tools:main"

これはPython標準のエントリーポイント仕様(PEP 621)に準拠した定義です。

uv runの動作フロー

uv run quickstartを実行すると、以下の処理が自動的に行われます:

プロジェクト認識: カレントディレクトリのpyproject.tomlを検出
仮想環境作成: .venvディレクトリに仮想環境を作成
依存関係の解決・インストール: uv.lockと環境を同期
プロジェクトのインストール: 現在のプロジェクト自体をeditable modeでインストール
スクリプト実行: scripts/quickstart.pyのmain()関数を実行

これはnpm run <script>(package.jsonのscriptsセクション)と同様の発想ですが、Python標準仕様に準拠している点がポイントです。

なぜこれが便利か

仮想環境を明示的にアクティベートする必要がない
依存関係が自動的に同期される
プロジェクト固有のコマンドを簡潔に実行できる
チーム全員が同じコマンドで同じ環境を再現できる

実際にやってみる

前提条件

DatabricksワークスペースでDatabricks Appsが有効化されていること
以下のツールがインストールされていること:
- uv
- nvm + Node 20 LTS
- Databricks CLI

手順1: テンプレートのクローン

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

クローンすると、CLAUDE.mdやAGENTS.mdが含まれているので、Claude Codeなどで活用できます。

手順2: quickstartの実行

uv run quickstart

初回実行時は依存関係のダウンロードに時間がかかります。scipyなどの大きなパッケージでタイムアウトが発生する場合は、タイムアウト値を増やしてください:

UV_HTTP_TIMEOUT=120 uv run quickstart

実行結果:

Installed 152 packages in 1.01s

===================================================================
Agent on Apps - Quickstart Setup
===================================================================

Checking prerequisites...
✓ uv is installed: uv 0.6.11 (0632e24d1 2025-03-30)
✓ node is installed: v22.14.0
✓ npm is installed: 10.9.2
✓ databricks is installed: Databricks CLI v0.280.0

Setting up configuration files...
✓ Copied .env.example to .env

Setting up Databricks authentication...

Found existing Databricks profiles:

  1) DEFAULT        https://xxxx.cloud.databricks.com          YES

Enter the number of the profile you want to use: 1

Selected profile: DEFAULT
✓ Successfully validated profile 'DEFAULT'
✓ Databricks profile 'DEFAULT' saved to .env

Getting Databricks username...
Username: takaaki.yayoi@databricks.com

Creating MLflow experiment...
✓ Created experiment '/Users/takaaki.yayoi@databricks.com/agents-on-apps' with ID: 2041467277079449
✓ Updated .env with experiment ID

===================================================================
Setup Complete!
===================================================================

✓ Prerequisites verified (uv, Node.js, Databricks CLI)
✓ Databricks authenticated with profile: DEFAULT
✓ Configuration files created (.env)
✓ MLflow experiment created: /Users/takaaki.yayoi@databricks.com/agents-on-apps
✓ Experiment ID: 2041467277079449

Next step: Run 'uv run start-app' to start the agent locally

手順3: アプリの起動

uv run start-app

ブラウザで http://localhost:8000 にアクセスすると、エージェントとチャットできるUIが表示されます。

チャットUIの画面:

手順4: Databricksへのデプロイ

アプリの作成

databricks apps create agent-openai-agents-sdk

ファイルの同期

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

デプロイ

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

手順5: エージェントの評価

テンプレートにはMLflowを使った評価コードも含まれています:

uv run agent-evaluate

テンプレートのアーキテクチャ

このテンプレートは以下のコンポーネントで構成されています:

コンポーネント	役割
MLflow AgentServer	トレースと監視機能を備えた非同期FastAPIサーバー
OpenAI Agents SDK	会話管理とツールオーケストレーションのフレームワーク
ResponsesAgent	様々なフレームワークとの互換性を保証するインターフェース
MCP Server	Databricksリソースへのアクセスを提供

ResponsesAgentインターフェースでラップすることで、AI Playground、エージェント評価、Databricks Appsデプロイとの互換性が自動的に得られます。

まとめ

Databricks Appsはカスタマイズ性が高く、ローカル開発やGit連携が必要な場合に最適
uv runはpyproject.tomlの[project.scripts]で定義されたエントリーポイントを実行する仕組み
テンプレートを使えばuv run quickstart一発で環境構築が完了
タイムアウトエラーが出たらUV_HTTP_TIMEOUT環境変数で対処