Создание средств агента ИИ с помощью функций каталога Unity

Используйте функции каталога Unity для создания средств агента ИИ, которые выполняют пользовательскую логику и выполняют определенные задачи, расширяющие возможности LLM за пределами создания языка.

Когда следует использовать функции каталога Unity и серверы MCP

Databricks рекомендует использовать функции каталога Unity в качестве средств агента специально для структурированных средств извлечения данных, когда запрос известен заранее, а агент предоставляет параметры. См. статью "Подключение агентов к структурированным данным".

В большинстве других вариантов использования Databricks рекомендует серверы MCP или определять логику непосредственно в коде агента для ускорения выполнения, поддержки проверки подлинности на пользователя и дополнительной гибкости.

Требования

Чтобы создать и использовать функции каталога Unity в качестве средств агента ИИ, вам потребуется следующее:

• Databricks Runtime: используйте Databricks Runtime 15.0 и более поздних версий
• версия Python: установите Python 3.10 или более поздней

Выполнение функций каталога Unity:

• Бессерверные вычисления должны быть включены в рабочей области для выполнения функций каталога Unity в качестве средств агента ИИ в рабочей среде. См. требования к бессерверным вычислениям.
  • Локальный режим выполнения для функций Python не требует выполнения бессерверных универсальных вычислений, однако локальный режим предназначен только для целей разработки и тестирования.

Чтобы создать функции каталога Unity, выполните приведенные действия.

• Бессерверные универсальные вычисления должны быть включены в рабочей области для создания функций с помощью инструкций Databricks Workspace Client или sql body.
  • Python функции можно создавать без бессерверных вычислений.

Создайте инструмент функции Unity Catalog

Ниже показано, как создать и проверить функцию каталога Unity. Выполните следующий код в записной книжке Databricks.

Установка зависимостей

Установите пакеты ИИ каталога Unity с дополнительными [databricks] .

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

dbutils.library.restartPython()

Инициализация клиента функции Databricks

Инициализируйте клиент функции Databricks, который является специализированным интерфейсом для создания, управления и выполнения функций в Unity Catalog на платформе Databricks.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Определение логики средства

Средства каталога Unity на самом деле являются определяемыми пользователем функциями каталога Unity (UDF). При определении средства каталога Unity вы регистрируете функцию в каталоге Unity. Чтобы узнать больше об определяемых пользователем функциях (UDF) в каталоге Unity, см. раздел "Определяемые пользователем функции (UDF) в каталоге Unity".

Вы можете создать функции каталога Unity с помощью одного из двух API:

• create_python_function принимает вызываемый Python.
• create_function принимает инструкцию создания функции в тексте SQL. См. раздел Create Python функций.

create_python_function Используйте API для создания функции.

Чтобы сделать вызываемую Python распознаваемой в модели данных функций каталога Unity, ваша функция должна соответствовать следующим требованиям:

• Type hints: сигнатура функции должна определять допустимые указания типов Python. У именованных аргументов и возвращаемого значения должны быть определены их типы.
• Не используйте аргументы переменной: аргументы переменной, такие как *args и **kwargs, не поддерживаются. Все аргументы должны быть явно определены.
• Совместимость типов: Не все типы Python поддерживаются в SQL. См. поддерживаемые типы данных Spark.
• Описательные строковые литералы: инструментарий функций каталога Unity читает, анализирует и извлекает важные сведения из строк документации.
  • Докстринги должны быть отформатированы в соответствии с синтаксисом документации Google.
  • Напишите четкие описания для функции и его аргументов, чтобы помочь LLM понять, как и когда использовать функцию.
• Импорт зависимостей: библиотеки должны быть импортированы в текст функции. Импорт за пределами функции не будет разрешен при запуске средства.

Следующие фрагменты кода используют create_python_function для регистрации вызываемого Python 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
)

Проверка функции

