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

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

ヒント

エージェントがDatabricksでホストされているツールのみを使用し、ツール呼び出し間にカスタムロジックを必要としない場合、Supervisor API (Beta) を使用してDatabricksにエージェントループを管理させることができます。

すべての会話型エージェント**Template**には、**組み込み**のチャットUI (上記参照) が付属しており、追加のセットアップは不要です。チャットUIは、**ストリーミング**応答、Markdownレンダリング、**Databricks**認証、およびオプションの永続的なチャット履歴に対応しています。

要件

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

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

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

このチュートリアルでは、agent-openai-agents-sdk Templateを使用しています。これには以下が含まれます。

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

Templateをセットアップするには、以下のいずれかのパスを選択してください：

Workspace UI

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

1. Databricksワークスペースで、**+ 新規** > **アプリ** をクリックします。

2. **エージェント** > **カスタムエージェント (OpenAI SDK)**をクリックします。

3. openai-agents-templateという名前で新しいMLflowエクスペリメントを作成し、残りのセットアップを完了してテンプレートをインストールします。

4. アプリを作成したら、アプリのURLをクリックしてチャットUIを開きます。

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

1. **ファイルを同期**の下にある最初のコマンドをコピーします。

   

2. ローカルターミナルで、コピーしたコマンドを実行します。

Clone from GitHub

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

Bash

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

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

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

各コンポーネントの詳細については、以下のセクションを開いてください：

組み込みチャットUI

エージェントTemplateは、チャットアプリTemplateをフロントエンドとして自動的にフェッチして実行します。このチャットUIは同じDatabricks Appsデプロイメントにバンドルされ、エージェントと共に提供されるため、追加の設定は不要です。

プロジェクトでチャットUIを直接カスタマイズできます。永続的なチャット履歴とユーザーフィードバックの収集を有効にする方法を含め、チャットアプリの機能の詳細については、Databricks Apps を使用してチャット UI を構築および共有するを参照してください。

MLflow AgentServer

組み込みのトレースと可観測性を備え、エージェントのリクエストを処理する非同期FastAPIサーバー。AgentServerは、エージェントをクエリするための/responsesEndpointを提供し、リクエストのルーティング、ログ記録、エラー処理を自動的に管理します。

ResponsesAgentインターフェース

Databricksは、エージェントを構築するためにMLflow ResponsesAgent を推奨しています。ResponsesAgent を使用すると、任意のサードパーティ製フレームワークでエージェントを構築し、堅牢なロギング、トレース、評価、デプロイ、モニタリング機能のためにDatabricks AI機能と統合できます。

ResponsesAgentを作成する方法を学ぶには、MLflowドキュメント - Model Serving向けResponsesAgentの例を参照してください。

ResponsesAgent 次の利点があります:

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

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

• 合理化された開発、デプロイ、およびモニタリング

  • 任意のフレームワークを使用してエージェントを作成 : 既存のエージェントを ResponsesAgent インターフェースでラップして、AI Playground、Agent Evaluation、および Agent モニタリング とのすぐに使える互換性を実現します。
  • 型付きオーサリングインターフェース ：型付きPythonクラスを使用してエージェントコードを記述し、IDEおよびノートブックのオートコンプリートのメリットを享受できます。
  • 自動トレース ：MLflow はストリーム応答をトレース内で自動的に集約し、評価と表示を容易にします。
  • OpenAI Responses スキーマと互換性があります :OpenAI: Responses vs. ChatCompletion を参照してください。

OpenAI エージェント SDK

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

MCP (モデルコンテキストプロトコル) サーバー

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

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

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

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

MCPサーバーに接続することで、データベースのクエリ、ドキュメントの検索、外部 APIs の呼び出しなどの機能をエージェントに付与できます。エージェント Template には、default の MCP サーバー接続が含まれています。さらにツールを追加するには、エージェント コードで追加の MCP サーバーを構成し、databricks.yml で必要な権限を付与してください。

サポートされているツールタイプとコード例については、エージェントをツールに接続するを参照してください。

ローカル Python 関数ツールを定義します

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

OpenAI Agents SDK

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

Python

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デコレーターを使用します。

Python

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 使用量を管理する

エージェントの LLM 呼び出しを Unity AI Gateway (Beta) 経由でルーティングすることで、どのプロバイダーが応答してもすべてのリクエストが同じ制御によって管理されます。リクエストパスにゲートウェイがあることで、エージェントコードを変更したり、プロバイダーの認証情報を変更したりすることなく、アクセス権限を一元管理し、アプリごとのコストを配分し、モデルをスワップし、トラフィックを検査またはリプレイできます。

備考

ベータ版

この機能はベータ版です。ワークスペース管理者は、 プレビュー ページからこの機能へのアクセスを制御できます。Databricksのプレビューを管理するを参照してください。

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

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

OpenAI

Python

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

Python

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の例については、モデルサービスのクエリーを参照してください。

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

ストリーミング応答

ストリーミング応答

ストリーミングにより、エージェントは完全な応答を待たずに、リアルタイムのチャンクで応答を送信できます。ストリーミングを ResponsesAgent で実装するには、一連の delta イベントの後に最終の完了イベントを出力します：

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

各デルタイベントは、テキストのチャンクをクライアントにストリームします。最後の完了イベントには、完全なレスポンステキストが含まれ、Databricksに以下の処理を行うよう通知します：

• MLflowトレースでエージェントの出力をトレースします。
• Unity AI Gateway推論テーブルでストリームされた応答を集約します。
• AI Playground UIで完全な出力を表示します。

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

Databricksは、databricks_output.errorの下の最後のトークンとともにストリーミング中に発生したエラーを伝播します。このエラーを適切に処理し、表面化させるのは、呼び出し元のクライアントの責任です。

Bash

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

カスタム入力と出力

カスタム入力と出力

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

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

The Agent Evaluation review app does not support rendering traces for agents with additional input fields.

AI Playground およびレビューアプリでcustom_inputsを提供してください。

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

1. AI Playground またはエージェント レビュー アプリで、歯車のアイコン を選択します。

2. custom_inputs を有効にします。

3. エージェントの定義された入力スキーマに一致する JSON オブジェクトを指定します。

   

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

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

1. uv（Python パッケージマネージャー）、nvm（Node バージョンマネージャー）、および Databricks CLI をインストールします。

   • uv インストール

   • nvm インストール

   • Node 20 LTS を使用するには、以下をランしてください：

     Bash

     nvm use 20

   • databricks CLI インストール

2. agent-openai-agents-sdkフォルダにディレクトリを変更します。

3. 提供されているクイックスタートスクリプトをランして、依存関係をインストールし、環境をセットアップし、アプリを起動します。

   Bash

   uv run quickstart
   uv run start-app

ブラウザーでhttp://localhost:8000に移動して組み込みチャットUIを開き、エージェントとのチャットを起動してください。

ステップ 6. 認証を構成します。

エージェントは、Databricksリソースにアクセスするために認証が必要です。Databricks Appsには、アプリ認可 (Service Principal) とユーザー認可 (ユーザー代理) の2つの認証方法があります。どちらか一方をワークスペースUIを介して、または宣言型自動化バンドルを使用してdatabricks.ymlで宣言的に構成できます。エージェントTemplateにはdatabricks.ymlが付属しているため、Templateから起動する際にそのパスがdefaultになります。

サポートされているすべてのリソースタイプ、権限値、およびエンドツーエンドのdatabricks.ymlウォークスルーを含む完全なリファレンスについては、AIエージェントの認証を参照してください。

App authorization (default)

アプリの認可には、Databricks がアプリ用に自動的に作成するService Principalが使用されます。すべてのユーザーが同じ権限を共有しています。

エージェントが使用するすべてのリソースをdatabricks.ymlのresources.apps.<app>.resourcesの下で宣言します。バンドルをデプロイして、Service Principalに宣言された権限を付与します：

YAML

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'

Bash

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

リソースの種類の全リストについては、アプリの認可を参照してください。

User authorization

ユーザー認可により、エージェントは各ユーザーの個別の権限で行動できます。ユーザーごとのアクセスコントロールまたは監査証跡が必要な場合に使用します。

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

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)

重要

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

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

YAML

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

Bash

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

利用可能なスコープのリストおよび完全なセットアップ手順については、「ユーザー認証」を参照してください。

ステップ 7: エージェントを評価します。

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

Bash

uv run agent-evaluate

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

認証を設定した後、エージェントをDatabricksにデプロイします。エージェントTemplateは、Databricks Asset Bundles (DAB)をデプロイに利用しています。Template内のdatabricks.ymlファイルは、アプリの構成とリソースのアクセス許可を定義します。Databricks CLIがインストールされ、構成されていることを確認してください。

注記

ステップ1でワークスペースUIからアプリを作成した場合、デプロイする前に databricks bundle deployment bind agent_openai_agents_sdk <app-name> --auto-approve を実行して、既存のアプリをバンドルにバインドしてください。それ以外の場合、databricks bundle deploy は「同名のアプリが既に存在します」というエラーで失敗します。

1. デプロイする前にエラーを検出するためにバンドル構成を検証します：

   Bash

   databricks bundle validate

2. バンドルをデプロイします。これにより、コードがuploadされ、databricks.yml で定義されているリソース（MLflow エクスペリメント、サービング Endpoint など）が構成されます。

   Bash

   databricks bundle deploy

3. アプリを起動または再起動：

   Bash

   databricks bundle run agent_openai_agents_sdk

注記

bundle deploy only uploadし、リソースを構成するだけです。bundle runは、新しいコードでアプリを起動または再起動するために必要です。

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

ステップ 9。デプロイ済みエージェントにクエリーします

次の例では、 OAuthを使用したクイックcurlリクエストを使用しています。 Databricks Appsでは、パーソナル アクセストークン (PAT) はサポートされていません。

Databricks OpenAIクライアントやREST APIを含むクエリーメソッドの全リストについては、Databricksにデプロイされたエージェントのクエリーを参照してください。

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

Bash

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

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

Bash

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機能との互換性を確保するためにモデルのシグネチャを理解する

Databricks では、MLflow モデルシグネチャ を使用して、エージェントの入力スキーマと出力スキーマを定義します。 AI Playground などの製品機能は、エージェントがサポートされている一連のモデルシグネチャのいずれかを持っていることを前提としています。

ResponsesAgentインターフェースを使用してエージェントを作成する推奨されるアプローチに従う場合、MLflowはDatabricks製品の機能と互換性のあるエージェントのシグネチャを自動的に推論します。

制限事項

• 中規模および大規模のコンピュートサイズのみがサポートされています。Databricks アプリのコンピュートリソースを構成するを参照してください。
• 現在、MLflow Review App チャット UI は Databricks Apps にデプロイされたエージェントをサポートしていません。既存のトレースを評価するには、デプロイ方法に関係なく機能するラベリングセッションを使用します。Databricksは、レビューおよびフィードバックのサポートをチャットボットテンプレートに直接構築しています。

次のステップ

エージェントが開発環境で動作したら、本番運用に移行します。推奨される順序（CI/CD、ロードテスト、Unity AI Gateway）については、Databricks Appsエージェントの本番運用への移行を参照してください。