Criar ferramentas de agente de IA usando funções do Catálogo do Unity

Use as funções do Catálogo do Unity para criar ferramentas de agente de IA que executam a lógica personalizada e executam tarefas específicas que estendem os recursos de LLMs além da geração de linguagem.

Quando usar funções do Catálogo do Unity versus servidores MCP

O Databricks recomenda o uso de funções do Catálogo do Unity como ferramentas de agente especificamente para ferramentas de recuperação de dados estruturadas quando a consulta é conhecida com antecedência e o agente fornece os parâmetros. Consulte Conectar agentes aos dados estruturados.

Na maioria dos outros casos de uso, o Databricks recomenda servidores MCP ou definir a lógica diretamente no código do agente para execução mais rápida, suporte à autenticação por usuário e flexibilidade adicional.

Requisitos

Para criar e usar as funções do Catálogo do Unity como ferramentas de agente de IA, você precisará do seguinte:

• Databricks Runtime: usar o Databricks Runtime 15.0 e superior
• Python versão: instalar Python 3.10 ou superior

Para executar funções do Catálogo do Unity:

• A computação sem servidor deve ser habilitada em seu workspace para executar funções do Catálogo do Unity como ferramentas de agente de IA em produção. Consulte os requisitos de computação sem servidor.
  • A execução do modolocal para funções de Python não exige que a computação genérica sem servidor seja executada, no entanto, o modo local destina-se apenas a fins de desenvolvimento e teste.

Para criar funções do Catálogo do Unity:

• A computação genérica sem servidor deve estar habilitada no seu workspace para criar funções usando o Cliente do Workspace do Databricks ou instruções de corpo do SQL.
  • Funções Python podem ser criadas sem serverless compute.

Criar uma ferramenta de função do Catálogo do Unity

As etapas a seguir mostram como criar e testar uma função do Catálogo do Unity. Execute o código a seguir em um bloco de anotações do Databricks.

Instalar dependências

Instale os pacotes de IA do Unity Catalog com o complemento [databricks].

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

dbutils.library.restartPython()

Inicializar o Cliente de Funções do Databricks

Inicialize o Cliente de Funções do Databricks, que é uma interface especializada para criar, gerenciar e executar funções do Catálogo do Unity no Databricks.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Definir a lógica da ferramenta

As ferramentas do Catálogo do Unity são, na verdade, apenas UDFs (funções definidas pelo usuário) do Catálogo do Unity sob o capô. Ao definir uma ferramenta de Catálogo do Unity, você está registrando uma função no Catálogo do Unity. Para saber mais sobre UDFs do Catálogo do Unity, consulte UDFs (funções definidas pelo usuário) no Catálogo do Unity.

Você pode criar funções do Catálogo do Unity usando uma das duas APIs:

• create_python_function aceita uma função ou objeto chamável em Python.
• create_function aceita uma instrução de criação de função SQL com corpo. Consulte Create Python functions.

Use a create_python_function API para criar a função.

Para tornar um objeto callable Python reconhecível pelo modelo de dados de funções do Unity Catalog, sua função deve atender aos seguintes requisitos:

• Type hints: a assinatura da função deve definir dicas de tipo válidas em Python. Os argumentos nomeados e o valor retornado devem ter seus tipos definidos.
• Não use argumentos variáveis: argumentos variáveis como *args e **kwargs não têm suporte. Todos os argumentos devem ser definidos explicitamente.
• Compatibilidade de tipos: Nem todos os tipos de Python têm suporte no SQL. Consulte os tipos de dados com suporte do Spark.
• Docstrings descritivos: O toolkit de funções do Unity Catalog lê, analisa e extrai informações importantes das suas docstrings.
  • Docstrings devem ser formatados de acordo com a sintaxe docstring do Google.
  • Escreva descrições claras para sua função e seus argumentos para ajudar o LLM a entender como e quando usar a função.
• Importações de dependência: as bibliotecas devem ser importadas dentro do corpo da função. As importações fora da função não serão resolvidas ao executar a ferramenta.

Os trechos de código a seguir usam o create_python_function para registrar o objeto chamável do 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
)

