Pular para o conteúdo principal
Última atualização em

Crie ferramentas de agente de AI usando funções do Unity Catalog

Use as funções do Unity Catalog para criar ferramentas de agente de AI que executam lógica personalizada e realizam tarefas específicas que estendem as capacidades de LLMs além da geração de linguagem.

Quando usar as funções do Unity Catalog vs. servidores MCP​

O Databricks recomenda o uso de funções do Unity Catalog como ferramentas de agente especificamente para ferramentas de recuperação de dados estruturados quando a consulta é conhecida antecipadamente e o agente fornece os parâmetros. Consulte Conectar agentes a 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 uma execução mais rápida, suporte à autenticação por usuário e flexibilidade adicional.

Requisitos​

Para criar e usar as funções do Unity Catalog como ferramentas de agente de AI, são necessários os seguintes itens:

  • Databricks Runtime : Use o Databricks Runtime 15,0 e acima.
  • Versão do Python: Instale o Python 3.10 ou acima.

Para a execução de funções do Unity Catalog:

  • Compute serverless deve ser habilitada em seu workspace para executar as funções do Unity Catalog como ferramentas de agente de AI em produção. Consulte os requisitos de compute serverless.
    • Execução em modo local para funções Python não exige o compute genérico serverless para execução, no entanto, o modo local se destina apenas a fins de desenvolvimento e teste.

Para criar funções do Unity Catalog:

  • O serverless generic compute deve ser habilitado em seu workspace para criar funções usando o Cliente do Databricks Workspace ou instruções SQL body.
    • Funções Python podem ser criadas sem compute serverless.

Criar uma ferramenta de função do Unity Catalog​

Os seguintes os passos mostram como criar e testar uma função do Unity Catalog. Execute o seguinte código em um Notebook do Databricks.

prompt

Diga ao Genie Code (modo Agente) para fazer isso por você:

Create a Unity Catalog Python function that an AI agent can use as a tool. It should take two floating point numbers and return their sum, with type hints and a Google-style docstring. Register it using the Databricks Function Client, then test calling it.

Instalar dependências​

Instale pacotes de AI do Unity Catalog com o extra [databricks].

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

dbutils.library.restartPython()

Inicialize o Cliente de Função do Databricks​

Inicialize o Databricks Function Client, que é uma interface especializada para criar, gerenciar e executar funções do Unity Catalog no Databricks.

Python
from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Defina a lógica da ferramenta​

As ferramentas do Unity Catalog são, na verdade, apenas funções definidas pelo usuário (UDFs) do Unity Catalog internamente. Ao definir uma ferramenta do Unity Catalog, você faz o registro de uma função no Unity Catalog. Para saber mais sobre UDFs do Unity Catalog, consulte Funções definidas pelo usuário (UDFs) no Unity Catalog.

atenção

A execução de código arbitrário em uma ferramenta de agente pode expor informações confidenciais ou privadas às quais o agente tem acesso. Os clientes são responsáveis por executar apenas código confiável e configurar barreiras de segurança e permissões apropriadas para evitar o acesso não intencional aos dados.

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

  • create_python_function aceita um objeto invocável Python.
  • create_function aceita uma instrução SQL de criação de função. Consulte Criar funções Python.

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

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

  • **Dicas de tipo**: A assinatura da função deve definir dicas de tipo Python válidas. Tanto os argumentos nomeados quanto o valor de retorno devem ter seus tipos definidos.

  • Não devem ser usados argumentos variáveis : argumentos variáveis como *args e **kwargs não são suportados. Todos os argumentos devem ser explicitamente definidos.

  • Compatibilidade de tipo : Nem todos os tipos Python são compatíveis com SQL. Consulte Tipos de dados compatíveis do Spark.

  • Docstrings descritivos : O kit de ferramentas de funções do Unity Catalog lê, analisa e extrai informações importantes do seu docstring.

    • Docstrings devem ser formatadas de acordo com a sintaxe de 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 seguintes trechos de código usam o create_python_function para registrar o invocável Python add_numbers:

Python

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
)

Teste a função​

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

Python
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'

Adicione funções do Unity Catalog ao seu agente​

Depois de ter criado e testado sua função do Unity Catalog, escolha uma das seguintes abordagens para adicioná-la ao seu agente.

Ícone do MCP. Usando MCP (recomendado)

Usando MCP (recomendado)​

A Databricks recomenda usar servidores MCP para adicionar funções do Unity Catalog ao seu agente. A abordagem MCP oferece uma integração mais simples com descoberta automática de ferramentas e suporte de autenticação integrada.

A URL MCP gerenciada para funções do Unity Catalog é: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}. Opcionalmente, é possível especificar uma função específica anexando /{function_name}.

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

Python
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 acesso do aplicativo à função do Unity Catalog em databricks.yml:

YAML
resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_uc_function'
          uc_securable:
            securable_full_name: '<catalog>.<schema>.<function-name>'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

Ícone de função. Usando o UCFunctionToolkit

Usando UCFunctionToolkit​

Este exemplo usa LangChain, mas uma abordagem semelhante pode ser aplicada a outras bibliotecas. Consulte a integração de ferramentas do Unity Catalog.

Instalar dependências adicionais​

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

Python
%pip install unitycatalog-langchain[databricks]==0.2.0

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

dbutils.library.restartPython()

Envolva 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 entre diferentes bibliotecas de AI generativa e adiciona recursos úteis como o rastreamento automático para recuperadores.

Python
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

Use a ferramenta em um agente​

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

nota

This example uses LangChain. However you can integrate Unity Catalog tools with other frameworks such as LlamaIndex, OpenAI, Anthropic, and more. See Unity Catalog tool integration.

Este exemplo cria um agente simples usando a API AgentExecutor da LangChain para simplificar. Para cargas de trabalho de produção, use o fluxo de trabalho de criação de agentes visto em Crie um agente de AI e seja implantado nos Databricks Apps.

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

Melhore a chamada 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 Unity Catalog, utilize a cláusula COMMENT 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 para agentes e humanos usarem.

Exemplo: Documentação de ferramenta eficaz​

O exemplo a seguir mostra strings COMMENT claras para uma ferramenta que consulta uma tabela estruturada.

SQL
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 carece de detalhes importantes, dificultando que os agentes usem a ferramenta de forma eficaz:

SQL
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;

Execute funções usando o modo serverless ou local​

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

A chamada execute_function pode executar funções em dois modos de execução: serverless ou local. Este modo determina qual recurso realiza a execução da função.

Modo Serverless para produção​

O modo serverless é a opção default e recomendada para casos de uso de produção ao executar funções do Unity Catalog como ferramentas de agente de AI. Este modo usa o compute genérico serverless (Spark Connect serverless) para executar funções remotamente, e o Lakeguard garante que o processo do seu agente permaneça seguro e livre dos riscos de execução de código arbitrário localmente.

nota

Funções do Unity Catalog executadas como ferramentas de agente de AI exigem compute genérico serverless (Spark Connect serverless), não SQL warehouse serverless. Tentativas de executar ferramentas sem compute genérico serverless produzirão erros como PERMISSION_DENIED: Cannot access Spark Connect.

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

Quando o seu agente solicita a execução de uma ferramenta no modo **serverless**, ocorre o seguinte:

  1. O DatabricksFunctionClient envia uma solicitação para o Unity Catalog para recuperar a definição da função se a definição não tiver sido armazenada em cache localmente.
  2. O DatabricksFunctionClient extrai a definição da função e valida os nomes e tipos de parâmetros.
  3. O DatabricksFunctionClient envia a execução como uma UDF para o compute genérico serverless.

Modo local para desenvolvimento​

