Microsoft Teams — Enterprise Chat

Think of connecting Hermes Agent to Microsoft Teams like giving your AI assistant a company badge — once it’s on the team, it can join meetings, answer questions in channels, and help out in DMs, all without leaving the app your colleagues already use every day.

Why Teams Is Different from Slack

If you’ve used Slack’s Socket Mode before, Teams works a bit differently. Instead of keeping an open connection, Teams calls your bot’s public webhook whenever someone sends a message. That means your Hermes instance needs a public HTTPS URL — not localhost. For testing, you can use a tunnel; for production, you’ll point it at your real server domain.

How the Bot Behaves

Here’s the simple rule of thumb:

Where you talk to it	What happens
Personal chat (DM)	Bot replies to every message — no need to @mention
Group chat	Bot only replies when you @mention it
Channel	Bot only replies when you @mention it

Teams sends @mentions as <at>BotName</at> tags, but Hermes automatically strips them before processing — so you don’t have to worry about that.

Step 1: Install the Teams CLI

First, install Microsoft’s command-line tool that automates bot registration — no Azure portal needed:

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

To verify your login and find your AAD object ID (you’ll need this later to restrict access), run:

teams status --verbose

Step 2: Expose the Webhook Port

Teams can’t deliver messages to localhost. For local development, use a tunnel to get a public HTTPS URL. The default port is 3978 (change it with TEAMS_PORT if needed).

Here are three easy options:

# devtunnel (Microsoft)
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol https
devtunnel host hermes-bot

# ngrok
ngrok http 3978

# cloudflared
cloudflared tunnel --url http://localhost:3978

Copy the https:// URL from the output — you’ll need it in the next step. Leave the tunnel running while you develop.

Step 3: Create the Bot

Now register your bot with Teams:

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

The CLI will output your CLIENT_ID, CLIENT_SECRET, and TENANT_ID, plus an install link. Save the client secret immediately — it won’t be shown again.

Step 4: Configure Environment Variables

Add these to your ~/.hermes/.env file:

# 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

If you’re using Docker, 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

For source installs, make sure you include the Teams extra first:

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

Wrapping Up

Connecting Hermes to Teams is a four-step dance: install the CLI, expose a public URL, create the bot, and set your environment variables. Once it’s running, your AI assistant becomes a full team member — responding in DMs automatically and joining group chats when summoned.

Practical tip: Start with TEAMS_ALLOWED_USERS set to just your own AAD object ID. That way, you can test safely without worrying about random colleagues triggering your bot — then expand access once you’re confident everything works.