Create agent tools using Unity Catalog functions

Use Unity Catalog functions to create agent tools that execute custom logic and perform specific tasks that extend the capabilities of LLMs beyond language generation.

When to use Unity Catalog functions vs. MCP servers

Databricks recommends using Unity Catalog functions as agent tools specifically for structured data retrieval tools when the query is known ahead of time and the agent provides the parameters. See Connect agents to structured data.

In most other use cases, Databricks recommends MCP servers or defining the logic directly in agent code for faster execution, per-user authentication support, and additional flexibility.

Requirements

To create and use Unity Catalog functions as agent tools, you need the following:

• Databricks Runtime: Use Databricks Runtime 15.0 and above
• Python version: Install Python 3.10 or above

To run Unity Catalog functions:

• Serverless compute must be enabled in your workspace to execute Unity Catalog functions as agent tools in production. See Serverless compute requirements.
  • Local mode execution for Python functions does not require serverless generic compute to run, however local mode is only intended for development and testing purposes.

To create Unity Catalog functions:

• Serverless generic compute must be enabled in your workspace to create functions using the Databricks Workspace Client or SQL body statements.
  • Python functions can be created without serverless compute.

Create a Unity Catalog function tool

The following steps show how to create and test a Unity Catalog function. Run the following code in a Databricks notebook.

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.

Install dependencies

Install Unity Catalog AI packages with the [databricks] extra.

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

dbutils.library.restartPython()

Initialize the Databricks Function Client

Initialize the Databricks Function Client, which is a specialized interface for creating, managing, and running Unity Catalog functions in Databricks.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Define the tool's logic

Unity Catalog tools are really just Unity Catalog user-defined functions (UDFs) under the hood. When you define a Unity Catalog tool, you're registering a function in Unity Catalog. To learn more about Unity Catalog UDFs, see SQL and Python user-defined functions (UDFs) in Unity Catalog.

You can create Unity Catalog functions using one of two APIs:

• create_python_function accepts a Python callable.
• create_function accepts a SQL body create function statement. See Create Python functions.

Use the create_python_function API to create the function.

To make a Python callable recognizable to the Unity Catalog functions data model, your function must meet the following requirements:

• Type hints: The function signature must define valid Python type hints. Both the named arguments and the return value must have their types defined.
• Do not use variable arguments: Variable arguments such as *args and **kwargs are not supported. All arguments must be explicitly defined.
• Type compatibility: Not all Python types are supported in SQL. See Spark Supported Data Types.
• Descriptive docstrings: The Unity Catalog functions toolkit reads, parses, and extracts important information from your docstring.
  • Docstrings must be formatted according to the Google docstring syntax.
  • Write clear descriptions for your function and its arguments to help the LLM understand how and when to use the function.
• Dependency imports: Libraries must be imported within the function's body. Imports outside the function will not be resolved when running the tool.

The following code snippets uses the create_python_function to register the Python callable add_numbers:

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
)

Test the function

Test your function to check it works as expected. Specify a fully qualified function name in the execute_function API to run the function:

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'

Add Unity Catalog functions to your agent

Once you have created and tested your Unity Catalog function, choose one of the following approaches to add it to your agent.

Using MCP (recommended)

Using MCP (recommended)

Databricks recommends using MCP servers to add Unity Catalog functions to your agent. The MCP approach provides a simpler integration with automatic tool discovery and built-in authentication support.

The managed MCP URL for Unity Catalog functions is: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}. You can optionally specify a specific function by appending /{function_name}.

The following examples show how to connect your agent to Unity Catalog functions through MCP. Replace <catalog> and <schema> with the location of your functions.

OpenAI Agents SDK (Apps)

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)

Grant the app access to the Unity Catalog function in databricks.yml:

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

LangGraph (Apps)

from databricks.sdk import WorkspaceClient
from databricks_langchain import ChatDatabricks, DatabricksMCPServer, DatabricksMultiServerMCPClient
from langgraph.prebuilt import create_react_agent

