Vytvoření nástrojů agenta AI pomocí funkcí katalogu Unity

Pomocí funkcí katalogu Unity můžete vytvářet nástroje agenta AI, které provádějí vlastní logiku a provádějí konkrétní úlohy, které rozšiřují možnosti LLM nad rámec generování jazyka.

Kdy používat funkce katalogu Unity vs. servery MCP

Databricks doporučuje používat funkce katalogu Unity jako nástroje agenta speciálně pro nástroje pro načítání strukturovaných dat, pokud je dotaz známý předem a agent poskytuje parametry. Viz Připojení agentů ke strukturovaným datům.

Ve většině ostatních případů použití databricks doporučuje servery MCP nebo definování logiky přímo v kódu agenta pro rychlejší spouštění, podporu ověřování pro jednotlivé uživatele a další flexibilitu.

Požadavky

Pokud chcete vytvářet a používat funkce katalogu Unity jako nástroje agenta AI, potřebujete následující:

  • Databricks Runtime: Použijte Databricks Runtime 15.0 a vyšší
  • Python verze: Instalace Python 3.10 nebo novější

Spuštění funkcí katalogu Unity:

  • Aby bylo možné spouštět funkce Katalogu Unity jako nástroje agenta AI v produkčním prostředí, musí být ve vašem pracovním prostoru povolené bezserverové výpočetní prostředí. Viz požadavky na výpočetní prostředky bez serveru.
    • Provádění místního režimu pro funkce Python nevyžaduje spuštění bezserverového obecného výpočetního prostředí, ale místní režim je určený pouze pro účely vývoje a testování.

Vytvoření funkcí katalogu Unity:

  • Aby bylo možné vytvářet funkce pomocí klienta pracovního prostoru Databricks nebo příkazů textu SQL, musí být ve vašem pracovním prostoru povolené bezserverové obecné výpočetní prostředky.
    • Python funkce lze vytvářet bez použití bezserverové výpočetní techniky.

Vytvořte nástroj pro funkci katalogu Unity

Následující kroky ukazují, jak vytvořit a otestovat funkci Katalogu Unity. V poznámkovém bloku Databricks spusťte následující kód.

Nainstalujte závislosti

Nainstalujte balíčky AI katalogu Unity s doplňkem [databricks].

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

dbutils.library.restartPython()

Inicializace klienta funkce Databricks

Inicializace klienta funkce Databricks, což je specializované rozhraní pro vytváření, správu a spouštění funkcí katalogu Unity v Databricks.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Definování logiky nástroje

Nástroje katalogu Unity jsou ve skutečnosti jen uživatelem definované funkce (UDF) v Unity Catalog. Při definování nástroje Unity Catalog zaregistrujete funkci v Katalogu Unity. Další informace o uživatelem definovaných funkcích katalogu Unity najdete v tématu Uživatelem definované funkce (UDF) v katalogu Unity.

Výstraha

Spuštění libovolného kódu v nástroji agenta může vystavit citlivé nebo soukromé informace, ke kterým má agent přístup. Zákazníci zodpovídají za spouštění jenom důvěryhodného kódu a konfiguraci mantinely a odpovídajících oprávnění, aby zabránili neúmyslnému přístupu k datům.

Funkce katalogu Unity můžete vytvořit pomocí jednoho ze dvou rozhraní API:

  • create_python_function přijímá volatelnou Python funkci.
  • create_function přijímá SQL příkaz pro vytvoření funkce. Viz Vytvoření funkcí Python.

create_python_function K vytvoření funkce použijte rozhraní API.

Aby bylo možné, aby funkce v Pythonu byly rozpoznatelné datovým modelem funkcí v Katalogu Unity, musí vaše funkce splňovat následující požadavky:

  • Typové anotace: Podpis funkce musí definovat platné Python typové anotace. Pojmenované argumenty i návratová hodnota musí mít definované typy.
  • Nepoužívejte argumenty proměnných: Argumenty proměnných, jako jsou *args a **kwargs, nejsou podporovány. Všechny argumenty musí být explicitně definovány.
  • Kompatibilita typů: Sql nepodporuje všechny typy Python. Viz podporované datové typy Sparku.
  • Popisné dokumenty: Sada nástrojů funkcí katalogu Unity čte, analyzuje a extrahuje důležité informace z docstringu.
    • Řetězce docstring musí být formátované podle syntaxe docstringu Google.
    • Napište jasné popisy vaší funkce a jejích argumentů, které pomohou LLM pochopit, jak a kdy tuto funkci používat.
  • Importy závislostí: Knihovny musí být importovány uvnitř těla funkce. Importy mimo funkci nebudou při spuštění nástroje vyřešeny.

Následující úryvky kódu používají create_python_function k registraci volatelné funkce 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
)

Testování funkce

