Erstellen von KI-Agent-Tools mithilfe von Unity-Katalogfunktionen

Verwenden Sie Unity Catalog-Funktionen, um KI-Agent-Tools zu erstellen, die benutzerdefinierte Logik ausführen und bestimmte Aufgaben ausführen, die die Funktionen von LLMs über die Sprachgenerierung hinaus erweitern.

Wann Unity Catalog-Funktionen anstelle von MCP-Servern verwendet werden sollten

Databricks empfiehlt die Verwendung von Unity-Katalogfunktionen als Agent-Tools speziell für strukturierte Datenabruftools, wenn die Abfrage rechtzeitig bekannt ist und der Agent die Parameter bereitstellt. Siehe Verbinden von Agents mit strukturierten Daten.

In den meisten anderen Anwendungsfällen empfiehlt Databricks MCP-Server oder die Definition der Logik direkt im Agentcode für eine schnellere Ausführung, Unterstützung der Benutzerauthentifizierung und zusätzliche Flexibilität.

Anforderungen

Um Unity Catalog-Funktionen als KI-Agent-Tools zu erstellen und zu verwenden, benötigen Sie Folgendes:

• Databricks Runtime: Verwenden Von Databricks Runtime 15.0 und höher
• Python Version: Installieren Python 3.10 oder höher

So führen Sie Unity-Katalogfunktionen aus:

• Serverlose Berechnung muss in Ihrem Arbeitsbereich aktiviert sein, um Unity Catalog-Funktionen als KI-Agent-Tools in der Produktion auszuführen. Siehe Serverlose Computeanforderungen.
  • Lokale Modus-Ausführung für Python-Funktionen erfordert keine serverlosen generischen Rechenressourcen zum Ausführen. Der lokale Modus ist jedoch nur für Entwicklungs- und Testzwecke vorgesehen.

So erstellen Sie Unity-Katalogfunktionen:

• Serverless Generic Compute muss in Ihrem Arbeitsbereich aktiviert sein, um Funktionen mit dem Databricks Workspace-Client oder mit SQL-Anweisungen zu erstellen.
  • Python Funktionen können ohne serverlose Berechnung erstellt werden.

Erstellen eines Unity-Katalog-Funktionstools

Die folgenden Schritte zeigen, wie Sie eine Unity Catalog-Funktion erstellen und testen. Führen Sie den folgenden Code in einem Databricks-Notizbuch aus.

Installieren von Abhängigkeiten

Installieren Sie KI-Pakete im Unity Catalog mit dem zusätzlichen [databricks].

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

dbutils.library.restartPython()

Initialisieren des Databricks-Funktionsclients

Initialisieren Sie den Databricks Function Client, der eine spezielle Schnittstelle zum Erstellen, Verwalten und Ausführen von Unity-Katalogfunktionen in Databricks ist.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Definieren der Logik des Tools

Unity Catalog-Tools sind wirklich nur benutzerdefinierte Unity-Katalog-Funktionen (UDFs) unter der Haube. Wenn Sie ein Unity-Katalogtool definieren, registrieren Sie eine Funktion im Unity-Katalog. Weitere Informationen zu Unity-Katalog-UDFs finden Sie unter Benutzerdefinierte Funktionen (UDFs) im Unity-Katalog.

Sie können Unity-Katalogfunktionen mit einer von zwei APIs erstellen:

• create_python_function akzeptiert ein Python Callable.
• create_function akzeptiert eine „SQL body create function“-Anweisung. Weitere Informationen finden Sie unter Create Python functions.

Verwenden Sie die create_python_function API, um die Funktion zu erstellen.

Damit ein Python-Callable im Datenmodell der Unity-Katalog-Funktionen erkannt wird, muss Ihre Funktion die folgenden Anforderungen erfüllen:

• Type-Hinweise: Die Funktionssignatur muss gültige Python Typhinweise definieren. Sowohl die benannten Argumente als auch der Rückgabewert müssen ihre Typen definiert haben.
• Verwenden Sie keine Variablenargumente: Variablenargumente wie *args und **kwargs werden nicht unterstützt. Alle Argumente müssen explizit definiert werden.
• Type-Kompatibilität: Nicht alle Python Typen werden in SQL unterstützt. Siehe spark supported data types.
• Beschreibende Docstrings: Das Unity Catalog Functions Toolkit liest, analysiert und extrahiert wichtige Informationen aus Ihrem Docstring.
  • Docstrings müssen gemäß der Google Docstring-Syntax formatiert werden.
  • Schreiben Sie klare Beschreibungen für Ihre Funktion und ihre Argumente, damit der LLM verstehen kann, wie und wann die Funktion verwendet werden soll.
• Abhängigkeitsimporte: Bibliotheken müssen innerhalb des Textkörpers der Funktion importiert werden. Importe außerhalb der Funktion werden beim Ausführen des Tools nicht aufgelöst.

Der folgende Codeausschnitt verwendet die create_python_function, um die Python-aufrufbare add_numbers zu registrieren.

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
)

Testen der Funktion