O modo local executa funções Python em um subprocesso local em vez de fazer solicitações ao compute genérico serverless. Isso permite solucionar problemas de chamadas de ferramentas de forma mais eficaz, fornecendo rastreamentos de pilha locais. Ele é projetado para o desenvolvimento e a depuração de funções do Unity Catalog em Python.

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

  1. Envia uma solicitação ao Unity Catalog para recuperar a definição da função se a definição não tiver sido armazenada em cache localmente.
  2. Extrai a definição de invocável Python, armazena o invocável em cache localmente e valida os nomes e tipos de parâmetros.
  3. Invoca o chamável com os parâmetros especificados em um subprocesso restrito com proteção de tempo limite.
Python
# Defaults to serverless if `execution_mode` is not specified
client = DatabricksFunctionClient(execution_mode="local")

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

  • Limite de tempo da CPU: Restringe o tempo de execução total da CPU para execução invocável para evitar cargas computacionais excessivas.

    O limite de tempo de CPU é baseado no uso real de CPU, e não no tempo real. Devido à programação do sistema e processos concorrentes, o tempo de CPU pode exceder o tempo real em cenários do mundo real.

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

  • Proteção contra tempo limite: impõe um tempo limite total de relógio para a execução de funções.

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

Limitações do modo local​

  • Somente funções Python : As funções baseadas em SQL não são compatíveis 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 AI. Isso é principalmente uma preocupação quando as 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 serverless e locais, o que pode levar a um comportamento de função diferente.

variável de ambiente​

Configure como as funções são colocadas em execução no DatabricksFunctionClient usando a seguinte variável de ambiente:

Variável de ambiente

Valor padrão

Descrição

EXECUTOR_MAX_CPU_TIME_LIMIT

10 Segundos

Tempo máximo permitido de execução da CPU (somente modo local).

EXECUTOR_MAX_MEMORY_LIMIT

100 MB

Alocação máxima permitida de memória virtual para o processo (somente no modo local).

EXECUTOR_TIMEOUT

20 Segundos

Tempo máximo total de relógio de parede (somente modo local).

UCAI_DATABRICKS_SESSION_RETRY_MAX_ATTEMPTS

5

O número máximo de tentativas para tentar novamente atualizar o cliente da sessão em caso de expiração do tokens.

UCAI_DATABRICKS_SERVERLESS_EXECUTION_RESULT_ROW_LIMIT

100

O número máximo de linhas a serem retornadas ao executar funções usando compute serverless e databricks-connect.

Chamar APIs externas com http_request (legado)​

nota

Para conectar agentes a serviços externos, o Databricks recomenda Serviços MCP ou o proxy de conexões do Unity Catalog. As ferramentas de função UC que envolvem http_request continuam sendo compatíveis, mas não são mais a abordagem recomendada.

Você pode criar uma função do Unity Catalog que encapsula http_request() para chamar serviços externos. Essa abordagem é útil para definições de ferramentas baseadas em SQL.

O exemplo a seguir cria uma ferramenta de função do Unity Catalog que publica uma mensagem no Slack:

SQL
CREATE OR REPLACE FUNCTION main.default.slack_post_message(
  text STRING COMMENT 'message content'
)
RETURNS STRING
COMMENT 'Sends a Slack message by passing in the message and returns the response received from the external service.'
RETURN (http_request(
  conn => 'test_sql_slack',
  method => 'POST',
  path => '/api/chat.postMessage',
  json => to_json(named_struct(
    'channel', "C032G2DAH3",
    'text', text
  ))
)).text

Consulte CREATE FUNCTION (SQL e Python).

nota

O acesso SQL com http_request é bloqueado para os tipos de conexão Usuário para Máquina por Usuário e Registro Dinâmico de Cliente. Use o SDK do Databricks para Python em vez disso.

Notebooks de exemplo​

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

Ferramenta de agente de mensagens do Slack

Abrir notebook em uma nova aba

Ferramenta de agente da API do gráfico da Microsoft

Abrir notebook em uma nova aba

Ferramenta de agente do Azure AI Search

Abrir notebook em uma nova aba

Próximos os passos​

Nesta página