Otestujte funkci a zkontrolujte, jestli funguje podle očekávání. Zadejte plně kvalifikovaný název funkce v execute_function rozhraní API pro spuštění funkce:

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'

Přidání funkcí katalogu Unity do agenta

Jakmile vytvoříte a otestujete funkci Katalogu Unity, zvolte jeden z následujících přístupů a přidejte ji do svého agenta.

Ikona Mcp. Použití MCP (doporučeno)

Databricks doporučuje používat servery MCP k přidání funkcí katalogu Unity do vašeho agenta. Přístup MCP poskytuje jednodušší integraci s automatickým zjišťováním nástrojů a integrovanou podporou ověřování.

Spravovaná adresa URL MCP pro funkce katalogu Unity je: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}. Volitelně můžete zadat konkrétní funkci dodáním /{function_name}.

Následující příklady ukazují, jak připojit agenta k funkcím katalogu Unity prostřednictvím MCP. Nahraďte <catalog> a <schema> umístěním vašich funkcí.

OpenAI Agents SDK (Aplikace)

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)

Udělte aplikaci přístup k funkci Unity Catalog v 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 (Aplikace)

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)

Udělte aplikaci přístup k funkci Unity Catalog v 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'

Poskytnutí Modelu

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

Pokud chcete nasadit agenta, přečtěte si téma Nasazení agenta pro generování aplikací umělé inteligence (obsluha modelů). Podrobnosti o agentech protokolování s prostředky MCP najdete v tématu Použití serverů MCP spravovaných službou Databricks.

Ikona funkce Použití UCFunctionToolkitu

Použití UCFunctionToolkitu

Tento příklad používá LangChain, ale podobný přístup lze použít i na jiné knihovny. Viz Integrace nástrojů katalogu Unity s rozhraními generování AI třetích stran.

Nainstalovat další závislosti

Nainstalujte integrační balíčky LangChain pro UCFunctionToolkit.

%pip install unitycatalog-langchain[databricks]

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

dbutils.library.restartPython()

Zabalte funkci pomocí UCFunctionToolKit

Zabalte funkci pomocí UCFunctionToolkit, aby byla přístupná knihovnám pro vytváření agentů. Sada nástrojů zajišťuje konzistenci napříč různými knihovnami generativní umělé inteligence a přidává užitečné funkce, jako je automatické trasování pro vyhledávače.

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

Použití nástroje v agentu

Přidejte pomocí vlastnosti tools nástroj do agenta LangChain z UCFunctionToolkit.

Poznámka:

V tomto příkladu se používá LangChain. Nástroje Katalogu Unity ale můžete integrovat s jinými architekturami, jako jsou LlamaIndex, OpenAI, Anthropic a další. Viz Integrace nástrojů katalogu Unity s rozhraními generování AI třetích stran.

V tomto příkladu autoři pro zjednodušení používají jednoduchého agenta využívajícího rozhraní LangChain AgentExecutor API. V případě produkčních úloh použijte pracovní postup vytváření agentů, který je vidět v tématu Vytvoření agenta AI, a nasaďte ho v 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?"})

Vylepšení volání nástrojů pomocí jasné dokumentace

Dobrá dokumentace pomáhá vašim agentům zjistit, kdy a jak jednotlivé nástroje používat. Při dokumentování nástrojů postupujte podle těchto osvědčených postupů:

  • Pro funkce katalogu Unity použijte COMMENT klauzuli k popisu funkčnosti a parametrů nástrojů.
  • Jasně definovat očekávané vstupy a výstupy.
  • Napište smysluplné popisy, které usnadňují používání nástrojů pro agenty a lidi.

Příklad: Efektivní dokumentace k nástrojům

Následující příklad ukazuje jasné COMMENT řetězce pro nástroj, který dotazuje strukturovanou tabulku.

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;

Příklad: Neefektivní dokumentace k nástrojům

V následujícím příkladu chybí důležité podrobnosti, což ztěžuje efektivní používání nástroje agenty:

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;

Spouštění funkcí pomocí bezserverového nebo místního režimu

Když služba generativní AI určí, že je potřeba použít nástroj, integrační balíčky (UCFunctionToolkit instance) spustí DatabricksFunctionClient.execute_function rozhraní API.

Volání execute_function může spouštět funkce ve dvou režimech spuštění: bezserverové nebo místní. Tento režim určuje, který prostředek funkci spouští.

Bezserverový režim pro produkční prostředí

Bezserverový režim je výchozí a doporučená možnost pro případy použití v produkčním prostředí při spouštění funkcí katalogu Unity jako nástroje agenta AI. Tento režim používá bezserverové obecné výpočetní prostředky (Bezserverové připojení Spark Connect) ke vzdálenému spouštění funkcí a Lakeguard zajišťuje, aby proces vašeho agenta zůstal zabezpečený a bez rizik spuštění libovolného kódu místně.

