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

Utilize funções do Unity Catalog quando o seu agente precisar de executar lógica pré-definida, como uma consulta SQL cujos parâmetros o agente fornece. Para outras ferramentas, começa pelos MCPs.

Este guia utiliza o Unity Catalog AI para criar uma pequena função Python, testá-la e adicioná-la a um agente usando o framework que escolher. Se já tens uma função, instala as bibliotecas no passo 1 e vai para o passo 3.

Requirements

• Um caderno Azure Databricks com Python 3.10 ou superior. No compute clássico, use Databricks Runtime 15.0 ou superior.
• Computação serverless ativada no seu espaço de trabalho. O Function Client utiliza computação geral serverless para executar ferramentas; um SQL warehouse por si só não é suficiente.
• USE CATALOG e USE SCHEMA no catálogo e esquema pai da função. A criação de uma função também requer CREATE FUNCTION no esquema; chamar uma função existente requer EXECUTE nela. Consulte Privilégios de função.
• Um modelo que suporta a invocação de ferramentas. O exemplo do LangGraph utiliza um endpoint do modelo Azure Databricks. Os exemplos OpenAI, Anthropic e LlamaIndex utilizam credenciais de API de fornecedores, conforme descrito nos seus separadores.

Passo 1: Instalar as bibliotecas

Executa o comando de instalação do teu framework numa célula de caderno:

Para código-fonte de pacotes, consulte o repositório Unity Catalog AI.

Depois reinicia o Python numa célula separada:

dbutils.library.restartPython()

Passo 2: Criar e testar uma função

Utilize DatabricksFunctionClient para criar e testar a função. Substitui my_catalog e my_schema por um catálogo e esquema existentes onde possas criar funções. Este exemplo cria add_numbers; escolha um nome diferente se já existir.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()
CATALOG = "my_catalog"
SCHEMA = "my_schema"


def add_numbers(number_1: float, number_2: float) -> float:
    """Add two numbers.

    Args:
        number_1: The first number to add.
        number_2: The second number to add.

    Returns:
        The sum of the two numbers.
    """
    return number_1 + number_2


client.create_python_function(func=add_numbers, catalog=CATALOG, schema=SCHEMA)

result = client.execute_function(
    function_name=f"{CATALOG}.{SCHEMA}.add_numbers",
    parameters={"number_1": 2.0, "number_2": 3.0},
)
if result.error:
    raise RuntimeError(result.error)
print(result.value)  # 5.0

Passo 3: Use a função no seu agente

Define function_name como o nome completo da tua função, depois executa o exemplo para o teu framework. Cada um usa UCFunctionToolkit para chamar diretamente a função.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

function_name = "my_catalog.my_schema.add_numbers"
client = DatabricksFunctionClient()
question = "Use the tool to add 2.0 and 3.0."

LangGraph

Este exemplo utiliza o databricks-claude-sonnet-4-5 endpoint. Substitua-o por um modelo de chamada de ferramentas disponível no seu espaço de trabalho.

from databricks_langchain import ChatDatabricks, UCFunctionToolkit
from langgraph.prebuilt import create_react_agent

toolkit = UCFunctionToolkit(function_names=[function_name], client=client)
agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=toolkit.tools,
)
result = agent.invoke({"messages": [{"role": "user", "content": question}]})
print(result["messages"][-1].content)

Veja a referência de integração do LangChain.

OpenAI

Define as variáveis de ambiente OPENAI_API_KEY e OPENAI_MODEL para o processo do notebook. Utilize um modelo que suporte chamadas de ferramentas e armazene a chave API num segredo do Azure Databricks.

import os
from openai import OpenAI
from unitycatalog.ai.openai.toolkit import UCFunctionToolkit
from unitycatalog.ai.openai.utils import generate_tool_call_messages

toolkit = UCFunctionToolkit(function_names=[function_name], client=client)
model_client = OpenAI()
messages = [{"role": "user", "content": question}]

for _ in range(10):
    response = model_client.chat.completions.create(
        model=os.environ["OPENAI_MODEL"],
        messages=messages,
        tools=toolkit.tools,
    )
    if not response.choices[0].message.tool_calls:
        print(response.choices[0].message.content)
        break
    messages.extend(generate_tool_call_messages(response=response, client=client))
else:
    raise RuntimeError("The agent reached the tool-calling limit.")

O assistente executa as funções solicitadas e formata os seus resultados para a próxima chamada ao modelo. Veja a referência de integração OpenAI.

