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

Тестовые агенты с помощью пакета SDK Microsoft Agent 365

Это важно

Чтобы получить ранний доступ к Microsoft Agent 365, необходимо быть частью программы предварительного просмотра Фронтир. Frontier напрямую подключает вас к последним инновациям ИИ от Microsoft. Получите практический опыт с прорывными функциями, делитесь своими впечатлениями с продуктовыми командами и помогите сформировать будущее Искусственного интеллекта. Предпросмотры Frontier подчиняются существующим условиям предварительного просмотра в рамках ваших клиентских соглашений. Так как эти функции по-прежнему находятся в разработке, их доступность и возможности могут меняться со временем.

Протестируйте агента локально с помощью Agents Playground перед развертыванием. В этом руководстве описывается настройка среды разработки, настройка проверки подлинности и проверка функциональности агента с помощью средства тестирования на игровой площадке агентов.

После локальной работы агента можно развернуть и опубликовать его для тестирования в приложениях Microsoft 365, таких как Teams.

Предпосылки

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

Общие предварительные требования

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

Настройка среды тестирования агента

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

Настройка среды тестирования агента следует последовательному рабочему процессу:

  1. Настройка среды — создание или обновление файла конфигурации среды

  2. Конфигурация LLM — получение ключей API и настройка параметров OpenAI или Azure OpenAI

  3. Настройка проверки подлинности — настройка агентической проверки подлинности

  4. Справочник по переменным среды. Настройка обязательных переменных среды:

    1. Переменные проверки подлинности
    2. Конфигурация конечной точки MCP
    3. Переменные наблюдаемости
    4. Конфигурация сервера приложений агента

Выполнив эти действия, вы можете начать тестирование агента на игровой площадке агентов.

Шаг 1. Настройка среды

Настройте файл конфигурации:

cp .env.template .env

Замечание

Ознакомьтесь с примерами пакета SDK Microsoft Agent 365 , чтобы найти шаблоны конфигурации с обязательными полями.

Шаг 2. Конфигурация LLM

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

Добавьте в .env файл:

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

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

Variable Description Обязательно Example
OPENAI_API_KEY Ключ API для службы OpenAI Для OpenAI sk-proj-...
AZURE_OPENAI_API_KEY Ключ API для службы Azure OpenAI Для Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT URL-адрес конечной точки службы Azure OpenAI Для Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Имя развертывания в Azure OpenAI Для Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION Версия API для Azure OpenAI Для Azure OpenAI 2024-02-15-preview

Шаг 3. Настройка параметров аутентификации для проверки подлинности удостоверения агента

Используйте команду CLI A365 a365 config display для получения учетных данных шаблона агента.

a365 config display -g

Эта команда отображает конфигурацию схемы агента. Скопируйте следующие значения:

Ценность Description
agentBlueprintId Идентификатор клиента агента
agentBlueprintClientSecret Секрет клиента агента
tenantId Идентификатор клиента Microsoft Entra

Используйте эти значения для настройки агентной проверки подлинности в агенте:

Добавьте следующие настройки в файл .env, заменив значения заполнителей на ваши фактические учетные данные.

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Variable Description Обязательно Example
USE_AGENTIC_AUTH Включение режима проверки подлинности агента Да true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID Идентификатор клиента шаблона агента из a365 config display -g Да 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Секрет клиента шаблона агента из a365 config display -g Да abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Идентификатор клиента Microsoft Entra из a365 config display -g Да adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

Замечание

Для .NET также убедитесь, что USE_AGENTIC_AUTH=true установлен в launchSettings.json (см. Шаг 4: Справочник по переменным среды)

Шаг 4. Справочник по переменным среды

Выполните настройку среды, настроив следующие необходимые переменные среды:

Переменные аутентификации

Настройте параметры обработчика проверки подлинности, необходимые для правильной работы агентной проверки подлинности.