Testen Sie Ihre Funktion, um sicherzustellen, dass sie wie erwartet funktioniert. Geben Sie einen vollqualifizierten Funktionsnamen in der execute_function API an, um die Funktion auszuführen:

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'

Hinzufügen von Unity-Katalogfunktionen zu Ihrem Agent

Nachdem Sie Ihre Unity Catalog-Funktion erstellt und getestet haben, wählen Sie einen der folgenden Ansätze aus, um sie Ihrem Agent hinzuzufügen.

Verwenden von MCP (empfohlen)

Verwenden von MCP (empfohlen)

Databricks empfiehlt die Verwendung von MCP-Servern, um Ihrem Agent Unity Catalog-Funktionen hinzuzufügen. Der MCP-Ansatz bietet eine einfachere Integration mit automatischer Toolermittlung und Unterstützung für integrierte Authentifizierung.

Die verwaltete MCP-URL für Unity-Katalogfunktionen lautet: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}. Sie können optional eine bestimmte Funktion angeben, indem Sie diese anfügen /{function_name}.

Die folgenden Beispiele zeigen, wie Sie Ihren Agent über MCP mit Unity Catalog-Funktionen verbinden. Ersetzen Sie <catalog> und <schema> durch die Position Ihrer Funktionen.

OpenAI Agents SDK (Apps)

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)

Gewähren Sie der App Zugriff auf die Unity-Katalogfunktion in 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 (Apps)

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)

Gewähren Sie der App Zugriff auf die Unity-Katalogfunktion in 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'

Bereitstellung von Modellen

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(),
)

Informationen zum Bereitstellen des Agents finden Sie unter Bereitstellen eines Agents für generative KI-Anwendungen (Model Serving). Ausführliche Informationen zum Protokollieren von Agents mit MCP-Ressourcen finden Sie unter Use Databricks managed MCP servers.

Verwenden von UCFunctionToolkit

Verwenden von UCFunctionToolkit

In diesem Beispiel wird LangChain verwendet, aber ein ähnlicher Ansatz kann auf andere Bibliotheken angewendet werden. Siehe Integration von Unity-Katalogtools in generative KI-Frameworks von Drittanbietern.

Installieren zusätzlicher Abhängigkeiten

Installieren Sie die LangChain-Integrationspakete für UCFunctionToolkit.

%pip install unitycatalog-langchain[databricks]

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

dbutils.library.restartPython()

Die Funktion mithilfe des UCFunctionToolKit umschließen

Umschließen Sie die Funktion mithilfe des UCFunctionToolkit, um sie für die Agenterstellungsbibliotheken zugänglich zu machen. Das Toolkit sorgt für Konsistenz in verschiedenen generativen KI-Bibliotheken und fügt hilfreiche Funktionen wie das automatische Tracking für Retriever hinzu.

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

Verwenden des Tools in einem Agent

Fügen Sie das Tool einem LangChain-Agent mithilfe der Eigenschaft tools aus dem UCFunctionToolkit hinzu.

Hinweis

In diesem Beispiel wird LangChain verwendet. Sie können jedoch Unity-Katalogtools in andere Frameworks wie LlamaIndex, OpenAI, Anthropic und mehr integrieren. Siehe Integration von Unity-Katalogtools in generative KI-Frameworks von Drittanbietern.

In diesem Beispiel wird ein einfacher Agent mit der LangChain-API AgentExecutor aus Gründen der Einfachheit erstellt. Verwenden Sie für Produktionsworkloads den Agenterstellungsworkflow, der in "Author an AI"-Agent angezeigt wird, und stellen Sie ihn in Databricks-Apps bereit.

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

Verbesserung des Aufrufs von Tools mit klarer Dokumentation

Eine gute Dokumentation hilft Ihren Agents zu wissen, wann und wie Sie jedes Tool verwenden. Befolgen Sie die folgenden bewährten Methoden zum Dokumentieren Ihrer Tools:

• Verwenden Sie für Unity-Katalogfunktionen die COMMENT Klausel zum Beschreiben von Toolfunktionen und Parametern.
• Definieren Sie die erwarteten Eingaben und Ausgaben eindeutig.
• Schreiben Sie aussagekräftige Beschreibungen, um Tools für Agenten und Menschen zu vereinfachen.

Beispiel: Effektive Tooldokumentation

Das folgende Beispiel zeigt klare COMMENT Zeichenfolgen für ein Tool, das eine strukturierte Tabelle abfragt.

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;

Beispiel: Ineffektive Tooldokumentation

Im folgenden Beispiel fehlen wichtige Details, wodurch es für Agents schwieriger wird, das Tool effektiv zu verwenden:

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;

Ausführen von Funktionen mithilfe des serverlosen oder lokalen Modus

Wenn ein generativer KI-Dienst ermittelt, dass ein Tool-Aufruf erforderlich ist, führen Integrationspakete (UCFunctionToolkit Instanzen) die DatabricksFunctionClient.execute_function API aus.

Der execute_function Aufruf kann Funktionen in zwei Ausführungsmodi ausführen: serverlos oder lokal. Dieser Modus bestimmt, welche Ressource die Funktion ausführt.

Serverloser Modus für die Produktion

