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

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

Use 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 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 query é 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, você precisa do seguinte:

  • Databricks Runtime : Use o Databricks Runtime 15.0 e acima
  • Versão do Python : Instale o Python 3.10 ou acima

Para executar funções do Unity Catalog:

  • O compute Serverless deve ser habilitado em seu Workspace para executar as funções do Unity Catalog como ferramentas de agente de AI em produção. Consulte requisitos de compute Serverless.
    • Execução em modo local para funções Python não requer compute genérico serverless para ser executado, no entanto, o modo local se destina apenas a fins de desenvolvimento e teste.

Para criar funções do Unity Catalog:

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

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

Os passos a seguir mostram como criar e testar uma função do Unity Catalog. Execute o código a seguir em um notebook 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()

Inicializar o Cliente de Função do Databricks​

Inicialize o Cliente de Função do Databricks, 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 por baixo dos panos. Ao definir uma ferramenta do Unity Catalog, você está registrando uma função no Unity Catalog. Para saber mais sobre as UDFs do Unity Catalog, consulte funções definidas pelo usuário (UDFs) de SQL e Python 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 por configurar barreiras de segurança e permissões apropriadas para evitar acesso não intencional a dados.

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

  • create_python_function aceita um chamável Python.
  • create_function aceita uma instrução SQL CREATE FUNCTION. Consulte Criar funções Python.

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

Para que um callable Python seja 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 use 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 com Spark.

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

    • Docstrings devem ser formatados 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. 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 callable 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
)

Testar a função​

Teste sua função para verificar se funciona conforme o esperado. Especifique um nome de função totalmente qualificado na API execute_function para executar a 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'

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

Depois de criar e testar 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 o uso de 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}. Você pode, opcionalmente, 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 das 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 ao aplicativo acesso à 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 UCFunctionToolkit

Usando o UCFunctionToolkit​

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

Instalar dependências adicionais​

Instale os pacotes de integração do 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​

Encapsule a função usando UCFunctionToolkit para torná-la acessível às bibliotecas de criação de agentes. O kit de ferramentas garante consistência em diferentes bibliotecas de IA generativa e adiciona recursos úteis como 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 do LangChain para simplificar. Para cargas de trabalho de produção, use o fluxo de trabalho de autoria de agente visto em Criar um agente de AI e implantá-lo no 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 ferramenta 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, use a cláusula COMMENT para descrever a funcionalidade da ferramenta e os parâmetros.
  • 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 COMMENT strings claras para uma ferramenta que query 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, tornando mais difícil para os agentes usarem 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, os pacotes de integração (instâncias UCFunctionToolkit) 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 executa a 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 compute genérico serverless (Spark Connect serverless) para executar funções remotamente, e Lakeguard garante que o processo do seu agente permaneça seguro e livre dos riscos de executar código arbitrário localmente.

nota

Funções do Unity Catalog executadas como ferramentas de agente de AI requerem compute genérico Serverless (Spark Connect Serverless), não SQL warehouses Serverless. Tentativas de executar ferramentas sem o 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 seu agente solicita a execução de uma ferramenta no modo Serverless , ocorre o seguinte:

  1. O DatabricksFunctionClient 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. 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 para o compute genérico serverless. Isso permite solucionar problemas de chamadas de ferramentas de forma mais eficaz, fornecendo rastreamentos de pilha locais. Ele é projetado para desenvolvimento e depuração de funções Python do Unity Catalog.

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

  1. 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. Extrai a definição do callable Python, armazena o callable em cache localmente e valida os nomes e tipos dos parâmetros.
  3. Invoca o callable com os parâmetros especificados em um subprocesso restrito com proteção contra tempo limite.
Python
# Defaults to serverless if `execution_mode` is not specified
client = DatabricksFunctionClient(execution_mode="local")

Executar no modo "local" fornece os seguintes recursos:

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

    O limite de tempo da CPU é baseado no uso real da CPU, não no tempo real. Devido ao agendamento do sistema e processos concorrentes, o tempo da 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 (wall-clock) para a execução de funções.

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

Limitações do modo local​

  • **Apenas funções Python**: 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, existe um risco de segurança potencial ao executar código arbitrário gerado por sistemas de AI. Esta é principalmente uma preocupação quando as funções executam código Python gerado dinamicamente que não foi revisado.
  • Diferenças de versão de biblioteca : as versões de 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 executadas em DatabricksFunctionClient usando as seguintes variáveis 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 de memória virtual permitida para o processo (somente no modo local).

EXECUTOR_TIMEOUT

20 Segundos

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

UCAI_DATABRICKS_SESSION_RETRY_MAX_ATTEMPTS

5

O número máximo de tentativas para tentar novamente a atualização do cliente de sessão em caso de expiração do token.

UCAI_DATABRICKS_SERVERLESS_EXECUTION_RESULT_ROW_LIMIT

100

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

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 de memória virtual permitida para o processo (somente no modo local).

EXECUTOR_TIMEOUT

20 Segundos

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

UCAI_DATABRICKS_SESSION_RETRY_MAX_ATTEMPTS

5

O número máximo de tentativas para tentar novamente a atualização do cliente de sessão em caso de expiração do token.

UCAI_DATABRICKS_SERVERLESS_EXECUTION_RESULT_ROW_LIMIT

100

O número máximo de linhas a retornar 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, a 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, Python, Scala e Java).

nota

Acesso SQL com http_request está 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 seguintes Notebooks demonstram como criar ferramentas de agente de AI que se conectam a serviços externos usando as funções do Unity Catalog.

Ferramenta de agente de mensagens do Slack

Abrir notebook em uma nova abaOpen in Databricks

Ferramenta de agente da API do Microsoft Graph

Abrir notebook em uma nova abaOpen in Databricks

Ferramenta de agente do Azure AI Search

Abrir notebook em uma nova abaOpen in Databricks

Próximos passos​

Nesta página