Membuat alat agen menggunakan fungsi Unity Catalog

Gunakan fungsi Katalog Unity untuk membuat alat agen yang menjalankan logika kustom dan melakukan tugas tertentu yang memperluas kemampuan LLM di luar pembuatan bahasa.

Kapan menggunakan fungsi Katalog Unity vs. server MCP

Databricks merekomendasikan penggunaan fungsi Unity Catalog sebagai alat agen khusus untuk alat pengambilan data terstruktur ketika kueri diketahui sebelumnya dan agen menyediakan parameter. Lihat Menyambungkan agen ke data terstruktur.

Dalam sebagian besar kasus penggunaan lainnya, Databricks merekomendasikan server MCP atau menentukan logika langsung dalam kode agen untuk eksekusi yang lebih cepat, dukungan autentikasi per pengguna, dan fleksibilitas tambahan.

Requirements

Untuk membuat dan menggunakan fungsi Katalog Unity sebagai alat agen, Anda memerlukan hal berikut:

  • Databricks Runtime: Gunakan Databricks Runtime 15.0 ke atas
  • Versi Python: Instal Python 3.10 atau lebih tinggi

Untuk menjalankan fungsi Katalog Unity:

  • Komputasi tanpa server harus diaktifkan di ruang kerja Anda untuk menjalankan fungsi Katalog Unity sebagai alat agen dalam produksi. Lihat Persyaratan komputasi tanpa server.
    • Eksekusi mode lokal untuk fungsi Python tidak memerlukan komputasi generik tanpa server untuk dijalankan, namun mode lokal hanya ditujukan untuk tujuan pengembangan dan pengujian.

Untuk membuat fungsi Katalog Unity:

  • Komputasi generik tanpa server harus diaktifkan di ruang kerja Anda untuk membuat fungsi menggunakan pernyataan Klien Ruang Kerja Databricks atau isi SQL.
    • Fungsi Python dapat dibuat tanpa menggunakan komputasi tanpa server.

Membuat alat fungsi Unity Catalog

Langkah-langkah berikut menunjukkan cara membuat dan menguji fungsi Katalog Unity. Jalankan kode berikut di buku catatan Databricks.

Tip

Sampaikan kepada Genie Code (mode Agen) agar melaksanakan ini untuk Anda:

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.

Pasang dependensi

Instal paket AI Unity Catalog dengan [databricks] tambahan.

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

dbutils.library.restartPython()

Menginisialisasi Klien Fungsi Databricks

Inisialisasi Klien Fungsi Databricks, yang merupakan antarmuka khusus untuk membuat, mengelola, dan menjalankan fungsi Unity Catalog di Databricks.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Menentukan logika alat

Alat Katalog Unity sebenarnya hanyalah fungsi yang ditentukan pengguna (UDF) di balik layar. Saat Anda menentukan alat Katalog Unity, Anda mendaftarkan fungsi di Unity Catalog. Untuk mempelajari selengkapnya tentang Unity Catalog UDF, lihat SQL dan Python fungsi yang ditentukan pengguna (UDF) di Unity Catalog.

Warning

Menjalankan kode arbitrer dalam alat agen dapat mengekspos informasi sensitif atau privat yang dapat diakses agen. Pelanggan bertanggung jawab untuk hanya menjalankan kode tepercaya dan mengonfigurasi pagar pembatas dan izin yang sesuai untuk mencegah akses yang tidak diinginkan ke data.

Anda dapat membuat fungsi Katalog Unity menggunakan salah satu dari dua API:

  • create_python_function menerima fungsi atau objek yang dapat dipanggil dalam Python.
  • create_function menerima pernyataan pembuatan fungsi struktur SQL. Lihat Membuat fungsi Python.

create_python_function Gunakan API untuk membuat fungsi.

Agar fungsi Python yang dapat dipanggil diakui oleh model data fungsi Unity Catalog, fungsi tersebut harus memenuhi persyaratan berikut:

  • Petunjuk jenis: Tanda tangan fungsi harus menentukan petunjuk jenis Python yang valid. Argumen bernama dan nilai pengembalian harus memiliki jenis yang ditentukan.
  • Jangan gunakan argumen variabel: Argumen variabel seperti *args dan **kwargs tidak didukung. Semua argumen harus didefinisikan secara eksplisit.
  • Kompatibilitas jenis: Tidak semua jenis Python didukung di SQL. Lihat Jenis Data yang Didukung Spark.
  • Docstring yang deskriptif: Perangkat fungsi Unity Catalog membaca, mengurai, dan mengekstrak informasi penting dari docstring Anda.
    • Docstring harus diformat sesuai dengan sintaks Google docstring.
    • Tulis deskripsi yang jelas untuk fungsi Anda dan argumennya untuk membantu LLM memahami bagaimana dan kapan menggunakan fungsi.
  • Impor dependensi: Pustaka harus diimpor dalam isi fungsi. Impor di luar fungsi tidak akan diatasi saat menjalankan alat.

Cuplikan kode berikut menggunakan create_python_function untuk mendaftarkan callable Python add_numbers:


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
)

Uji fungsi

Uji fungsi Anda untuk memastikan berfungsi seperti yang diharapkan. Tentukan nama fungsi yang sepenuhnya memenuhi syarat di execute_function API untuk menjalankan fungsi:

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'

Menambahkan fungsi Unity Catalog ke agen Anda

Setelah Anda membuat dan menguji fungsi Katalog Unity Anda, pilih salah satu pendekatan berikut untuk menambahkannya ke agen Anda.

Ikon Mcp. Menggunakan MCP (disarankan)

Databricks merekomendasikan penggunaan server MCP untuk menambahkan fungsi Unity Catalog ke agen Anda. Pendekatan MCP menyediakan integrasi yang lebih sederhana dengan penemuan alat otomatis dan dukungan autentikasi bawaan.

URL MCP terkelola untuk fungsi Katalog Unity adalah: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}. Anda dapat secara opsional menentukan fungsi tertentu dengan menambahkan /{function_name}.

Contoh berikut menunjukkan cara menghubungkan agen Anda ke fungsi Katalog Unity melalui MCP. Ganti <catalog> dan <schema> dengan lokasi fungsi Anda.

OpenAI Agents SDK (Aplikasi)

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)

Berikan akses aplikasi ke fungsi Unity Catalog di databricks.yml:

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

LangGraph (Aplikasi)

from databricks.sdk import WorkspaceClient
from databricks_langchain import ChatDatabricks, DatabricksMCPServer, DatabricksMultiServerMCPClient
from langgraph.prebuilt import create_react_agent

workspace_client = WorkspaceClient()
host = workspace_client.config.host

mcp_client = DatabricksMultiServerMCPClient([
    DatabricksMCPServer(
        name="uc-functions",
        url=f"{host}/api/2.0/mcp/functions/<catalog>/<schema>",
        workspace_client=workspace_client,
    ),
])

async with mcp_client:
    tools = await mcp_client.get_tools()
    agent = create_react_agent(
        ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
        tools=tools,
    )
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "Look up customer info for Acme Corp"}]}
    )
    print(result["messages"][-1].content)

Berikan akses aplikasi ke fungsi Unity Catalog di databricks.yml:

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

Model Serving

from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksMCPClient
import mlflow

workspace_client = WorkspaceClient()
host = workspace_client.config.host

# Connect to the UC functions MCP server
mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/functions/<catalog>/<schema>",
    workspace_client=workspace_client,
)

# List available tools
tools = mcp_client.list_tools()

# Log the agent with the required resources for deployment
mlflow.pyfunc.log_model(
    "agent",
    python_model=my_agent,
    resources=mcp_client.get_databricks_resources(),
)

Untuk menyebarkan agen, lihat Menyebarkan agen untuk aplikasi AI (Model Serving). Untuk detail selengkapnya tentang agen pencatatan log dengan sumber daya MCP, lihat server MCP terkelola Azure Databricks.

Ikon fungsi. Menggunakan UCFunctionToolkit

Menggunakan UCFunctionToolkit

Contoh ini menggunakan LangChain, tetapi pendekatan serupa dapat diterapkan ke pustaka lain. Lihat Integrasi alat Unity Catalog.

Menginstal dependensi tambahan

Instal paket integrasi LangChain untuk UCFunctionToolkit.

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

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

dbutils.library.restartPython()

