Creación de herramientas de agente de IA mediante funciones de catálogo de Unity

Utiliza las funciones del catálogo de Unity para crear herramientas de agente de IA que ejecuten lógica personalizada y realicen tareas específicas que amplíen las capacidades de los LLM más allá de la generación de lenguaje.

Cuándo usar funciones del catálogo de Unity frente a servidores MCP

Databricks recomienda usar funciones de Catálogo de Unity como herramientas de agente específicamente para herramientas de recuperación de datos estructurados cuando la consulta se conoce con antelación y el agente proporciona los parámetros. Consulte Conexión de agentes a datos estructurados.

En la mayoría de los otros casos de uso, Databricks recomienda servidores MCP o definir la lógica directamente en el código del agente para una ejecución más rápida, compatibilidad con la autenticación por usuario y flexibilidad adicional.

Requisitos

Para crear y usar funciones del catálogo de Unity como herramientas del agente de IA, necesita lo siguiente:

• Databricks Runtime: uso de Databricks Runtime 15.0 y versiones posteriores
• Python versión: instalar Python 3.10 o superior

Para ejecutar funciones de Catálogo de Unity:

• El cómputo sin servidor debe estar habilitado en el área de trabajo para ejecutar funciones de Unity Catalog como herramientas de agente de IA en producción. Consulte Requisitos de proceso sin servidor.
  • Ejecución del modo local para las funciones de Python no requiere que se ejecute el proceso genérico sin servidor, pero el modo local solo está pensado para fines de desarrollo y pruebas.

Para crear funciones de catálogo de Unity:

• El proceso genérico sin servidor debe estar habilitado en el área de trabajo para crear funciones mediante las instrucciones Databricks Workspace Client o SQL Body.
  • Funciones de Python se pueden crear sin computación sin servidor.

Creación de una herramienta de función de catálogo de Unity

En los pasos siguientes se muestra cómo crear y probar una función de catálogo de Unity. Ejecute el código siguiente en un cuaderno de Databricks.

Instalación de dependencias

Instale los paquetes AI de Unity Catalog con el [databricks] como complemento.

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

dbutils.library.restartPython()

Inicializa el cliente de funciones de Databricks

Inicialice el cliente de funciones de Databricks, que es una interfaz especializada para crear, administrar y ejecutar funciones de Catálogo de Unity en Databricks.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Definición de la lógica de la herramienta

Las herramientas de catálogo de Unity en realidad simplemente son funciones definidas por el usuario (UDF) del catálogo de Unity. Al definir una herramienta de catálogo de Unity, va a registrar una función en el catálogo de Unity. Para obtener más información sobre las UDF del catálogo de Unity, consulte Funciones definidas por el usuario (UDF) en el catálogo de Unity.

Puede crear funciones de Catálogo de Unity con una de las dos API:

• create_python_function acepta un objeto o función llamable en Python.
• create_function acepta una instrucción de creación de función SQL. Consulte Crear funciones de Python.

Use la create_python_function API para crear la función .

Para que una función callable de Python sea reconocible por el modelo de datos de funciones del Catálogo de Unity, su función debe cumplir los siguientes requisitos:

• Type hints: la firma de función debe definir sugerencias de tipo Python válidas. Tanto los argumentos con nombre como el valor devuelto deben tener sus tipos definidos.
• No use argumentos variables: no se admiten argumentos variables como *args y **kwargs. Todos los argumentos deben definirse explícitamente.
• Type compatibility: No todos los tipos de Python se admiten en SQL. Consulte Tipos de datos admitidos por Spark.
• Docstrings descriptivos: El conjunto de funcionalidades del Unity Catalog lee, analiza y extrae información importante de la cadena de documentación.
  • Los docstrings deben tener el formato según la sintaxis docstring de Google.
  • Escriba descripciones claras para la función y sus argumentos para ayudar al LLM a comprender cómo y cuándo usar la función.
• Importaciones de dependencias: las bibliotecas deben importarse dentro del cuerpo de la función. Las importaciones fuera de la función no se resolverán al ejecutar la herramienta.

En los siguientes fragmentos de código se utiliza create_python_function para registrar el callable de 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
)

Prueba de la función

