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

Criar ferramentas do agente AI usando as funções Unity Catalog

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

Quando usar as funções do Unity Catalog em vez dos servidores MCP​

A 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, a Databricks recomenda servidores MCP ou a definição da lógica diretamente no código do agente para uma execução mais rápida, suporte à autenticação por usuário e maior flexibilidade.

Requisitos​

Para criar e utilizar funções d Unity Catalog como ferramentas de agente d AI, é necessário o seguinte:

  • Databricks Runtime Utilize um Databricks Runtime ão 15.0 ou superior.
  • Python versão: Instale o Python 3.10 ou superior

Para executar as funções d Unity Catalog:

  • O computesem servidor deve estar habilitado em seu workspace para executar funções Unity Catalog como ferramentas de agente AI na produção. Consulte os requisitos do compute sem servidor.
    • A execução em modo local para funções Python não requer um compute genérico serverless para execução; no entanto, o modo local destina-se apenas a fins de desenvolvimento e teste.

Para criar funções d Unity Catalog:

  • O recurso genérico sem servidor compute deve estar habilitado em seu workspace para criar funções usando o cliente Databricks Workspace ou instruções de corpo SQL.
    • Python As funções podem ser criadas sem serverless compute.

Criar uma ferramenta de função Unity Catalog​

Os passos a seguir mostram como criar e testar uma função Unity Catalog . execute o código a seguir em um notebook Databricks .

Instalar dependências​

Instale o pacote Unity Catalog AI 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 da função 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, funções definidas pelo usuário (UDFs) do Unity Catalog que funcionam internamente. Ao definir uma ferramenta Unity Catalog , você está registrando uma função no Unity Catalog. Para saber mais sobre as UDFs 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 sensíveis ou privadas às quais o agente tem acesso. Os clientes são responsáveis por executar apenas código confiável e configurar mecanismos de proteção e permissões adequadas para evitar o acesso não autorizado aos dados.

O senhor 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 de função de criação de corpo SQL. Consulte Criar funções Python.

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

Para tornar um chamável Python reconhecível no 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 definidos explicitamente.

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

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

    • As docstrings devem ser formatadas 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 : biblioteca deve ser importada 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 Python chamável 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 conforme o esperado. Especifique um nome de função totalmente qualificado no endereço execute_function API 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'

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

Depois de criar e testar sua função no Unity Catalog, escolha uma das seguintes abordagens para adicioná-la ao seu agente.

Ícone do Mcp. Utilizando MCP (recomendado)

Utilizando MCP (recomendado)​

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

O URL do gerenciador MCP para funções Unity Catalog é: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}. Você pode opcionalmente especificar uma função específica adicionando /{function_name}.

Os exemplos a seguir mostram como conectar seu agente às funções do Unity Catalog por meio do MCP. Substitua <catalog> e <schema> pela localização 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 ao aplicativo acesso à função 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. Utilizando o UCFunctionToolkit

Utilizando o UCFunctionToolkit​

Este exemplo usa o site LangChain, mas uma abordagem semelhante pode ser aplicada a outras bibliotecas. Consulte Integrar ferramentas Unity Catalog com estruturas geradoras de AI de terceiros.

Instalar dependências adicionais​

Instale o pacote de integração LangChain para UCFunctionToolkit.

Python
%pip install unitycatalog-langchain[databricks]

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

dbutils.library.restartPython()

Envolva a função usando o UCFunctionToolkit​

Envolva a função usando o endereço UCFunctionToolkit para torná-la acessível à biblioteca de autoria do agente. O kit de ferramentas garante a consistência em diferentes gerações AI biblioteca 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 Integrate Unity Catalog tools with third party generative AI frameworks.

Este exemplo cria um agente simples usando a API LangChain AgentExecutor para maior simplicidade. Para cargas de trabalho de produção, use o fluxo de trabalho de autoria de agentes visto em Criar um agente AI e implantá-lo em 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 as funções do Unity Catalog, use 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 facilitar o uso das ferramentas por agentes e humanos.

Exemplo: documentação eficaz da ferramenta​

O exemplo a seguir mostra claramente COMMENT strings 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 ineficaz da ferramenta​

O exemplo a seguir carece de detalhes importantes, dificultando o uso eficaz da ferramenta pelos agentes:

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;

funções de execução usando modo serverless ou local​

Quando um serviço de geração AI determina que uma chamada de ferramenta é necessária, o pacote de integração (instânciasUCFunctionToolkit ) executa o DatabricksFunctionClient.execute_function API.

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

modo sem servidor para produção​

O modo sem servidor é a opção default e recomendada para casos de uso em produção ao executar funções Unity Catalog como ferramentas de agentes AI . Este modo utiliza compute genérica 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 executar código arbitrário localmente.

nota

Unity Catalog serverless As funções executadas como ferramentas de agente d AI, requerem um compute genérico (Spark Connect serverless), e não um serverless SQL warehouse. Tentativas de executar ferramentas sem o serverless genérico compute 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 acontece o seguinte:

  1. O site DatabricksFunctionClient envia uma solicitação ao Unity Catalog para recuperar a definição da função, caso a definição não tenha sido armazenada em cache localmente.
  2. O DatabricksFunctionClient extrai a definição da função e valida os nomes e tipos dos parâmetros.
  3. A Associação Nacional de Consultores de Saúde e Segurança ( DatabricksFunctionClient ) submete a execução como um Relatório de Incidente de Saúde e Segurança ( UDF ) para serverless genérico compute.

Modo local para desenvolvimento​

O modo local executa funções Python em um subprocesso local, em vez de fazer solicitações para serverless genérico compute. Isso permite que você solucione problemas de chamadas de ferramentas com mais eficiência, fornecendo rastreamentos de pilha locais. Ele foi projetado para o desenvolvimento e depuração de funções Python Unity Catalog .

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 do chamável Python, armazena em cache o chamável localmente e valida os nomes e os tipos dos parâmetros.
  3. Invoca o callable 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 o seguinte recurso:

  • Limite de tempo de CPU: restringe o tempo de execução total da CPU para execução que pode ser chamada para evitar cargas computacionais excessivas.

    O limite de tempo da CPU é baseado no uso real da CPU, não no tempo do relógio de parede. Devido aos processos de programar e concorrente do sistema, o tempo da CPU pode exceder o tempo do relógio de parede 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 a variável de ambiente (leia mais).

Limitações do modo local​

  • Apenas funções Python : funções baseadas em SQL não são suportadas 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 processos, existe um risco potencial de segurança ao executar código arbitrário gerado por sistemas AI. Isso é principalmente uma preocupação quando as funções executam código Python gerado dinamicamente que não foi revisado.
  • Diferenças entre versões da biblioteca : as versões da biblioteca podem diferir entre serverless e os ambientes de execução locais, o que pode resultar em comportamentos diferentes das funções.

variável de ambiente​

Configure a execução das funções no site 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 no 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 do relógio de parede (somente no modo local).

UCAI_DATABRICKS_SESSION_RETRY_MAX_ATTEMPTS

5

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

UCAI_DATABRICKS_SERVERLESS_EXECUTION_RESULT_ROW_LIMIT

100

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

Exemplo de caderno​

O seguinte Notebook demonstra a criação de ferramentas de agentes AI que se conectam a serviços externos usando funções Unity Catalog .

Ferramenta de agente de mensagens Slack

Abrir notebook em uma nova aba

Ferramenta de agente API gráfica Microsoft

Abrir notebook em uma nova aba

Ferramenta de agente de pesquisa AI Azure

Abrir notebook em uma nova aba

Próximas etapas​