Poznámka:

Funkce katalogu Unity spuštěné jako nástroje agenta AI vyžadují bezserverové obecné výpočetní prostředky (Spark Connect serverless), nikoli bezserverové SQL sklady. Pokusy o spuštění nástrojů bez bezserverového obecného výpočetního prostředí způsobí chyby jako PERMISSION_DENIED: Cannot access Spark Connect.

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

Když váš agent požádá o spuštění nástroje v bezserverovém režimu, stane se toto:

  1. Pokud definice není místně uložena do mezipaměti, odešle DatabricksFunctionClient požadavek do katalogu Unity Catalog, aby načetl definici funkce.
  2. DatabricksFunctionClient extrahuje definici funkce a ověří názvy a typy parametrů.
  3. Odešle DatabricksFunctionClient spuštění jako UDF do bezserverového obecného výpočetního prostředí.

Místní režim vývoje

Místní režim spouští Python funkce v místním podprocesu místo provádění požadavků na bezserverové obecné výpočetní prostředky. Díky tomu můžete efektivněji řešit problémy s voláními nástrojů tím, že poskytnete trasování místního zásobníku. Je určen pro vývoj a ladění Python funkce katalogu Unity.

Když agent požádá o spuštění nástroje v místním režimu, DatabricksFunctionClient provede následující kroky:

  1. Odešle požadavek do katalogu Unity, aby načetl definici funkce, pokud nebyla definice místně uložena do mezipaměti.
  2. Extrahuje definici volatelnou v Pythonu, uloží volatelnou funkci do místní mezipaměti a ověřuje názvy a typy parametrů.
  3. Vyvolá funkci se zadanými parametry v omezeném podprocesu s ochranou proti překročení časového limitu.
# Defaults to serverless if `execution_mode` is not specified
client = DatabricksFunctionClient(execution_mode="local")

Běh v "local" režimu poskytuje následující výhody:

  • Časový limit procesoru: Omezuje celkový modul runtime procesoru pro volatelné spouštění, aby se zabránilo nadměrnému výpočetnímu zatížení.

    Časový limit procesoru je založený na skutečném využití procesoru, nikoli na hodinovém čase. Vzhledem k plánování systému a souběžným procesům může čas procesoru v reálných scénářích překročit hodinový čas.

  • Limit paměti: Omezí virtuální paměť přidělenou procesu.

  • Ochrana časového limitu: Vynucuje celkový časový limit skutečného času pro spuštěné funkce.

Přizpůsobte si tato omezení pomocí proměnných prostředí (přečtěte si další informace).

Omezení místního režimu

  • Pouze funkce Pythonu: Funkce založené na SQL nejsou v místním režimu podporovány.
  • Aspekty zabezpečení pro nedůvěryhodný kód: Zatímco místní režim spouští funkce v podprocesu pro izolaci procesů, existuje potenciální bezpečnostní riziko při provádění libovolného kódu generovaného systémy AI. To je primárně problém, když funkce spouští dynamicky generované Python kód, který nebyl zkontrolován.
  • Rozdíly ve verzi knihovny: Verze knihoven se můžou lišit mezi bezserverovými a místními spouštěcími prostředími, což může vést k odlišnému chování funkce.

Proměnné prostředí

Nakonfigurujte, jak se funkce spouštějí v DatabricksFunctionClient pomocí následujících proměnných prostředí:

Proměnná prostředí Výchozí hodnota Popis
EXECUTOR_MAX_CPU_TIME_LIMIT 10 sekundy Maximální povolená doba provádění procesoru (pouze místní režim).
EXECUTOR_MAX_MEMORY_LIMIT 100 MB Maximální povolené přidělení virtuální paměti pro proces (pouze místní režim).
EXECUTOR_TIMEOUT 20 sekundy Maximální celková doba nástěnných hodin (pouze místní režim).
UCAI_DATABRICKS_SESSION_RETRY_MAX_ATTEMPTS 5 Maximální počet pokusů o opakování aktualizace klienta relace v případě vypršení platnosti tokenu.
UCAI_DATABRICKS_SERVERLESS_EXECUTION_RESULT_ROW_LIMIT 100 Maximální počet řádků, které se mají vrátit při spouštění funkcí pomocí bezserverových výpočetních prostředků a databricks-connect.

Příklady poznámkových bloků

Následující poznámkové bloky ukazují vytváření nástrojů agenta AI, které se připojují k externím službám pomocí funkcí katalogu Unity.

Nástroj agenta zasílání zpráv Slack

Pořiďte si notebook

Nástroj agenta Microsoft Graph API

Pořiďte si notebook

nástroj agenta Azure AI Search

Pořiďte si notebook

Další kroky

  • Last updated on