Создание агента ИИ и его развертывание в Приложениях Databricks

Создайте агент ИИ и разверните его с помощью Databricks Apps. Databricks Apps обеспечивает полный контроль над кодом агента, конфигурацией сервера и рабочим процессом развертывания. Этот подход идеально подходит, если требуется настраиваемое поведение сервера, версии на основе Git или локальная среда разработки.

Каждый шаблон разговорного агента включает встроенный пользовательский интерфейс чата (показан выше) без необходимости дополнительной настройки. Пользовательский интерфейс чата поддерживает потоковые ответы, рендеринг markdown, аутентификацию Databricks и необязательное сохранение истории чата.

Требования

Включите Приложения Databricks в рабочей области. См. статью "Настройка рабочей области Databricks Apps" и среды разработки.

Шаг 1. Клонирование шаблона приложения агента

Начните с использования готового шаблона агента из репозитория шаблонов приложений Databricks.

В этом руководстве используется шаблон agent-openai-agents-sdk, который включает:

• Агент, созданный с помощью пакета SDK агента OpenAI
• Стартовый код для приложения агента с REST API для общения и интерактивного интерфейса чата
• Код для оценки агента с помощью MLflow

Выберите один из следующих путей для настройки шаблона:

Пользовательский интерфейс рабочей области

Установите шаблон приложения с помощью пользовательского интерфейса рабочей области. Это устанавливает приложение и развертывает его в вычислительном ресурсе в рабочей области. Затем вы можете синхронизировать файлы приложений с локальной средой для дальнейшего развития.

1. В рабочей области Databricks нажмите кнопку +Создать>приложение.

2. Щелкните Агенты>Настраиваемый агент (пакет SDK OpenAI).

3. Создайте новый эксперимент MLflow с именем openai-agents-template и завершите оставшуюся часть настройки для установки шаблона.

4. После создания приложения щелкните URL-адрес приложения, чтобы открыть пользовательский интерфейс чата.

После создания приложения скачайте исходный код на локальный компьютер, чтобы настроить его:

1. Скопируйте первую команду в разделе "Синхронизация файлов"

   

2. В локальном терминале выполните скопированную команду.

Клонирование из GitHub

Чтобы начать работу с локальной среды, клонируйте репозиторий agent-openai-agents-sdk шаблонов агента и откройте каталог:

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk

Шаг 2. Понять приложение агента

Шаблон агента демонстрирует рабочую архитектуру с этими ключевыми компонентами. Дополнительные сведения о каждом компоненте см. в следующих разделах:

Дополнительные сведения о каждом компоненте см. в следующих разделах:

Встроенный пользовательский интерфейс чата

Шаблон агента автоматически извлекает и запускает шаблон приложения чата в качестве внешнего интерфейса. Этот интерфейс чата упакован в то же развертывание приложений Databricks и обслуживается вместе с вашим агентом, поэтому дополнительная настройка не требуется.

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

MLflow AgentServer

Асинхронный сервер FastAPI, обрабатывающий запросы агента со встроенной трассировкой и наблюдаемостью. AgentServer предоставляет конечную точку /responses для запроса агента и автоматически управляет маршрутизацией запросов, ведением журнала и обработкой ошибок.

ResponsesAgent Интерфейс

Databricks рекомендует использовать MLflow ResponsesAgent для создания агентов. ResponsesAgent позволяет создавать агенты с любой сторонней платформой, а затем интегрировать ее с функциями ИИ Databricks для надежного ведения журнала, трассировки, оценки, развертывания и мониторинга.

См. примеры по созданию ResponsesAgent в документации MLflow — ResponsesAgent для обслуживания моделей.

ResponsesAgent предоставляет следующие преимущества:

• Расширенные возможности агента

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

• Оптимизация разработки, развертывания и мониторинга

  • Создание агентов с помощью любой платформы: обертывание любого существующего агента с помощью ResponsesAgent интерфейса для обеспечения совместимости с ИИ-площадкой, оценкой агента и мониторингом агентов.
  • Интерфейсы разработки с типизацией: создание кода агента с использованием типизированных классов Python, что позволяет использовать преимущества автозаполнения в записных книжках и интегрированной среды разработки.
  • Автоматическая трассировка: MLflow автоматически агрегирует потоковые ответы в трассировках для упрощения оценки и отображения.
  • Совместимо со схемой OpenAIResponses: См. OpenAI: Ответы против ChatCompletion.

Пакет SDK для агентов OpenAI

