🏠 Главная › User Guide › teams

sidebar_position: 5 title: "Microsoft Teams" description: "Set up Hermes Agent as a Microsoft Teams bot" lang: ru

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

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

Как реагирует бот

Контекст Поведение
Личный чат (DM) Бот отвечает на каждое сообщение. Никакого @упоминания не требуется.
Групповой чат Бот отвечает только тогда, когда @упоминается.
Канал Бот отвечает только тогда, когда @упоминается.

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

Шаг 1. Установите интерфейс командной строки Teams

@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  # replace 3978 with TEAMS_PORT if changed
devtunnel host hermes-bot

# ngrok
ngrok http 3978  # replace 3978 with TEAMS_PORT if changed

# cloudflared
cloudflared tunnel --url http://localhost:3978  # replace 3978 with TEAMS_PORT if changed

Скопируйте https:// URL from the output — you'll use it in the next step. Leave the tunnel running while developing.

For production, point your bot's endpoint at your server's public domain instead (see Production Deployment).

Step 3: Create the Bot

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

The CLI outputs your CLIENT_ID, CLIENT_SECRET, and TENANT_ID, plus an install link for Step 6. Save the client secret — it won't be shown again.

Step 4: Configure Environment Variables

Add to ~/.hermes/.env:

# Required
TEAMS_CLIENT_ID=<your-client-id>
TEAMS_CLIENT_SECRET=<your-client-secret>
TEAMS_TENANT_ID=<your-tenant-id>

# Restrict access to specific users (recommended)
# Use AAD object IDs from `teams status --verbose`
TEAMS_ALLOWED_USERS=<your-aad-object-id>

Step 5: Start the Gateway

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

This starts the gateway. The default webhook port is 3978 (override with TEAMS_PORT@@ IC0012@@TEAMS_CLIENT_ID | Azure AD App (client) ID | | TEAMS_CLIENT_SECRET | Azure AD client secret | | TEAMS_TENANT_ID | Azure AD tenant ID | | TEAMS_ALLOWED_USERS | Comma-separated AAD object IDs allowed to use the bot | | TEAMS _ALLOW_ALL_USERS | Set true to skip the allowlist and allow anyone | | TEAMS_HOME_CHANNEL | Conversation ID for cron/proactive message delivery | | TEAMS_HOME_CHANNEL_NAME | Display name for the home channel | | TEAMS_PORT | Webhook port (default: 3978) |

config.yaml

Alternatively, configure via ~/.hermes/config.yaml:

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

Features

Interactive Approval Cards

When the agent needs to run a potentially dangerous command, it sends an Adaptive Card with four buttons instead of asking you to type /approve:

Clicking a button resolves the approval inline and replaces the card with the decision.

Production Deployment

For a permanent server, skip devtunnel and register your bot with your server's public HTTPS endpoint:

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

If you've already created the bot and just need to update the endpoint:

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

Make sure your configured port (TEAMS_PORT, default 3978) is reachable from the internet and that your TLS certificate is valid — Teams rejects self-signed certificates.

Troubleshooting

Problem Solution
health endpoint works but bot doesn't respond Check that your tunnel is still running and the bot's messaging endpoint matches the tunnel URL
KeyError: 'teams' in logs Restart the container — this is fixed in the current version
Bot responds with auth errors Verify TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET, and TEAMS_TENANT_ID are all set correctly
Нет поставщика выводов configure Check that ANTHROPIC_API_KEY (or another provider key) is set in ~/.hermes/.env
Bot receives messages but ignores them Your AAD object ID may not be in TEAMS_ALLOWED_USERS. Run teams status --verbose to find it
Tunnel URL changes on restart devtunnel URLs are persistent if you use a named tunnel (devtunnel создать hermes-bot). ngrok and cloudflared generate a new URL each run unless you have a paid plan — update the bot endpoint with teams app update when it changes
Teams shows "This bot is not responding" The webhook returned an error. Check docker logs hermes for tracebacks
[teams] Не удалось подключиться in logs The SDK failed to authenticate. Double-check your credentials and that the tenant ID matches the account you used in teams login

Security

⚠️ Warning

**Always set `TEAMS_ALLOWED_USERS`** with the AAD object IDs of authorized users. Without this, anyone who can find or install your bot can interact with it. Treat `TEAMS_CLIENT_SECRET` like a password — rotate it periodically via the Azure portal or Teams CLI.