Testar a função

Teste sua função para verificar se ela funciona conforme o esperado. Especifique um nome de função totalmente qualificado na execute_function API para executar a função:

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'

Adicionar funções do Catálogo do Unity ao seu agente

Depois de criar e testar sua função de Catálogo do Unity, escolha uma das abordagens a seguir para adicioná-la ao seu agente.

Usando MCP (recomendado)

Usando o MCP (recomendado)

O Databricks recomenda o uso de servidores MCP para adicionar funções do Catálogo do Unity ao seu agente. A abordagem MCP fornece uma integração mais simples com a descoberta automática de ferramentas e o suporte à autenticação interna.

A URL gerenciada do MCP para funções do Catálogo do Unity é: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}. Opcionalmente, você pode especificar uma função específica acrescentando /{function_name}.

Os exemplos a seguir mostram como conectar seu agente às funções do Catálogo do Unity por meio do MCP. Substitua <catalog> e <schema> pelo local de suas funções.

SDK de Agentes do OpenAI (Aplicativos)

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 ao aplicativo acesso à função catálogo do Unity em 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 (Aplicativos)

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 ao aplicativo acesso à função catálogo do Unity em 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'

Serviço de Modelo

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 implantar o agente, consulte Implantar um agente para aplicativos de IA generativos (Model Serving). Para obter detalhes sobre agentes de log com recursos mcp, consulte Usar servidores MCP gerenciados pelo Databricks.

Usando UCFunctionToolkit

Usando UCFunctionToolkit

Este exemplo usa LangChain, mas uma abordagem semelhante pode ser aplicada a outras bibliotecas. Veja Integrar ferramentas do Unity Catalog com estruturas de IA generativa de terceiros.

Instalar dependências adicionais

Instale os pacotes de integração do LangChain para UCFunctionToolkit.

%pip install unitycatalog-langchain[databricks]

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

dbutils.library.restartPython()

Encapsular a função usando o UCFunctionToolKit

Empacote a função usando UCFunctionToolkit para torná-la acessível às bibliotecas de criação de agentes. O kit de ferramentas garante a consistência em diferentes bibliotecas de IA generativa e adiciona recursos úteis, como o rastreamento automático para mecanismos de recuperação.

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

Usar a ferramenta em um agente

Adicione a ferramenta a um agente LangChain usando a propriedade tools de UCFunctionToolkit.

Observação

Este exemplo usa LangChain. No entanto, você pode integrar as ferramentas do Catálogo do Unity a outras estruturas, como LlamaIndex, OpenAI, Antropic e muito mais. Veja Integrar ferramentas do Unity Catalog com estruturas de IA generativa de terceiros.

Este exemplo cria um agente simples usando a API LangChain AgentExecutor para simplificar. Para cargas de trabalho de produção, use o fluxo de trabalho de criação de agente visto em Criar um agente de IA e implantá-lo nos Aplicativos do 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?"})

Aprimorar o acionamento de ferramentas com documentação clara

Uma boa documentação ajuda seus agentes a saber quando e como usar cada ferramenta. Siga estas práticas recomendadas para documentar suas ferramentas:

• Para funções do Catálogo do Unity, use a COMMENT cláusula para descrever a funcionalidade e os parâmetros da ferramenta.
• Defina claramente as entradas e saídas esperadas.
• Escreva descrições significativas para tornar as ferramentas mais fáceis de usar para agentes e humanos.

Exemplo: Documentação efetiva da ferramenta

O exemplo a seguir mostra cadeias de caracteres claras COMMENT para uma ferramenta que consulta uma tabela estruturada.

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;

Exemplo: documentação de ferramenta ineficaz

O exemplo a seguir não tem detalhes importantes, tornando mais difícil para os agentes usarem a ferramenta efetivamente:

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;

Executar funções usando o modo local ou sem servidor

Quando um serviço de IA generativa determina que uma chamada de ferramenta é necessária, os pacotes de integração (UCFunctionToolkit instâncias) executam a DatabricksFunctionClient.execute_function API.