workspace_client = WorkspaceClient()
host = workspace_client.config.host

mcp_client = DatabricksMultiServerMCPClient([
    DatabricksMCPServer(
        name="uc-functions",
        url=f"{host}/api/2.0/mcp/functions/<catalog>/<schema>",
        workspace_client=workspace_client,
    ),
])

async with mcp_client:
    tools = await mcp_client.get_tools()
    agent = create_react_agent(
        ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
        tools=tools,
    )
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "Look up customer info for Acme Corp"}]}
    )
    print(result["messages"][-1].content)

Grant the app access to the Unity Catalog function in databricks.yml:

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

Model Serving

from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksMCPClient
import mlflow

workspace_client = WorkspaceClient()
host = workspace_client.config.host

# Connect to the UC functions MCP server
mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/functions/<catalog>/<schema>",
    workspace_client=workspace_client,
)

# List available tools
tools = mcp_client.list_tools()

# Log the agent with the required resources for deployment
mlflow.pyfunc.log_model(
    "agent",
    python_model=my_agent,
    resources=mcp_client.get_databricks_resources(),
)

To deploy the agent, see Deploy an agent for AI applications (Model Serving). For details on logging agents with MCP resources, see Azure Databricks managed MCP servers.

Using UCFunctionToolkit

Using UCFunctionToolkit

This example uses LangChain, but a similar approach can be applied to other libraries. See Use Unity Catalog tools with other AI frameworks.

Install additional dependencies

Install the LangChain integration packages for UCFunctionToolkit.

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

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

dbutils.library.restartPython()

Wrap the function using the UCFunctionToolKit

Wrap the function using the UCFunctionToolkit to make it accessible to agent authoring libraries. The toolkit ensures consistency across different AI libraries and adds helpful features like auto-tracing for retrievers.

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 the tool in an agent

Add the tool to a LangChain agent using the tools property from UCFunctionToolkit.

Note

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

This example authors a simple agent using LangChain AgentExecutor API for simplicity. For production workloads, use the agent authoring workflow seen in Author an agent and deploy it on Databricks Apps.

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

Use Unity Catalog tools with other AI frameworks

Beyond LangChain (shown above), Unity Catalog agent tools work with other popular AI libraries like LlamaIndex, OpenAI, and Anthropic. These integrations combine Unity Catalog tool governance with the capabilities of third-party agent authoring frameworks. For example, in OpenAI or Anthropic integrations, the functions are called directly by the AI model during execution.

Select your framework in the following tabs to create a Unity Catalog tool and use it with that framework. Run the code in a Azure Databricks notebook or Python script.

LlamaIndex

Use Azure Databricks Unity Catalog to integrate SQL and Python functions as tools in LlamaIndex workflows. This integration combines Unity Catalog governance with LlamaIndex's capabilities to index and query large datasets for LLMs.

1. Install the Databricks Unity Catalog integration package for LlamaIndex.

   %pip install unitycatalog-llamaindex[databricks]
   dbutils.library.restartPython()
   

2. Create an instance of the Unity Catalog functions client.

   from unitycatalog.ai.core.base import get_uc_function_client
   
   client = get_uc_function_client()
   

3. Create a Unity Catalog function written in Python.

   CATALOG = "your_catalog"
   SCHEMA = "your_schema"
   
   func_name = f"{CATALOG}.{SCHEMA}.code_function"
   
   def code_function(code: str) -> str:
     """
     Runs Python code.
   
     Args:
       code (str): The Python code to run.
     Returns:
       str: The result of running the Python code.
     """
     import sys
     from io import StringIO
     stdout = StringIO()
     sys.stdout = stdout
     exec(code)
     return stdout.getvalue()
   
   client.create_python_function(
     func=code_function,
     catalog=CATALOG,
     schema=SCHEMA,
     replace=True
   )
   

