エージェントを構造化データに接続する

エージェントが必要とするデータと、クエリーを記述するユーザーに基づいてツールを選択します。

エージェントに必要な条件	使用
ワークスペース全体でビジネス上の質問に回答する	Genie One MCP
Pythonからキュレーションされた1つのGenie Agentにクエリーを実行する	AI Bridge ツール
SQL の記述とラン	Databricks SQL MCP
パラメーターを指定して定義済みのクエリーをランする	Unity Catalog 関数ツール

エージェントに必要な条件	使用
ワークスペース全体でビジネス上の質問に回答する	Genie One MCP
Pythonからキュレーションされた1つのGenie Agentにクエリーを実行する	AI Bridge ツール
SQL の記述とラン	Databricks SQL MCP
パラメーターを指定して定義済みのクエリーをランする	Unity Catalog 関数ツール

Genie Oneでデータをクエリーする

Databricksでは、ワークスペース全体でビジネスに関する質問に自然言語で回答するエージェント向けに、Genie One MCPを推奨しています。これは、Genieオントロジーを使用してビジネス用語を解釈し、呼び出し元の権限を使用してワークスペースデータをクエリーします。

Python エージェントでの MCP ツールの使用に従い、server_url を Genie One MCP URL に設定します。

Text

https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp

<workspace-hostname> をワークスペースのホスト名に置き換えます。次に、「前四半期の収益の上位10社の顧客は何ですか？」など、データについてエージェントに質問します。

Claude CodeまたはCodexの場合は、Databricks AI Toolsをインストールし、Databricks CLI経由でGenie Oneにクエリーを実行するデータディスカバリー スキルを使用します。

Python から特定の Genie Agent をクエリーします。

AI Bridge を使用して、特定の Genie Agent を Python エージェント内のツールとして公開します。AI Bridge は、Genie API を介してリクエスト、ポーリング、およびクエリー結果を処理します。

Claude Code または Codex の場合は、Databricks AI Tools をインストールし、Databricks CLI 経由で Genie Agents skill を使用します。

起動する前に

1. Python 3.12を使用します。ローカル開発を行うには、Databricks CLIでサインインし、Pythonクライアントが認証情報を見つけられるようにDEFAULTプロファイルを使用します。
2. 必要なwarehouse and data権限を持ち、自身のIDでアクセスできるGenie Agentを選択します。 [設定 (Settings)] からスペースIDをコピーし、<genie-agent-id>をそのIDに置き換えます。
3. <model-endpoint> を、ツール呼び出しをサポートする Databricks モデルの Endpoint（クエリーのアクセス権を持つもの）に置き換えます。
4. ターミナルでフレームワークのインストールコマンドをランします。ノートブックで %pip を使用し、インストールの完了後に Python を再起動します。トップレベルの await をサポートするノートブックで、await を使用して例をランします。

エージェントをランします。

どちらの例でも、モデルがask_genieを呼び出し、その結果を回答に使用できます。databricks-ai-bridgeからのGenieクライアントは、他のフレームワークでPython関数ツールとしてラップすることもできます。OpenAI Agents SDK tabには、LangChain依存関係なしでこのクライアントが表示されます。

LangGraph

この例では、AI BridgeのGenieAgentヘルパーをLangChainツールとしてラップします。

Bash

pip install --upgrade databricks-langchain langgraph

Python

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

genie = GenieAgent(genie_space_id="<genie-agent-id>")


@tool
def ask_genie(question: str) -> str:
    """Ask the configured Genie Agent a question about its business data."""
    response = genie.invoke({
        "messages": [{"role": "user", "content": question}]
    })
    return response["messages"][-1].content


agent = create_react_agent(
    ChatDatabricks(endpoint="<model-endpoint>"),
    tools=[ask_genie],
)
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Use Genie to find total sales last month.",
    }]
})
print(result["messages"][-1].content)

OpenAI Agents SDK

この例では、AI Bridge Genie クライアントおよび OpenAI Agents SDK の function_tool デコレーターを使用します。このモデルは Databricks で実行されます。

Bash

pip install --upgrade databricks-ai-bridge databricks-openai openai-agents

Python

from agents import Agent, Runner, function_tool
from agents import set_default_openai_api, set_default_openai_client
from agents.tracing import set_trace_processors
from databricks_ai_bridge.genie import Genie
from databricks_openai import AsyncDatabricksOpenAI

