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

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

すべての会話 エージェント テンプレート には、追加のセットアップを必要とせず、組み込みのチャット UI (上記) が含まれています。 チャット UI では、ストリーミング応答、マークダウン レンダリング、Databricks 認証、およびオプションの常設チャット履歴がサポートされます。

必要条件

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

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

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

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

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

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

ワークスペース UI

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

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

2. エージェント>カスタム エージェント (OpenAI 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. エージェント アプリケーションを理解する

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

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

組み込みのチャット UI

エージェント テンプレートは、 チャット アプリ テンプレート をフロントエンドとして自動的にフェッチして実行します。 このチャット UI は、同じ Databricks Apps デプロイにバンドルされ、エージェントと共に提供されるため、追加のセットアップは必要ありません。

プロジェクトでチャット UI を直接カスタマイズできます。 常設チャット履歴やユーザー フィードバック収集を有効にする方法など、チャット アプリの機能の詳細については、「 Databricks Apps でチャット UI を構築して共有する」を参照してください。

MLflow AgentServer

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

ResponsesAgent インターフェイス

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

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

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

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

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

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

  • 任意のフレームワークを使用してエージェントを作成する: ResponsesAgent インターフェイスを使用して既存のエージェントをラップして、AI Playground、Agent Evaluation、Agent Monitoring とのすぐに使用できる互換性を実現します。
  • Typed オーサリングインターフェース: 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 を開発してデプロイできます。

ステップ 3。 エージェントにツールを追加する

MCP サーバーに接続して、データベースのクエリ、ドキュメントの検索、外部 API の呼び出しなどのエージェント機能を提供します。 エージェント テンプレートには、既定の MCP サーバー接続が含まれています。 さらにツールを追加するには、エージェント コードで追加の MCP サーバーを構成し、 databricks.ymlで必要なアクセス許可を付与します。

サポートされているツールの種類とコード例については、 AI エージェント ツールを参照してください。

ローカル Python関数ツールの定義

外部データ ソースや API を必要としない操作の場合は、エージェント コードでツールを直接定義します。 これらのツールはエージェントと同じプロセスで実行され、データ変換、計算、またはユーティリティ操作に役立ちます。

OpenAI Agents SDK

OpenAI Agents SDK の @function_tool デコレーターを使用します。

from agents import Agent, function_tool

@function_tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time],
)

LangGraph

LangChain の @tool デコレーターを使用します。

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from databricks_langchain import ChatDatabricks

@tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=[get_current_time],
)

ローカル関数ツールは、エージェント プロセス内で実行されるため、 databricks.yml でリソース許可を必要としません。

手順 4. Unity AI Gateway を使用して Databricks Apps 上のエージェントから LLM の使用を管理する

AI ゲートウェイ (ベータ) を介してエージェントの LLM 呼び出しをルーティングし、どのプロバイダーが応答するかに関係なく、すべての要求が同じコントロールによって制御されるようにします。 要求パスにゲートウェイを使用すると、エージェント コードを変更したり、プロバイダーの資格情報をローテーションしたりすることなく、アクセス許可の一元化、アプリごとの属性コストの設定、モデルのスワップ、トラフィックの検査または再生を行うことができます。

1. ワークスペースで AI ゲートウェイを有効にします。 AI ゲートウェイはベータ期間中にオプトインされます。 ゲートウェイ エンドポイントを作成またはクエリする前に、アカウント管理者がアカウント コンソール の [プレビュー ] ページから有効にする必要があります。 Manage Azure Databricks プレビューを参照してください。