Проверьте вашу функцию, чтобы убедиться, что она работает как ожидается. Укажите полное имя функции в execute_function API для запуска функции:

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'

Добавьте функции каталога Unity в ваш агент

После создания и тестирования функции Unity Catalog выберите один из следующих подходов, чтобы добавить её в агент.

Использование MCP (рекомендуется)

Использование MCP (рекомендуется)

Databricks рекомендует использовать серверы MCP для добавления функций каталога Unity в агент. Подход MCP обеспечивает более простую интеграцию с автоматическим обнаружением инструментов и встроенной поддержкой проверки подлинности.

Управляемый URL-адрес MCP для функций каталога Unity: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}. При необходимости можно указать определенную функцию, добавив /{function_name}.

В следующих примерах показано, как подключить агент к функциям каталога Unity через MCP. Замените <catalog> и <schema> местоположением ваших функций.

Пакет SDK для агентов OpenAI (приложения)

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)

Предоставьте приложению доступ к функции каталога Unity в 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 (приложения)

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)

Предоставьте приложению доступ к функции каталога Unity в 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'

Обслуживание моделей

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(),
)

Сведения о развертывании агента см. в статье "Развертывание агента для создания приложений ИИ (обслуживание моделей)". Дополнительные сведения об агентах ведения журнала с ресурсами MCP см. в разделе "Использование управляемых серверов MCP Databricks".

Использование UCFunctionToolkit

Использование UCFunctionToolkit

В этом примере используется LangChain, но аналогичный подход можно применить к другим библиотекам. См. статью "Интеграция средств каталога Unity" с сторонними платформами искусственного интеллекта.

Установка дополнительных зависимостей

Установите пакеты интеграции LangChain для UCFunctionToolkit.

%pip install unitycatalog-langchain[databricks]

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

dbutils.library.restartPython()

Оберните функцию с помощью UCFunctionToolKit

Оборачивайте функцию с помощью UCFunctionToolkit, чтобы сделать ее доступной в библиотеках разработки агентов. Набор средств обеспечивает согласованность между различными библиотеками генеративного ИИ и добавляет полезные функции, такие как автопрослеживание для извлекателей.

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

Использовать инструмент в агенте

Добавьте средство в агент LangChain с помощью свойства tools от UCFunctionToolkit.

Замечание

В этом примере используется LangChain. Однако вы можете интегрировать средства каталога Unity с другими платформами, такими как LlamaIndex, OpenAI, Anthropic и многое другое. См. статью "Интеграция средств каталога Unity" с сторонними платформами искусственного интеллекта.

В этом примере создаётся простой агент с использованием API LangChain AgentExecutor для простоты. Для рабочих нагрузок используйте рабочий процесс разработки агента, который рассматривается в разделе "Создание агента ИИ" и его развертывание в Приложениях Databricks.

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

Улучшите использование инструментов с помощью четкой документации

Хорошая документация помогает агентам знать, когда и как использовать каждое средство. Следуйте приведенным ниже рекомендациям по документированию инструментов.

• Для функций каталога Unity используйте COMMENT предложение для описания функциональных возможностей и параметров средства.
• Четко определите ожидаемые входные и выходные данные.
• Напишите значимые описания, чтобы упростить использование средств для агентов и людей.

Пример. Документация по эффективному инструменту

В следующем примере показаны четкие COMMENT строки для инструмента, который запрашивает структурированную таблицу.

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;

Пример: документация по неэффективным инструментам

В следующем примере отсутствуют важные сведения, что затрудняет использование средства агентами.

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;

Выполнение функций с помощью бессерверного или локального режима

Когда служба генеративного искусственного интеллекта определяет необходимость вызова инструмента, пакеты интеграции (UCFunctionToolkit экземпляры) запускают DatabricksFunctionClient.execute_function API.

Вызов execute_function может выполнять функции в двух режимах выполнения: бессерверных или локальных. Этот режим определяет, какой ресурс запускает функцию.

Бессерверный режим для рабочей среды

