mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-10 03:22:05 +00:00
docs(teams): split meetings setup from operator runbook
This commit is contained in:
Dilee
Teknium
parent
1997b3baf8
commit
b79ef8827f
4 changed files with 429 additions and 1 deletions
|
|
@ -427,5 +427,6 @@ Each platform has its own toolset:
|
|||
- [QQBot Setup](qqbot.md)
|
||||
- [Yuanbao Setup](yuanbao.md)
|
||||
- [Microsoft Teams Setup](teams.md)
|
||||
- [Teams Meetings Pipeline](teams-meetings.md)
|
||||
- [Open WebUI + API Server](open-webui.md)
|
||||
- [Webhooks](webhooks.md)
|
||||
- [Webhooks](webhooks.md)
|
||||
|
|
|
|||
227
website/docs/user-guide/messaging/teams-meetings.md
Normal file
227
website/docs/user-guide/messaging/teams-meetings.md
Normal file
|
|
@ -0,0 +1,227 @@
|
|||
---
|
||||
sidebar_position: 6
|
||||
title: "Teams Meetings"
|
||||
description: "Set up the Microsoft Teams meeting summary pipeline with Microsoft Graph webhooks"
|
||||
---
|
||||
|
||||
# Microsoft Teams Meetings
|
||||
|
||||
Use the Teams meeting pipeline when you want Hermes to ingest Microsoft Graph meeting events, fetch transcripts first, fall back to recordings plus STT when needed, and deliver a structured summary to downstream sinks.
|
||||
|
||||
This page focuses on setup and enablement:
|
||||
- Graph credentials
|
||||
- webhook listener configuration
|
||||
- Teams delivery modes
|
||||
- pipeline config shape
|
||||
|
||||
For day-2 operations, go-live checks, and the operator worksheet, use the dedicated guide: [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline).
|
||||
|
||||
## What This Feature Does
|
||||
|
||||
The pipeline:
|
||||
1. receives Microsoft Graph webhook events
|
||||
2. resolves the meeting and prefers transcript artifacts first
|
||||
3. falls back to recording download plus STT when no usable transcript is available
|
||||
4. stores durable job state and sink records locally
|
||||
5. can write summaries to Notion, Linear, and Microsoft Teams
|
||||
|
||||
Operator actions stay in the CLI:
|
||||
|
||||
```bash
|
||||
hermes teams-pipeline validate
|
||||
hermes teams-pipeline list
|
||||
hermes teams-pipeline maintain-subscriptions
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before enabling the meetings pipeline, make sure you have:
|
||||
|
||||
- a working Hermes install
|
||||
- the existing [Microsoft Teams bot setup](/docs/user-guide/messaging/teams) if you want Teams outbound delivery
|
||||
- Microsoft Graph application credentials with the permissions required for the meeting resources you plan to subscribe to
|
||||
- a public HTTPS URL that Microsoft Graph can call for webhook delivery
|
||||
- `ffmpeg` installed if you want recording-plus-STT fallback
|
||||
|
||||
## Step 1: Add Microsoft Graph Credentials
|
||||
|
||||
Add Graph app-only credentials to `~/.hermes/.env`:
|
||||
|
||||
```bash
|
||||
MSGRAPH_TENANT_ID=<tenant-id>
|
||||
MSGRAPH_CLIENT_ID=<client-id>
|
||||
MSGRAPH_CLIENT_SECRET=<client-secret>
|
||||
```
|
||||
|
||||
These credentials are used by:
|
||||
- the Graph client foundation
|
||||
- subscription maintenance commands
|
||||
- meeting resolution and artifact fetches
|
||||
- Graph-based Teams outbound delivery when you do not provide a dedicated Teams access token
|
||||
|
||||
## Step 2: Enable the Graph Webhook Listener
|
||||
|
||||
The webhook listener is a gateway platform named `msgraph_webhook`. At minimum, enable it and set a client state value:
|
||||
|
||||
```bash
|
||||
MSGRAPH_WEBHOOK_ENABLED=true
|
||||
MSGRAPH_WEBHOOK_PORT=8646
|
||||
MSGRAPH_WEBHOOK_CLIENT_STATE=<random-shared-secret>
|
||||
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings
|
||||
```
|
||||
|
||||
The listener exposes:
|
||||
- `/msgraph/webhook` for Graph notifications
|
||||
- `/health` for a simple health check
|
||||
|
||||
You need to route your public HTTPS endpoint to that listener. For example, if your public domain is `https://ops.example.com`, your Graph notification URL would typically be:
|
||||
|
||||
```text
|
||||
https://ops.example.com/msgraph/webhook
|
||||
```
|
||||
|
||||
## Step 3: Configure Teams Delivery and Pipeline Behavior
|
||||
|
||||
The meeting pipeline reads its runtime config from the existing `teams` platform entry. Pipeline-specific knobs live under `teams.extra.meeting_pipeline`. Teams outbound delivery stays on the normal Teams platform config surface.
|
||||
|
||||
Example `~/.hermes/config.yaml`:
|
||||
|
||||
```yaml
|
||||
platforms:
|
||||
msgraph_webhook:
|
||||
enabled: true
|
||||
extra:
|
||||
port: 8646
|
||||
client_state: "replace-me"
|
||||
accepted_resources:
|
||||
- "communications/onlineMeetings"
|
||||
|
||||
teams:
|
||||
enabled: true
|
||||
extra:
|
||||
client_id: "your-teams-client-id"
|
||||
client_secret: "your-teams-client-secret"
|
||||
tenant_id: "your-teams-tenant-id"
|
||||
|
||||
# outbound summary delivery
|
||||
delivery_mode: "graph" # or incoming_webhook
|
||||
team_id: "team-id"
|
||||
channel_id: "channel-id"
|
||||
# incoming_webhook_url: "https://..."
|
||||
|
||||
meeting_pipeline:
|
||||
transcript_min_chars: 80
|
||||
transcript_required: false
|
||||
transcription_fallback: true
|
||||
ffmpeg_extract_audio: true
|
||||
notion:
|
||||
enabled: false
|
||||
linear:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
## Teams Delivery Modes
|
||||
|
||||
The pipeline supports two Teams summary-delivery modes inside the existing Teams plugin.
|
||||
|
||||
### `incoming_webhook`
|
||||
|
||||
Use this when you want a simple webhook post into Teams without channel-message creation through Graph.
|
||||
|
||||
Required config:
|
||||
|
||||
```yaml
|
||||
platforms:
|
||||
teams:
|
||||
enabled: true
|
||||
extra:
|
||||
delivery_mode: "incoming_webhook"
|
||||
incoming_webhook_url: "https://..."
|
||||
```
|
||||
|
||||
### `graph`
|
||||
|
||||
Use this when you want Hermes to post the summary through Microsoft Graph into a Teams chat or channel.
|
||||
|
||||
Supported targets:
|
||||
- `chat_id`
|
||||
- `team_id` + `channel_id`
|
||||
- `team_id` + `home_channel` fallback for the existing Teams platform
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
platforms:
|
||||
teams:
|
||||
enabled: true
|
||||
extra:
|
||||
delivery_mode: "graph"
|
||||
team_id: "team-id"
|
||||
channel_id: "channel-id"
|
||||
```
|
||||
|
||||
## Step 4: Start the Gateway
|
||||
|
||||
Start Hermes normally after updating config:
|
||||
|
||||
```bash
|
||||
hermes gateway run
|
||||
```
|
||||
|
||||
Or, if you run Hermes in Docker, start the gateway the same way you already do for your deployment.
|
||||
|
||||
Check the listener:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8646/health
|
||||
```
|
||||
|
||||
## Step 5: Create Graph Subscriptions
|
||||
|
||||
Use the plugin CLI to create and inspect subscriptions.
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
hermes teams-pipeline subscribe \
|
||||
--resource communications/onlineMeetings/getAllTranscripts \
|
||||
--notification-url https://ops.example.com/msgraph/webhook \
|
||||
--client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"
|
||||
|
||||
hermes teams-pipeline subscribe \
|
||||
--resource communications/onlineMeetings/getAllRecordings \
|
||||
--notification-url https://ops.example.com/msgraph/webhook \
|
||||
--client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"
|
||||
```
|
||||
|
||||
For subscription maintenance and day-2 operator flows, continue with the guide: [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline).
|
||||
|
||||
## Validation
|
||||
|
||||
Run the built-in validation snapshot:
|
||||
|
||||
```bash
|
||||
hermes teams-pipeline validate
|
||||
```
|
||||
|
||||
Useful companion checks:
|
||||
|
||||
```bash
|
||||
hermes teams-pipeline token-health
|
||||
hermes teams-pipeline subscriptions
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | What to check |
|
||||
|---------|---------------|
|
||||
| Graph webhook validation fails | Confirm the public URL is correct and reachable, and that Graph is calling the exact `/msgraph/webhook` path |
|
||||
| Jobs do not appear in `hermes teams-pipeline list` | Confirm `msgraph_webhook` is enabled and that subscriptions point at the right notification URL |
|
||||
| Transcript-first never succeeds | Check Graph permissions for transcript resources and whether the transcript artifact exists for that meeting |
|
||||
| Recording fallback fails | Confirm `ffmpeg` is installed and the Graph app can access recording artifacts |
|
||||
| Teams summary delivery fails | Re-check `delivery_mode`, target IDs, and Teams auth config |
|
||||
|
||||
## Related Docs
|
||||
|
||||
- [Microsoft Teams bot setup](/docs/user-guide/messaging/teams)
|
||||
- [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline)
|
||||
|
|
@ -8,6 +8,8 @@ description: "Set up Hermes Agent as a Microsoft Teams bot"
|
|||
|
||||
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](/docs/user-guide/messaging/teams-meetings).
|
||||
|
||||
## How the Bot Responds
|
||||
|
||||
| Context | Behavior |
|
||||
|
|
@ -243,3 +245,8 @@ Treat `TEAMS_CLIENT_SECRET` like a password — rotate it periodically via the A
|
|||
- 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](/docs/user-guide/messaging/teams-meetings)
|
||||
- [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue