To set up hermes agent microsoft teams, you connect Hermes to Teams as a bot your colleagues can message, then optionally add a Graph-driven pipeline that turns finished meeting transcripts into summaries.
Here's how I'd set up both, in order, using only the commands in the official Hermes Teams setup page and the Teams Meetings page.
The example running through every step is a small IT support shop with one Microsoft 365 tenant, one Linux server and a Teams channel called Support.
If you want a second opinion on your tenant before you touch it, book a free SEO strategy session with my team.
The Two Builds, And Which One Comes First
Build one is the teams gateway platform: a chat bot that runs the agent with its full toolset.
The messaging gateway docs list its toolset as hermes-teams, with full tools including the terminal.
Build two is the teams_pipeline plugin plus a listener called msgraph_webhook.
Nobody chats with build two; Microsoft Graph pings it when a meeting artifact appears.
Do the bot first, because the pipeline reuses the Teams platform entry for delivering summaries back into a channel.
For the support shop, that means the Support channel gets a working bot on day one and meeting summaries a few days later.
Step 1: Install The Teams CLI And Log In
On the machine that will run Hermes, install Microsoft's Teams CLI and sign in:
npm install -g @microsoft/teams.cli@preview
teams login
teams status --verbose
The Hermes page says this CLI registers the bot for you, with no Azure portal visit required.
The last command prints your own AAD object ID.
Copy it now, because it becomes the first entry in your allowlist in Step 4.
Collect the object IDs of the two support engineers who should be able to use the bot as well.
Step 2: Give Teams A Public HTTPS Address
Teams pushes every message to a webhook, so localhost is unreachable from its side.
The listener port defaults to 3978, and TEAMS_PORT changes it.
For testing, the docs offer three tunnels:
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol http
devtunnel host hermes-bot
ngrok http 3978
cloudflared tunnel --url http://localhost:3978
Pick the named devtunnel if you can.
The troubleshooting table notes that ngrok and cloudflared hand out a new URL on each run unless you're on a paid plan, which forces an endpoint update every time.
Keep the tunnel's local side on plain HTTP; the tunnel handles TLS and the Hermes listener does not serve HTTPS.
Step 3: Register The Bot With One Command
teams app create \
--name "Hermes" \
--endpoint "https://<your-tunnel-url>/api/messages"
The output gives you a client ID, a client secret, a tenant ID and an install link.
Paste the secret somewhere safe immediately, because the CLI only shows it once.
The endpoint path must end in /api/messages, which is where the adapter listens.
🔥 Want the whole Teams stack already wired? Inside the AI Profit Boardroom members install a ready-built Agent OS, follow video walkthroughs of every Hermes gateway, and join four live coaching calls each week alongside 3,400+ operators. → Join the AI Profit Boardroom
Step 4: Fill The Env File And Lock The Allowlist
Add these lines to ~/.hermes/.env:
TEAMS_CLIENT_ID=<your-client-id>
TEAMS_CLIENT_SECRET=<your-client-secret>
TEAMS_TENANT_ID=<your-tenant-id>
TEAMS_ALLOWED_USERS=<aad-id-1>,<aad-id-2>,<aad-id-3>
Then run chmod 600 ~/.hermes/.env, as the security section recommends.
Treat the allowlist as mandatory.
The docs warn that without it, anyone who can find or install the bot can talk to it.
TEAMS_ALLOW_ALL_USERS exists, but it's meant for development only.
Messages from people outside the list are dropped without a reply, which is why a missing ID looks like a dead bot.
Step 5: Start The Gateway And Prove It Listens
hermes gateway restart
# or run it in the foreground while testing
hermes gateway run
curl http://localhost:3978/health
The health check should print ok.
In the logs, look for the line saying the Teams webhook server is listening on 3978 at /api/messages.
Docker users start it with docker compose up -d gateway from the cloned repo folder, not from the home directory.
If Python says the Teams SDK is missing, the docs say to request the teams extra through PM and restart, rather than installing packages into a system Python.
Step 6: Install The App And Send The First Message
teams app get <teamsAppId> --install-link
Open that link in a browser and it jumps into the Teams client.
Send the bot a direct message first; in a personal chat it answers everything.
Then add it to the Support channel and @mention it.
In group chats and channels it only replies when mentioned, and Hermes removes the mention tag before the agent reads the text.
Want it to read every channel message? That needs resource-specific consent in the manifest, and then TEAMS_REQUIRE_MENTION=true so it still only speaks when called.
What The Teams Adapter Can And Can't Do Yet
Set expectations with your team before launch, using the platform comparison table in the messaging docs:
| Capability | Teams row in the docs | What it means for the support shop |
|---|---|---|
| Images | Ticked | Engineers can paste a screenshot of an error into the chat. |
| Threads | Ticked | Replies can stay inside a channel thread instead of flooding the channel. |
| Typing indicator | Ticked | People can see the agent is working on a long job. |
| Voice | Not ticked | No voice notes to the bot. |
| Files | Not ticked | Share logs as pasted text or images, not as attachments. |
| Reactions and streaming | Not ticked | Answers arrive as finished messages. |
Two extras are worth switching on early.
Set TEAMS_HOME_CHANNEL to the Support channel's conversation ID, and cron jobs or proactive alerts will post there.
And per the updating guide, an allowed user can send /update from Teams; the gateway pulls the latest code and restarts, so the bot drops offline for roughly 5 to 15 seconds.
The usual gateway commands, such as /new to start a fresh session, work inside Teams chats as well.
If you'd rather keep secrets out of the env file entirely, the same keys can sit under platforms.teams.extra in config.yaml, next to require_mention.
Moving From Tunnel To Production
A tunnel is fine for the first week, but a support bot needs a stable address.
Put a reverse proxy with a valid certificate on your domain, terminate TLS there, and forward plain HTTP to 127.0.0.1:3978.
Keep the Hermes listener behind that proxy, because port 3978 never serves HTTPS on its own.
Point the bot at the new address with teams app update, then repeat the health check from outside the server.
Requests to /api/messages are authenticated by the Bot Framework, which rejects calls without a valid JWT, so the endpoint doesn't need a second password.
Rotate TEAMS_CLIENT_SECRET on a schedule through the Azure portal or the Teams CLI, the same way you would a password.
Gotchas I'd Check Before Going Live
- 400 errors in the logs: the tunnel or proxy is forwarding HTTPS to the plain HTTP listener. Terminate TLS at the proxy.
- "This bot is not responding": the webhook returned an error. Read
hermes gateway status -lfor the traceback. - Auth errors: one of the three
TEAMS_credentials is wrong, or the tenant doesn't match the account used inteams login. - Self-signed certificates: Teams rejects them. Production needs a valid certificate on a reverse proxy in front of
127.0.0.1:3978. - Moving to a real domain: run
teams app update --id <teamsAppId> --endpoint "https://your-domain.com/api/messages".
Approvals deserve their own test.
Ask the bot to do something that triggers the dangerous-command check and you'll get an Adaptive Card with Allow Once, Allow Session, Always Allow and Deny.
In a shared channel, the security docs say any admitted member can answer by default; set approvals.approvers to [] and each card is bound to the person who asked, so a teammate who taps it gets a private card response instead.
📞 Planning a bot for a whole tenant? Book a free SEO strategy session and we'll walk through your channels, users and approval rules with you. → Grab a free strategy call
Step 7: Register The Graph App For Meetings
Build two needs a separate Entra app, and the Graph app registration guide walks through it.
It uses app-only sign-in, so a tenant admin has to grant consent.
The tenant also needs Teams Premium or Teams licences that actually produce transcripts and recordings.
In entra.microsoft.com, open Identity, Applications, App registrations, and create a single-tenant app with no redirect URI.
Create a client secret and copy the Value column, not the Secret ID.
Then add only the application permissions you need:
OnlineMeetings.Read.AllandOnlineMeetingTranscript.Read.Allfor transcript summaries.OnlineMeetingRecording.Read.AllandCallRecords.Read.Allfor the recording fallback.ChannelMessage.SendorChat.ReadWrite.Allif summaries post back through Graph.
Click Grant admin consent and wait for every row to show a green tick.
Then scope it: by default those permissions cover every meeting in the tenant, so the guide recommends an Application Access Policy, which Microsoft also documents on Microsoft Learn.
New-CsApplicationAccessPolicy -Identity "Hermes-Meeting-Pipeline-Policy" -AppIds "<MSGRAPH_CLIENT_ID>"
Grant-CsApplicationAccessPolicy -PolicyName "Hermes-Meeting-Pipeline-Policy" -Identity "lead@example.com"
Test-CsApplicationAccessPolicy -Identity "lead@example.com" -AppId "<MSGRAPH_CLIENT_ID>"
Allow up to 30 minutes for the policy to take effect before you test.
Step 8: Turn On The Listener And The Pipeline
Enable the bundled plugin, which the built-in plugins page says never switches itself on:
hermes plugins enable teams_pipeline
Add the Graph credentials and the listener to the env file:
MSGRAPH_TENANT_ID=<tenant-id>
MSGRAPH_CLIENT_ID=<client-id>
MSGRAPH_CLIENT_SECRET=<client-secret>
MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=<output of openssl rand -hex 32>
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings
The webhook listener page says it won't start without a client state, and it compares that value in a timing-safe way.
Bind it to 127.0.0.1 behind your proxy; a public bind needs allowed_source_cidrs set to Microsoft's ranges.
Under platforms.teams.extra, set delivery_mode to graph with a team_id and channel_id, or to incoming_webhook with a Teams-generated URL.
The pipeline's own knobs sit under meeting_pipeline, such as transcription_fallback, which needs ffmpeg installed, plus optional Notion and Linear sinks.
Step 9: Subscribe, Then Automate Renewal
hermes teams-pipeline subscribe \
--resource communications/onlineMeetings/getAllTranscripts \
--notification-url https://ops.example.com/msgraph/webhook \
--client-state "<your-client-state>"
Repeat it with getAllRecordings if you want the fallback.
Then do the step most people skip.
Graph subscriptions last 72 hours at most and nothing renews them for you.
The operator runbook gives a Hermes cron job that runs every 12 hours:
hermes cron create "0 */12 * * *" \
--name "teams-pipeline-maintain-subscriptions" \
--no-agent \
--script maintain-teams-subscriptions.sh \
--deliver local
The script lives in ~/.hermes/scripts/ and simply runs hermes teams-pipeline maintain-subscriptions.
A systemd timer or a plain crontab line work too.
Day-Two Checks For The Pipeline
hermes teams-pipeline validate
hermes teams-pipeline token-health --force-refresh
hermes teams-pipeline subscriptions
hermes teams-pipeline list --status failed
hermes teams-pipeline show <job-id>
hermes teams-pipeline run <job-id>
Run validate after every config change.
Use run to replay a stored job after you fix a delivery target.
For a meeting created from a short /meet/ link, fetch needs --organizer-user-id, because Graph rejects those links on the default endpoint.
One Microsoft-side gotcha: if an admin turns off Graph access to transcripts, Microsoft says new or renewed transcript subscriptions fail with a 403.
My Verdict On This Setup Order
The bot is a one-afternoon job: CLI, tunnel, four env lines, install link.
The pipeline is an admin job: Entra app, consent, access policy, listener, subscriptions and a renewal schedule.
Do them in that order and test each one alone.
The official pipeline works from transcripts after the call; it doesn't sit in the meeting, and the community MeetStream plugin in the plugin catalog is the option that says it joins calls.
If you're weighing a hosted agent instead, compare this with our Grok Bot Microsoft Teams setup guide.
Members of the AI Profit Boardroom can bring their config to a live call and have it checked.
Also On Our Network
- 🌐 Plain-English steps to set up a Hermes agent in Microsoft Teams for a small firm
- 🌐 The four ways to connect Hermes to Microsoft Teams, compared in one table
- 🌐 How to set up a Hermes Teams bot inside your Agent OS, step by step
- 🌐 A two-stage Hermes Microsoft Teams setup, with a short model pick at the end
- 🌐 The complete Hermes Agent Microsoft Teams guide on AI Profit Boardroom
FAQ: Hermes Agent Microsoft Teams Setup
What is the fastest way to connect Hermes to Microsoft Teams?
Run hermes gateway setup and choose Microsoft Teams, or follow the manual route: install the Teams CLI, open a tunnel to port 3978, run teams app create, fill four env lines and restart the gateway.
Which ID goes into TEAMS_ALLOWED_USERS?
The AAD object ID of each person allowed to use the bot. teams status --verbose shows your own.
Why does the gateway log 400 errors when Teams sends a message?
Your tunnel or proxy is sending HTTPS to the Hermes listener, which only speaks plain HTTP. Terminate TLS at the proxy and forward HTTP to port 3978.
Which Graph permissions does the meeting pipeline need?
OnlineMeetings.Read.All and OnlineMeetingTranscript.Read.All for transcripts, plus OnlineMeetingRecording.Read.All and CallRecords.Read.All for the recording fallback, and ChannelMessage.Send or Chat.ReadWrite.All for Graph delivery.
How often should subscription renewal run?
The operator runbook suggests every 12 hours, which leaves plenty of room inside Graph's 72-hour limit.
Can I replay a meeting summary that failed to post?
Yes. Find the job with hermes teams-pipeline list --status failed, fix the target, then run hermes teams-pipeline run with that job ID.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote "Link Building Mastery".
- My Udemy courses have taught over 29,000 students.
→ Get my best AI training inside the AI Profit Boardroom
Register the bot, lock the allowlist, prove the health check, then add the Graph app and the 12-hour renewal job, and if you want help, grab a free SEO strategy session with my team, or get coached through it in the AI Profit Boardroom, to finish your hermes agent microsoft teams build.