Pruebe la función para comprobar que funciona según lo previsto. Especifique un nombre de función completo en la execute_function API para ejecutar la función:

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'

Añade funciones del Unity Catalog a tu agente

Una vez que haya creado y probado la función catálogo de Unity, elija uno de los métodos siguientes para agregarlo al agente.

Uso de MCP (recomendado)

Uso de MCP (recomendado)

Databricks recomienda usar servidores MCP para agregar funciones de catálogo de Unity al agente. El enfoque MCP proporciona una integración más sencilla con la detección automática de herramientas y la compatibilidad con la autenticación integrada.

La dirección URL de MCP administrada para las funciones de catálogo de Unity es: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}. Opcionalmente, puede especificar una función específica anexando /{function_name}.

En los ejemplos siguientes se muestra cómo conectar el agente a las funciones del catálogo de Unity a través de MCP. Reemplace <catalog> y <schema> por la ubicación de las funciones.

SDK de agentes de OpenAI (aplicaciones)

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)

Conceda a la aplicación acceso a la función Catálogo de Unity en 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 (Aplicaciones)

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)

Conceda a la aplicación acceso a la función Catálogo de Unity en 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'

Servicio de modelos

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

Para implementar el agente, consulte Deploy an agent for generative AI applications (Model Serving). Para más información sobre el registro de agentes con recursos de MCP, consulte Uso de servidores MCP administrados de Databricks.

Uso de UCFunctionToolkit

Uso de UCFunctionToolkit

En este ejemplo se usa LangChain, pero se puede aplicar un enfoque similar a otras bibliotecas. Consulte Integración de herramientas de Catálogo de Unity con marcos de IA generativos de terceros.

Instalación de dependencias adicionales

Instale los paquetes de integración de LangChain para UCFunctionToolkit.

%pip install unitycatalog-langchain[databricks]

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

dbutils.library.restartPython()

Envuelva la función usando el UCFunctionToolKit

Ajuste la función mediante UCFunctionToolkit para que sea accesible para las bibliotecas de creación de agentes. El conjunto de herramientas garantiza la coherencia en diferentes bibliotecas de inteligencia artificial generativa y agrega funciones útiles, como el rastreo automático para los módulos de recuperación.

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

Uso de la herramienta en un agente

Agregue la herramienta a un agente de LangChain utilizando la propiedad tools de UCFunctionToolkit.

Nota:

En este ejemplo se usa LangChain. Sin embargo, puede integrar herramientas de Catálogo de Unity con otros marcos como LlamaIndex, OpenAI, Anthropic, etc. Consulte Integración de herramientas de Catálogo de Unity con marcos de IA generativos de terceros.

En este ejemplo se crea un agente sencillo mediante LangChain AgentExecutor API para simplificar. En el caso de las cargas de trabajo de producción, use el flujo de trabajo de creación de agentes que se ve en Creación de un agente de IA e impleméntelo en Aplicaciones de Databricks.

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

Mejora de las llamadas a herramientas con documentación clara

Una buena documentación ayuda a los agentes a saber cuándo y cómo usar cada herramienta. Siga estos procedimientos recomendados para documentar las herramientas:

• En el caso de las funciones de Catálogo de Unity, use la COMMENT cláusula para describir la funcionalidad y los parámetros de la herramienta.
• Defina claramente las entradas y salidas esperadas.
• Escriba descripciones significativas para que las herramientas sean más fáciles de usar para los agentes y los seres humanos.

Ejemplo: Documentación eficaz de la herramienta

En el ejemplo siguiente se muestran cadenas claras COMMENT para una herramienta que consulta una tabla estructurada.

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;

Ejemplo: Documentación de herramientas ineficaces

En el ejemplo siguiente faltan detalles importantes, lo que dificulta que los agentes usen la herramienta de forma eficaz:

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;

Ejecución de funciones mediante el modo local o sin servidor

Cuando un servicio de inteligencia artificial genera determina que se necesita realizar una llamada a herramienta, los paquetes de integración (UCFunctionToolkit instancias) ejecutan la API de DatabricksFunctionClient.execute_function.

La execute_function llamada puede ejecutar funciones en dos modos de ejecución: sin servidor o local. Este modo determina qué recurso ejecuta la función.

Modo sin servidor para producción

