メインコンテンツまでスキップ
に最終更新

Unity Catalog関数を使用してAIエージェントツールを作成

Unity Catalog関数を使用して、カスタムロジックを実行し、言語生成を超えてLLMの機能を拡張する特定のタスクを実行するAIエージェントツールを作成します。

Unity Catalog関数とMCPサーバーの使い分け​

Databricks では、クエリが事前にわかっていて、エージェントがパラメーターを提供する場合は、Unity Catalog 関数を、特に構造化データ取得ツール用のエージェント ツールとして使用することをお勧めします。「エージェントを構造化データに接続する」を参照してください。

その他のほとんどのユースケースでは、Databricks は、より高速な実行、ユーザーごとの認証サポート、および追加の柔軟性のために、MCP サーバーを使用するか、エージェント コードにロジックを直接定義することをお勧めします。

要件​

Unity Catalog の関数を AI エージェント ツールとして作成および使用するには、次のものが必要です。

  • Databricks Runtime ：Databricks Runtime 15.0 以降を使用します
  • **Python バージョン**: Python 3.10 以降をインストールします。

Unity Catalog 関数を実行するには：

  • サーバレスコンピュート は、本番運用でAIエージェントツールとしてUnity Catalog関数を実行するために、ワークスペースで有効にする必要があります。サーバレスコンピュートの要件を参照してください。
    • Python 関数に対するローカルモード実行にはサーバレス汎用コンピュートの実行は必要ありませんが、ローカルモードは開発およびテスト目的でのみ使用されます。

Unity Catalog 関数を作成するには。

  • Databricks Workspace ClientまたはSQLボディステートメントを使用して関数を作成するには、ワークスペースで サーバレス汎用コンピュート を有効にする必要があります。
    • Python関数はサーバレス コンピュートなしで作成できます。

Unity Catalog関数ツールを作成します​

以下のステップでは、Unity Catalog 関数を作成およびテストする方法を示します。Databricks ノートブックで次のコードを実行します。

プロンプト

Genie Code (エージェントモード) にこれを行うよう指示してください。

Create a Unity Catalog Python function that an AI agent can use as a tool. It should take two floating point numbers and return their sum, with type hints and a Google-style docstring. Register it using the Databricks Function Client, then test calling it.

依存関係をインストールする​

[databricks] のエクストラを使用して Unity Catalog AI パッケージをインストールします。

Python
# Install Unity Catalog AI integration packages with the Databricks extra
%pip install unitycatalog-ai[databricks]

dbutils.library.restartPython()

Databricks ファンクションクライアントを初期化​

Databricks で Unity Catalog 関数を作成、管理、実行するための特殊なインターフェイスである Databricks Function Client を初期化します。

Python
from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

ツールのロジックを定義します。​

Unity Catalog ツールは、実際には Unity Catalog のユーザー定義関数 (UDF) にすぎません。Unity Catalogのツールを定義すると、Unity Catalogに関数を登録する。Unity Catalog UDF の詳細については、Unity Catalog のユーザー定義関数 (UDF)を参照してください。

警告

エージェントツールで任意のコードを実行すると、エージェントがアクセスできる機密情報やプライベート情報が公開される可能性があります。顧客は、データへの意図しないアクセスを防ぐために、信頼できるコードのみを実行し、ガードレールと適切な権限を構成する責任があります。

Unity Catalog関数は、次の 2 つのAPIのいずれかを使用して作成できます。

  • create_python_function Pythonの呼び出し可能オブジェクトを受け入れます。
  • create_function SQL 本体の create function ステートメントを受け入れます。Python 関数の作成を参照してください。

create_python_function API を使用して関数を作成します。

Unity Catalog関数のデータモデルでPython呼び出し可能を認識できるようにするには、関数が次の要件を満たしている必要があります。

  • 型ヒント ：関数シグネチャでは、有効な Python 型ヒントを定義する必要があります。名前付き引数と戻り値の両方にその型が定義されている必要があります。

  • **可変引数は使用しないでください**：*args や **kwargs などの可変引数はサポートされていません。すべての引数は明示的に定義する必要があります。

  • 型の互換性 : すべての Python 型が SQL でサポートされているわけではありません。Spark でサポートされるデータ型を参照してください。

  • 記述的なdocstring ：Unity Catalog関数ツールキットは、docstringから重要な情報を読み取り、解析し、抽出します。

    • docstring は、Google docstring 構文に従ってフォーマットする必要があります。
    • LLMが関数の使用方法と使用時期を理解できるように、関数とその引数について明確な説明を記述します。

  • 依存関係のインポート ：ライブラリは関数の本体内でインポートする必要があります。関数外のインポートは、ツール実行時に解決されません。

