Начало работы с агентами ИИ

2025-05-14

Создайте вашего первого агента ИИ с помощью Платформы агента ИИ Mosaic. В этом руководстве описано следующее:

Создание агента с помощью Agent Framework.
Добавьте инструмент для вашего агента.
Разверните агент в конечной точке обслуживания модели Databricks.

Общие сведения об агентах и других приложениях ИИ поколения см. в статье "Что такое приложения ИИ поколения"?

Требования

Рабочая область должна иметь следующие функции:

Каталог Unity
Фреймворк агента ИИ Mosaic
Базовые модели (оплата за токен, подготовленную пропускную способность или внешние модели). См. Функции с ограниченной региональной доступностью

пример записной книжки

Эта записная книжка содержит весь код, необходимый для создания и развертывания первого агента ИИ. Импортируйте записную книжку в рабочую область Azure Databricks, чтобы её запустить.

Демонстрация агента ИИ Mosaic

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

Определение агента

Агент ИИ состоит из следующих элементов:

Большая языковая модель (LLM), которая может рассуждать и принимать решения
Инструменты, которые LLM может использовать не только для создания текста, но и для выполнения кода Python или получения данных.

Выполните следующий код в записной книжке Databricks, чтобы определить простой агент вызова инструментов:

Установите необходимые пакеты Python:
```
%pip install -U -qqqq mlflow databricks-openai databricks-agents
dbutils.library.restartPython()
```
- mlflow: используется для разработки и отслеживания агентов.
- databricks-openai: используется для подключения к LLM, размещенной на Databricks.
- databricks-agent: используется для упаковки и развертывания агента.

Определите агент. В этом фрагменте кода выполняется следующее:

Подключается к конечной точке обслуживания модели Databricks с помощью клиента OpenAI.
Включает трассировку MLflow с помощью autolog(). Это добавляет инструменты мониторинга, чтобы вы могли видеть, как агент выполняет свои задачи при запросе.
Добавляет инструмент system.ai.python_exec вашему агенту. Эта встроенная функция каталога Unity позволяет агенту запускать код Python.
Определяется функция, которая взаимодействует с LLM через запрос и обрабатывает ответы.

import mlflow
import json
from databricks.sdk import WorkspaceClient
from databricks_openai import UCFunctionToolkit, DatabricksFunctionClient

# Get an OpenAI client configured to connect to Databricks model serving endpoints
# Use this client to query the LLM
openai_client = WorkspaceClient().serving_endpoints.get_open_ai_client()

# Enable automatic tracing for easier debugging
mlflow.openai.autolog()

# Load Databricks built-in tools (Python code interpreter)
client = DatabricksFunctionClient()
builtin_tools = UCFunctionToolkit(function_names=["system.ai.python_exec"], client=client).tools
for tool in builtin_tools:
  del tool["function"]["strict"]


def call_tool(tool_name, parameters):
  if tool_name == "system__ai__python_exec":
    return DatabricksFunctionClient().execute_function("system.ai.python_exec", parameters=parameters)
  raise ValueError(f"Unknown tool: {tool_name}")

def run_agent(prompt):
  """
  Send a user prompt to the LLM and return a list of LLM response messages
  The LLM is allowed to call the code interpreter tool, if needed, to respond to the user
  """
  result_msgs = []
  response = openai_client.chat.completions.create(
    model="databricks-claude-3-7-sonnet",
    messages=[{"role": "user", "content": prompt}],
    tools=builtin_tools,
  )
  msg = response.choices[0].message
  result_msgs.append(msg.to_dict())

  # If the model executed a tool, call it
  if msg.tool_calls:
    call = msg.tool_calls[0]
    tool_result = call_tool(call.function.name, json.loads(call.function.arguments))
    result_msgs.append({"role": "tool", "content": tool_result.value, "name": call.function.name, "tool_call_id": call.id})
  return result_msgs

Тестирование агента

Протестируйте агент, запросив его с помощью запроса, требующего выполнения кода Python:

answer = run_agent("What is the 100th fibonacci number?")
for message in answer:
  print(f'{message["role"]}: {message["content"]}')

Помимо выходных данных LLM, вы увидите подробные сведения о трассировке непосредственно в вашей рабочей тетради. Эти следы помогают отлаживать медленные или неудачные вызовы агента. Эти следы были автоматически добавлены с помощью mlflow.openai.autolog() .

Развертывание агента

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

Подготовка кода агента для развертывания

Чтобы подготовить код агента к развертыванию, оберните его, используя интерфейс MLflow ChatAgent. Интерфейс ChatAgent — это рекомендуемый способ упаковки агентов для развертывания в Azure Databricks.

Чтобы реализовать ChatAgent интерфейс, необходимо определить predict() функцию, которая отправляет пользователю сообщение агенту, собирает ответ агента и возвращает его в ChatAgentResponses формате.

import uuid
from typing import Any, Optional

from mlflow.pyfunc import ChatAgent
from mlflow.types.agent import ChatAgentMessage, ChatAgentResponse, ChatContext

class QuickstartAgent(ChatAgent):
  def predict(
    self,
    messages: list[ChatAgentMessage],
    context: Optional[ChatContext] = None,
    custom_inputs: Optional[dict[str, Any]] = None,
  ) -> ChatAgentResponse:
    # 1. Extract the last user prompt from the input messages
    prompt = messages[-1].content

    # 2. Call run_agent to get back a list of response messages
    raw_msgs = run_agent(prompt)

    # 3. Map each response message into a ChatAgentMessage and return
    # the response
    out = []
    for m in raw_msgs:
      out.append(ChatAgentMessage(
        id=uuid.uuid4().hex,
        **m
      ))

    return ChatAgentResponse(messages=out)