Бессерверный режим — это стандартный и рекомендуемый вариант для рабочих вариантов использования при выполнении функций каталога Unity в качестве средств агента ИИ. Этот режим использует бессерверные универсальные вычислительные ресурсы (Spark Connect без сервера) для удаленного выполнения функций, и Lakeguard гарантирует, что процесс агента остается безопасным и свободным от рисков выполнения произвольного кода локально.

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

Когда агент запрашивает выполнение средства в бессерверном режиме, происходит следующее:

1. Он DatabricksFunctionClient отправляет запрос в каталог Unity, чтобы получить определение функции, если определение не было локально кэшировано.
2. Модуль DatabricksFunctionClient извлекает определение функции и проверяет имена и типы параметров.
3. Объект DatabricksFunctionClient отправляет выполнение в виде UDF в бессерверные универсальные вычислительные ресурсы.

Локальный режим разработки

Локальный режим выполняет функции Python в локальном подпроцессе вместо отправки запросов к бессерверным общим вычислительным ресурсам. Это позволяет более эффективно устранять неполадки вызовов инструментов, предоставляя локальные трассировки стека. Он предназначен для разработки и отладки Python функций каталога Unity.

Когда агент запрашивает средство в локальном режиме, DatabricksFunctionClient выполняет следующие действия.

1. Отправляет запрос в каталог Unity, чтобы получить определение функции, если определение не было локально кэшировано.
2. Извлекает вызываемое определение Python, кэширует вызываемый объект локально и проверяет имена и типы параметров.
3. Вызывает функцию с указанными параметрами в ограниченном дочернем процессе с защитой от превышения времени ожидания.

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

Использование режима "local" предоставляет следующие функции.

• Ограничение времени ЦП: Ограничивает общую среду выполнения ЦП для вызываемого выполнения, чтобы предотвратить чрезмерные вычислительные нагрузки.

  Ограничение времени ЦП основано на фактическом использовании ЦП, а не на временном времени. Из-за системного планирования и параллельных процессов время центрального процессора может превышать время по реальным часам в реальных сценариях.

• Ограничение памяти: Ограничивает виртуальную память, выделенную для процесса.

• Защита от превышения времени: Устанавливает общее время ожидания по внутренним часам для выполнения функций.

Настройте эти ограничения с помощью переменных среды (см. дополнительные сведения).

Ограничения локального режима

• Только функции Python: функции на основе SQL не поддерживаются в локальном режиме.
• Вопросы безопасности для ненадежного кода. Хотя локальный режим выполняет функции в подпроцессе для изоляции процесса, при выполнении произвольного кода, созданного системами ИИ, может возникнуть риск безопасности. Это в первую очередь проблема, когда функции выполняют динамически созданные Python коде, который не был проверен.
• Различия версий библиотеки: версии библиотеки могут отличаться между бессерверными и локальными средами выполнения, что может привести к различным функциям.

Переменные среды

Настройте, как функции выполняются в DatabricksFunctionClient, используя следующие переменные среды:

Примеры записных книжек

В следующих записных книжках показано создание средств агента ИИ, которые подключаются к внешним службам с помощью функций каталога Unity.

Средство агента обмена сообщениями Slack

Получите ноутбук

Инструмент агента Microsoft Graph API

Получите ноутбук

агентское средство Azure AI Search

Получите ноутбук

Дальнейшие шаги

• Добавьте средства каталога Unity в агенты программным способом. См . статью "Создание агента ИИ" и его развертывание в приложениях Databricks.

• Добавьте средства каталога Unity в агенты посредством пользовательского интерфейса платформы AI Playground. См. Начало работы: создавайте запросы LLM и прототипы агентов ИИ бескодовыми средствами.

• Управление функциями каталога Unity с помощью клиента-функции. См. документацию по каталогу Unity — клиент-функция

• Подключение агентов к внешним службам для обзора всех подходов к подключению агентов к внешним службам.