次のコードスニペットは、create_python_function を使用して Python の呼び出し可能オブジェクト add_numbers を登録する。

Python

CATALOG = "my_catalog"
SCHEMA = "my_schema"

def add_numbers(number_1: float, number_2: float) -> float:
  """
  A function that accepts two floating point numbers adds them,
  and returns the resulting sum as a float.

  Args:
    number_1 (float): The first of the two numbers to add.
    number_2 (float): The second of the two numbers to add.

  Returns:
    float: The sum of the two input numbers.
  """
  return number_1 + number_2

function_info = client.create_python_function(
  func=add_numbers,
  catalog=CATALOG,
  schema=SCHEMA,
  replace=True
)

関数をテストする​

関数をテストし、期待どおりに機能することを確認します。execute_function API で完全修飾関数名を指定し、関数を実行します：

Python
result = client.execute_function(
  function_name=f"{CATALOG}.{SCHEMA}.add_numbers",
  parameters={"number_1": 36939.0, "number_2": 8922.4}
)

result.value # OUTPUT: '45861.4'

エージェントにUnity Catalog関数を追加します​

Unity Catalog 関数を作成してテストしたら、次のいずれかのアプローチを選択してエージェントに追加してください。

Mcpアイコン。 MCP の使用 (推奨)

MCPの使用（推奨）​

Databricksは、MCP サーバーを使用して Unity Catalog 関数をエージェントに追加することをお勧めします。MCPアプローチは、自動ツール検出と組み込み認証サポートを備えた、より簡単な統合を提供します。

Unity Catalog関数用の管理対象MCP URLは次のとおりです: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}。オプションで、/{function_name}を付加して特定の関数を指定できます。

次の例では、エージェントをMCPを介してUnity Catalog関数に接続する方法を示します。<catalog>と<schema>を関数のある場所に置き換えます。

Python
from agents import Agent, Runner
from databricks.sdk import WorkspaceClient
from databricks_openai.agents import McpServer

workspace_client = WorkspaceClient()

async with McpServer.from_uc_function(
    catalog="<catalog>",
    schema="<schema>",
    workspace_client=workspace_client,
    name="uc-functions",
) as uc_server:
    agent = Agent(
        name="Tool-using agent",
        instructions="You are a helpful assistant. Use the available tools to answer questions.",
        model="databricks-claude-sonnet-4-5",
        mcp_servers=[uc_server],
    )
    result = await Runner.run(agent, "Look up customer info for Acme Corp")
    print(result.final_output)

アプリにdatabricks.ymlにあるUnity Catalog関数へのアクセスを許可します。

YAML
resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_uc_function'
          uc_securable:
            securable_full_name: '<catalog>.<schema>.<function-name>'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

機能アイコン。 UCFunctionToolkit の使用

UCFunctionToolkitの使用​

この例では LangChain を使用していますが、同様のアプローチを他のライブラリにも適用できます。Unity Catalog ツール統合をご覧ください。

追加の依存関係をインストールする​

UCFunctionToolkit用のLangChainインテグレーションパッケージをインストールしてください。

Python
%pip install unitycatalog-langchain[databricks]==0.2.0

# Install the Databricks LangChain integration package
%pip install databricks-langchain==0.5.0

dbutils.library.restartPython()

UCFunctionToolKitを使用して関数をラップします。​

UCFunctionToolkitを使用して関数をラップし、エージェントオーサリングライブラリからアクセスできるようにします。このツールキットは、異なる生成AI ライブラリ間での一貫性を確保し、レトリーバーの自動トレースなどの便利な機能を追加します。

Python
from databricks_langchain import UCFunctionToolkit

# Create a toolkit with the Unity Catalog function
func_name = f"{CATALOG}.{SCHEMA}.add_numbers"
toolkit = UCFunctionToolkit(function_names=[func_name])

tools = toolkit.tools

エージェントでツールを使用します​

UCFunctionToolkit の tools プロパティを使用して、ツールを LangChain エージェントに追加します。

注記

This example uses LangChain. However you can integrate Unity Catalog tools with other frameworks such as LlamaIndex, OpenAI, Anthropic, and more. See Unity Catalog tool integration.

この例では、わかりやすくするためにLangChain AgentExecutor API を使用してシンプルなエージェントを作成します。本番運用ワークロードの場合は、「AIエージェントを作成してDatabricks Appsにデプロイする」に示されているエージェント作成ワークフローを使用してください。

Python
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain.prompts import ChatPromptTemplate
from databricks_langchain import (
  ChatDatabricks,
  UCFunctionToolkit,
)
import mlflow