A execute_function chamada pode executar funções em dois modos de execução: sem servidor ou local. Esse modo determina qual recurso executa a função.

Modo sem servidor para produção

O modo sem servidor é a opção padrão e recomendada para casos de uso de produção ao executar funções do Catálogo do Unity como ferramentas de agente de IA. Esse modo usa a computação genérica sem servidor (execução sem servidor via Spark Connect) para executar funções remotamente, e o Lakeguard garante que o processo do agente permaneça seguro e livre dos riscos de executar código arbitrário localmente.

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

Quando o agente solicita uma execução de ferramenta no modo sem servidor , acontece o seguinte:

1. Envia DatabricksFunctionClient uma solicitação ao Catálogo do Unity para recuperar a definição de função se a definição não tiver sido armazenada em cache localmente.
2. O DatabricksFunctionClient extrai a definição de função e valida os nomes e tipos de parâmetro.
3. O DatabricksFunctionClient envia a execução como uma UDF para computação genérica sem servidor.

Modo local para desenvolvimento

O modo local executa Python funções em um subprocesso local em vez de fazer solicitações para computação genérica sem servidor. Isso permite que você resolva problemas de chamadas de ferramenta com mais eficiência, fornecendo rastreamentos de pilha locais. Ele foi projetado para desenvolver e depurar funções do Unity Catalog do Python.

Quando o agente solicita a execução de uma ferramenta no modo local, o DatabricksFunctionClient faz o seguinte:

1. Envia uma solicitação ao Catálogo do Unity para recuperar a definição de função se a definição não tiver sido armazenada em cache localmente.
2. Extrai a definição de callable em Python, armazena o callable em cache localmente e valida os nomes e tipos de parâmetro.
3. Chama o invocável com os parâmetros especificados em um subprocesso restrito com proteção contra tempo limite.

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

A execução no "local" modo fornece os seguintes recursos:

• Limite de tempo da CPU: Restringe o runtime total da CPU para execução callable para evitar cargas computacionais excessivas.

  O limite de tempo da CPU baseia-se no uso real da CPU, não no tempo do relógio de parede. Devido ao agendamento do sistema e a processos simultâneos, o tempo de CPU pode exceder o tempo de relógio em cenários reais.

• Limite de memória: Restringe a memória virtual alocada ao processo.

• Proteção de tempo limite: Impõe um tempo limite total do relógio de parede para executar funções.

Personalize esses limites usando variáveis de ambiente (leia mais).

Limitações do modo local

• Somente funções Python: não há suporte para funções baseadas em SQL no modo local.
• Considerações de segurança para código não confiável: embora o modo local execute funções em um subprocesso para isolamento de processo, há um risco potencial de segurança ao executar código arbitrário gerado por sistemas de IA. Essa é principalmente uma preocupação quando funções executam código Python gerado dinamicamente que não foi revisado.
• Diferenças de versão da biblioteca: as versões da biblioteca podem diferir entre ambientes de execução local e sem servidor, o que pode levar a um comportamento de função diferente.

Variáveis de ambiente

Configure como as DatabricksFunctionClient funções são executadas usando as seguintes variáveis de ambiente:

Exemplos de notebooks

Os notebooks a seguir demonstram a criação de ferramentas de agentes de IA que se conectam a serviços externos usando funções do Unity Catalog.

Ferramenta do agente de mensagens do Slack

Obter laptop

Ferramenta de agente do Microsoft API do Graph

Obter laptop

ferramenta de agente do Pesquisa de IA do Azure 

Obter laptop

Próximas etapas

• Adicione ferramentas do Catálogo do Unity aos agentes programaticamente. Consulte Criar um agente de IA e implantá-lo nos Aplicativos do Databricks.

• Adicione ferramentas do Unity Catalog aos agentes usando a interface do usuário do AI Playground. Confira Comece: Consulte LLMs e desenvolva protótipos de agentes de IA sem código.

• Gerenciar funções do Catálogo do Unity usando o Cliente de Funções. Consulte a documentação do Catálogo do Unity – Cliente de funções

• Conecte agentes a serviços externos para obter uma visão geral de todas as abordagens para conectar agentes a serviços externos.