set_default_openai_client(AsyncDatabricksOpenAI())
set_default_openai_api("chat_completions")
set_trace_processors([])
genie = Genie(space_id="<genie-agent-id>", return_pandas=False)


@function_tool
def ask_genie(question: str) -> str:
    """Ask the configured Genie Agent a question about its business data."""
    return genie.ask_question(question).result


agent = Agent(
    name="Data analyst",
    instructions="Use ask_genie to answer questions about business data.",
    model="<model-endpoint>",
    tools=[ask_genie],
)
result = await Runner.run(agent, "What were total sales last month?")
print(result.final_output)

エージェントの出力またはトレースを確認して、ask_genie が呼び出され、その結果が使用されていることを確認します。これらの例では、ツール呼び出しごとに新しいGenieの会話が起動します。コンテキストを保持するには、ユーザーの会話ごとに返された会話IDを保存し、次の呼び出しで渡します。

• GenieAgent: response["conversation_id"] を読み取り、次の入力辞書に "messages" と並行して "conversation_id" を含めます。
• Genie：response.conversation_id を読み取り、conversation_id として ask_question() に渡します。

クライアントのオプションと実装の詳細については、GenieAgent ヘルパー や クライアント などを含め、GenieAI Bridge リポジトリ を参照してください。

Databricks Appsでエージェントをホストする場合、 Can run 権限を持つ Genie Agentをアプリリソースとして追加します 。アプリのService Principalには、モデルEndpoint、および基になるwarehouseとデータへのアクセス権も必要です。

Databricks SQL MCPを使用してSQLをランする

Unity Catalogテーブルに対してSQLを記述してランする必要があるエージェントには、Databricks SQL MCPを使用します。

system.ai.dbsql、system.ai.sandbox、または system.ai.web_search を使用するには、アカウント管理者がアカウント コンソールの [Previews] ページから Unity Gateway のベータ版を有効にする必要があります。アカウントのプレビューの管理を参照してください。

「Python エージェントでの MCP ツールの使用」に従って、server_url を次のように設定します。

Text

https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql

<workspace-hostname>をワークスペースのホスト名に置き換えます。エージェントにSELECT 1 AS resultをランするように依頼し、ツールを呼び出して1を返すことを確認します。

コーディング・エージェントについては、エージェントのセットアップガイドを使用してください。warehouseの選択とSQL固有のオプションについては、Databricks SQL MCP リファレンスを参照してください。

Unity Catalog関数を使用して事前定義されたクエリーをランする

クエリーが事前にわかっていてエージェントがパラメーターを提供する場合、Unity Catalog SQL関数を使用して構造化された検索ツールを作成します。

次の例では、lookup_customer_info という Unity Catalog 関数を作成します。customer_name、customer_id、およびcustomer_email列を持つcustomer_dataテーブルがあると仮定します。

関数の要件と権限を確認します。my_catalog.my_schema を、関数を作成できるカタログとスキーマに置き換え、テーブル名と列名を使用するデータに合わせて調整します。SQL エディターで次のコードをランします。

SQL

CREATE FUNCTION my_catalog.my_schema.lookup_customer_info(
  customer_name_input STRING COMMENT 'Name of the customer whose info to look up'
)
RETURNS STRING
COMMENT 'Returns metadata about a particular customer, given the customer''s name, including the customer''s email and ID. The
customer ID can be used for other queries.'
RETURN SELECT CONCAT(
    'Customer ID: ', customer_id, ', ',
    'Customer Email: ', customer_email
  )
  FROM my_catalog.my_schema.customer_data
  WHERE customer_name = customer_name_input
  LIMIT 1;

テーブルの顧客名を使用して関数をテストします。

SQL

SELECT my_catalog.my_schema.lookup_customer_info('Example Customer');

次に、Unity Catalog AIを使用して、関数をエージェントに追加します。そのガイドには、LangGraph、OpenAI、Anthropic、LlamaIndexの例が含まれています。

MCP を使用して Genie Agent に対してクエリーを実行する

MCP 経由で特定の Genie Agent に接続するには、その URL と要件について Genie Agent MCP リファレンスを参照してください。MCP なしで Python から Genie Agent に対してクエリーを実行するには、AI Bridge ツールの例を使用します。