Шаблон использует пакет SDK для агентов OpenAI в качестве фреймворка агентов для управления беседами и управления инструментами. Вы можете создавать агенты с помощью любой платформы. Ключ заключается в обёртывании вашего агента с помощью интерфейса MLflow ResponsesAgent.

Серверы MCP (протокол контекста модели)

Шаблон подключается к серверам Databricks MCP, чтобы предоставить агентам доступ к средствам и источникам данных. См. протокол контекста модели (MCP) в Databricks.

Создание агентов с помощью помощников по написанию кода ИИ

Databricks рекомендует использовать помощников по программированию на основе ИИ, таких как Claude, Cursor и Copilot, для создания агентов. Используйте предоставленные навыки агента и /.claude/skillsAGENTS.md файл, чтобы помочь помощникам ИИ понять структуру проекта, доступные инструменты и рекомендации. Агенты могут автоматически считывать эти файлы для разработки и развертывания приложений Databricks.

Шаг 3. Добавьте инструменты вашему агенту

Предоставьте своим агентам такие возможности, как запросы к базам данных, поиск документов или вызов внешних API путем подключения к серверам MCP. Шаблон агента включает подключение сервера MCP по умолчанию. Чтобы добавить дополнительные средства, настройте дополнительные серверы MCP в коде агента и предоставьте необходимые разрешения.databricks.yml

Ознакомьтесь с инструментами агента ИИ для поддерживаемых типов инструментов и примеров кода.

Определите инструменты локальной функции Python

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

Пакет SDK для агентов OpenAI

@function_tool Используйте декоратор из пакета SDK для агентов OpenAI:

from agents import Agent, function_tool

@function_tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time],
)

LangGraph

Используйте декоратор @tool из LangChain.

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from databricks_langchain import ChatDatabricks

@tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=[get_current_time],
)

Локальные средства функций не требуют предоставления ресурсов, databricks.yml так как они выполняются в процессе агента.

Шаг 4. Управляйте использованием LLM вашими агентами в приложениях Databricks с помощью шлюза Unity AI Gateway.

Перенаправьте вызовы LLM агента через шлюз ИИ (бета-версия), поэтому каждый запрос управляется теми же элементами управления независимо от того, какой поставщик отвечает на него. С помощью шлюза в пути запроса можно централизировать разрешения, распределение затрат для каждого приложения, смену моделей и инспекцию или воспроизведение трафика без изменения кода агента или обновления или ротации учетных данных поставщика.

1. Включите шлюз искусственного интеллекта в рабочей области. Шлюз искусственного интеллекта доступен для выбора в бета-версии. Администратор учетной записи должен включить эту функцию на странице Предварительные версии консоли учетной записи, прежде чем создавать или запрашивать конечные точки шлюза. См. статью "Управление предварительными версиями Azure Databricks".

2. Укажите вашему агенту конечную точку шлюза ИИ. В коде агента передайте имя конечной точки шлюза ИИ в качестве аргумента model и задайте use_ai_gateway=True на клиенте LLM Azure Databricks. Клиент направляет трафик через шлюз и автоматически обрабатывает проверку подлинности.

   OpenAI

   from agents import Agent, set_default_openai_api, set_default_openai_client
   from databricks_openai import AsyncDatabricksOpenAI
   
   set_default_openai_client(AsyncDatabricksOpenAI(use_ai_gateway=True))
   set_default_openai_api("chat_completions")
   
   agent = Agent(
       name="Agent",
       instructions="You are a helpful assistant.",
       model="<ai-gateway-endpoint>",
   )
   

   LangGraph

   from databricks_langchain import ChatDatabricks
   
   llm = ChatDatabricks(
       model="<ai-gateway-endpoint>",
       use_ai_gateway=True,
   )
   

   Дополнительные поверхности API (API OpenAI Responses, API сообщений Anthropic, Google Gemini) и примеры REST см. в Конечные точки шлюза ИИ Query Unity.

Разделы расширенной разработки

{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}

Шаг 5. Локальное запуск приложения агента

Настройте локальную среду:

1. Установите uv (диспетчер пакетов Python), nvm (диспетчер версий узла) и cli Databricks:

   • uv Установка
   • nvm Установка
   • Выполните следующую команду, чтобы использовать узел 20 LTS:

     nvm use 20
     

   • databricks CLI Установка

2. Измените каталог на папку agent-openai-agents-sdk .

3. Запустите предоставленные скрипты быстрого запуска, чтобы установить зависимости, настроить среду и запустить приложение.

   uv run quickstart
   uv run start-app
   