Der Serverless-Modus ist die Standard- und empfohlene Option für Produktionsanwendungsfälle beim Ausführen von Unity Catalog-Funktionen als KI-Agent-Tools. Dieser Modus verwendet serverlose generische Rechenleistung (Spark Connect serverless), um Funktionen remote auszuführen, und Lakeguard stellt sicher, dass der Prozess Ihres Agents sicher bleibt und nicht den Risiken ausgesetzt ist, beliebigen Code lokal auszuführen.

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

Wenn Ihr Agent eine Toolausführung im serverlosen Modus anfordert, geschieht Folgendes:

1. Die DatabricksFunctionClient Sendet eine Anforderung an unity Catalog, um die Funktionsdefinition abzurufen, wenn die Definition nicht lokal zwischengespeichert wurde.
2. Die DatabricksFunctionClient Funktionsdefinition extrahiert und überprüft die Parameternamen und -typen.
3. Die DatabricksFunctionClient übermittelt die Ausführung als UDF an serverlose generische Rechenkraft.

Lokaler Modus für die Entwicklung

Der lokale Modus führt Python Funktionen in einem lokalen Unterprozess aus, anstatt Anforderungen an serverlose generische Compute zu senden. Auf diese Weise können Sie Toolaufrufe effektiver beheben, indem Sie lokale Stack-Traces bereitstellen. Sie wurde für die Entwicklung und das Debuggen Python Unity-Katalogfunktionen entwickelt.

Wenn Ihr Agent die Ausführung eines Tools im lokalen Modus anfordert, führt DatabricksFunctionClient Folgendes aus:

1. Sendet eine Anforderung an unity Catalog, um die Funktionsdefinition abzurufen, wenn die Definition nicht lokal zwischengespeichert wurde.
2. Extrahiert die aufrufbare Python-Definition, speichert den aufrufbaren Code lokal und überprüft die Parameternamen und -typen.
3. Ruft die callable-Funktion mit den angegebenen Parametern in einem eingeschränkten Unterprozess mit Timeoutschutz auf.

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

Die Ausführung im "local" Modus bietet die folgenden Features:

• CPU-Zeitlimit: Schränkt die gesamte CPU-Laufzeit für die aufrufbare Ausführung ein, um übermäßige Rechenlasten zu verhindern.

  Das CPU-Zeitlimit basiert auf der tatsächlichen CPU-Auslastung, nicht auf der Wanduhrzeit. Aufgrund der Systemplanung und gleichzeitiger Prozesse kann die CPU-Zeit in Echtzeitszenarien die Wall-Clock-Zeit überschreiten.

• Speicherlimit: Schränkt den virtuellen Speicher ein, der dem Prozess zugeordnet ist.

• Timeoutschutz: Erzwingt ein Gesamtbetrachtungs-Timeout für ausgeführte Funktionen.

Passen Sie diese Grenzwerte mithilfe von Umgebungsvariablen an (lesen Sie weiter).

Einschränkungen für den lokalen Modus

• nur Python Funktionen: SQL-basierte Funktionen werden im lokalen Modus nicht unterstützt.
• Sicherheitsüberlegungen für nicht vertrauenswürdigen Code: Während der lokale Modus Funktionen in einem Teilprozess zur Prozessisolation ausführt, besteht ein potenzielles Sicherheitsrisiko beim Ausführen von beliebigem Code, der von KI-Systemen generiert wird. Dies ist in erster Linie ein Problem, wenn Funktionen dynamisch generierten Python Code ausführen, der nicht überprüft wurde.
• Unterschiede bei der Bibliotheksversion: Bibliotheksversionen können sich zwischen serverlosen und lokalen Ausführungsumgebungen unterscheiden, was zu unterschiedlichen Funktionsverhalten führen kann.

Umgebungsvariablen

Konfigurieren Sie, wie Funktionen mit den folgenden Umgebungsvariablen in DatabricksFunctionClient ausgeführt werden.

Beispielnotebooks

Die folgenden Notizbücher veranschaulichen das Erstellen von KI-Agent-Tools, die mithilfe von Unity-Katalogfunktionen eine Verbindung mit externen Diensten herstellen.

Messagingagententool von Slack

Notebook abrufen

Microsoft Graph-API-Agent-Tool

Notebook abrufen

Azure-AI-Suchagent-Tool

Notebook abrufen

Nächste Schritte

• Fügen Sie Unity-Katalogtools programmgesteuert zu Agents hinzu. Weitere Informationen finden Sie unter Erstellen eines KI-Agenten und Bereitstellung in Databricks-Apps.

• Fügen Sie Unity-Katalog-Tools zu Agenten hinzu, die die Benutzeroberfläche des KI-Playgrounds verwenden. Weitere Informationen finden Sie unter "Erste Schritte": Abfrage-LLMs und Prototyp-KI-Agents ohne Code.

• Verwalten Sie Unity-Katalogfunktionen mithilfe des Funktionsclients. Siehe Unity-Katalogdokumentation – Funktionsclient

• Verbinden Sie Agents mit externen Diensten , um einen Überblick über alle Ansätze zum Verbinden von Agents mit externen Diensten zu haben.