Краткое руководство. Настройка и запуск демонстрационного агента Agent Framework на Python

В этом кратком руководстве вам предстоит шаг за шагом настроить рабочего агента Python на базе Agent Framework с использованием инструментов, уведомлений и наблюдаемости Agent 365, а также протестировать агента в Agents Playground и Teams.

Prerequisites

  • Если вы планируете использовать Visual Studio Code, у вас должен быть установлен .NET. (Рекомендуется использовать .NET 8.0.)

  • Установленный Python 3.11+

  • Установленный Диспетчер пакетов UV. Установите его в терминале с помощью pip install uv.

  • Зависимости от набора инструментов для создания агентов Microsoft / Agent Framework

    Пример, используемый в руководстве, зависит от библиотек Agent Framework, предоставляемых посредством набора инструментов для создания агентов Microsoft 365 (Microsoft 365 Agents Toolkit, ATK). Эти зависимости будут установлены автоматически, когда вы используете расширение Agents Toolkit в VS Code для создания образца, или вы можете установить пакет вручную с помощью следующей команды:

    uv pip install -e . --prerelease=allow

  • Необходим доступ к GitHub

  • Существующий проект агента ИИ. В этом быстром старте используется пример агента Agent 365 из набора инструментов для создания агентов Microsoft 365, также известного как ATK в VS Code.

  • A365 CLI

  • Аутентификация идентификатора агента

Настройка примера Agent Framework + Python из набора инструментов для создания агентов Microsoft 365

Чтобы все подготовить, установите набор инструментов для создания агентов Microsoft 365 в VS Code, откройте галерею примеров и создайте локальный шаблон Agent Framework + Python, чтобы затем настроить и запустить его. Следующие снимки экрана показывают, что вы будете видеть по мере выполнения шагов.

  1. Откройте Visual Studio Code, затем откройте панель РасширенияCtrl+Shift+X.

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

    Снимок экрана поиска расширения набора инструментов для создания агентов в магазине расширений.

  3. Выберите Набор инструментов для создания агентов Microsoft 365.

  4. Нажмите кнопку Установить.

    VS Code показывает страницу с деталями расширения, похожую на:

    Снимок экрана страницы со сведениями о расширении с кнопками

  5. После установки значок Набор инструментов для создания агентов M365 появляется на левой панели навигации.

  6. Выберите его, чтобы открыть приветственный интерфейс.

    Теперь вы должны увидеть такие варианты, как Создать декларативный агент, Создать новый агент/приложение и Просмотреть образцы, как показано здесь:

    Снимок экрана приветственного представления набора инструментов с вариантами:

  7. Выберите Просмотреть образцы.

  8. Прокрутите список примеров, чтобы найти пример агента Agent Framework + Python.

  9. Выберите это.

    Вы увидите два варианта: Создать (создать локально) или Просмотреть на GitHub.

  10. Выберите Создать.

    Снимок экрана с примером агента Agent Framework с SDK Agent 365, реализованного на Python.

  11. Когда появится запрос, выберите на компьютере папку, в которой должен быть создан пример. Например: C:\A365-python-sample

    Набор инструментов создает пример Agent Framework + Python в подпапке (например, sample_agent) и затем автоматически открывает его в VS Code.

    После завершения создания шаблона у вас на компьютере будет полностью функциональный проект агента Agent Framework + Python

  12. Установите необходимые пакеты Agent 365

    Перед запуском примера откройте файл pyproject.toml в вашем проекте и убедитесь, что все необходимые зависимости Agent 365 и Agent Framework указаны. Сгенерированный с помощью набора инструментов для создания агентов Microsoft 365 пример уже включает эти записи.

    Проверив pyproject.toml, установите все, выполнив следующую команду:

    uv pip install -e . --prerelease=allow

    Эта команда устанавливает все библиотеки SDK Agent 365, зависимости Agent Framework, компоненты размещения и другие зависимости, указанные в примере.

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

    uv run python start_with_generic_host.py

Добавление инструментов Microsoft 365 (серверы MCP)

Вы можете исследовать MCP-серверы и управлять ими с помощью команд разработчика a365 в интерфейсе командной строки.

Когда вы работаете с инструментами Microsoft MCP, вы можете:

  • Узнавать, какие MCP-серверы доступны для использования
  • Добавлять один или несколько MCP-серверов в конфигурацию вашего агента
  • Просматривать настроенные MCP-серверы
  • Удалять MCP-серверы, которые вам больше не нужны

После добавления MCP-серверов манифест инструментов вашего агента расширяется и включает записи, такие как:

{
   "mcpServers": [
      {
         "mcpServerName": "mcp_MailTools",
         "mcpServerUniqueName": "mcp_MailTools",
         "scope": "McpServers.Mail.All",
         "audience": "api://00001111-aaaa-2222-bbbb-3333cccc4444"
      }
   ]
}

Узнайте, как добавлять инструменты и управлять ими

Подписка на уведомления и их обработка

Пример агента подписывается на все уведомления SDK Agent 365 с помощью onAgentNotification("*") и направляет их в единый обработчик. Этот обработчик позволяет агенту реагировать на фоновые или системные события, а не только на прямые сообщения пользователя.

Подробнее о том, как отправлять уведомления агентам

В следующем коде показано, как настроено уведомление в файле agent.py.

if notification_type == NotificationTypes.EMAIL_NOTIFICATION: 
if not hasattr(notification_activity, "email") or not notification_activity.email: return "I could not find the email notification details."
email = notification_activity.email
email_body = getattr(email, "html_body", "") or getattr(email, "body", "")

message = (
    "You have received the following email. "
    "Please follow any instructions in it. "
    f"{email_body}"
)

result = await self.agent.run(message)
return self._extract_result(result) or "Email notification processed."

Observability

Important

Этот выборка использует устаревший SDK Agent 365 Observability. Не используйте этот паттерн для новой интеграции наблюдаемости. Используйте дистрибутив Microsoft OpenTelemetry вместо этого.

Следующий фрагмент показывает устаревшую систему Agent 365 Observability SDK, используемую в этом образце.

В следующем коде показан простой пример реализации наблюдаемости в файле agent.py.

def _enable_agentframework_instrumentation(self): 
"""Enable Agent Framework instrumentation.""" 
try: 
AgentFrameworkInstrumentor().instrument() 
logger.info("✅ Instrumentation enabled")
 except Exception as e: 
logger.warning(f"⚠️ Instrumentation failed: {e}")

Этот код использует устаревшую настройку SDK Agent 365 Observability, необходимую для примера Python + Agent Framework. Для полной настройки и рекомендаций по миграции Microsoft OpenTelemetry см. устаревшую документацию по SDK.

Проверьте своего агента

Задайте необходимые переменные среды, выберите режим аутентификации и запустите агент локально. Вы можете провести комплексное тестирование с помощью Agents Playground без необходимости иметь арендатор Microsoft 365, если только не хотите опубликовать агент и использовать его в таких приложениях, как Teams или Outlook.

Обзор этапов тестирования

  • Добавьте ваши ключи API и настройки модели в файл .env, чтобы пример мог работать с LLM.
  • Выберите режим аутентификации. Для локальной разработки пример поддерживает режим агентской аутентификации с использованием значений, созданных из вашей схемы агента.
  • Запустите агент локально, после чего он станет доступен инструментам, например Agents Playground.
  • Используйте Agents Playground для тестирования сообщений, инструментов и уведомлений без настройки арендатора или развертывания каких-либо компонентов.
  • Когда вы будете готовы к работе в реальных условиях, опубликуйте агент в арендаторе Microsoft 365 и протестируйте его внутри Teams, Outlook или других приложений Microsoft 365.

Подробнее о тестировании

Опубликовать вашего агента

Когда ваш агент готов к реальному использованию в Microsoft 365 — например, для чатов Teams, сообщений Outlook, Word @mentions — вы публикуете его в арендаторе Microsoft 365. Команда publish интерфейса командной строки Agent 365 отвечает за упаковку: она обновляет ваш манифест, объединяет все и отправлять агент в центр администрирования Microsoft.

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

Important

После публикации агента необходимо настроить шаблон агента на портале разработчика перед созданием экземпляров. Узнайте, как настроить схему агента на портале разработчика

Здесь вы можете посмотреть опубликованные агенты: https://admin.cloud.microsoft/#/agents/all

Узнайте больше о полном рабочем процессе и пошаговых инструкциях

  • Последнее обновление: