Creare strumenti per agenti di intelligenza artificiale utilizzando le funzioni del catalogo Unity

Usare le funzioni di Unity Catalog per creare strumenti per agenti di intelligenza artificiale che implementano logica personalizzata e svolgono compiti specifici, estendendo le capacità dei modelli di linguaggio di grandi dimensioni oltre la generazione del linguaggio.

Avvertimento

L'esecuzione di codice arbitrario in uno strumento agente può esporre informazioni riservate o private a cui l'agente ha accesso. I clienti sono responsabili dell'esecuzione solo di codice attendibile e dell'implementazione di protezioni e autorizzazioni appropriate per impedire l'accesso imprevisto ai dati.

Requisiti

Per creare e usare funzioni del catalogo Unity come strumenti dell'agente di intelligenza artificiale, sono necessari gli elementi seguenti:

Databricks Runtime: usare Databricks Runtime 15.0 e versioni successive
Versione python: installare Python 3.10 o versione successiva

Per eseguire le funzioni del catalogo Unity:

L'ambiente di calcolo serverless deve essere abilitato nell'area di lavoro per eseguire funzioni del catalogo Unity come strumenti dell'agente di intelligenza artificiale nell'ambiente di produzione. Vedere Requisiti di calcolo serverless.
- L'esecuzione in modalità locale per le funzioni Python non richiede l'esecuzione di calcolo generico serverless, ma la modalità locale è destinata solo a scopi di sviluppo e test.

Per creare funzioni del catalogo Unity:

L'ambiente di calcolo generico serverless deve essere abilitato nell'area di lavoro per creare funzioni usando le istruzioni del corpo sql o del client dell'area di lavoro di Databricks.
- Le funzioni Python possono essere create senza elaborazione senza server.

Creare uno strumento agente

In questo esempio si crea uno strumento Catalogo Unity, ne si testa la funzionalità e lo si aggiunge a un agente. Eseguire il codice seguente in un notebook di Databricks.

Installa le dipendenze

Installare i pacchetti di intelligenza artificiale di Unity Catalog con l'extra [databricks] e installare il pacchetto di integrazione Databricks-LangChain.

Questo esempio usa LangChain, ma un approccio simile può essere applicato ad altre librerie. Vedere Integrare gli strumenti del catalogo Unity con framework di intelligenza artificiale generati da terze parti.

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

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

dbutils.library.restartPython()

Inizializzare il Databricks Function Client

Inizializzare il client di funzioni di Databricks, che è un'interfaccia specializzata per la creazione, la gestione e l'esecuzione di funzioni del catalogo Unity in Databricks.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Definire la logica dello strumento

Gli strumenti del catalogo unity sono in realtà solo funzioni definite dall'utente (UDF) di Unity Catalog. Quando si definisce uno strumento nel Catalogo Unity, si sta registrando una funzione nel Catalogo Unity. Per altre informazioni sulle funzioni definite dall'utente del catalogo Unity, vedere Funzioni definite dall'utente (UDF) nel catalogo unity.

È possibile creare funzioni del catalogo Unity usando una delle due API seguenti:

create_python_function accetta un oggetto Python callable.
create_function accetta un'istruzione SQL di creazione funzione body. Vedere Creare funzioni Python.

Usare l'API create_python_function per creare la funzione.

Per rendere richiamabile una funzione Python riconoscibile per il modello di dati delle funzioni di Unity Catalog, la tua funzione deve soddisfare i requisiti seguenti:

Hint di tipo: la firma della funzione deve definire hint di tipo Python validi. Sia gli argomenti denominati che il valore restituito devono avere i relativi tipi definiti.
Non usare argomenti di variabile: gli argomenti variabili, ad esempio *args e **kwargs, non sono supportati. Tutti gli argomenti devono essere definiti in modo esplicito.
Compatibilità dei tipi: non tutti i tipi Python sono supportati in SQL. Vedere Tipi di dati supportati da Spark.
Documentazione descrittiva: il toolkit delle funzioni del catalogo Unity legge, analizza ed estrae informazioni importanti dalla docstring.
- Le docstrings devono essere formattate in base alla sintassi della docstring di Google.
- Scrivere descrizioni chiare per la funzione e i relativi argomenti per comprendere come e quando usare la funzione.
Importazioni di dipendenze: le librerie devono essere importate all'interno del corpo della funzione. Le importazioni esterne alla funzione non verranno risolte durante l'esecuzione dello strumento.