Добавьте в .env файл:

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
Variable Description Обязательно
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Тип обработчика проверки подлинности Да
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Области проверки подлинности для Microsoft Graph Да
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Альтернативное имя подключения чертежа Да
CONNECTIONSMAP_0_SERVICEURL Шаблон URL-адреса службы для сопоставления подключений Да
CONNECTIONSMAP_0_CONNECTION Имя подключения для сопоставления Да

Конфигурация конечной точки MCP

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

Добавьте в .env файл:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Variable Description Обязательно По умолчанию Example
MCP_PLATFORM_ENDPOINT URL-адрес конечной точки платформы MCP (предварительная версия, тестирование или продакшн) нет Конечная точка продакшена

Важно: Если MCP_PLATFORM_ENDPOINT не указан, по умолчанию используется конечная точка продакшн.

Переменные наблюдаемости

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

Замечание

Конфигурация наблюдаемости одинакова для всех языков.

Variable Description По умолчанию Example
ENABLE_A365_OBSERVABILITY Включение и отключение наблюдаемости false true
ENABLE_A365_OBSERVABILITY_EXPORTER Экспорт трассировок в сервис наблюдаемости false true
OBSERVABILITY_SERVICE_NAME Имя службы для трассировки Имя агента my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Пространство имен службы agent365-samples my-company-agents

Конфигурация сервера приложений агента

Настройте порт, на котором работает сервер приложений агента. Это необязательно и применяется к агентам Python и JavaScript.

Добавьте в .env файл:

# Server Configuration
PORT=3978
Variable Description Обязательно По умолчанию Example
PORT Номер порта, на котором выполняется сервер агента нет 3978 3978

Установка зависимостей и запуск сервера приложений агента

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

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

uv pip install -e .

Эта команда считывает зависимости пакета, определенные в pyproject.toml , и устанавливает их из PyPI. При создании приложения агента с нуля необходимо создать pyproject.toml файл для определения зависимостей. Примеры агентов из репозитория примеров уже определены в этих пакетах. Их можно добавить или обновить по мере необходимости.

Запуск сервера приложений агента

python <main.py>

Замените <main.py> именем основного файла Python, содержащего точку входа для приложения агента (например, start_with_generic_host.pyилиapp.pymain.py).

Или с помощью ультрафиолета:

uv run python <main.py>

Теперь сервер агента работает и готов принимать запросы от Площадки агентов или приложений Microsoft 365.

Агент тестирования на игровой площадке агентов

Платформа агентов — это локальное средство тестирования, которое имитирует среду Microsoft 365 без полной настройки клиента. Это самый быстрый способ проверки логики и вызовов инструментов агента. Дополнительные сведения см. в разделе "Тестирование на платформе Agents Playground".

Откройте новый терминал (PowerShell в Windows) и запустите площадку агентов:

agentsplayground

Откроется веб-браузер с интерфейсом Платформы агентов. В этом средстве отображается интерфейс чата, в котором можно отправлять сообщения агенту.

Базовый тест

Сначала убедитесь, что агент настроен правильно. Отправьте сообщение агенту:

What can you do?

Агент должен ответить с инструкциями, настроенными на основе системного запроса и возможностей агента. Это подтверждает следующее:

  • Агент работает корректно
  • Агент может обрабатывать сообщения и отвечать
  • Коммуникация между игровой площадкой агентов и вашим агентом работает успешно

Вызовы средства тестирования

После настройки серверов инструментов MCP в toolingManifest.json (см. Tooling для инструкций по настройке), проверьте вызовы инструментов с примерами, как показано ниже.

Сначала проверьте, какие средства доступны:

List all tools I have access to

Затем протестируйте вызовы конкретного средства:

Средства почты

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

Ожидаемый ответ: агент отправляет сообщение электронной почты с помощью сервера MAIL MCP и подтверждает отправку сообщения.

Инструменты календаря

List my calendar events for today

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

Инструменты SharePoint

List all SharePoint sites I have access to

Ожидаемый ответ: агент запрашивает SharePoint и возвращает список сайтов, к которым у вас есть доступ.

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

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