# Initialize the LLM (optional: replace with your LLM of choice)
LLM_ENDPOINT_NAME = "databricks-meta-llama-3-3-70b-instruct"
llm = ChatDatabricks(endpoint=LLM_ENDPOINT_NAME, temperature=0.1)

# Define the prompt
prompt = ChatPromptTemplate.from_messages(
  [
    (
      "system",
      "You are a helpful assistant. Make sure to use tools for additional functionality.",
    ),
    ("placeholder", "{chat_history}"),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
  ]
)

# Enable automatic tracing
mlflow.langchain.autolog()

# Define the agent, specifying the tools from the toolkit above
agent = create_tool_calling_agent(llm, tools, prompt)

# Create the agent executor
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
agent_executor.invoke({"input": "What is 36939.0 + 8922.4?"})

明確なドキュメントでツール呼び出しを改善する​

良いドキュメントは、エージェントが各ツールをいつ、どのように使用するかを知るのに役立ちます。ツールのドキュメント化に関するベストプラクティスは以下の通りです：

  • Unity Catalog の関数では、ツールの機能とパラメーターを記述するために COMMENT 句を使用します。
  • 期待される入力と出力を明確に定義してください。
  • エージェントや人間がツールをより簡単に使用できるように、意味のある説明を記述してください。

例：効果的なツール ドキュメント​

以下の例では、構造化されたテーブルをクエリするツールに対する明確なCOMMENT文字列が示されています。

SQL
CREATE OR REPLACE FUNCTION main.default.lookup_customer_info(
  customer_name STRING COMMENT 'Name of the customer whose info to look up.'
)
RETURNS STRING
COMMENT 'Returns metadata about a specific customer including their email and ID.'
RETURN SELECT CONCAT(
    'Customer ID: ', customer_id, ', ',
    'Customer Email: ', customer_email
  )
  FROM main.default.customer_data
  WHERE customer_name = customer_name
  LIMIT 1;

例：効果のないツール ドキュメント​

次の例は重要な詳細が不足しているため、エージェントがそのツールを効果的に使用しにくくなります。

SQL
CREATE OR REPLACE FUNCTION main.default.lookup_customer_info(
  customer_name STRING COMMENT 'Name of the customer.'
)
RETURNS STRING
COMMENT 'Returns info about a customer.'
RETURN SELECT CONCAT(
    'Customer ID: ', customer_id, ', ',
    'Customer Email: ', customer_email
  )
  FROM main.default.customer_data
  WHERE customer_name = customer_name
  LIMIT 1;

サーバレスまたはローカル モードで関数を実行します​

生成AI サービスがツール呼び出しが必要であると判断すると、統合パッケージ (UCFunctionToolkit インスタンス) は DatabricksFunctionClient.execute_function API を実行します。

execute_functionの呼び出しは、サーバレスまたはローカルの2つの実行モードで関数を実行できます。このモードは、どのリソースが関数を実行するかを決定します。

本番運用におけるサーバレスモード​

サーバレスモードは、AIエージェントツールとしてUnity Catalog関数を実行する際の本番運用ユースケースにおいて、デフォルトかつ推奨されるオプションです。このモードでは、サーバレス汎用コンピュート (Spark Connect サーバレス) を使用して関数をリモートで実行します。Lakeguardは、エージェントのプロセスが安全で、ローカルで任意のコードを実行するリスクがないことを保証します。

注記

AIエージェントツールとして実行されるUnity Catalog関数には、サーバレスSQLウェアハウスではなく、サーバレス汎用コンピュート（Spark Connectサーバレス）が必要です。サーバレス汎用コンピュートなしでツールを実行しようとすると、PERMISSION_DENIED: Cannot access Spark Connectのようなエラーが発生します。

Python
# Defaults to serverless if `execution_mode` is not specified
client = DatabricksFunctionClient(execution_mode="serverless")

エージェントが サーバレス モードでツール実行を要求すると、次のことが発生します：

  1. DatabricksFunctionClientは、関数定義がローカルにキャッシュされていない場合、その定義を取得するためにUnity Catalogにリクエストを送信します。
  2. DatabricksFunctionClientは関数定義を抽出し、パラメーター名とタイプを検証します。
  3. DatabricksFunctionClientは、実行をUDFとしてサーバレス汎用コンピュートに送信します。

開発用のローカルモード​

ローカルモードは、サーバレス汎用コンピュートにリクエストを送信するのではなく、ローカルサブプロセスでPython関数を実行します。これにより、ローカルのスタックトレースを提供することで、ツール呼び出しのトラブルシューティングをより効果的に行えます。Python Unity Catalog関数の開発とデバッグのために設計されています。