Anthropic

Define as variáveis de ambiente ANTHROPIC_API_KEY e ANTHROPIC_MODEL para o processo do notebook. Utilize um modelo que suporte chamadas de ferramentas e armazene a chave API num segredo do Azure Databricks.

import os
from anthropic import Anthropic
from unitycatalog.ai.anthropic.toolkit import UCFunctionToolkit
from unitycatalog.ai.anthropic.utils import generate_tool_call_messages

toolkit = UCFunctionToolkit(function_names=[function_name], client=client)
model_client = Anthropic()
messages = [{"role": "user", "content": question}]

for _ in range(10):
    response = model_client.messages.create(
        model=os.environ["ANTHROPIC_MODEL"],
        max_tokens=1024,
        tools=toolkit.tools,
        messages=messages,
    )
    if response.stop_reason != "tool_use":
        print("\n".join(block.text for block in response.content if block.type == "text"))
        break
    messages.extend(
        generate_tool_call_messages(
            response=response, client=client, conversation_history=[],
        )
    )
else:
    raise RuntimeError("The agent reached the tool-calling limit.")

O assistente executa as funções solicitadas. Acrescente as suas mensagens à conversa antes da próxima chamada do modelo. Veja a referência de integração Anthropic.

LlamaIndex

Este exemplo utiliza um modelo OpenAI. Define as variáveis de ambiente OPENAI_API_KEY e OPENAI_MODEL para o processo do notebook. Utilize um modelo que suporte chamadas de ferramentas e armazene a chave API num segredo do Azure Databricks.

import os
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from unitycatalog.ai.llama_index.toolkit import UCFunctionToolkit

toolkit = UCFunctionToolkit(function_names=[function_name], client=client)
agent = FunctionAgent(
    tools=toolkit.tools,
    llm=OpenAI(model=os.environ["OPENAI_MODEL"]),
)
result = await agent.run(user_msg=question)
print(result)

Execute as duas últimas linhas numa célula de notebook que suporte await. Consulte a referência de integração do LlamaIndex.

O agente chama add_numbers e retorna uma resposta contendo 5. Se usares uma função existente, altera question para uma tarefa suportada por essa função.

Para implementação e autenticação, veja Construir um agente personalizado e autenticação de agente.

Desenvolvimento local

Para testar funções Python de confiança, inicialize o cliente com execution_mode="local" e envie-o para a caixa de ferramentas do seu framework:

client = DatabricksFunctionClient(execution_mode="local")
toolkit = UCFunctionToolkit(function_names=[function_name], client=client)

O modo local recupera a função do Unity Catalog e executa-a num subprocesso local. Não suporta funções SQL. Utilize o modo serverless predefinido para produção e execute apenas código de confiança. Veja modos de execução.

Para timeouts, limites de memória e definições serverless, consulte os limites locais de execução e as variáveis de ambiente do Cliente de Funções.

Usar o endpoint MCP da área de trabalho (legacy)

Para integrações MCP existentes, este exemplo do LangGraph liga-se à mesma função através do endpoint do workspace legado. Ative a Pré-visualização dos Servidores MCP Geridos e use uma identidade com acesso à função.

Executa %pip install --upgrade databricks-langchain langgraph "mcp>=1.24,<2" numa célula de notebook e depois reinicia o Python. Substitua my_catalog/my_schema/add_numbers pelo caminho da sua função.

from databricks.sdk import WorkspaceClient
from databricks_langchain import (
    ChatDatabricks,
    DatabricksMCPServer,
    DatabricksMultiServerMCPClient,
)
from langchain_core.messages import convert_to_openai_messages
from langgraph.prebuilt import create_react_agent

workspace_client = WorkspaceClient()
function_path = "my_catalog/my_schema/add_numbers"
mcp_client = DatabricksMultiServerMCPClient([
    DatabricksMCPServer(
        name="uc-functions",
        url=f"{workspace_client.config.host}/api/2.0/mcp/functions/{function_path}",
        workspace_client=workspace_client,
    ),
])
agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=await mcp_client.get_tools(),
    prompt=lambda state: convert_to_openai_messages(state["messages"]),
)
result = await agent.ainvoke({
    "messages": [{"role": "user", "content": "Use the tool to add 2.0 and 3.0."}],
})
print(result["messages"][-1].content)

Para implantação, consulte Autenticação de Agente. Para uma função que chama uma API externa com http_request, veja Ferramentas Legadas da API REST.