AI-agenthulpprogramma's maken met Unity Catalog-functies

Gebruik Unity Catalog-functies om AI-agenthulpprogramma's te maken die aangepaste logica uitvoeren en specifieke taken uitvoeren waarmee de mogelijkheden van LLM's buiten taalgeneratie worden uitgebreid.

Wanneer gebruikt u Unity Catalog-functies versus MCP-servers

Databricks raadt het gebruik van Unity Catalog-functies aan als agenthulpprogramma's specifiek voor gestructureerde hulpprogramma's voor het ophalen van gegevens wanneer de query van tevoren bekend is en de agent de parameters levert. Zie Agents verbinden met gestructureerde gegevens.

In de meeste andere gebruiksvoorbeelden raadt Databricks MCP-servers aan of definieert u de logica rechtstreeks in agentcode voor snellere uitvoering, ondersteuning voor verificatie per gebruiker en extra flexibiliteit.

Requirements

Als u Unity Catalog-functies wilt maken en gebruiken als AI-agenthulpprogramma's, hebt u het volgende nodig:

• Databricks Runtime: Databricks Runtime 15.0 en hoger gebruiken
• Python-versie: Python 3.10 of hoger installeren

Unity Catalog-functies uitvoeren:

• Serverloze rekenkracht moet in uw werkruimte zijn ingeschakeld om Unity Catalog-functies als AI-agenttools in productie uit te voeren. Zie serverloze rekenvereisten.
  • Uitvoering van lokale modus voor Python-functies vereist geen serverloze algemene berekeningen, maar de lokale modus is alleen bedoeld voor ontwikkelings- en testdoeleinden.

Ga als volgende te werk om Unity Catalog-functies te maken:

• Serverloze algemene rekenkracht moet zijn ingeschakeld in uw werkruimte om functies te maken met behulp van de Databricks Workspace Client- of SQL-hoofdtekstinstructies.
  • Python-functies kunnen worden gemaakt zonder serverloze rekenkracht.

Een Unity Catalog-functiehulpprogramma maken

In de volgende stappen ziet u hoe u een Unity Catalog-functie maakt en test. Voer de volgende code uit in een Databricks-notebook.

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.

Afhankelijkheden installeren

Installeer AI-pakketten voor Unity Catalog met de [databricks] extra.

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

dbutils.library.restartPython()

De Databricks-functieclient initialiseren

Initialiseer de Databricks-functieclient, een gespecialiseerde interface voor het maken, beheren en uitvoeren van Unity Catalog-functies in Databricks.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

De logica van het hulpprogramma definiëren

Unity Catalog-hulpprogramma's zijn eigenlijk alleen door de gebruiker gedefinieerde functies (UDF's) van Unity Catalog. Wanneer u een Unity Catalog-hulpprogramma definieert, registreert u een functie in Unity Catalog. Zie Door de gebruiker gedefinieerde functies (UDF's) in Unity Catalog voor meer informatie over UDF's (Unity Catalog).

U kunt Unity Catalog-functies maken met behulp van een van de twee API's:

• create_python_function accepteert een Python-aanroepbaar.
• create_function accepteert een SQL body CREATE FUNCTION-instructie. Zie Python-functies maken.

Gebruik de create_python_function API om de functie te maken.

Als u een Python aanroepbaar wilt maken die kan worden herkend aan het gegevensmodel van de Unity Catalog-functies, moet uw functie voldoen aan de volgende vereisten:

• Type hints: De functiehandtekening moet geldige Python typehints definiëren. Zowel de benoemde argumenten als de retourwaarde moeten hun typen hebben gedefinieerd.
• Gebruik geen variabeleargumenten: Variabeleargumenten zoals *args en **kwargs worden niet ondersteund. Alle argumenten moeten expliciet worden gedefinieerd.
• Typecompatibiliteit: niet alle Python-typen worden ondersteund in SQL. Zie ondersteunde Spark-gegevenstypen.
• Beschrijvende docstrings: De Toolkit voor Unity Catalog-functies leest, parseert en extraheert belangrijke informatie uit uw docstring.
  • Docstrings moeten worden opgemaakt volgens de syntaxis van Google docstring.
  • Schrijf duidelijke beschrijvingen voor uw functie en de bijbehorende argumenten om de LLM te helpen begrijpen hoe en wanneer de functie moet worden gebruikt.
• Import van afhankelijkheden: bibliotheken moeten binnen de functie worden geïmporteerd. Importeren buiten de functie wordt niet opgelost bij het uitvoeren van het hulpprogramma.

De volgende codefragmenten gebruiken de create_python_function om de aanroepbare Python-functie add_numbers te registreren:

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
)

De functie testen

Test uw functie om te controleren of deze werkt zoals verwacht. Geef een volledig gekwalificeerde functienaam op in de execute_function API om de functie uit te voeren:

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-functies toevoegen aan uw agent

Nadat u uw Unity Catalog-functie hebt gemaakt en getest, kiest u een van de volgende methoden om deze toe te voegen aan uw agent.

MCP gebruiken (aanbevolen)

MCP gebruiken (aanbevolen)

Databricks raadt het gebruik van MCP-servers aan om Unity Catalog-functies toe te voegen aan uw agent. De MCP-benadering biedt een eenvoudigere integratie met automatische detectie van hulpprogramma's en ingebouwde verificatieondersteuning.

De beheerde MCP-URL voor Unity Catalog-functies is: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}. U kunt desgewenst een specifieke functie opgeven door toe te /{function_name}voegen.

In de volgende voorbeelden ziet u hoe u uw agent verbindt met Unity Catalog-functies via MCP. Vervang <catalog> en <schema> door de locatie van uw functies.

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)

Verleen de app toegang tot de Unity Catalog-functie 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)

Verleen de app toegang tot de Unity Catalog-functie 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'

Model serveren

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

Zie Een agent implementeren voor generatieve AI-toepassingen (Model Serving) om de agent te implementeren. Zie Azure Databricks beheerde MCP-servers voor meer informatie over het registreren van agents met MCP-resources.

UCFunctionToolkit gebruiken

UCFunctionToolkit gebruiken

In dit voorbeeld wordt LangChain gebruikt, maar een vergelijkbare benadering kan worden toegepast op andere bibliotheken. Zie Integratie van hulpprogramma's voor Unity Catalog.

Aanvullende afhankelijkheden installeren

Installeer de LangChain-integratiepakketten voor 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()

De functie verpakken met behulp van de UCFunctionToolKit

Wikkel de functie in met behulp van de UCFunctionToolkit om deze toegankelijk te maken voor agent authoring libraries. De toolkit zorgt voor consistentie in verschillende GEN AI-bibliotheken en voegt nuttige functies toe, zoals automatisch traceren voor retrievers.

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

Het hulpprogramma in een agent gebruiken

Voeg het hulpprogramma toe aan een LangChain-agent met behulp van de tools eigenschap van UCFunctionToolkit.

Note

In dit voorbeeld wordt LangChain gebruikt. U kunt Unity Catalog-hulpprogramma's echter integreren met andere frameworks, zoals LlamaIndex, OpenAI, Antropic en meer. Zie Integratie van hulpprogramma's voor Unity Catalog.

In dit voorbeeld wordt een eenvoudige agent gemaakt met behulp van de LangChain-API AgentExecutor voor het gemak. Voor productieworkloads gebruikt u de werkstroom voor het ontwerpen van agents die wordt weergegeven in Een AI-agent ontwerpen en implementeren in Databricks-apps.

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

Het aanroepen van hulpprogramma's verbeteren met duidelijke documentatie

Goede documentatie helpt uw medewerkers te weten wanneer en hoe ze elk hulpprogramma moeten gebruiken. Volg deze aanbevolen procedures voor het documenteren van uw hulpprogramma's:

• Voor Unity Catalog-functies gebruikt u de COMMENT component om de functionaliteit en parameters van het hulpprogramma te beschrijven.
• Definieer duidelijk de verwachte invoer en uitvoer.
• Schrijf zinvolle beschrijvingen om hulpprogramma's voor agents en mensen gemakkelijker te gebruiken.

Voorbeeld: Effectieve hulpprogrammadocumentatie

In het volgende voorbeeld ziet u duidelijke COMMENT tekenreeksen voor een hulpprogramma waarmee een query wordt uitgevoerd op een gestructureerde tabel.

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;

Voorbeeld: Ineffectieve hulpprogrammadocumentatie

In het volgende voorbeeld ontbreken belangrijke details, waardoor het voor agents moeilijker is om het hulpprogramma effectief te gebruiken:

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;

Functies uitvoeren met serverloze of lokale modus

Wanneer een gen AI-service bepaalt dat er een hulpprogramma-aanroep nodig is, voeren integratiepakketten (UCFunctionToolkit exemplaren) de DatabricksFunctionClient.execute_function API uit.

De execute_function aanroep kan functies uitvoeren in twee uitvoeringsmodi: serverloos of lokaal. Deze modus bepaalt welke resource de functie uitvoert.

Serverloze modus voor productie

Serverloze modus is de standaard- en aanbevolen optie voor productiegebruiksscenario's bij het uitvoeren van Unity Catalog-functies als AI-agenthulpprogramma's. In deze modus wordt gebruikgemaakt van serverloze algemene compute (Serverloze Spark Connect) om functies op afstand uit te voeren en Zorgt Lakeguard ervoor dat het proces van uw agent veilig en vrij blijft van de risico's van het lokaal uitvoeren van willekeurige code.

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