エージェントが ローカル モードでのツールの実行を要求すると、 DatabricksFunctionClient は次の処理を行います。

  1. 定義がローカルにキャッシュされていない場合、Unity Catalogにファンクション定義の取得をリクエストします。
  2. Pythonの呼び出し可能な定義を抽出し、呼び出し可能をローカルにキャッシュし、パラメーターの名前と型を検証します。
  3. タイムアウト保護された制限付きサブプロセスで、指定されたパラメーターを使用して呼び出し可能オブジェクトを呼び出します。
Python
# Defaults to serverless if `execution_mode` is not specified
client = DatabricksFunctionClient(execution_mode="local")

"local"モードで実行すると、次の機能が提供されます:

  • CPU時間制限: 過度な計算負荷を防ぐために、呼び出し可能な実行の総CPUランタイムを制限します。

    CPU時間制限は、実CPU使用量に基づいており、経過実時間には基づいていません。システムスケジューリングと並列プロセスのため、現実世界のシナリオではCPU時間が経過実時間を超過する可能性があります。

  • メモリ制限： プロセスに割り当てられる仮想メモリを制限します。

  • タイムアウト保護 ：関数を実行するための合計実行時間タイムアウトを適用します。

環境変数を使用してこれらの制限をカスタマイズします（詳細はこちらをお読みください）。

ローカルモードの制限事項​

  • Python関数のみ : SQLベースの関数はローカルモードではサポートされていません。
  • **信頼できないコードに関するセキュリティ上の考慮事項**: ローカルモードでは、プロセス分離のためにサブプロセスで関数が実行されますが、AIシステムによって生成された任意のコードを実行する際には、潜在的なセキュリティリスクがあります。これは主に、レビューされていない動的に生成されたPythonコードを関数が実行する場合に懸念されます。
  • ライブラリのバージョンの違い ：ライブラリのバージョンは、サーバレス実行環境とローカル実行環境の間で異なる場合があり、これにより関数の動作が異なる可能性があります。

環境変数​

DatabricksFunctionClientで関数が実行される方法を、以下の環境変数を使用して設定します：

環境変数

デフォルト値

説明

EXECUTOR_MAX_CPU_TIME_LIMIT

10 秒

最大許容CPU実行時間（ローカルモードのみ）。

EXECUTOR_MAX_MEMORY_LIMIT

100 MB

プロセスに対する最大許容仮想メモリ割り当て（ローカルモードのみ）。

EXECUTOR_TIMEOUT

20 秒

最大合計経過実時間（ローカルモードのみ）。

UCAI_DATABRICKS_SESSION_RETRY_MAX_ATTEMPTS

5

トークンの有効期限が切れた場合にセッションクライアントの更新を再試行する最大試行回数。

UCAI_DATABRICKS_SERVERLESS_EXECUTION_RESULT_ROW_LIMIT

100

サーバレスコンピュートおよびdatabricks-connectを使用して関数を実行する際の最大行数。

http_requestで外部APIを呼び出す（レガシー）​

注記

エージェントを外部サービスに接続するには、DatabricksはMCPサービスまたはUnity Catalog接続プロキシのいずれかを推奨します。UC関数ツールは、http_requestをラップするものについては引き続きサポートされますが、もはや推奨されるアプローチではありません。

外部サービスを呼び出すためにhttp_request()をラップするUnity Catalog関数を作成できます。このアプローチは、SQLベースのツール定義に役立ちます。

次の例では、Slack にメッセージを投稿する Unity Catalog 関数ツールを作成します。

SQL
CREATE OR REPLACE FUNCTION main.default.slack_post_message(
  text STRING COMMENT 'message content'
)
RETURNS STRING
COMMENT 'Sends a Slack message by passing in the message and returns the response received from the external service.'
RETURN (http_request(
  conn => 'test_sql_slack',
  method => 'POST',
  path => '/api/chat.postMessage',
  json => to_json(named_struct(
    'channel', "C032G2DAH3",
    'text', text
  ))
)).text

CREATE FUNCTION (SQL および Python)を参照してください。

注記

http_requestを使用したSQLアクセスは、ユーザーごとのユーザーからマシンへ、および動的クライアント登録接続タイプについてはブロックされます。代わりにPython Databricks SDKを使用してください。

ノートブックの例​

以下のノートブックでは、Unity Catalog関数を使用して外部サービスに接続するAIエージェントツールを作成する方法を示しています。

Slack メッセージング エージェント ツール

ノートブックを新しいタブで開く

Microsoft Graph API エージェント ツール

ノートブックを新しいタブで開く

Azure AI Search エージェントツール

ノートブックを新しいタブで開く

次のステップ​

このページの見出し