Microsoft Teams Setup

Connect Hermes Agent to Microsoft Teams as a bot. Unlike Slack's Socket Mode, Teams delivers messages by calling a public HTTPS webhook, so your instance needs a publicly reachable endpoint — either a dev tunnel (local dev) or a real domain (production).

Need meeting summaries from Microsoft Graph events rather than normal bot conversations? Use the dedicated setup page: Teams Meetings.

Run hermes gateway setup and pick Microsoft Teams for a guided walk-through.

How the Bot Responds

Teams delivers @mentions as regular messages with <at>BotName</at> tags, which Hermes strips automatically before processing.

For source or local installs, include the Teams extra so the bundled adapter can import the Microsoft Teams SDK:

uv sync --extra teams
# or, for editable installs:
uv pip install -e ".[teams]"

Step 1: Install the Teams CLI

The @microsoft/teams.cli automates bot registration — no Azure portal needed.

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

To verify your login and find your own AAD object ID (needed for TEAMS_ALLOWED_USERS):

teams status --verbose

Step 2: Expose the Webhook Port

Teams cannot deliver messages to localhost. For local development, use any tunnel tool to get a public HTTPS URL. The default port is 3978 — change it with TEAMS_PORT if needed.

# devtunnel (Microsoft)
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol http  # 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

Copy the https:// URL from the output — you'll use it in the next step. Leave the tunnel running while developing.

The public tunnel URL uses HTTPS, but Hermes' local webhook listener uses plain HTTP. The tunnel terminates TLS and forwards HTTP to port 3978; do not configure the local tunnel port as HTTPS.

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

Docker (must run from the directory that contains docker-compose.yml — usually your cloned hermes-agent repo, not ~):

cd /path/to/hermes-agent
HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d gateway

Native / systemd install (typical hermes one-liner installer under ~/.hermes/hermes-agent):

hermes gateway restart
# or foreground: hermes gateway run

The Teams SDK is optional; when Teams is enabled, the gateway lazy-installs it into Hermes' own venv on first start (do not use system pip install on Ubuntu 24.04 — that hits PEP 668 externally-managed-environment). To install manually into the Hermes venv:

~/.hermes/hermes-agent/venv/bin/pip install microsoft-teams-apps aiohttp
# or from a clone of the agent: uv sync --extra teams

The default webhook port is 3978 (override with TEAMS_PORT). Check that it's running:

curl http://localhost:3978/health   # should return: ok
# Docker:
docker logs -f hermes
# Native:
hermes gateway status -l

Look for:

[teams] Webhook server listening on * (all interfaces, IPv4+IPv6):3978/api/messages

Step 6: Install the App in Teams

teams app get <teamsAppId> --install-link

Open the printed link in your browser — it opens directly in the Teams client. After installing, send a direct message to your bot — it's ready.

Configuration Reference

Environment Variables

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:

• Allow Once — approve this specific command
• Allow Session — approve this pattern for the rest of the session
• Always Allow — permanently approve this pattern
• Deny — reject the command

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

Meeting Summary Delivery (Teams Meeting Pipeline)

When the Teams meeting pipeline plugin is enabled, this adapter also handles outbound delivery of meeting summaries — one Teams integration surface, not two. After a meeting's transcript is summarized, the writer posts the summary into your chosen Teams target.

Pipeline summary delivery is configured under the teams platform entry alongside the bot config:

platforms:
  teams:
    enabled: true
    extra:
      # existing bot config (client_id, client_secret, tenant_id, port) ...

      # Meeting summary delivery (only used when the teams_pipeline plugin is enabled)
      delivery_mode: "graph"       # or "incoming_webhook"
      # For delivery_mode: graph — pick ONE of:
      chat_id: "19:meeting_..."    # post into a Teams chat
      # team_id: "..."             # OR post into a channel
      # channel_id: "..."
      # access_token: "..."        # optional; falls back to MSGRAPH_* app credentials
      # For delivery_mode: incoming_webhook:
      # incoming_webhook_url: "https://outlook.office.com/webhook/..."

If the teams_pipeline plugin is not enabled, these settings are inert — they only wire up when the pipeline runtime binds to the Graph webhook ingress.

Production Deployment

For a permanent server, terminate TLS at a reverse proxy and forward requests to the plain HTTP Hermes listener, normally http://127.0.0.1:3978. Register the proxy's public HTTPS endpoint with Teams:

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 the public HTTPS endpoint is reachable from the internet and uses a valid TLS certificate. Teams rejects self-signed certificates. Keep the Hermes listener behind the proxy; port 3978 does not serve HTTPS itself.

Troubleshooting

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. :::

• Store credentials in ~/.hermes/.env with permissions 600 (chmod 600 ~/.hermes/.env)
• The bot only accepts messages from users in TEAMS_ALLOWED_USERS; unauthorized messages are silently dropped
• Your public endpoint (/api/messages) is authenticated by the Teams Bot Framework — requests without valid JWTs are rejected

Related Docs

• Teams Meetings
• Operate the Teams Meeting Pipeline