4. Create an instance of the Unity Catalog function as a toolkit, and run it to verify that the tool behaves properly.

   from unitycatalog.ai.llama_index.toolkit import UCFunctionToolkit
   import mlflow
   
   # Enable traces
   mlflow.llama_index.autolog()
   
   # Create a UCFunctionToolkit that includes the UC function
   toolkit = UCFunctionToolkit(function_names=[func_name])
   
   # Fetch the tools stored in the toolkit
   tools = toolkit.tools
   python_exec_tool = tools[0]
   
   # Run the tool directly
   result = python_exec_tool.call(code="print(1 + 1)")
   print(result)  # Outputs: {"format": "SCALAR", "value": "2\n"}
   

5. Use the tool in a LlamaIndex ReActAgent by defining the Unity Catalog function as part of a LlamaIndex tool collection. Then verify that the agent behaves properly by calling the LlamaIndex tool collection.

   from llama_index.llms.openai import OpenAI
   from llama_index.core.agent import ReActAgent
   
   llm = OpenAI()
   
   agent = ReActAgent.from_tools(tools, llm=llm, verbose=True)
   
   agent.chat("Please run the following python code: `print(1 + 1)`")
   

OpenAI

Use Azure Databricks Unity Catalog to integrate SQL and Python functions as tools in OpenAI workflows. This integration combines the governance of Unity Catalog with OpenAI to create powerful AI apps.

1. Install the Databricks Unity Catalog integration package for OpenAI.

   %pip install unitycatalog-openai[databricks]
   %pip install mlflow -U
   dbutils.library.restartPython()
   

2. Create an instance of the Unity Catalog functions client.

   from unitycatalog.ai.core.base import get_uc_function_client
   
   client = get_uc_function_client()
   

3. Create a Unity Catalog function written in Python.

   CATALOG = "your_catalog"
   SCHEMA = "your_schema"
   
   func_name = f"{CATALOG}.{SCHEMA}.code_function"
   
   def code_function(code: str) -> str:
     """
     Runs Python code.
   
     Args:
       code (str): The python code to run.
     Returns:
       str: The result of running the Python code.
     """
     import sys
     from io import StringIO
     stdout = StringIO()
     sys.stdout = stdout
     exec(code)
     return stdout.getvalue()
   
   client.create_python_function(
     func=code_function,
     catalog=CATALOG,
     schema=SCHEMA,
     replace=True
   )
   

4. Create an instance of the Unity Catalog function as a toolkit and verify that the tool behaves properly by running the function.

   from unitycatalog.ai.openai.toolkit import UCFunctionToolkit
   import mlflow
   
   # Enable tracing
   mlflow.openai.autolog()
   
   # Create a UCFunctionToolkit that includes the UC function
   toolkit = UCFunctionToolkit(function_names=[func_name])
   
   # Fetch the tools stored in the toolkit
   tools = toolkit.tools
   client.execute_function = tools[0]
   

5. Submit the request to the OpenAI model along with the tools.

   import openai
   
   messages = [
     {
       "role": "system",
       "content": "You are a helpful customer support assistant. Use the supplied tools to assist the user.",
     },
     {"role": "user", "content": "What is the result of 2**10?"},
   ]
   response = openai.chat.completions.create(
     model="gpt-4o-mini",
     messages=messages,
     tools=tools,
   )
   # check the model response
   print(response)
   

6. After OpenAI returns a response, invoke the Unity Catalog function call to generate the response answer back to OpenAI.

   import json
   
   # OpenAI sends only a single request per tool call
   tool_call = response.choices[0].message.tool_calls[0]
   # Extract arguments that the Unity Catalog function needs to run
   arguments = json.loads(tool_call.function.arguments)
   
   # Run the function based on the arguments
   result = client.execute_function(func_name, arguments)
   print(result.value)
   

7. Once the answer has been returned, you can construct the response payload for subsequent calls to OpenAI.

   # Create a message containing the result of the function call
   function_call_result_message = {
     "role": "tool",
     "content": json.dumps({"content": result.value}),
     "tool_call_id": tool_call.id,
   }
   assistant_message = response.choices[0].message.to_dict()
   completion_payload = {
     "model": "gpt-4o-mini",
     "messages": [*messages, assistant_message, function_call_result_message],
   }
   
   # Generate final response
   openai.chat.completions.create(
     model=completion_payload["model"], messages=completion_payload["messages"]
   )
   

Utilities

To simplify the process of crafting the tool response, the ucai-openai package has a utility, generate_tool_call_messages, that converts OpenAI ChatCompletion response messages so that they can be used for response generation.

from unitycatalog.ai.openai.utils import generate_tool_call_messages

messages = generate_tool_call_messages(response=response, client=client)
print(messages)

Anthropic

Use Azure Databricks Unity Catalog to integrate SQL and Python functions as tools in Anthropic SDK LLM calls. This integration combines the governance of Unity Catalog with Anthropic models to create powerful AI apps.

1. Install the Databricks Unity Catalog integration package for Anthropic.

   %pip install unitycatalog-anthropic[databricks]
   dbutils.library.restartPython()
   

2. Create an instance of the Unity Catalog functions client.

   from unitycatalog.ai.core.base import get_uc_function_client
   
   client = get_uc_function_client()
   

3. Create a Unity Catalog function written in Python.

   CATALOG = "your_catalog"
   SCHEMA = "your_schema"
   
   func_name = f"{CATALOG}.{SCHEMA}.weather_function"
   
   def weather_function(location: str) -> str:
     """
     Fetches the current weather from a given location in degrees Celsius.
   
     Args:
       location (str): The location to fetch the current weather from.
     Returns:
       str: The current temperature for the location provided in Celsius.
     """
     return f"The current temperature for {location} is 24.5 celsius"
   
   client.create_python_function(
     func=weather_function,
     catalog=CATALOG,
     schema=SCHEMA,
     replace=True
   )
   

4. Create an instance of the Unity Catalog function as a toolkit.

   from unitycatalog.ai.anthropic.toolkit import UCFunctionToolkit
   
   # Create an instance of the toolkit
   toolkit = UCFunctionToolkit(function_names=[func_name], client=client)
   

5. Use a tool call in Anthropic.

   import anthropic
   
   # Initialize the Anthropic client with your API key
   anthropic_client = anthropic.Anthropic(api_key="YOUR_ANTHROPIC_API_KEY")
   
   # User's question
   question = [{"role": "user", "content": "What's the weather in New York City?"}]
   
   # Make the initial call to Anthropic
   response = anthropic_client.messages.create(
     model="claude-3-5-sonnet-20240620",  # Specify the model
     max_tokens=1024,  # Use 'max_tokens' instead of 'max_tokens_to_sample'
     tools=toolkit.tools,
     messages=question  # Provide the conversation history
   )
   
   # Print the response content
   print(response)
   

6. Construct a tool response. The response from the Claude model contains a tool request metadata block if a tool needs to be called.

   from unitycatalog.ai.anthropic.utils import generate_tool_call_messages
   
   # Call the UC function and construct the required formatted response
   tool_messages = generate_tool_call_messages(
     response=response,
     client=client,
     conversation_history=question
   )
   
   # Continue the conversation with Anthropic
   tool_response = anthropic_client.messages.create(
     model="claude-3-5-sonnet-20240620",
     max_tokens=1024,
     tools=toolkit.tools,
     messages=tool_messages,
   )
   
   print(tool_response)
   

The unitycatalog.ai-anthropic package includes a message handler utility to simplify the parsing and handling of a call to the Unity Catalog function. The utility does the following:

1. Detects tool calling requirements.
2. Extracts tool calling information from the query.
3. Performs the call to the Unity Catalog function.
4. Parses the response from the Unity Catalog function.
5. Craft the next message format to continue the conversation with Claude.

Improve tool-calling with clear documentation

Good documentation helps your agents know when and how to use each tool. Follow these best practices for documenting your tools:

• For Unity Catalog functions, use the COMMENT clause to describe tool functionality and parameters.
• Clearly define expected inputs and outputs.
• Write meaningful descriptions to make tools easier for agents, and humans, to use.

Example: Effective tool documentation

The following example shows clear COMMENT strings for a tool that queries a structured table.

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;

Example: Ineffective tool documentation

The following example lacks important details, making it harder for agents to use the tool effectively:

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;

Run functions using serverless or local mode

When an AI service determines a tool call is needed, integration packages (UCFunctionToolkit instances) run the DatabricksFunctionClient.execute_function API.

The execute_function call can run functions in two execution modes: serverless or local. This mode determines which resource runs the function.

Serverless mode for production

Serverless mode is the default and recommended option for production use cases when executing Unity Catalog functions as agent tools. This mode uses serverless generic compute (Spark Connect serverless) to execute functions remotely, and Lakeguard ensures that your agent's process remains secure and free from the risks of running arbitrary code locally.

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

When your agent requests a tool execution in serverless mode, the following happens:

1. The DatabricksFunctionClient sends a request to Unity Catalog to retrieve the function definition if the definition has not been locally cached.
2. The DatabricksFunctionClient extracts the function definition and validates the parameter names and types.
3. The DatabricksFunctionClient submits the execution as a UDF to serverless generic compute.

Local mode for development

Local mode executes Python functions in a local subprocess instead of making requests to serverless generic compute. This allows you to troubleshoot tool calls more effectively by providing local stack traces. It is designed for developing and debugging Python Unity Catalog functions.

When your agent requests running a tool in local mode, the DatabricksFunctionClient does the following:

1. Sends a request to Unity Catalog to retrieve the function definition if the definition has not been locally cached.
2. Extracts the Python callable definition, caches the callable locally, and validates the parameter names and types.
3. Invokes the callable with the specified parameters in a restricted subprocess with timeout protection.

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

Running in "local" mode provides the following features:

• CPU time limit: Restricts the total CPU runtime for callable execution to prevent excessive computational loads.

  The CPU time limit is based on actual CPU usage, not wall-clock time. Due to system scheduling and concurrent processes, CPU time can exceed wall-clock time in real-world scenarios.

• Memory limit: Restricts the virtual memory allocated to the process.

• Timeout protection: Enforces a total wall-clock timeout for running functions.

Customize these limits using environment variables (read further).

Local mode limitations

• Python functions only: SQL-based functions are not supported in local mode.
• Security considerations for untrusted code: While local mode runs functions in a subprocess for process isolation, there is a potential security risk when executing arbitrary code generated by AI systems. This is primarily a concern when functions execute dynamically generated Python code that hasn't been reviewed.
• Library version differences: Library versions may differ between serverless and local execution environments, which could lead to different function behavior.

Environment variables

Configure how functions run in the DatabricksFunctionClient using the following environment variables:

Call external APIs with http_request (legacy)

You can create a Unity Catalog function that wraps http_request() to call external services from SQL-based tool definitions. This approach remains supported but is no longer recommended for new integrations. For the walkthrough, including the SQL example and connection-type limitations, see Wrap http_request() in a Unity Catalog function.

Example notebooks

The following notebooks demonstrate creating agent tools that connect to external services using Unity Catalog functions.

Slack messaging agent tool

Get notebook

Microsoft Graph API agent tool

Get notebook

Azure AI Search agent tool

Get notebook

Next steps

• Add Unity Catalog tools to agents programmatically. See Author an agent and deploy it on Databricks Apps.

• Add Unity Catalog tools to agents using the AI Playground UI. See Get started: Query LLMs and prototype agents with no code.

• Manage Unity Catalog functions using the Function Client. See Unity Catalog documentation - Function client

• Connect agents to tools with MCP Services for an overview of all approaches to connect agents to external services.