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

エージェントが必要とするデータとクエリを書く人に基づいてツールを選びましょう:

お使いのエージェントには次のアクションが必要です: Use
ワークスペース全体でビジネスの質問に答える ジーニーワンMCP
Python で厳選された Genie エージェントを 1 つクエリする AIブリッジツール
SQLを書いて実行する Databricks SQL MCP
パラメータ付きの事前定義クエリを実行します Unity カタログ関数ツール

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

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

「Python エージェントで MCP ツールを使う」に従って、server_url を Genie One MCP URL に設定:

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エージェントをクエリする

AI ブリッジを使って、Python エージェント内で特定の Genie エージェントをツールとして利用可能にします。 AI Bridgeは Genie APIを通じてリクエスト、ポーリング、クエリ結果を処理します。

Claude CodeやCodexの場合は、 Databricks AI Tools をインストールして Genie Agentsスキル をDatabricks CLIで活用してください。

始める前に

  1. Python 3.12を使ってください。 ローカル開発の場合は、Databricks CLI でサインインし、DEFAULT プロファイルを使用して Python クライアントが認証情報を見つけられるようにします。
  2. 必要なウェアハウス権限とデータ権限を持つ、あなたのアイデンティティがアクセス可能な Genieエージェント を選びましょう。 設定からスペースIDをコピーして、<genie-agent-id>をそのIDで置き換えてください。
  3. を、ツール呼び出しをサポートし、クエリする権限がある<model-endpoint>に置き換えてください。
  4. フレームワークのインストールコマンドをターミナルで実行してください。 ノートブックでは%pipを使い、インストール後にPython再起動してください。 トップレベルawaitをサポートするノートブックでawait例を実行してください。

エージェントを実行してください

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

LangGraph

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

pip install --upgrade databricks-langchain langgraph

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 エージェント SDK

この例は AI Bridge Genie クライアント とOpenAI Agents SDKの function_tool デコレーターを使用しています。 このモデルはAzure Databricks上で動作します。

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

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 を呼び出し、その結果を使っているか確認してください。 これらの例は、各ツール呼び出しごとに新しいジーニー会話を始めます。 文脈を保持するために、各ユーザーの会話で返された会話IDを保存し、次の呼び出しで渡します:

  • GenieAgent: response["conversation_id"]を読み、次の入力辞書に"conversation_id"を"messages"とともに含めてください。
  • Genie: response.conversation_id を読んで、conversation_id として ask_question() に渡します。

クライアントのオプションや実装の詳細については、GenieAgent（Genieやクライアントを含む）をご覧ください。

Databricks Appsでエージェントをホストする際は、Genieエージェントをアプリ リソースとして追加し、実行可能権限を付与してください。 アプリのサービスプリンシパルもモデルエンドポイントや基盤となるウェアハウス、データへのアクセスが必要です。

Databricks SQL MCPでSQLを実行します

エージェントがUnityカタログのテーブルに対してSQLを書き実行する必要がある場合は、 Databricks SQL MCP を使いましょう。

system.ai.dbsql、system.ai.sandbox、またはsystem.ai.web_searchを利用するには、アカウント管理者がアカウントコンソールのプレビューページからUnity Gatewayベータを有効にする必要があります。 「アカウント プレビューを管理」をご覧ください。

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

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

<workspace-hostname>をワークスペースのホスト名に置き換えてください。 担当者に SELECT 1 AS result を実行してもらい、ツールを呼び出して 1 を返すことを確認してください。

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

Unityカタログ関数で事前定義されたクエリを実行します

クエリが事前にわかっており、エージェントがパラメーターを提供している場合は、Unity カタログ SQL 関数を使用して構造化取得ツールを作成します。

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

機能要件とアクセス許可を確認してください。 my_catalog.my_schemaを、関数を作成できるカタログとスキーマに置き換え、テーブル名や列名をデータに合わせて調整します。 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;

テーブルの顧客名で関数をテストします:

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

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

マルチエージェントシステムでGenieを使う

ジーニーエージェントを他のエージェントやツールと連携させるには、スーパーバイザーエージェントを参照してください。 既存のモデルサービング統合については、「 マルチエージェントシステムにおけるGenieの使用」を参照してください。

MCPを使ってGenieエージェントに問い合わせ

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

  • 最終更新: