Microsoft Teams — 엔터프라이즈 채팅

Hermes 에이전트를 Microsoft Teams에 연결하는 건 AI 어시스턴트에게 사원증을 달아주는 것과 같아요. 일단 팀에 합류하면, 동료들이 매일 쓰는 앱을 벗어나지 않고도 미팅에 참석하고, 채널에서 질문에 답하고, DM에서도 도움을 줄 수 있습니다.

Slack과 Teams가 다른 점

Slack의 Socket Mode를 써본 적이 있다면, Teams는 좀 다르게 동작한다는 걸 알 수 있을 거예요. 열린 연결을 유지하는 대신, Teams는 누군가 메시지를 보낼 때마다 봇의 공개 웹훅(webhook)을 호출합니다. 즉, Hermes 인스턴스에 localhost가 아닌 공개 HTTPS URL이 필요하다는 뜻이에요. 테스트할 때는 터널을 사용할 수 있고, 프로덕션에서는 실제 서버 도메인을 연결하면 됩니다.

봇 동작 방식

여기 간단한 규칙이 있어요:

어디서 대화하나	어떻게 동작하나
개인 채팅 (DM)	봇이 모든 메시지에 답장 — @멘션 필요 없음
그룹 채팅	@멘션할 때만 봇이 답장
채널	@멘션할 때만 봇이 답장

Teams는 @멘션을 <at>BotName</at> 태그로 보내지만, Hermes가 처리 전에 자동으로 제거해요 — 그러니 그 부분은 신경 쓸 필요 없습니다.

1단계: Teams CLI 설치

먼저 봇 등록을 자동화하는 Microsoft의 명령줄 도구를 설치하세요 — Azure 포털은 필요 없어요:

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

로그인을 확인하고 AAD 개체 ID(나중에 접근 제한에 필요함)를 찾으려면 다음을 실행하세요:

teams status --verbose

2단계: 웹훅 포트 노출

Teams는 localhost로 메시지를 보낼 수 없어요. 로컬 개발에서는 터널을 사용해 공개 HTTPS URL을 얻으세요. 기본 포트는 3978입니다 (필요하면 TEAMS_PORT로 변경 가능).

세 가지 쉬운 옵션이 있어요:

# 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

출력된 https:// URL을 복사하세요 — 다음 단계에서 필요합니다. 개발하는 동안 터널을 계속 실행해 두세요.

3단계: 봇 생성

이제 Teams에 봇을 등록합니다:

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

CLI가 CLIENT_ID, CLIENT_SECRET, TENANT_ID와 설치 링크를 출력할 거예요. 클라이언트 시크릿은 바로 저장하세요 — 다시 보여주지 않습니다.

4단계: 환경 변수 설정

~/.hermes/.env 파일에 다음을 추가하세요:

# 필수
TEAMS_CLIENT_ID=<your-client-id>
TEAMS_CLIENT_SECRET=<your-client-secret>
TEAMS_TENANT_ID=<your-tenant-id>

# 특정 사용자로 접근 제한 (권장)
# `teams status --verbose`에서 AAD 개체 ID 사용
TEAMS_ALLOWED_USERS=<your-aad-object-id>

5단계: 게이트웨이 시작

Docker를 사용한다면 docker-compose.yml이 있는 디렉토리에서 실행하세요 (보통 클론한 hermes-agent 저장소, ~ 아님):

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

소스 설치의 경우, 먼저 Teams 추가 기능을 포함해야 해요:

uv sync --extra teams
# 또는, editable 설치의 경우:
uv pip install -e ".[teams]"

마무리

Hermes를 Teams에 연결하는 건 네 단계 댄스와 같아요: CLI 설치, 공개 URL 노출, 봇 생성, 환경 변수 설정. 실행되면 AI 어시스턴트는 완전한 팀 구성원이 됩니다 — DM에서는 자동으로 응답하고, 그룹 채팅에서는 호출되면 참여하죠.

실용적인 팁: 처음에는 TEAMS_ALLOWED_USERS를 본인의 AAD 개체 ID로만 설정하세요. 그러면 동료들이 봇을 무작위로 트리거할 걱정 없이 안전하게 테스트할 수 있어요 — 모든 게 잘 작동한다는 확신이 들면 접근 범위를 넓히면 됩니다.