Тестирование с помощью действий уведомлений

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

Прежде чем тестировать действия уведомлений, убедитесь, что у вас есть следующее:

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

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

  1. Запустите своего агента и учебную среду агентов
  2. На игровой площадкеагентов перейдите к макету>
  3. Скопируйте conversationId из активности (идентификатор беседы изменяется при каждом перезапуске Agents Playground)
  4. Вставьте JSON пользовательского действия и обновите personal-chat-id поле со скопированным идентификатором беседы. Пример уведомления по электронной почте
  5. Выбор действия "Отправить"
  6. Посмотрите результат в чате и в панели протоколов

Уведомление по электронной почте

Это имитирует сообщение электронной почты, отправленное агенту. Замените значения заполнителей фактическими сведениями об агенте:

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

Просмотр журналов наблюдаемости

Чтобы просмотреть журналы наблюдаемости во время локальной разработки, оснастите агент кодом для наблюдаемости (см. Наблюдаемость для примеров кода) и настройте переменные среды, как описано в переменные для наблюдаемости. После завершения настройки в консоли отображаются трассировки в режиме реального времени:

  • Трассировки вызовов агента
  • Сведения о выполнении инструмента
  • Вызовы инференции LLM
  • Входные и выходные сообщения
  • Использование токенов
  • Время отклика
  • Сведения об ошибке

Эти журналы помогают отлаживать проблемы, понимать поведение агента и оптимизировать производительность.

Устранение неполадок

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

Проблемы с подключением и средой

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

Проблемы с подключением к игровой площадке агентов

Симптом: Agents Playground не может подключиться к вашему агенту

Solutions:

  • Проверка запуска сервера агента
  • Убедитесь, что номера портов совпадают между вашим агентом и средой Agents Playground
  • Убедитесь, что правила брандмауэра не блокируют локальные подключения
  • Попробуйте перезапустить агент и игровую площадку агентов

Устаревшая версия платформы агентов

Симптом: непредвиденные ошибки или отсутствующие функции на детской площадке агентов

Решение: Удалите и установите заново Agents Playground:

winget uninstall agentsplayground
winget install agentsplayground

Конфликты портов

Симптом: ошибка, указывающая, что порт уже используется

Решение.

  • Остановите все другие экземпляры вашего агента
  • Изменение порта в конфигурации
  • Убить все процессы, использующие порт:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Не удается добавить DeveloperMCPServer

Симптом: ошибка при попытке добавить DeveloperMCPServer в VS Code

Решение. Закройте и снова откройте Visual Studio Code, а затем повторите попытку добавить сервер.

Проблемы с проверкой подлинности

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

Срок действия маркера носителя истек

Симптом: ошибки проверки подлинности или 401 Несанкционированные ответы

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

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

Симптом: ошибка при получении маркера агентического экземпляра

Решение: Проверьте ALT_BLUEPRINT_NAME параметр в .env.

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

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

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

Сообщение электронной почты не получено

Симптом: агент указывает, что сообщение отправлено, но вы не получаете его

Solutions:

  • Проверьте папку "Нежелательная почта"/ "Спам"
  • Доставка по электронной почте может быть отложена на несколько минут — подождите до 5 минут.
  • Проверка правильности адреса электронной почты получателя
  • Проверка журналов агента на наличие ошибок во время отправки электронной почты

Ответы на комментарии в Word не работают

Известная проблема: служба уведомлений в настоящее время не может отвечать непосредственно на комментарии Word. Эта функция разрабатывается.

Получение помощи

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

Репозитории пакета SDK для Microsoft Agent 365

Дополнительная поддержка

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

Теперь, когда вы успешно проверили агент локально, вы готовы развернуть его в Azure и опубликовать его в Microsoft 365:

  • Развертывание и публикация агентов. Узнайте, как развернуть агент в Веб-приложении Azure и опубликовать его в Центре администрирования Майкрософт, что делает его доступным для вашей организации для обнаружения и найма в Microsoft 365.
  • Last updated on