Wanneer uw agent een uitvoering van een hulpprogramma aanvraagt in de serverloze modus, gebeurt het volgende:

1. Een verzoek wordt naar Unity Catalog gestuurd om de functiedefinitie op te halen als de definitie niet lokaal is gecachet.
2. De DatabricksFunctionClient functiedefinitie wordt geëxtraheerd en de parameternamen en -typen gevalideerd.
3. De DatabricksFunctionClient uitvoering wordt verzonden als een UDF naar serverloze algemene berekening.

Lokale modus voor ontwikkeling

In de lokale modus worden Python-functies uitgevoerd in een lokaal subproces in plaats van aanvragen te verzenden naar serverloze algemene berekeningen. Hierdoor kunt u efficiënter problemen met hulpprogramma-aanroepen oplossen door lokale stack-traceringen op te geven. Het is ontworpen voor het ontwikkelen en debuggen van functies van de Python Unity Catalog.

Wanneer uw agent vraagt om een hulpprogramma in lokale modus uit te voeren, doet DatabricksFunctionClient het volgende:

1. Hiermee wordt een aanvraag naar Unity Catalog verzonden om de functiedefinitie op te halen als de definitie niet lokaal in de cache is opgeslagen.
2. Extraheert de aanroepbare Python-definitie, slaat de aanroepbare lokaal op en valideert de parameternamen en -typen.
3. Roept de oproepbare functie aan met de opgegeven parameters in een beperkt subproces met bescherming tegen time-outs.

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

Draaien in modus "local" biedt de volgende functies:

• CPU-tijdslimiet: Hiermee beperkt u de totale CPU-runtime voor aanroepbare uitvoering om overmatige rekenkracht te voorkomen.

  De CPU-tijdslimiet is gebaseerd op het werkelijke CPU-gebruik, niet op wandkloktijd. Vanwege systeemplanning en gelijktijdige processen kan de CPU-tijd de tijd van de wandklok in realtime scenario's overschrijden.

• Geheugenlimiet: Hiermee beperkt u het virtuele geheugen dat aan het proces is toegewezen.

• Time-outbeveiliging: Hiermee wordt een time-out van de totale wandklok afgedwongen voor het uitvoeren van functies.

Pas deze limieten aan met behulp van omgevingsvariabelen (lees verder).

Beperkingen van de lokale modus

• Python functies alleen: op SQL gebaseerde functies worden niet ondersteund in de lokale modus.
• Beveiligingsoverwegingen voor niet-vertrouwde code: terwijl in de lokale modus functies worden uitgevoerd in een subproces voor procesisolatie, is er een potentieel beveiligingsrisico bij het uitvoeren van willekeurige code die door AI-systemen wordt gegenereerd. Dit is voornamelijk een probleem wanneer functies dynamisch gegenereerde Python-code uitvoeren die niet is gecontroleerd.
• Verschillen in bibliotheekversies: Bibliotheekversies kunnen verschillen tussen serverloze en lokale uitvoeringsomgevingen, wat kan leiden tot ander functiegedrag.

Omgevingsvariabelen

Configureer hoe functies worden uitgevoerd in de DatabricksFunctionClient met behulp van de volgende omgevingsvariabelen:

Externe API's aanroepen met http_request (verouderd)

U kunt een Unity Catalog-functie maken die wordt verpakt http_request() om externe services aan te roepen. Deze methode is handig voor op SQL gebaseerde hulpprogrammadefinities.

In het volgende voorbeeld wordt een functiehulpprogramma voor Unity Catalog gemaakt waarmee een bericht naar Slack wordt geplaatst:

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

Zie CREATE FUNCTION (SQL en Python).

Voorbeeldnotitieboeken

De volgende notebooks laten zien hoe u AI-agenthulpprogramma's maakt die verbinding maken met externe services met behulp van Unity Catalog-functies.

Slack Messaging Agent-hulpprogramma

Notebook krijgen

Microsoft Graph API-agent hulpprogramma

Notebook krijgen

Azure AI Zoeken-agent hulpprogramma

Notebook krijgen

Volgende stappen 

• Voeg Unity Catalog-hulpprogramma's programmatisch toe aan agents. Zie Een AI-agent ontwerpen en implementeren in Databricks-apps.

• Voeg Unity Catalog-hulpprogramma's toe aan agents met behulp van de AI Playground-gebruikersinterface. Zie Aan de slag: queries uitvoeren op LLM's en prototypen van AI-agenten zonder te coderen.

• Beheer Unity Catalog-functies met behulp van de functieclient. Raadpleeg documentatie voor Unity Catalog - Functieclient

• Verbind agents met hulpprogramma's van derden met MCP-services voor een overzicht van alle benaderingen om agents te verbinden met externe services.