2. AI ゲートウェイ エンドポイントでエージェントをポイントします。 エージェント コードで、ai Gateway エンドポイント名を model 引数として渡し、Azure Databricks LLM クライアントに use_ai_gateway=True を設定します。 クライアントはゲートウェイ経由でトラフィックをルーティングし、認証を自動的に処理します。

   OpenAI

   from agents import Agent, set_default_openai_api, set_default_openai_client
   from databricks_openai import AsyncDatabricksOpenAI
   
   set_default_openai_client(AsyncDatabricksOpenAI(use_ai_gateway=True))
   set_default_openai_api("chat_completions")
   
   agent = Agent(
       name="Agent",
       instructions="You are a helpful assistant.",
       model="<ai-gateway-endpoint>",
   )
   

   LangGraph

   from databricks_langchain import ChatDatabricks
   
   llm = ChatDatabricks(
       model="<ai-gateway-endpoint>",
       use_ai_gateway=True,
   )
   

   その他の API サーフェス (OpenAI Responses API、Anthropic Messages API、Google Gemini) と REST の例については、「Query Unity AI Gateway エンドポイントを参照してください。

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

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

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

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

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 に移動して組み込みのチャット UI を開き、エージェントとのチャットを開始します。

手順 6. 認証を構成する

Azure Databricks リソースにアクセスするには、エージェントに認証が必要です。 Databricks Apps には、アプリ承認 (サービス プリンシパル) とユーザー承認 (ユーザー代理) の 2 つの認証方法が用意されています。 ワークスペース UI を使用して構成するか、宣言型オートメーション バンドルを使用して databricks.yml で宣言的に構成できます。 エージェント テンプレートには databricks.ymlが付属しているため、テンプレートから開始するときにパスが既定になります。

サポートされているすべてのリソースの種類、アクセス許可の値、エンド ツー エンドの databricks.yml チュートリアルなど、完全なリファレンスについては、「 AI エージェントの認証」を参照してください。

アプリの承認 (既定)

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

エージェントがresources.apps.<app>.resourcesのdatabricks.ymlで使用するすべてのリソースを宣言します。 バンドルをデプロイして、宣言されたアクセス許可をサービス プリンシパルに付与します。

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_TRACKING_URI
            value: 'databricks'
          - name: MLFLOW_REGISTRY_URI
            value: 'databricks-uc'
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'
        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

リソースの種類の完全な一覧については、「 アプリの承認」を参照してください。

ユーザーの承認

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

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

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)

user_api_scopes のアプリで databricks.yml の下にスコープを追加して、エージェントがユーザーに代わって呼び出すことができるAzure Databricks API を構成します。

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

使用可能なスコープの一覧と完全なセットアップ手順については、「 ユーザー承認」を参照してください。

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

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

uv run agent-evaluate

手順 8. エージェントを Databricks Apps にデプロイする

認証を構成したら、エージェントを Azure Databricks にデプロイします。 エージェント テンプレートでは、デプロイに Databricks アセット バンドル (DAB) が 使用されます。 テンプレートの databricks.yml ファイルは、アプリの構成とリソースのアクセス許可を定義します。 Databricks CLI がインストールされ、構成されていることを確認します。

1. デプロイする前に、バンドル構成を検証してエラーをキャッチします。

   databricks bundle validate
   

2. バンドルをデプロイします。 これにより、コードがアップロードされ、 databricks.ymlで定義されているリソース (MLflow 実験、サービス エンドポイントなど) が構成されます。

   databricks bundle deploy
   

3. アプリを起動または再起動します。

   databricks bundle run agent_openai_agents_sdk
   

   注

   bundle deploy は、ファイルのアップロードとリソースの構成のみを行います。 bundle run は、新しいコードでアプリを起動または再起動するために必要です。

今後の更新については、 databricks bundle deploy を実行してから、再デプロイ databricks bundle run agent_openai_agents_sdk 。

手順 9 デプロイされたエージェントに対してクエリを実行する

次の例では、OAuth トークンを使用してクイック curl 要求を使用します。 Databricks Apps では、個人用アクセス トークン (AT) はサポートされていません。

Databricks OpenAI クライアントと REST API を含むクエリ メソッドの完全な一覧については、「Azure Databricks にデプロイされたエージェントのQuery」を参照してください。

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

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

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

curl -X POST <app-url.databricksapps.com>/responses \
   -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 では、レビューとフィードバックのサポートを チャットボット テンプレートに直接組み込んでいます。

次のステップ

• Databricks Apps エージェントをロード テストする