Добавьте следующий код в записную книжку для тестирования ChatAgent класса:

AGENT = QuickstartAgent()
for response_message in AGENT.predict({"messages": [{"role": "user", "content": "What's the 100th fibonacci number?"}]}).messages:
  print(f"role: {response_message.role}, content: {response_message.content}")

Объедините весь код агента в один файл, чтобы вы могли регистрировать и развертывать его.

Консолидируйте весь код агента в одну ячейку блокнота.
В верхней части ячейки добавьте магическую %%writefile quickstart_agent.py команду, чтобы сохранить агент в файле.
В нижней части ячейки вызовите объект агента с помощью mlflow.models.set_model(). Это сообщает MLflow, какой объект агента следует использовать при обслуживании прогнозов. Этот шаг эффективно настраивает точку входа в код агента.

Ячейка записной книжки должна выглядеть следующим образом:

%%writefile quickstart_agent.py

import json
import uuid
from databricks.sdk import WorkspaceClient
from databricks_openai import UCFunctionToolkit, DatabricksFunctionClient
from typing import Any, Optional

import mlflow
from mlflow.pyfunc import ChatAgent
from mlflow.types.agent import ChatAgentMessage, ChatAgentResponse, ChatContext

# Add an mlflow.openai.autolog() call to capture traces in the serving endpoint

# Get an OpenAI client configured to talk to Databricks model serving endpoints
# We'll use this to query an LLM in our agent
openai_client = WorkspaceClient().serving_endpoints.get_open_ai_client()

# Load Databricks built-in tools (a stateless Python code interpreter tool)
client = DatabricksFunctionClient()
builtin_tools = UCFunctionToolkit(function_names=["system.ai.python_exec"], client=client).tools
for tool in builtin_tools:
  del tool["function"]["strict"]


def call_tool(tool_name, parameters):
  if tool_name == "system__ai__python_exec":
    return DatabricksFunctionClient().execute_function("system.ai.python_exec", parameters=parameters)
  raise ValueError(f"Unknown tool: {tool_name}")

def run_agent(prompt):
  """
  Send a user prompt to the LLM, and return a list of LLM response messages
  The LLM is allowed to call the code interpreter tool if needed, to respond to the user
  """
  result_msgs = []
  response = openai_client.chat.completions.create(
    model="databricks-claude-3-7-sonnet",
    messages=[{"role": "user", "content": prompt}],
    tools=builtin_tools,
  )
  msg = response.choices[0].message
  result_msgs.append(msg.to_dict())

  # If the model executed a tool, call it
  if msg.tool_calls:
    call = msg.tool_calls[0]
    tool_result = call_tool(call.function.name, json.loads(call.function.arguments))
    result_msgs.append({"role": "tool", "content": tool_result.value, "name": call.function.name, "tool_call_id": call.id})
  return result_msgs

class QuickstartAgent(ChatAgent):
  def predict(
    self,
    messages: list[ChatAgentMessage],
    context: Optional[ChatContext] = None,
    custom_inputs: Optional[dict[str, Any]] = None,
  ) -> ChatAgentResponse:
    prompt = messages[-1].content
    raw_msgs = run_agent(prompt)
    out = []
    for m in raw_msgs:
      out.append(ChatAgentMessage(
        id=uuid.uuid4().hex,
        **m
      ))

    return ChatAgentResponse(messages=out)

AGENT = QuickstartAgent()
mlflow.models.set_model(AGENT)

Захегистрируйте агента

Внесите данные о вашем агенте и зарегистрируйте его в каталоге Unity. Это упаковывает агента и его зависимости в один артефакт для развертывания.

import mlflow
from mlflow.models.resources import DatabricksFunction, DatabricksServingEndpoint
from pkg_resources import get_distribution

# Change the catalog name ("main") and schema name ("default") to register the agent to a different location
registered_model_name = "main.default.quickstart_agent"

# Specify Databricks resources that the agent needs to access.
# This step lets Databricks automatically configure authentication
# so the agent can access these resources when it's deployed.
resources = [
  DatabricksServingEndpoint(endpoint_name="databricks-claude-3-7-sonnet"),
  DatabricksFunction(function_name="system.ai.python_exec"),
]

mlflow.set_registry_uri("databricks-uc")
logged_agent_info = mlflow.pyfunc.log_model(
  artifact_path="agent",
  python_model="quickstart_agent.py",
  extra_pip_requirements=[f"databricks-connect=={get_distribution('databricks-connect').version}"],
  resources=resources,
  registered_model_name=registered_model_name
)

Развертывание агента

Разверните зарегистрированного агента в точке доступа:

from databricks import agents

deployment_info = agents.deploy(
  model_name=registered_model_name, model_version=logged_agent_info.registered_model_version
)

После запуска конечной точки агента вы можете общаться с ним с помощью ИИ-площадки или поделиться им с заинтересованными лицами для получения отзывов.

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

Выберите, куда идти дальше на основе ваших целей:

Измерение и улучшение качества агента. См. краткое руководство по оценке агента.

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

Узнайте, как создавать агенты с помощью других платформ: узнайте, как создавать агенты с помощью популярных библиотек, таких как LangGraph, чистый Python и OpenAI. Смотрите Используйте ChatAgent для создания агентов

Поделиться через

Начало работы с агентами ИИ

Требования

пример записной книжки

Демонстрация агента ИИ Mosaic

Определение агента

Тестирование агента

Развертывание агента

Подготовка кода агента для развертывания

Захегистрируйте агента

Развертывание агента

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

Обратная связь

Дополнительные ресурсы