El modo sin servidor es la opción predeterminada y recomendada para casos de uso de producción al ejecutar funciones de Catálogo de Unity como herramientas del agente de IA. Este modo usa el proceso genérico sin servidor (Spark Connect sin servidor) para ejecutar funciones de forma remota y Lakeguard garantiza que el proceso del agente permanezca seguro y libre de los riesgos de ejecutar código arbitrario localmente.

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

Cuando el agente solicita una ejecución de herramientas en modo sin servidor , ocurre lo siguiente:

1. DatabricksFunctionClient Envía una solicitud al catálogo de Unity para recuperar la definición de función si la definición no se ha almacenado localmente en caché.
2. DatabricksFunctionClient extrae la definición de la función y valida los nombres y tipos de parámetros.
3. DatabricksFunctionClient envía la ejecución como una UDF a una computación genérica sin servidor.

Modo local para el desarrollo

El modo local ejecuta funciones de Python en un subproceso local en lugar de realizar solicitudes al procesamiento genérico sin servidor. Esto le permite solucionar problemas de llamadas a la herramienta de forma más eficaz proporcionando los rastros de pila locales. Está diseñado para desarrollar y depurar funciones de Unity Catalog en Python.

Cuando el agente solicita ejecutar una herramienta en modo local , DatabricksFunctionClient hace lo siguiente:

1. Envía una solicitud al catálogo de Unity para recuperar la definición de función si la definición no se ha almacenado localmente en caché.
2. Extrae la definición invocable en Python, almacena el invocable en caché localmente y valida los nombres y tipos de parámetros.
3. Invoca el invocable con los parámetros especificados en un subproceso restringido con protección de tiempo de espera.

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

La ejecución en "local" modo proporciona las siguientes características:

• Límite de tiempo de CPU: Restringe el tiempo de ejecución total de CPU para la ejecución invocable para evitar cargas computacionales excesivas.

  El límite de tiempo de CPU se basa en el uso real de la CPU, no en tiempo de reloj. Debido a la programación del sistema y a los procesos simultáneos, el tiempo de CPU puede superar el tiempo de reloj en situaciones del mundo real.

• Límite de memoria: Restringe la memoria virtual asignada al proceso.

• Protección de tiempo de espera: Impone un tiempo de espera total en tiempo real para las funciones en ejecución.

Personalice estos límites mediante variables de entorno (lea más adelante).

Limitaciones del modo local

• Solo funciones de Python: las funciones basadas en SQL no se admiten en modo local.
• Consideraciones de seguridad para código que no es de confianza: mientras que el modo local ejecuta funciones en un subproceso para el aislamiento de procesos, existe un riesgo de seguridad potencial al ejecutar código arbitrario generado por sistemas de inteligencia artificial. Esto es principalmente un problema cuando las funciones ejecutan dinámicamente código Python generado que no se ha revisado.
• Diferencias de versiones de biblioteca: las versiones de biblioteca pueden diferir entre los entornos de ejecución local y sin servidor, lo que podría provocar un comportamiento de función diferente.

Variables de entorno

Configure cómo se ejecutan las funciones en DatabricksFunctionClient mediante las siguientes variables de entorno:

Cuadernos de ejemplo

En los cuadernos siguientes se muestra cómo crear herramientas de agente de IA que se conectan a servicios externos mediante funciones de Catálogo de Unity.

Herramienta de agente de mensajería de Slack

Obtener el cuaderno

Herramienta de agente de Microsoft Graph API

Obtener el cuaderno

herramienta del agente de búsqueda de Azure AI

Obtener el cuaderno

Pasos siguientes

• Agregue herramientas de catálogo de Unity a los agentes mediante programación. Consulte Creación de un agente de IA e implementación en Aplicaciones de Databricks.

• Agregue herramientas de catálogo de Unity a los agentes mediante la interfaz de usuario de AI Playground. Consulte Empiece por: Consultar modelos de lenguaje y crear prototipos de agentes de IA sin necesidad de programación.

• Administrar funciones del catálogo de Unity mediante el cliente de funciones. Consulte la documentación del catálogo de Unity: Cliente de funciones

• Conecte agentes a servicios externos para obtener información general sobre todos los enfoques para conectar agentes a servicios externos.