I seguenti frammenti di codice usano create_python_function per registrare il chiamabile 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
)

Testare la funzione

Testare la funzione per verificarne il funzionamento come previsto. Specificare un nome di funzione completo nell'API execute_function per eseguire la funzione:

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'

Eseguire il wrapping della funzione usando UCFunctionToolKit

Avvolgi la funzione usando UCFunctionToolkit per renderla accessibile alle librerie di sviluppo dell'agente. Il toolkit garantisce la coerenza tra diverse librerie di intelligenza artificiale di generazione e aggiunge funzionalità utili come la traccia automatica per i retriever.

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

Utilizzare lo strumento in un agente

Aggiungere lo strumento a un agente LangChain utilizzando la proprietà tools da UCFunctionToolkit.

Annotazioni

Questo esempio usa LangChain. È tuttavia possibile integrare gli strumenti di Catalogo Unity con altri framework, ad esempio LlamaIndex, OpenAI, Anthropic e altro ancora. Vedere Integrare gli strumenti del catalogo Unity con framework di intelligenza artificiale generati da terze parti.

Questo esempio crea un agente semplice usando l'API LangChain AgentExecutor per semplicità. Per i carichi di lavoro di produzione, usare il flusso di lavoro di scrittura dell'agente visualizzato negli ResponsesAgent esempi.

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

Migliorare il processo di chiamata degli strumenti con una documentazione più chiara

Una buona documentazione aiuta gli agenti a sapere quando e come usare ogni strumento. Seguire queste procedure consigliate per documentare gli strumenti:

Per le funzioni del catalogo unity, usare la COMMENT clausola per descrivere le funzionalità e i parametri degli strumenti.
Definire chiaramente gli input e gli output previsti.
Scrivere descrizioni significative per semplificare l'uso degli strumenti da parte degli agenti e degli esseri umani.

Esempio: Documentazione efficace degli strumenti

Nell'esempio seguente vengono illustrate stringhe chiare COMMENT per uno strumento che esegue una query su una tabella strutturata.

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;

Esempio: Documentazione dello strumento inefficace

L'esempio seguente non contiene dettagli importanti, rendendo più difficile per gli agenti usare lo strumento in modo efficace:

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;

Esecuzione di funzioni tramite modalità serverless o locale

Quando un servizio di intelligenza artificiale generativa determina che è necessaria una chiamata a uno strumento, i pacchetti di integrazione (UCFunctionToolkit istanze) eseguono l'API DatabricksFunctionClient.execute_function.

La execute_function chiamata può eseguire funzioni in due modalità di esecuzione: serverless o locale. Questa modalità determina la risorsa che esegue la funzione.

Modalità serverless per l'ambiente di produzione

La modalità serverless è l'opzione predefinita e consigliata per i casi d'uso di produzione quando si eseguono funzioni del catalogo Unity come strumenti dell'agente di intelligenza artificiale. Questa modalità usa il calcolo generico serverless (Spark Connect serverless) per eseguire funzioni in remoto, assicurandosi che il processo dell'agente rimanga sicuro e privo di rischi di esecuzione di codice arbitrario in locale.

Annotazioni

Le funzioni del catalogo Unity eseguite come strumenti dell'agente di intelligenza artificiale richiedono risorse di calcolo generiche serverless (Spark Connect serverless), non Serverless SQL Warehouses. I tentativi di eseguire strumenti senza un'elaborazione generica in modalità serverless genereranno errori come PERMISSION_DENIED: Cannot access Spark Connect.

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

Quando l'agente richiede l'esecuzione di uno strumento in modalità serverless , si verifica quanto segue:

Invia DatabricksFunctionClient una richiesta al catalogo unity per recuperare la definizione della funzione se la definizione non è stata memorizzata nella cache locale.
DatabricksFunctionClient Estrae la definizione della funzione e convalida i nomi e i tipi dei parametri.
DatabricksFunctionClient invia l'esecuzione come UDF al calcolo generico serverless.

Modalità locale per lo sviluppo

La modalità locale esegue le funzioni Python in un subprocesso locale invece di effettuare richieste a un calcolo generico serverless. In questo modo è possibile risolvere i problemi relativi alle chiamate degli strumenti in modo più efficace fornendo analisi dello stack locale. È progettato per lo sviluppo e il debug di funzioni del catalogo Unity di Python.

Quando l'agente richiede l'esecuzione di uno strumento in modalità locale , DatabricksFunctionClient esegue le operazioni seguenti:

Invia una richiesta al catalogo Unity per recuperare la definizione della funzione se la definizione non è stata memorizzata nella cache locale.
Estrae la definizione chiamabile di Python, memorizza nella cache il chiamabile in locale e convalida i nomi e i tipi di parametro.
Richiama l'oggetto chiamabile con i parametri specificati in un sottoprocesso limitato, con protezione contro il timeout.

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

L'esecuzione in "local" modalità offre le funzionalità seguenti:

Limite di tempo CPU: Limita il runtime totale della CPU per l'esecuzione chiamabile per evitare carichi di calcolo eccessivi.

Il limite di tempo della CPU si basa sull'utilizzo effettivo della CPU, non sull'ora di clock reale. A causa della pianificazione del sistema e dei processi simultanei, il tempo della CPU può superare il tempo reale in scenari del mondo reale.
Limite di memoria: Limita la memoria virtuale allocata al processo.
Protezione del timeout: Applica un timeout totale del tempo per le funzioni che vengono eseguite.

Personalizzare questi limiti usando le variabili di ambiente (altre informazioni).

Limitazioni della modalità locale

Solo funzioni Python: le funzioni basate su SQL non sono supportate in modalità locale.
Considerazioni sulla sicurezza per il codice non attendibile: mentre la modalità locale esegue funzioni in un subprocesso per l'isolamento dei processi, esiste un potenziale rischio per la sicurezza quando si esegue codice arbitrario generato dai sistemi di intelligenza artificiale. Questo è principalmente un problema quando le funzioni eseguono codice Python generato dinamicamente che non è stato esaminato.
Differenze di versione della libreria: le versioni della libreria possono variare tra gli ambienti di esecuzione serverless e locali, il che potrebbe causare un comportamento di funzione diverso.

Variabili di ambiente

Configurare come le funzioni vengono eseguite nel DatabricksFunctionClient usando le seguenti variabili di ambiente:

Variabile di ambiente	Valore predefinito	Descrizione
`EXECUTOR_MAX_CPU_TIME_LIMIT`	`10` Secondi	Tempo massimo consentito per l'esecuzione della CPU (solo modalità locale).
`EXECUTOR_MAX_MEMORY_LIMIT`	`100` MB	Allocazione massima di memoria virtuale consentita per il processo (solo modalità locale).
`EXECUTOR_TIMEOUT`	`20` Secondi	Tempo massimo reale (solo modalità locale).
`UCAI_DATABRICKS_SESSION_RETRY_MAX_ATTEMPTS`	`5`	Numero massimo di tentativi di aggiornamento del client di sessione in caso di scadenza del token.
`UCAI_DATABRICKS_SERVERLESS_EXECUTION_RESULT_ROW_LIMIT`	`100`	Numero massimo di righe da restituire durante l'esecuzione di funzioni con il calcolo serverless e `databricks-connect`.

Passaggi successivi

Aggiungere gli strumenti del catalogo Unity agli agenti programmaticamente. Vedi ResponsesAgent esempi.
Aggiungere gli strumenti del catalogo Unity agli agenti usando l'interfaccia utente di AI Playground. Vedi gli agenti prototipo che chiamano strumenti nel Parco giochi dell'IA.
Gestire le funzioni del catalogo Unity usando il client di funzioni. Vedere la documentazione di Unity Catalog - Client per le funzioni

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-15