Skapa AI-agentverktyg med hjälp av Unity Catalog-funktioner

Använd Unity Catalog-funktioner för att skapa AI-agentverktyg som kör anpassad logik och utför specifika uppgifter som utökar funktionerna i LLMs utöver språkgenerering.

När du ska använda Unity Catalog-funktioner jämfört med MCP-servrar

Databricks rekommenderar att du använder Unity Catalog-funktioner som agentverktyg specifikt för strukturerade datahämtningsverktyg när frågan är känd i förväg och agenten tillhandahåller parametrarna. Se Ansluta agenter till strukturerade data.

I de flesta andra användningsfall rekommenderar Databricks MCP-servrar eller definierar logiken direkt i agentkoden för snabbare körning, stöd för autentisering per användare och ytterligare flexibilitet.

Kravspecifikation

För att skapa och använda Unity Catalog-funktioner som AI-agentverktyg behöver du följande:

• Databricks Runtime: Använda Databricks Runtime 15.0 och senare
• Python version: Installera Python 3.10 eller senare

Så här kör du Unity Catalog-funktioner:

• Serverlös beräkning måste aktiveras på din arbetsyta för att köra Unity Catalog-funktioner som AI-agentverktyg i produktion. Se Krav för serverlös beräkning.
  • Läge för lokal körning av Python-funktioner kräver inte serverlös generell beräkning för att köras, men läge för lokal körning är endast avsett för utvecklings- och teständamål.

Så här skapar du Unity Catalog-funktioner:

• Serverlös allmän beräkning måste vara aktiverad på arbetsytan för att skapa funktioner med hjälp av Databricks-arbetsyteklienten eller SQL-brödtextinstruktionerna.
  • Python funktioner kan skapas utan serverlös beräkning.

Skapa ett funktionsverktyg för Unity Catalog

Följande steg visar hur du skapar och testar en Unity Catalog-funktion. Kör följande kod i en Databricks-notebook-fil.

Installera beroenden

Installera Unity Catalog AI-paket med [databricks] extra.

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

dbutils.library.restartPython()

Initiera Databricks-funktionsklienten

Initiera Databricks-funktionsklienten, som är ett specialiserat gränssnitt för att skapa, hantera och köra Unity Catalog-funktioner i Databricks.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Definiera verktygets logik

Unity Catalog-verktyg är egentligen bara användardefinierade funktioner i Unity Catalog (UDF: er) under huven. När du definierar ett Unity Catalog-verktyg registrerar du en funktion i Unity Catalog. Mer information om UDF:er för Unity-katalogen finns i Användardefinierade funktioner (UDF:er) i Unity Catalog.

Du kan skapa Unity Catalog-funktioner med något av två API:er:

• create_python_function accepterar en anropsbar funktion i Python.
• create_function accepterar en CREATE FUNCTION-sats för SQL-kropp. Se Skapa Python funktioner.

Använd API:et create_python_function för att skapa funktionen.

Om du vill göra en Python anropsbar igenkännlig för Unity Catalog-funktionsdatamodellen måste funktionen uppfylla följande krav:

• Typmarkeringar: Funktionssignaturen måste ange giltiga Python typmarkeringar. Både de namngivna argumenten och returvärdet måste ha sina typer definierade.
• Använd inte variabelargument: Variabelargument som *args och **kwargs stöds inte. Alla argument måste definieras uttryckligen.
• Type-kompatibilitet: Alla Python typer stöds inte i SQL. Se Spark-datatyper som stöds.
• Beskrivande dokumentsträngar: Verktygslådan för Unity Catalog-funktioner läser, parsar och extraherar viktig information från din dokumentsträng.
  • Docstrings måste formateras enligt Googles docstring-syntax.
  • Skriv tydliga beskrivningar för din funktion och dess argument för att hjälpa LLM att förstå hur och när funktionen ska användas.
• Beroendeimport: Bibliotek måste importeras i funktionens kropp. Importeringar utanför funktionen kommer inte att lösas när verktyget körs.

Följande kodfragment använder create_python_function för att registrera den Python-anropsbara funktionen 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
)

Testa funktionen

Testa funktionen för att kontrollera att den fungerar som förväntat. Ange ett fullständigt kvalificerat funktionsnamn i API:et execute_function för att köra funktionen:

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'

Lägga till Unity Catalog-funktioner i din agent

När du har skapat och testat funktionen Unity Catalog väljer du någon av följande metoder för att lägga till den i din agent.

Använda MCP (rekommenderas)

Använda MCP (rekommenderas)

Databricks rekommenderar att du använder MCP-servrar för att lägga till Unity Catalog-funktioner i din agent. MCP-metoden ger en enklare integrering med automatisk identifiering av verktyg och inbyggt autentiseringsstöd.

Den hanterade MCP-URL:en för Unity Catalog-funktioner är: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}. Du kan också ange en specifik funktion genom att lägga till /{function_name}.

Följande exempel visar hur du ansluter din agent till Unity Catalog-funktioner via MCP. Ersätt <catalog> och <schema> med platsen för dina funktioner.

OpenAI Agents SDK (Appar)

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)

Ge appen åtkomst till funktionen Unity Catalog i 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 (appar)

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)

Ge appen åtkomst till funktionen Unity Catalog i 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'

Modellhantering

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

Information om hur du distribuerar agenten finns i Distribuera en agent för generativa AI-program (modellservering). Mer information om loggningsagenter med MCP-resurser finns i Använda Databricks-hanterade MCP-servrar.

Använda UCFunctionToolkit

Använda UCFunctionToolkit

I det här exemplet används LangChain, men en liknande metod kan tillämpas på andra bibliotek. Se Integrera Unity Catalog-verktyg med generativa AI-ramverk från tredje part.

Installera ytterligare beroenden

Installera LangChain-integreringspaketen för UCFunctionToolkit.

%pip install unitycatalog-langchain[databricks]

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

dbutils.library.restartPython()

Omslut funktionen med hjälp av UCFunctionToolKit

Omslut funktionen med hjälp av UCFunctionToolkit för att göra den tillgänglig för agentredigeringsbibliotek. Verktygslådan säkerställer konsekvens i olika generativa AI-bibliotek och lägger till användbara funktioner som automatisk spårning för sökfunktioner.

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

Använd verktyget i en agent

Lägg till verktyget till en LangChain-agent med hjälp av egenskapen tools från UCFunctionToolkit.

Anmärkning

I det här exemplet används LangChain. Du kan dock integrera Unity Catalog-verktyg med andra ramverk som LlamaIndex, OpenAI, Anthropic med mera. Se Integrera Unity Catalog-verktyg med generativa AI-ramverk från tredje part.

Det här exemplet skapar en enkel agent med hjälp av LangChain AgentExecutor API för enkelhet. För produktionsarbetsbelastningar använder du arbetsflödet för agentredigering som visas i Skapa en AI-agent och distribuera den i Databricks-appar.

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

Förbättra användning av verktyg med tydlig dokumentation

Bra dokumentation hjälper dina agenter att veta när och hur de ska använda varje verktyg. Följ dessa metodtips för att dokumentera dina verktyg:

• För Unity Catalog-funktioner använder du COMMENT -satsen för att beskriva verktygsfunktioner och parametrar.
• Definiera tydligt förväntade indata och utdata.
• Skriv meningsfulla beskrivningar för att göra verktyg enklare för agenter och människor att använda.

Exempel: Dokumentation om effektiva verktyg

I följande exempel visas tydliga COMMENT strängar för ett verktyg som frågar en strukturerad tabell.

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;

Exempel: Dokumentation om ineffektivt verktyg

I följande exempel saknas viktig information, vilket gör det svårare för agenter att använda verktyget effektivt:

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;

Köra funktioner med serverlöst eller lokalt läge

När en generativ AI-tjänst bestämmer att ett verktygsanrop behövs kör integrationspaket (UCFunctionToolkit instanser) DatabricksFunctionClient.execute_function-API:et.

Anropet execute_function kan köra funktioner i två körningslägen: serverlös eller lokal. Det här läget avgör vilken resurs som kör funktionen.

Serverlöst läge för produktion

Serverlöst läge är standardalternativet och rekommenderas för produktionsanvändningsfall när du kör Unity Catalog-funktioner som AI-agentverktyg. I det här läget används serverlös allmän beräkning (Serverlös Spark Connect) för fjärrkörning av funktioner, och Lakeguard ser till att agentens process förblir säker och fri från riskerna med att köra godtycklig kod lokalt.

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

När din agent begär en verktygskörning i serverlöst läge händer följande:

1. DatabricksFunctionClient Skickar en begäran till Unity Catalog för att hämta funktionsdefinitionen om definitionen inte har cachelagrats lokalt.
2. Extraherar DatabricksFunctionClient funktionsdefinitionen och validerar parameternamnen och typerna.
3. DatabricksFunctionClient skickar körningen som en UDF till serverlös allmän beräkningskapacitet.

Lokalt läge för utveckling

Lokalt läge kör Python funktioner i en lokal underprocess i stället för att göra begäranden till serverlös allmän beräkning. På så sätt kan du felsöka verktygsanrop mer effektivt genom att tillhandahålla lokala stackspårningar. Den är utformad för att utveckla och felsöka Python Unity Catalog-funktioner.

När din agent begär att ett verktyg ska köras i lokalt läge DatabricksFunctionClient gör du följande:

1. Skickar en begäran till Unity Catalog för att hämta funktionsdefinitionen om definitionen inte har cachelagrats lokalt.
2. Extraherar den Python-anropsbara definitionen, cachelagrar den anropsbara lokalt och validerar parameternamnen och -typerna.
3. Anropar anropsbar med de angivna parametrarna i en begränsad underprocess med timeout-skydd.

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

När du kör i "local" läget finns följande funktioner:

• Cpu-tidsgräns: Begränsar den totala CPU-körningen för anropsbar körning för att förhindra överdriven beräkningsbelastning.

  Cpu-tidsgränsen baseras på den faktiska CPU-användningen, inte tid på väggklockan. På grund av systemplanering och samtidiga processer kan CPU-tiden överskrida kalendertiden i verkliga scenarier.

• Minnesgräns: Begränsar det virtuella minne som allokeras till processen.

• Timeout-skydd: Tvingar fram en total väggklockstidsgräns för att köra funktioner.

Anpassa dessa gränser med hjälp av miljövariabler (läs vidare).

Begränsningar i lokalt läge

• Python endast funktioner: SQL-baserade funktioner stöds inte i lokalt läge.
• Säkerhetsöverväganden för ej betrodd kod: Även om lokalt läge kör funktioner i en underprocess för processisolering finns det en potentiell säkerhetsrisk när godtycklig kod som genereras av AI-system körs. Detta är främst ett problem när funktioner körs med dynamiskt genererad Python-kod som inte har granskats.
• Skillnader i biblioteksversioner: Biblioteksversioner kan skilja sig mellan serverlösa och lokala körningsmiljöer, vilket kan leda till olika funktionsbeteenden.

Miljövariabler

Konfigurera hur funktioner körs i DatabricksFunctionClient med hjälp av följande miljövariabler:

Exempelanteckningsböcker

Följande notebook-filer visar hur du skapar AI-agentverktyg som ansluter till externa tjänster med hjälp av Unity Catalog-funktioner.

Verktyg för Slack-meddelandeagent

Hämta anteckningsbok

Microsoft Graph API agentverktyg

Hämta anteckningsbok

Azure AI Search agentverktyg

Hämta anteckningsbok

Nästa steg

• Lägg till Unity Catalog-verktyg till agenter programmatiskt. Se Skapa en AI-agent och distribuera den i Databricks-appar.

• Lägg till Unity Catalog-verktyg till agenter med hjälp av AI Playground-användargränssnittet. Se Kom igång: Förfråga LLM-modeller och AI-prototypagenter utan kod.

• Hantera Unity Catalog-funktioner med hjälp av funktionsklienten. Se Dokumentation om Unity Catalog – funktionsklient

• Anslut agenter till externa tjänster för en översikt över alla metoder för att ansluta agenter till externa tjänster.