В браузере перейдите на http://localhost:8000, чтобы открыть встроенный интерфейс чата и начать чат с агентом.

Шаг 6. Настройка проверки подлинности

Агенту требуется проверка подлинности для доступа к ресурсам Azure Databricks. Databricks Apps предоставляет два метода проверки подлинности: авторизация приложений (субъект-служба) и авторизация пользователей (от имени пользователя). Вы можете настроить любой из них через пользовательский интерфейс рабочей области или декларативно в databricks.yml с помощью пакетов декларативной автоматизации. Шаблоны агентов поставляются с databricks.yml, так что этот путь используется по умолчанию при запуске от шаблона.

Полный справочник, включая все поддерживаемые типы ресурсов, значения разрешений и сквозное databricks.yml пошаговое руководство, см. в разделе "Проверка подлинности для агентов ИИ".

Авторизация приложений (по умолчанию)

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

Объявите каждый ресурс, который агент использует в resources.apps.<app>.resourcesdatabricks.yml. Разверните пакет, чтобы предоставить субъекту-службе объявленные разрешения:

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_TRACKING_URI
            value: 'databricks'
          - name: MLFLOW_REGISTRY_URI
            value: 'databricks-uc'
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'
        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Полный список типов ресурсов см. в разделе "Авторизация приложений".

Авторизация пользователей

Авторизация пользователя позволяет агенту действовать с отдельными разрешениями каждого пользователя. Используйте это, если требуется управление доступом на уровне пользователей или аудиторские журналы.

Добавьте этот код в агент:

from agent_server.utils import get_user_workspace_client

# In your agent code (inside @invoke or @stream)
user_workspace = get_user_workspace_client()

# Access resources with the user's permissions
response = user_workspace.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Настройте, какие API-интерфейсы Azure Databricks агент может вызывать от имени пользователя, добавив сферы действий в user_api_scopes в приложении под databricks.yml.

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Список доступных областей и полные инструкции по настройке см. в разделе "Авторизация пользователей".

Шаг 7. Оценка агента

Шаблон содержит код оценки агента. См. agent_server/evaluate_agent.py для получения дополнительной информации. Оцените релевантность и безопасность ответов агента, выполнив следующие действия в терминале:

uv run agent-evaluate

Шаг 8. Разверните агента в приложениях Databricks

После настройки проверки подлинности разверните агент в Azure Databricks. Шаблоны агентов используют пакеты ресурсов Databricks (DAB) для развертывания. Файл databricks.yml в шаблоне определяет конфигурацию приложения и разрешения ресурсов. Убедитесь, что у вас установлен и настроен интерфейс командной строки Databricks .

1. Проверьте конфигурацию пакета для перехвата ошибок перед развертыванием:

   databricks bundle validate
   

2. Разверните пакет. Это отправляет код и настраивает ресурсы (эксперимент MLflow, обслуживание конечных точек и т. д.), определенные в databricks.yml:

   databricks bundle deploy
   

3. Запустите или перезапустите приложение:

   databricks bundle run agent_openai_agents_sdk
   

   Заметка

   bundle deploy отправляет только файлы и настраивает ресурсы. bundle run необходимо для запуска или перезапуска приложения с новым кодом.

Для будущих обновлений запустите databricks bundle deploy, а затем повторно разверните databricks bundle run agent_openai_agents_sdk.

Шаг 9. Запрос развернутого агента

В следующем примере используется быстрый curl запрос с маркером OAuth. Персональные токены доступа (PATs) не поддерживаются для приложений Databricks.

Полный список методов запроса, включая клиент Databricks OpenAI и REST API, см. раздел Запросите агента, развернутого на Azure Databricks.

Создайте маркер OAuth с помощью интерфейса командной строки Databricks:

databricks auth login --host <https://host.databricks.com>
databricks auth token

Используйте маркер для запроса агента:

curl -X POST <app-url.databricksapps.com>/responses \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

Ограничения

• Поддерживаются только средние и большие размеры вычислений. См. Настройка вычислительных ресурсов для приложения Databricks.
• В настоящее время пользовательский интерфейс чата проверки MLflow не поддерживает агенты, развернутые в приложениях Databricks. Чтобы оценить существующие трассировки, используйте сеансы маркировки, которые работают независимо от метода развертывания. Databricks создает поддержку отзывов и обратной связи прямо в шаблон чат-бота.

Дальнейшие действия

• Проведите нагрузочное тестирование агента приложений Databricks