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

Use as funções do Unity Catalog quando seu agente precisar executar uma lógica predefinida, como uma query SQL cujos parâmetros são fornecidos pelo agente. Para outras ferramentas, começar com MCPs.

Este guia usa Unity Catalog AI para criar uma pequena função Python, testá-la e adicioná-la a um agente usando a estrutura de sua escolha. Se você já tiver uma função, instale as bibliotecas no o passo 1 e vá para o o passo 3.

Requisitos

• Um Notebook Databricks com Python 3.10 ou acima. Em compute clássico, use o Databricks Runtime 15.0 ou acima.
• Serverless compute habilitado no seu workspace. O Function Client usa compute geral Serverless para execução de ferramentas; apenas um SQL Warehouse não é suficiente.
• USE CATALOG e USE SCHEMA no catálogo pai e no esquema da função. Criar uma função também exige CREATE FUNCTION no esquema; chamar uma função existente exige EXECUTE nela. Consulte Privilégios de função.
• Um modelo que oferece suporte à chamada de ferramentas. O exemplo do LangGraph usa um Databricks model endpoint. Os exemplos de OpenAI, Anthropic e LlamaIndex usam credenciais de API do provedor, conforme descrito em suas tab.

O passo 1: Instale as bibliotecas

Execute o comando de instalação do seu framework em uma célula de notebook:

Framework	Comando de instalação
LangGraph	%pip install --upgrade unitycatalog-langchain[databricks] databricks-langchain langgraph
OpenAI	%pip install --upgrade unitycatalog-openai[databricks]
Anthropic	%pip install --upgrade unitycatalog-anthropic[databricks]
LlamaIndex	%pip install --upgrade unitycatalog-llamaindex[databricks] llama-index-llms-openai

Framework	Comando de instalação
LangGraph	%pip install --upgrade unitycatalog-langchain[databricks] databricks-langchain langgraph
OpenAI	%pip install --upgrade unitycatalog-openai[databricks]
Anthropic	%pip install --upgrade unitycatalog-anthropic[databricks]
LlamaIndex	%pip install --upgrade unitycatalog-llamaindex[databricks] llama-index-llms-openai

Para obter o código-fonte do pacote, consulte o repository do Unity Catalog AI.

Em seguida, reinicie o Python em uma célula separada:

Python

dbutils.library.restartPython()

O passo 2: Criar e testar uma função

Use DatabricksFunctionClient para criar e testar a função. Substitua my_catalog e my_schema por um catálogo e um esquema existentes onde você possa criar funções. Este exemplo cria add_numbers; escolha um nome diferente se ele já existir.

Python

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

O passo 3: use a função em seu agente

Defina function_name como o nome completo da sua função e, em seguida, execução o exemplo para a sua estrutura. Cada um usa UCFunctionToolkit para chamar a função diretamente.

Python

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 usa o endpoint databricks-claude-sonnet-4-5. Substitua-o por um modelo de chamada de ferramenta disponível no seu workspace.

Python

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)

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

OpenAI

Defina as variáveis de ambiente OPENAI_API_KEY e OPENAI_MODEL para o seu processo de notebook. Use um modelo que dê suporte a chamadas de ferramentas e armazene a key da API em um segredo do Databricks.

Python

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 auxiliar execução as funções solicitadas e formata seus resultados para a próxima chamada de modelo. Consulte a referência de integração da OpenAI.

Anthropic

Defina as variáveis de ambiente ANTHROPIC_API_KEY e ANTHROPIC_MODEL para o seu processo de notebook. Use um modelo que dê suporte a chamadas de ferramentas e armazene a key da API em um segredo do Databricks.

Python

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 auxiliar executa as funções solicitadas. Acrescente suas mensagens à conversa antes da próxima chamada do modelo. Consulte a referência de integração da Anthropic.

LlamaIndex

Este exemplo usa um modelo do OpenAI. Defina as variáveis de ambiente OPENAI_API_KEY e OPENAI_MODEL para o seu processo de notebook. Use um modelo que dê suporte a chamadas de ferramentas e armazene a key da API em um segredo do Databricks.

Python

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)

Faça a execução das últimas duas linhas em uma célula de notebook que dê suporte a await. Consulte a referência de integração do LlamaIndex.

O agente chama add_numbers e retorna uma resposta contendo 5. Se você usar uma função existente, altere question para uma tarefa compatível com essa função.

Para implantação e autenticação, consulte Criar um agente personalizado e Autenticação do agente.

Desenvolvimento local

Para testar funções Python confiáveis, inicialize o cliente com execution_mode="local" e passe-o para o kit de ferramentas do seu framework:

Python

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

O modo local recupera a função do Unity Catalog e a executa em um subprocesso local. Ele não oferece suporte a funções SQL. Use o modo Serverless default para produção e faça a execução apenas de códigos confiáveis. Consulte Modos de execução.

Para obter informações sobre limites de tempo limite, limites de memória e configurações de serverless, consulte os limites de execução local e as variáveis de ambiente do cliente de função.

Use o endpoint MCP do workspace (legado)

Para integrações MCP existentes, este exemplo do LangGraph se conecta à mesma função por meio do endpoint de workspace herdado. Ative a versão prévia dos Servidores MCP Gerenciados e use uma identidade com acesso à função.

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

Python

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 ver uma função que chama uma API externa com http_request, consulte Ferramentas de API REST herdadas.