Membungkus fungsi menggunakan UCFunctionToolKit

Bungkus fungsi menggunakan UCFunctionToolkit untuk membuatnya dapat diakses oleh perpustakaan untuk penulisan agen. Toolkit ini memastikan konsistensi di berbagai pustaka AI dan menambahkan fitur berguna seperti pelacakan otomatis untuk retriever.

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

Menggunakan alat di dalam agen

Tambahkan alat ke agen LangChain dengan menggunakan properti tools dari UCFunctionToolkit.

Note

Contoh ini menggunakan LangChain. Namun Anda dapat mengintegrasikan alat Unity Catalog dengan kerangka kerja lain seperti LlamaIndex, OpenAI, Anthropic, dan banyak lagi. Lihat Integrasi alat Unity Catalog.

Contoh ini menulis agen sederhana menggunakan LangChain AgentExecutor API untuk kesederhanaan. Untuk beban kerja produksi, gunakan alur kerja penulisan agen yang terlihat di Penulis agen dan sebarkan di Aplikasi Databricks.

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?"})

Meningkatkan penggunaan alat dengan dokumentasi yang jelas

Dokumentasi yang baik membantu agen Anda mengetahui kapan dan bagaimana menggunakan setiap alat. Ikuti praktik terbaik ini untuk mendokumen alat Anda:

  • Untuk fungsi Katalog Unity, gunakan COMMENT klausul untuk menjelaskan fungsionalitas dan parameter alat.
  • Tentukan input dan output yang diharapkan dengan jelas.
  • Tulis deskripsi yang bermakna untuk mempermudah alat bagi agen, dan manusia, untuk digunakan.

Contoh: Dokumentasi alat yang efektif

Contoh berikut menunjukkan string yang jelas COMMENT untuk alat yang meminta tabel terstruktur.

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;

Contoh: Dokumentasi alat yang tidak efektif

Contoh berikut tidak memiliki detail penting, sehingga lebih sulit bagi agen untuk menggunakan alat ini secara efektif:

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;

Menjalankan fungsi menggunakan mode tanpa server atau lokal

Saat layanan AI menentukan bahwa pemanggilan alat diperlukan, paket integrasi (instance UCFunctionToolkit) menjalankan API DatabricksFunctionClient.execute_function.

Panggilan execute_function dapat menjalankan fungsi dalam dua mode eksekusi: tanpa server atau lokal. Mode ini menentukan sumber daya mana yang menjalankan fungsi.

Mode tanpa server untuk produksi

Mode tanpa server adalah opsi default dan direkomendasikan untuk kasus penggunaan produksi saat menjalankan fungsi Katalog Unity sebagai alat agen. Mode ini menggunakan komputasi generik tanpa server (Spark Connect tanpa server) untuk menjalankan fungsi dari jarak jauh, dan Lakeguard memastikan bahwa proses agen Anda tetap aman dan bebas dari risiko menjalankan kode arbitrer secara lokal.

Note

Fungsi Unity Catalog yang dijalankan sebagai alat agen memerlukan komputasi generik serverless (Spark Connect serverless), bukan gudang data SQL serverless. Upaya untuk menjalankan alat tanpa dukungan komputasi generik berbasis serverless akan menghasilkan kesalahan seperti PERMISSION_DENIED: Cannot access Spark Connect.

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

Saat agen Anda meminta eksekusi alat dalam mode tanpa server , hal berikut ini terjadi:

  1. DatabricksFunctionClient mengirim permintaan ke Katalog Unity untuk mengambil definisi fungsi jika definisi belum di-cache secara lokal.
  2. DatabricksFunctionClient mengekstrak definisi fungsi dan memvalidasi nama dan jenis parameter.
  3. DatabricksFunctionClient mengirimkan eksekusi sebagai UDF ke komputasi generik tanpa server.

Mode lokal untuk pengembangan

Mode lokal menjalankan fungsi Python dalam subprosces lokal alih-alih membuat permintaan ke komputasi generik tanpa server. Ini memungkinkan Anda memecahkan masalah panggilan alat secara lebih efektif dengan menyediakan jejak tumpukan lokal. Ini dirancang untuk mengembangkan dan men-debug fungsi Python Unity Catalog.

