에이전트를 Microsoft Teams에 연결하기
n8n v2.47요약
Microsoft Teams 채널을 사용하면 Teams의 다이렉트 메시지, 팀 채널, 그룹 채팅에서 n8n 에이전트와 대화할 수 있습니다. Microsoft Teams 채널은 다음 환경에서 사용할 수 있습니다. 에이전트용 Microsoft Teams 채널은 프리뷰 상태이며 이후 릴리즈에서 변경될 수 있습니다.
Microsoft Teams 채널을 사용하면 Teams의 다이렉트 메시지, 팀 채널, 그룹 채팅에서 n8n 에이전트와 대화할 수 있습니다.
기능 제공 범위
Microsoft Teams 채널은 다음 환경에서 사용할 수 있습니다.
- n8n Cloud: n8n 2.46.0부터 모든 플랜
- 셀프 호스팅: n8n 2.46.0부터 모든 플랜
프리뷰 상태
에이전트용 Microsoft Teams 채널은 프리뷰 상태이며 이후 릴리즈에서 변경될 수 있습니다. 프로덕션 환경에서는 의존하지 않는 것이 좋습니다.
Teams를 연결하는 방법은 두 가지입니다.
- 권장 설정: Microsoft로 로그인하면 n8n이 앱 등록, Azure Bot, Teams 앱을 대신 생성합니다.
- 수동 설정(Use your own Microsoft app으로 표시됨): 앱 등록과 Azure Bot을 직접 생성한 다음 n8n에 자격 증명을 제공합니다.
단계별 절차는 Teams 채널 설정을 참고하세요. 두 방법 모두 결과는 같습니다. 에이전트가 동작하는 위치, 메시지를 수신하는 방식, 에이전트가 스스로 보내는 메시지, 파일, Microsoft Graph 권한에 관한 섹션은 두 방법 모두에 적용됩니다.
Teams 채널의 동작 방식#
Teams 에이전트는 네 가지 구성 요소로 이루어집니다. Microsoft 측 리소스 세 가지와 n8n의 자격 증명 하나입니다.
| 구성 요소 | 역할 |
|---|---|
| Microsoft Entra 앱 등록 | 봇에 ID를 부여합니다. 단일 테넌트 앱이므로 사용자의 조직 안에서만 동작합니다. |
| Azure Bot | Teams에서 메시지를 받아 n8n으로 전달합니다. 무료 F0 티어를 사용하며 Microsoft Teams 채널이 켜져 있습니다. |
| Teams 앱 패키지 | 앱 매니페스트와 아이콘이 들어 있는 zip 파일입니다. 사용자는 Teams에서 이 앱을 추가하여 에이전트와 대화합니다. |
| Microsoft Entra Service Principal 자격 증명 | 앱 등록의 테넌트 ID, 클라이언트 ID, 클라이언트 시크릿을 n8n에 저장합니다. |
누군가 Teams에서 에이전트에 메시지를 보내면 다음과 같이 동작합니다.
- Teams가 메시지를 Azure Bot으로 보냅니다.
- Azure Bot이 메시지를 n8n 인스턴스로 전달합니다.
- n8n이 에이전트의 게시된 버전을 실행합니다.
- 에이전트가 같은 채팅 또는 스레드에 답장합니다. 에이전트가 작업하는 동안 Teams에 입력 중 표시가 나타납니다.
각 스레드는 별도의 세션이므로 에이전트는 같은 스레드의 이전 메시지를 기억합니다. 처음부터 다시 시작하려면 /new를 보냅니다. 도구에 승인이 필요하면 에이전트가 승인 카드를 게시합니다. 채널과 그룹 채팅에서는 답해야 하는 사람에게만 카드가 표시됩니다.
에이전트를 먼저 게시하세요
Teams 채널은 에이전트의 게시된 버전을 실행합니다. 에이전트를 게시하기 전에는 Teams에서 메시지를 받지 않습니다. 게시하기 전에 채널을 설정해 둘 수 있으며, 에이전트를 게시하면 n8n이 채널을 연결합니다.
사용자가 에이전트를 사용할 수 있는 위치#
Choose where it works 단계에서 사용자가 에이전트에 접근할 수 있는 위치를 정합니다. 다이렉트 채팅은 항상 켜져 있습니다. 팀 채널, 그룹 채팅, 그리고 에이전트가 해당 위치의 모든 메시지를 읽을지 여부도 켤 수 있습니다.
| 옵션 | 사용자가 사용하는 위치 | 대화 시작 방법 | 추가되는 권한 | 승인하는 사람 |
|---|---|---|---|---|
| Direct chat | 에이전트와의 일대일 채팅 | 앱을 열고 메시지를 보냅니다 | 없음 | 없음 |
| Team channels | 앱을 추가한 팀의 채널 | 팀에 앱을 추가한 다음 채널에서 에이전트를 @멘션합니다 | ChannelMessage.Read.Group |
앱을 추가할 때 팀 소유자 |
| Group and meeting chats | 앱을 추가한 그룹 채팅과 회의 채팅 | 채팅에 앱을 추가한 다음 에이전트를 @멘션합니다 | ChatMessage.Read.Chat |
채팅에 앱을 추가하는 사람 |
| Read all channel messages | 팀 채널 | 채널의 모든 메시지 | Team channels 외에 추가 없음 | 앱을 추가할 때 팀 소유자 |
| Read all group-chat messages | 그룹 채팅과 회의 채팅 | 채팅의 모든 메시지 | Group and meeting chats 외에 추가 없음 | 채팅에 앱을 추가하는 사람 |
이 표의 권한은 리소스별 동의(resource-specific consent, RSC) 권한입니다. 앱 패키지에 포함되며, 앱을 추가한 팀 또는 채팅에만 적용됩니다. 에이전트는 해당 팀 또는 채팅의 메시지와 붙여넣은 이미지를 읽을 수 있습니다. 조직의 다른 항목에 대한 접근 권한은 부여하지 않습니다.
이 옵션은 앱 패키지의 일부입니다. 나중에 옵션을 변경하면 n8n이 새 패키지를 빌드하며, 이를 다시 업로드하거나 게시해야 합니다. Teams 채널 관리를 참고하세요.
채널과 그룹 채팅에서 에이전트가 메시지를 수신하는 방식#
다이렉트 채팅에서는 모든 메시지가 에이전트를 실행하며, 에이전트가 작성하는 대로 답장이 한 단어씩 표시됩니다.
팀 채널과 그룹 채팅에서는 에이전트가 두 가지 방식으로 메시지를 수신할 수 있습니다. 답장은 에이전트가 작업을 마친 뒤 하나의 메시지로 도착합니다.
멘션할 때만#
기본값입니다. 누군가 에이전트를 @멘션할 때만 에이전트가 반응합니다.
- 누군가 에이전트를 @멘션하면 에이전트가 대화에 참여합니다. 채널에서는 해당 스레드 하나에 참여하고, 그룹 채팅에서는 채팅 전체에 참여합니다.
- 참여한 뒤에는 멘션이 없어도 해당 스레드 또는 채팅의 이후 메시지가 에이전트에 전달됩니다.
- 에이전트가 참여하지 않은 스레드나 채팅의 메시지는 에이전트에 전달되지 않습니다.
모든 메시지 읽기#
Read all channel messages 또는 Read all group-chat messages를 켜면 다음과 같이 동작합니다.
- 에이전트가 @멘션 없이 채널 또는 채팅의 모든 메시지에서 실행됩니다.
- 답장할지 여부는 에이전트가 스스로 판단합니다. 자신을 향한 메시지가 아니면 응답하지 않을 수 있습니다.
- 에이전트가 답장하지 않더라도 모든 메시지에서 모델 크레딧이 사용됩니다.
- n8n은 다른 봇이 보낸 메시지를 무시합니다.
사용자가 에이전트에 직접 도움을 요청하는 경우에는 기본값을 유지합니다. 에이전트가 전체 대화를 따라가야 하는 경우, 예를 들어 아무도 에이전트에게 지정하지 않은 질문에 답해야 할 때 모든 메시지 읽기 옵션을 켭니다. 활발한 채널에서는 모델 크레딧이 많이 사용됩니다.
에이전트가 스스로 보내는 메시지#
에이전트는 답장만 하는 것이 아닙니다. 예를 들어 "anna@example.com에게 월요일 요약을 보내 줘"와 같은 예약 작업으로 대화를 먼저 시작할 수도 있습니다.
- 다이렉트 메시지: 에이전트가 사용자에게 다이렉트 메시지를 보냅니다. 해당 사용자가 먼저 Teams에서 앱을 추가해야 합니다.
- 채널 및 그룹 채팅 게시물: 에이전트가 팀 채널 또는 그룹 채팅에 새 게시물을 시작합니다. 앱이 이미 해당 팀 또는 채팅에 추가되어 있어야 합니다.
대상에게 메시지를 보내려면 에이전트에게 해당 사용자의 Teams ID 또는 채널 ID가 필요합니다. 에이전트가 대신 조회할 수도 있습니다.
- 이메일로 조회: 에이전트가 이메일 주소로 사용자를 찾습니다.
User.ReadBasic.All이 필요합니다. - 이름으로 조회: 에이전트가 팀 이름과 채널 이름(예: "Marketing General")으로 채널을 찾습니다.
Team.ReadBasic.All과Channel.ReadBasic.All이 필요합니다.
관리자가 이러한 권한을 파일 접근 권한과 함께 승인합니다. Microsoft Graph 권한을 참고하세요. 이 권한이 없어도, 누군가 채널에서 에이전트를 @멘션한 뒤에는 해당 채널에, 또는 에이전트가 이미 Teams ID를 알고 있는 사용자에게는 메시지를 보낼 수 있습니다.
파일 및 파일 권한#
사용자는 메시지에 파일을 첨부할 수 있으며, 에이전트는 텍스트와 함께 파일을 받습니다. 파일은 각각 최대 10 MB이고, 메시지 하나에 최대 10개까지 첨부할 수 있습니다. n8n이 파일을 읽지 못하더라도 에이전트는 메시지를 받습니다.
파일이 에이전트에 전달되는 방식은 사용자가 파일을 보내는 위치에 따라 달라집니다.
다이렉트 메시지의 파일#
다이렉트 채팅에서는 Teams가 메시지와 함께 파일을 보냅니다. 추가 권한이 필요하지 않습니다.
채널과 그룹 채팅의 파일#
팀 채널과 그룹 채팅에서는 Teams가 메시지에 파일을 포함하지 않습니다. n8n이 Microsoft Graph를 통해 메시지를 다시 읽어 파일을 찾습니다.
- 붙여넣은 이미지는 앱이 이미 가진 RSC 권한(
ChannelMessage.Read.Group또는ChatMessage.Read.Chat, 사용자가 에이전트를 사용할 수 있는 위치 참고)으로 처리됩니다. 다른 권한은 필요하지 않습니다. - 첨부 파일은 SharePoint 또는 OneDrive에 저장됩니다. 파일을 다운로드하려면 앱 등록에 관리자 동의가 포함된 Microsoft Graph 애플리케이션 권한
Files.Read.All이 필요합니다. Microsoft Graph 권한을 참고하세요.
Files.Read.All이 있더라도 n8n은 다음 중 하나에 해당할 때만 파일을 다운로드합니다.
- 파일이 채널의 Files 폴더에 있습니다.
- 파일이 메시지를 보낸 사용자의 OneDrive에 있습니다.
이렇게 하면 에이전트가 대화와 관련 없는 파일을 열지 못합니다.
에이전트가 파일을 읽을 수 없는 경우#
n8n이 파일을 다운로드하지 못하면 그 이유를 에이전트에 알리므로, 에이전트가 파일을 보낸 사용자에게 이유를 설명할 수 있습니다.
| 원인 | 조치 |
|---|---|
| 아직 어떤 관리자도 권한을 승인하지 않았습니다 | 접근 승인에 설명된 대로 권한을 승인한 다음 최대 1시간 기다립니다. |
| Teams의 앱에 권한이 없습니다 | 최신 앱 패키지를 업로드하거나 게시합니다. 이전 패키지에는 RSC 권한이 없을 수 있습니다. |
| 파일이 채널의 파일에 없고 보낸 사용자가 소유한 파일도 아닙니다 | 해당 사용자에게 채널에서 또는 본인의 OneDrive에서 파일을 공유해 달라고 요청합니다. |
제한 사항#
- Teams 채널은 글로벌 Microsoft 클라우드에서만 동작합니다. 소버린 클라우드는 지원되지 않습니다.
- 봇 자격 증명은 클라이언트 시크릿을 사용해야 합니다. 인증서 인증은 지원되지 않습니다.
- 자격 증명 하나로 에이전트 하나만 Teams에 연결할 수 있으며, 에이전트 하나는 Teams 연결을 하나만 가집니다.
- 에이전트가 이름으로 채널을 찾을 때는 최대 50개 팀을 검색합니다.
- 권장 설정은 항상 West Europe의
n8n-agents리소스 그룹에 봇을 생성합니다. - 파일은 각각 최대 10 MB이며, 메시지 하나에 최대 10개까지 첨부할 수 있습니다.
- 에피소딕 메모리는 아직 Teams 대화에 적용되지 않습니다. 에이전트는 같은 스레드의 이전 메시지는 기억하지만 다른 스레드나 채팅의 컨텍스트는 기억하지 못합니다.
이 섹션의 문서#
- Teams 채널 설정: 권장 설정 또는 수동 설정으로 에이전트를 Teams에 연결하고 Microsoft Graph 권한을 승인합니다.
- Teams 채널 관리: 앱을 게시하거나 업로드하고, 업데이트하고, 클라이언트 시크릿을 갱신하고, Teams 연결을 해제하고, 일반적인 문제를 해결합니다.