Membuat alat agen AI menggunakan fungsi Unity Catalog

Gunakan fungsi Unity Catalog untuk membuat alat agen AI 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.

Persyaratan

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

  • Databricks Runtime: Gunakan Databricks Runtime 15.0 ke atas
  • versi Python: Menginstal 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 AI dalam produksi. Lihat Persyaratan komputasi tanpa server.
    • Eksekusi mode Local 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.

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 Fungsi yang ditentukan pengguna (UDF) di Unity Catalog.

Peringatan

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 Buat fungsi Python.

create_python_function Gunakan API untuk membuat fungsi.

Untuk membuat Python dapat dikenali oleh model data fungsi Unity Catalog, fungsi Anda harus memenuhi persyaratan berikut:

  • Petunjuk tipe: Tanda tangan fungsi harus menentukan petunjuk tipe 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 Tipe: Tidak semua tipe 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 Python yang dapat dipanggil 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 generatif (Model Melayani). Untuk detail tentang agen pengelogan dengan sumber daya MCP, lihat Menggunakan server MCP terkelola Databricks.

Ikon fungsi. Menggunakan UCFunctionToolkit

Menggunakan UCFunctionToolkit

Contoh ini menggunakan LangChain, tetapi pendekatan serupa dapat diterapkan ke pustaka lain. Lihat Mengintegrasikan alat Unity Catalog dengan kerangka kerja AI generatif pihak ketiga.

Menginstal dependensi tambahan

Instal paket integrasi LangChain untuk UCFunctionToolkit.

%pip install unitycatalog-langchain[databricks]

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

dbutils.library.restartPython()

Membungkus fungsi menggunakan UCFunctionToolKit

Bungkus fungsi menggunakan UCFunctionToolkit untuk membuatnya dapat diakses oleh perpustakaan untuk penulisan agen. Toolkit memastikan konsistensi di berbagai pustaka AI generatif dan menambahkan fitur bermanfaat seperti pelacakan otomatis untuk pencari informasi.

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.

Nota

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

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 AI 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

Ketika layanan AI generatif menentukan bahwa pemanggilan fungsi diperlukan, paket integrasi (instans 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 AI. 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.

Nota

Fungsi Katalog Unity yang dijalankan sebagai alat oleh agen AI memerlukan komputasi generik tanpa server (Spark Connect tanpa server), bukan gudang SQL tanpa server. 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 Python fungsi 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

  • Python fungsi saja: 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 Deskripsi
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.

Contoh buku catatan

Buku catatan berikut menunjukkan pembuatan alat agen AI yang tersambung ke layanan eksternal menggunakan fungsi Katalog Unity.

Alat agen olahpesan Slack

Dapatkan buku catatan

Alat agen Microsoft Graph API

Dapatkan buku catatan

alat agen Azure AI Search

Dapatkan buku catatan

Langkah selanjutnya

  • Last updated on