Настройка команд Microsoft

Подключите Hermes Agent к Microsoft Teams в качестве бота. В отличие от режима Slack Socket, Teams передает сообщения, вызывая публичный HTTPS-вебхук, поэтому ваш экземпляр должен иметь общедоступную конечную точку — либо туннель для разработки (локальная разработка), либо реальный домен (продакшн).

Нужны сводки, собранные из событий Microsoft Graph, вместо обычного беседы с ботом? Используйте настройки страницы: Teams Meetings.

Как отвечает бот

Teams доставляет @упоминания как обычные сообщения с тегами <at>BotName</at>, которые Hermes автоматически удаляет перед обработкой.

Шаг 1: Установка Teams CLI

@microsoft/teams.cli автоматизирует регистрацию бота — портал Azure не требуется.

npm install -g @microsoft/teams.cli@preview
teams login

Чтобы проверить свой вход и найти свой идентификатор объекта AAD (нужен для TEAMS_ALLOWED_USERS):

teams status --verbose

Шаг 2: Открытие порта вебхука

Команды не могут отправлять сообщения на «localhost». Для локальной разработки используйте любой инструмент туннелирования для получения публичного URL-адреса HTTPS. Порт по умолчанию — 3978 — измените его с помощью TEAMS_PORT при необходимости.

# devtunnel (Microsoft)
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol https  # замените 3978 на TEAMS_PORT, если изменен
devtunnel host hermes-bot

# ngrok
ngrok http 3978  # замените 3978 на TEAMS_PORT, если изменен

# cloudflared
cloudflared tunnel --url http://localhost:3978  # замените 3978 на TEAMS_PORT, если изменен

Скопируйте URL-адрес https://` из результатов — он понадобится на следующем шаге. Оставьте туннель рабочим во время разработки.

Для продакшена укажите конечную точку вашего бота на публичном домене вашего сервера (см. Развертывание в продакшн).

Шаг 3: Создание бота

teams app create \
  --name "Hermes" \
  --endpoint "https://<your-tunnel-url>/api/messages"

CLI выведет ваши CLIENT_ID, CLIENT_SECRET и TENANT_ID, а также ссылку для установки для шага 6. Сохраните секрет клиента — он больше не будет показан.

Шаг 4: Настройка контура окружения

Добавьте в ~/.hermes/.env:

# Обязательно
TEAMS_CLIENT_ID=<your-client-id>
TEAMS_CLIENT_SECRET=<your-client-secret>
TEAMS_TENANT_ID=<your-tenant-id>

# Ограничение доступа к конкретным пользователям (рекомендуется)
# Используйте AAD object ID из `teams status --verbose`
TEAMS_ALLOWED_USERS=<your-aad-object-id>

Шаг 5: Запуск шлюза

HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d gateway

Это запускает шлюз. Порт вебхука по умолчанию — 3978 (переопределяется с помощью TEAMS_PORT). Проверьте, что он работает:

curl http://localhost:3978/health   # должно вернуть: ok
docker logs -f hermes

Ищите:

[teams] Webhook server listening on 0.0.0.0:3978/api/messages

Шаг 6: Установка приложений в Teams

teams app get <teamsAppId> --install-link

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

Справочник по конфигурации

Переменные окружения

конфиг.yaml

В качестве альтернативы настроить через ~/.hermes/config.yaml:

platforms:
  teams:
    enabled: true
    extra:
      client_id: "your-client-id"
      client_secret: "your-secret"
      tenant_id: "your-tenant-id"
      port: 3978

функции

Интерактивные карточки подтверждения

Когда агенту необходимо выполнить проверку опасной команды, он отправляет Adaptive Card специальными кнопками вместо того, чтобы попросить вас ввести /approve:

• Allow Once — надежность этой конкретной команды
• Разрешить сеанс — надежно этот шаблон на оставшейся части сессии.
• Всегда разрешать — навсегда надежность этого шаблона
• Запретить — отклонить команду

Нажатие кнопки разрешает действие на месте и заменяет карточку судебного решения.

Доставка сводок собранных (конвейер Teams Meeting)

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

Доставка конвейера для обнаружения в записи платформы команды вместе с конфигурацией бота:

platforms:
  teams:
    enabled: true
    extra:
      # существующая конфигурация бота (client_id, client_secret, tenant_id, port)...

      # Доставка сводки собраний (используется только при включенном плагине teams_pipeline)
      delivery_mode: "graph"       # или "incoming_webhook"
      # Для delivery_mode: graph — выберите ОДНО из:
      chat_id: "19:meeting_..."    # опубликовать в чат Teams
      # team_id: "..."             # ИЛИ опубликовать в канал
      # channel_id: "..."
      # access_token: "..."        # опционально; по умолчанию использует учетные данные приложения MSGRAPH_*
      # Для delivery_mode: incoming_webhook:
      # incoming_webhook_url: "https://outlook.office.com/webhook/..."

Если плагин teams_pipeline не включен, эти настройки неактивны — они срабатывают только тогда, когда среда выполнения конвейера находится на входе вебхука Graph.

Развертывание в продакшн

Для постоянного сервера пропустите devtunnel и зарегистрируйте свою боту с публичной конечной точкой HTTPS вашего сервера:

teams app create \
  --name "Hermes" \
  --endpoint "https://your-domain.com/api/messages"

Если вы уже создаете боту и необходимо только обновить конечную точку:

teams app update --id <teamsAppId> --endpoint "https://your-domain.com/api/messages"

Убедитесь, что настроенный порт (TEAMS_PORT, по умолчанию 3978) доступен из Интернета и что ваш TLS-сертификат действителен — Teams отклоняет самоподписанные сертификаты.

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

Безопасность:::предупреждение

Всегда устанавливайте TEAMS_ALLOWED_USERS с идентификатором объекта AAD авторизованных пользователей. Без этого любой, кто сможет найти или установить вашу боту, сможет с ним взаимодействовать.

Относитесь к TEAMS_CLIENT_SECRET как к паролю — периодически меняйте его через портал Azure или Teams CLI.