Teams와 Slack 봇에서 채널 처리와 도구 실행 분리하기
Teams와 Slack은 사용자 식별, 스레드 처리, 재전송, 인증 방식이 다르다. 채널별 처리를 업무 코드에 넣으면 같은 도구를 실행하는 경로도 채널마다 달라진다.
채널 어댑터에서 원본 payload를 내부 메시지로 변환한다. 내부 메시지에는 인증한 사용자, 대화 식별자, 요청 내용을 담고 공통 업무 로직으로 전달한다.
구현한 범위
Teams·Slack 봇에서 사용자 요청을 인증, 도구 호출, 외부 일정 API, 채널별 응답으로 연결했다. 개발 환경의 Argo CD Application, Deployment, Service, Ingress, HPA도 작성했다. 아래 타입과 흐름은 이 경험을 설명하기 위한 공개 예제이며 회사 코드와 실제 인증 설정은 제외했다.
채널 어댑터의 책임
type IncomingMessage struct {
Channel string
TenantID string
UserID string
ConversationID string
MessageID string
ThreadID string
Text string
}
type ReplyTarget struct {
Channel string
TenantID string
ConversationID string
ThreadID string
}위 타입은 SDK 타입을 대체하는 내부 예제다. 어댑터가 요청 인증과 원본 이벤트 해석을 끝낸 뒤 이 형태로 변환한다. 응답도 공통 결과를 각 채널의 메시지·카드·스레드 형식으로 렌더링한다.
Slack의 HTTP 요청 검증에는 파싱 전 본문과 서명 헤더가 사용된다. 자세한 입력은 Slack 서명 검증 문서를 기준으로 한다. 요청이 Slack에서 왔다는 사실과 그 사용자가 업무 데이터에 접근할 권한이 있다는 사실은 별개다.
Teams도 채널 요청 검증과 업무 API를 위한 사용자 인증을 구분한다. SSO를 사용하더라도 tenant와 사용자 매핑, 토큰 만료를 처리해야 한다. 관련 흐름은 Teams SSO 문서에 설명돼 있다.
대화 상태의 키
상태 키를 user_id 하나로 만들면 같은 사용자의 서로 다른 채널이나 스레드가 섞인다. 예제에서는 (channel, tenant_id, conversation_id, thread_id)를 기본 대화 범위로 잡고, 사용자별 비공개 상태가 필요한 기능은 별도 범위로 저장한다.
동시에 메시지 두 개가 들어오면 대화 상태도 경합한다. version 조건으로 저장하거나 대화 단위 큐에서 순서를 정한다. 모델 호출 동안 DB 트랜잭션을 잡기보다, 읽은 상태의 version을 기록하고 결과 반영 시 충돌을 처리한다.
수신 중복 제거 키에는 채널과 tenant, 이벤트 식별자를 포함한다. 수신 사실만 저장한 뒤 작업 등록에 실패하지 않도록, 처리할 작업을 같은 트랜잭션에 남긴 후 채널에 수신 완료를 응답하는 구조를 고려할 수 있다.
모델은 도구 실행 요청을 만들고 서버가 검증한다
메시지 정규화
→ 사용자 업무 권한 확인
→ 대화 상태 읽기
→ 모델 호출
→ 도구 이름과 인자 스키마 검증
→ 대상 자원 권한 확인
→ 도구 실행
→ 결과를 모델에 전달
→ 응답과 상태 저장도구 목록은 서버가 등록한 allowlist로 관리한다. 모델이 만든 URL이나 함수 이름을 그대로 실행하지 않는다. inventory.lookup 같은 도구는 검증된 tenant 범위로만 조회하고, 외부 API 주소는 서버 설정에서 정한다. 공개 예제 주소는 api.example.com처럼 가상 도메인을 사용한다.
한 턴의 도구 실행 횟수, 전체 시간, 반환 데이터 크기도 제한한다. 모델의 도구 호출 ID는 응답을 연결하는 식별자이고, 업무 멱등키와 항상 같지는 않다. 쓰기 작업을 재실행할 수 있다면 사용자 요청과 업무 작업의 안정적인 식별자를 별도로 둔다.
Python에서 Go로 옮길 때
문법보다 먼저 고정할 것은 외부에 보이는 계약이다. 도구 이름과 JSON Schema, 누락·null 처리, 오류 코드, 시간대, 소수 직렬화, 대화 키를 목록으로 만든다.
공통 합성 입력을 Python과 Go 구현에 넣고 정규화된 메시지와 도구 호출 결과를 비교한다. 실제 모델 응답은 비결정적일 수 있으므로 이 비교에서는 모델과 외부 API를 stub으로 고정한다. 모델 품질 평가는 별도 입력 집합에서 한다.
Go의 context는 요청 취소와 도구 timeout에 연결한다. 채널 수신 응답을 이미 끝낸 비동기 작업은 요청 context 대신 워커가 소유한 context로 실행하되, 서비스 종료와 작업 제한 시간은 유지한다.
API 연동과 실행 환경을 함께 구성하기
일정 API 연동은 모델이 인자를 만드는 단계와 인증된 사용자 권한으로 외부 요청을 보내는 단계로 나눈다. 로그인 만료, 권한 부족, API 오류는 도구 결과에서 구분해야 채널 응답도 원인을 설명할 수 있다. 외부 요청의 결과가 불명확한 경우에는 성공이나 실패를 임의로 확정하지 않는다.
개발 환경 배포에는 Argo CD Application과 Deployment, Service, Ingress, HPA를 작성했다. 이 구성의 검토 항목은 요청 유입 경로, 인증 설정의 주입, 외부 API 접근, 대화 상태의 저장 위치다. replica가 늘어날 수 있으면 프로세스 메모리에만 둔 대화 상태와 중복 제거 기록을 공유할 방법도 필요하다.
이 글에서 설명하는 배포 경험은 매니페스트 작성 범위다. 클러스터 실행 이력과 운영 지표는 검증 근거에 포함하지 않는다.
검증할 경계
이 글의 공개 예제로 채널 연동 테스트를 실행하지는 않았다. 어댑터와 업무 로직을 나눠 다음 조건을 확인한다.
- 같은 tenant의 같은 이벤트를 두 번 보내도 쓰기 도구가 중복 실행되지 않는다.
- 같은 사용자 ID라도 tenant가 다르면 대화와 권한이 섞이지 않는다.
- 알 수 없는 도구와 잘못된 인자는 외부 호출 전에 거절한다.
- 외부 API timeout 후 쓰기 결과가 불명확하면 무조건 재실행하지 않는다.
- Python과 Go가 같은 합성 입력을 같은 내부 타입과 오류 코드로 변환한다.
공통 타입으로 표현할 수 없는 채널 기능은 해당 어댑터의 확장으로 처리한다.