Microsoft Teams 세션

Hermes가 Microsoft Graph 세션 이벤트를 수집하고, 먼저 transcript를 가져오고, 필요하면 recording과 STT로 fallback하며, 구조화된 요약을 다운스트림 sink에 전달하길 원할 때 Teams 세션 파이프라인 사용.

이 페이지는 설정과 활성화에 집중:

• Graph 자격 증명
• webhook listener 설정
• Teams 전달 모드
• 파이프라인 config 형태

day-2 운영, go-live 확인, operator worksheet는 전용 가이드 사용: Operate the Teams Meeting Pipeline.

이 기능이 하는 일

파이프라인은:

1. Microsoft Graph webhook 이벤트 수신
2. 세션 해석 후 transcript artifact 우선
3. 사용 가능한 transcript 없으면 recording 다운로드 + STT로 fallback
4. 영구 job 상태와 sink 레코드를 로컬에 저장
5. Notion, Linear, Microsoft Teams로 요약 작성 가능

운영자 작업은 CLI에 유지 (teams-pipeline 서브커맨드는 teams_pipeline 플러그인이 등록 — hermes plugins enable teams_pipeline로 활성화하거나 config.yaml에서 plugins.enabled: [teams_pipeline] 설정):

hermes teams-pipeline validate
hermes teams-pipeline list
hermes teams-pipeline maintain-subscriptions

사전 요구사항

세션 파이프라인 활성화 전 확인:

• 작동하는 Hermes 설치
• Teams 아웃바운드 전달 원하면 기존 Microsoft Teams bot setup
• 구독할 세션 리소스에 필요한 권한을 가진 Microsoft Graph 애플리케이션 자격 증명
• Microsoft Graph가 webhook 전달용으로 호출할 수 있는 공개 HTTPS URL
• recording + STT fallback 원하면 ffmpeg 설치

Step 1: Microsoft Graph 자격 증명 추가

~/.hermes/.env에 Graph app-only 자격 증명 추가:

MSGRAPH_TENANT_ID=<tenant-id>
MSGRAPH_CLIENT_ID=<client-id>
MSGRAPH_CLIENT_SECRET=<client-secret>

이 자격 증명 사용처:

• Graph 클라이언트 기반
• 구독 유지 관리 커맨드
• 세션 해석과 artifact fetch
• 전용 Teams 액세스 토큰 미제공 시 Graph 기반 Teams 아웃바운드 전달

Step 2: Graph Webhook Listener 활성화

webhook listener는 msgraph_webhook 이름의 gateway 플랫폼. 최소한 활성화하고 client state 값 설정:

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=<random-shared-secret>
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

Listener 노출:

• Graph 알림용 /msgraph/webhook
• 간단한 헬스 체크용 /health

공개 HTTPS 엔드포인트를 해당 listener로 라우팅해야 함. 예를 들어 공개 도메인이 https://ops.example.com이면 Graph 알림 URL은 일반적으로:

https://ops.example.com/msgraph/webhook

Step 3: Teams 전달과 파이프라인 동작 설정

세션 파이프라인은 런타임 config를 기존 teams 플랫폼 항목에서 읽음. 파이프라인 전용 설정은 teams.extra.meeting_pipeline 아래 위치. Teams 아웃바운드 전달은 일반 Teams 플랫폼 config 표면에 유지.

~/.hermes/config.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 전달 모드

파이프라인은 기존 Teams 플러그인 안에서 두 가지 Teams 요약 전달 모드 지원.

incoming_webhook

Graph 통한 채널 메시지 생성 없이 Teams에 단순 webhook post 원할 때 사용.

필수 config:

platforms:
  teams:
    enabled: true
    extra:
      delivery_mode: "incoming_webhook"
      incoming_webhook_url: "https://..."

graph

Hermes가 Microsoft Graph 통해 Teams chat 또는 channel에 요약을 post하길 원할 때 사용.

지원 대상:

• chat_id
• team_id + channel_id
• 기존 Teams 플랫폼용 team_id + home_channel fallback

예시:

platforms:
  teams:
    enabled: true
    extra:
      delivery_mode: "graph"
      team_id: "team-id"
      channel_id: "channel-id"

Step 4: Gateway 시작

config 업데이트 후 Hermes 평소대로 시작:

hermes gateway run

또는 Docker로 Hermes 실행 시, 기존 배포 방식대로 gateway 시작.

Listener 확인:

curl http://localhost:8646/health

Step 5: Graph 구독 생성

플러그인 CLI로 구독 생성 및 검사.

예시:

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"

Graph subscriptions expire in 72 hours

Microsoft Graph는 webhook 구독을 72시간으로 제한하며 자동 갱신 안 함. go-live 전 hermes teams-pipeline maintain-subscriptions 반드시 스케줄링해야 함. 안 그러면 수동 구독 생성 3일 후 알림이 조용히 중단됨. operator runbook의 Automating subscription renewal 참조 — 세 가지 옵션 (Hermes cron, systemd timer, 일반 crontab).

구독 유지 관리와 day-2 운영자 흐름은 가이드 계속: Operate the Teams Meeting Pipeline.

검증

내장 검증 스냅샷 실행:

hermes teams-pipeline validate

유용한 동반 체크:

hermes teams-pipeline token-health
hermes teams-pipeline subscriptions

문제 해결

문제	확인 사항
Graph webhook 검증 실패	공개 URL이 올바르고 도달 가능한지, Graph가 정확한 /msgraph/webhook 경로 호출하는지 확인
hermes teams-pipeline list에 job 안 나타남	msgraph_webhook 활성화 여부와 구독이 올바른 알림 URL 가리키는지 확인
Transcript-first 절대 성공 안 함	transcript 리소스에 대한 Graph 권한과 해당 세션에 transcript artifact 존재 여부 확인
Recording fallback 실패	ffmpeg 설치 여부와 Graph 앱이 recording artifact 접근 가능한지 확인
Teams 요약 전달 실패	delivery_mode, 대상 ID, Teams 인증 config 재확인

관련 문서

• Microsoft Teams bot setup
• Operate the Teams Meeting Pipeline