Saat agen Anda meminta menjalankan alat dalam mode lokal , DatabricksFunctionClient lakukan hal berikut:

  1. Mengirim permintaan ke Katalog Unity untuk mengambil definisi fungsi jika definisi belum di-cache secara lokal.
  2. Mengekstrak definisi fungsi Python yang dapat dipanggil, menyimpan fungsi tersebut dalam cache secara lokal, dan memvalidasi nama serta jenis parameter.
  3. Memanggil fungsi yang dapat dipanggil dengan parameter yang ditentukan dalam subproses terbatas dengan pelindung batas waktu.
# Defaults to serverless if `execution_mode` is not specified
client = DatabricksFunctionClient(execution_mode="local")

Berjalan dalam "local" mode menyediakan fitur berikut:

  • Batas waktu CPU: Membatasi total runtime CPU untuk eksekusi yang dapat dipanggil untuk mencegah beban komputasi yang berlebihan.

    Batas waktu CPU didasarkan pada penggunaan CPU aktual, bukan waktu jam dinding. Karena penjadwalan sistem dan proses bersamaan, waktu CPU dapat melebihi waktu jam dinding dalam skenario dunia nyata.

  • Batas memori: Membatasi memori virtual yang dialokasikan untuk proses.

  • Perlindungan batas waktu: Memberlakukan batas waktu keseluruhan untuk menjalankan fungsi.

Sesuaikan batas ini menggunakan variabel lingkungan (baca lebih lanjut).

Batasan mode lokal

  • Hanya fungsi Python: Fungsi berbasis SQL tidak didukung dalam mode lokal.
  • Pertimbangan keamanan untuk kode yang tidak tepercaya: Meskipun mode lokal menjalankan fungsi dalam subproses untuk isolasi proses, ada potensi risiko keamanan saat menjalankan kode arbitrer yang dihasilkan oleh sistem AI. Ini terutama menjadi perhatian ketika fungsi menjalankan kode Python yang dihasilkan secara dinamis yang belum ditinjau.
  • Perbedaan versi pustaka: Versi pustaka mungkin berbeda antara lingkungan eksekusi tanpa server dan lokal, yang dapat menyebabkan perilaku fungsi yang berbeda.

Variabel lingkungan

Konfigurasikan bagaimana fungsi berjalan dalam DatabricksFunctionClient menggunakan variabel lingkungan berikut:

Variabel lingkungan Nilai bawaan Description
EXECUTOR_MAX_CPU_TIME_LIMIT 10 detik Waktu eksekusi CPU maksimum yang diizinkan (hanya mode lokal).
EXECUTOR_MAX_MEMORY_LIMIT 100 MB Alokasi memori virtual maksimum yang diizinkan untuk proses (hanya mode lokal).
EXECUTOR_TIMEOUT 20 detik Total waktu jam dinding maksimum (hanya mode lokal).
UCAI_DATABRICKS_SESSION_RETRY_MAX_ATTEMPTS 5 Jumlah maksimum upaya untuk mencoba menyegarkan kembali klien sesi jika token kedaluwarsa.
UCAI_DATABRICKS_SERVERLESS_EXECUTION_RESULT_ROW_LIMIT 100 Jumlah maksimum baris yang akan dikembalikan saat menjalankan fungsi menggunakan komputasi tanpa server dan databricks-connect.

Memanggil API eksternal dengan http_request (warisan)

Anda dapat membuat fungsi Unity Catalog yang membungkus http_request() untuk memanggil layanan eksternal dari definisi alat berbasis SQL. Pendekatan ini tetap didukung tetapi tidak lagi direkomendasikan untuk integrasi baru. Untuk panduan lanjut, termasuk contoh SQL dan batasan tipe koneksi, lihat Unity Catalog function tools with HTTP connection.

Contoh buku catatan

Notebook berikut mendemonstrasikan cara membuat alat untuk agen yang terhubung ke layanan eksternal menggunakan fungsi Unity Catalog.

Alat agen olahpesan Slack

Dapatkan buku catatan

Alat agen Microsoft Graph API

Dapatkan buku catatan

Alat agen Pencarian Azure AI

Dapatkan buku catatan

Langkah berikutnya

  • Last updated on