Google Chat 봇 설정 및 사용 가이드
이 문서에서는 Agentic Engine에 Google Chat 봇을 연동하는 방법을 소개하고, 관리자 설정, 일반 사용자 연결, 다이렉트 메시지와 그룹 채팅 사용, 파일 처리, 자주 묻는 질문을 설명합니다. 내용은 현재 시스템 구현을 기준으로 합니다.
현재 권장 사항: 새 Google Chat 앱은 보통 Google Workspace Add-on 모드를 사용하며, 이전 프로젝트는 기존 Chat app 모드를 계속 사용할 수 있습니다. Agentic Engine은 두 가지 HTTP 콜백 형식을 모두 지원합니다.
다이렉트 메시지만 필요하면 Join spaces and group conversations를 켤 필요가 없습니다. Space @멘션과 Thread 대화가 필요할 때 켭니다.
1. 현재 지원하는 기능
| 기능 | 상태 | 설명 |
|---|---|---|
| Google Chat 다이렉트 메시지 | 지원 | 사용자가 연결한 후 바로 메시지를 보낼 수 있으며, 봇은 같은 메시지를 편집하면서 답변을 계속 업데이트합니다. |
| Space @멘션 | 선택 사항 | Google Chat API 설정에서 Join spaces and group conversations를 켜야 합니다. 그룹 채팅에서는 반드시 봇을 명시적으로 @멘션해야 합니다. |
| Thread 대화 | 지원 | 그룹 채팅의 서로 다른 Thread는 독립된 대화 컨텍스트를 사용하며, 답변은 원래 Thread로 돌아갑니다. |
| 그룹 채팅 기능 분배 | 지원 | 관리자는 기본 Agent/Team, 호출 명령, 키워드를 설정할 수 있으며, 사용자는 기능을 명시적으로 호출하거나 자동 매칭을 사용할 수 있습니다. |
| 이미지 및 문서 입력 | 지원 | 사용자가 Google Chat에 직접 업로드한 이미지와 일반 오피스 문서를 읽습니다. Google Drive 공유 파일은 읽지 않습니다. |
| 생성 파일 | 지원 | 사용자가 OAuth 파일 인증을 완료하면 네이티브 첨부 파일로 보냅니다. 인증하지 않았거나 업로드에 실패하면 단기 HTTPS 다운로드 링크로 자동 대체합니다. |
2. 설정 전 준비
- 대상 Google Cloud 프로젝트와 Google Chat API Configuration에 대한 관리 권한 보유
- Google Chat에 접근할 수 있는 Google Workspace 계정 사용
- Agentic Engine에 공용 HTTPS 도메인으로 접근 가능
- Agentic Engine의 시스템 관리 → 채널 관리 권한 보유
- 그룹 채팅이 필요한 경우 Workspace 관리자가 조직 내 Chat app의 설치 및 사용을 허용
연동 필수 점검: Service Account JSON만 입력했다고 연동이 완료된 것은 아닙니다. Google Chat HTTP 콜백과 앱 표시 범위도 설정해야 하며, 필요에 따라 그룹 채팅과 사용자 OAuth를 활성화해야 합니다.
인스턴스와 신원: 같은 Google Chat Bot 신원을 같은 실행 환경의 여러 채널 인스턴스에 동시에 연결하거나 여러 클러스터에 동시에 연결하지 마십시오. 그렇지 않으면 중복 답변, 대화 혼선, 취소 명령이 잘못된 작업에 적용되는 문제가 발생할 수 있습니다.
두 Service Account의 차이
| 설정 | 확인 위치 | 용도 |
|---|---|---|
| Workspace Add-on 서비스 계정 이메일 | Google Chat API → Configuration → Connection settings | Google이 Agentic Engine Webhook을 호출할 때 OIDC 호출자 신원을 검증하는 데 사용합니다. 여기에는 이메일만 입력하며 키는 필요하지 않습니다. |
| 답장용 Service Account JSON | Google Cloud → IAM 및 관리자 → 서비스 계정 → 키 | Agentic Engine은 chat.bot Scope로 Google Chat API를 호출하여 봇 메시지를 보내고 업데이트합니다. |
이 두 신원은 같은 계정이 아닐 수 있습니다. JSON의 client_email로 Configuration 페이지에 표시된 Add-on 서비스 계정 이메일을 추측하거나 대체하지 마십시오.
3. 설정 절차 개요
4. 관리자 설정
1. 답장용 Service Account 생성
- Google Cloud Console에서 대상 프로젝트를 생성하거나 선택합니다.
- Google Chat API를 활성화합니다.
- IAM 및 관리자 → 서비스 계정으로 이동하여 이 봇 전용 Service Account를 생성합니다.
- Service Account의 JSON 키를 생성하고 바로 다운로드합니다.
- JSON은 민감한 자격 증명으로 보관하고, 그룹 채팅이나 티켓으로 보내거나 코드 저장소에 커밋하지 마십시오.
Agentic Engine은 https://www.googleapis.com/auth/chat.bot Scope만 사용합니다. JSON은 필요한 필드로 파싱되어 암호화 저장되며, 관리 API는 개인 키를 반환하지 않습니다.
2. Agentic Engine에서 채널 생성
- 시스템 관리 → 채널 관리로 이동하여 새 채널을 클릭합니다.
- 채널 타입으로 Google Chat을 선택하고 채널 이름, 모델, 시스템 프롬프트를 입력합니다.
- Workspace Add-on 모드를 사용하는 경우 Google Chat Configuration 페이지에 표시된 Workspace Add-on 서비스 계정 이메일을 입력합니다. 기존 Chat app 모드에서는 비워 둘 수 있습니다.
- 답장용 전체 Service Account JSON을 설정 입력란에 붙여넣습니다.
- 사용자가 자신의 신원으로 네이티브 첨부 파일을 받게 하려면 사용자 OAuth 첨부 파일 활성화를 켜고 OAuth Client ID와 Client Secret을 입력합니다.
- 채널을 저장합니다. 해당 채널을 다시 편집하여 시스템이 생성한 읽기 전용 Webhook URL을 복사합니다.
Webhook URL에는 채널 ID와 무작위 callback token이 포함되어 있습니다. 반드시 채널 관리 페이지에서 전체 주소를 복사해야 하며, 직접 입력하거나 잘라 내거나 도메인, 프로토콜, basePath, 끝의 슬래시를 수정하지 마십시오.
같은 채널의 Service Account를 업데이트해도 Webhook URL은 바뀌지 않습니다. 채널을 삭제한 후 다시 생성하면 새 주소가 생성되므로 Google Chat API Configuration도 반드시 함께 업데이트해야 합니다.
3. Google Chat API 설정: Workspace Add-on 모드
새 Chat 앱을 생성할 때 Google Cloud Console에서 Build this Chat app as a Workspace add-on이 자동으로 활성화되어 끌 수 없는 경우가 있으며, 이는 정상입니다.
- 앱 이름, HTTPS 아바타 주소, 설명을 입력합니다.
- Connection settings에서 Use a common HTTP endpoint URL for all triggers를 선택합니다.
- Agentic Engine 채널 관리 페이지의 전체 Webhook URL을 HTTP endpoint로 붙여넣습니다.
- 같은 영역에 표시된 Service Account email을 기록하여 Agentic Engine의 Workspace Add-on 서비스 계정 이메일에 입력합니다.
- 다이렉트 메시지를 위해 사용자가 Google Chat에서 이 앱을 직접 찾아 메시지를 보낼 수 있음 옵션을 유지합니다.
- Space @멘션과 Thread가 필요하면 Join spaces and group conversations를 켜고, 다이렉트 메시지만 필요하면 꺼 둡니다.
- Visibility에서 먼저 테스트 계정이나 Google Group을 추가하고, 앱 상태를 테스트 사용자가 사용할 수 있도록 설정합니다.
- 설정을 저장합니다.
현재 시스템은 Add-on의 메시지, Space 추가/제거, 버튼, Widget 업데이트, App Command 등의 이벤트를 인식할 수 있습니다. 메시지 이벤트만 Agent로 전달되며, 나머지 이벤트는 안전하게 확인 응답만 하고 대화를 트리거하지 않습니다.
4. Google Chat API 설정: 기존 Chat app 모드
- Interactive features에서 Receive 1:1 messages를 활성화합니다. 그룹 채팅이 필요하면 Spaces 참여도 함께 허용합니다.
- Connection settings에서 HTTP endpoint URL을 선택하고 전체 Webhook URL을 입력합니다.
- Authentication audience에서 HTTP endpoint URL을 선택하고, Webhook URL과 한 글자도 다르지 않게 완전히 일치하는지 확인합니다.
- Visibility를 먼저 테스트 사용자나 테스트 그룹으로 제한하고 설정을 저장합니다.
기존 모드에서는 Workspace Add-on 서비스 계정 이메일을 입력할 필요가 없습니다. Agentic Engine이 Google Chat의 시스템 서비스 신원을 검증합니다.
5. 선택: 사용자 OAuth 네이티브 첨부 파일 설정
Google Chat Media Upload API는 chat.bot 앱 신원으로 파일을 업로드하는 것을 지원하지 않습니다. 생성 파일을 네이티브 첨부 파일로 보내려면 사용자 OAuth를 추가로 설정해야 합니다.
- 같은 Google Cloud 프로젝트에서 OAuth consent screen을 설정하고 테스트 사용자 또는 게시 범위를 추가합니다.
- Web application 타입의 OAuth Client를 생성합니다.
- 현재 사이트의 전체 콜백 주소를 Authorized redirect URIs에 추가합니다:
https://{域名}{basePath}/api/google-chat-oauth/callback. - Agentic Engine 채널 관리에서 사용자 OAuth 첨부 파일 활성화를 켜고 OAuth Client ID와 Client Secret을 입력합니다.
시스템은 openid와 https://www.googleapis.com/auth/chat.messages.create만 요청합니다. OAuth Token과 Client Secret은 암호화되어 저장되며, 관리 API나 일반 로그에 표시되지 않습니다.
6. HTTPS, 리버스 프록시 및 로컬 연동 테스트
- Google Chat 콜백은 공용 네트워크에서 접근 가능한 HTTPS 주소여야 하며,
http://localhost나 내부망 HTTP 주소를 직접 사용할 수 없습니다. - 로컬 연동 테스트는 Cloudflare Tunnel, ngrok 등 HTTPS 터널을 통해 로컬 서비스로 전달할 수 있습니다.
- 공개 도메인이 바뀌면
ALLOWED_ORIGINS를 함께 업데이트하고 서비스를 재시작한 다음, Google Chat API의 전체 엔드포인트도 업데이트해야 합니다. - 리버스 프록시는
Host,X-Forwarded-Host,X-Forwarded-Proto를 올바르게 전달해야 합니다.
5. 일반 사용자: 설치 및 연결
1. Google Chat에서 앱 찾기
- 현재 Google Workspace 계정이 앱의 Visibility 또는 테스트 사용자 범위에 추가되어 있는지 확인합니다.
- Google Chat을 열고 새 채팅 또는 앱 찾기를 클릭합니다.
- Google Chat Configuration에 입력한 전체 앱 이름으로 검색합니다. Cloud Project ID, Service Account 이메일, Agentic Engine 채널 이름으로 검색하지 마십시오.
- 앱 표시가 있는 결과를 선택하여 설치합니다. 다이렉트 메시지만 사용하는 경우 1:1 대화 열기를 선택하고 Space에 추가하지 마십시오.
2. Google Chat 계정 연결
| 채널 상태 | 사용자 작업 |
|---|---|
| 관리자가 사용자 OAuth를 활성화한 경우 | Agentic Engine 왼쪽 하단 계정 메뉴의 채널 연결로 이동하여 Google Chat을 선택하고 연결 및 인증을 클릭합니다. Google 페이지에서 Google Chat에 사용 중인 계정과 같은 계정을 선택하고 인증에 동의합니다. |
| 관리자가 사용자 OAuth를 활성화하지 않은 경우 | 채널 연결에서 +bind ABC234와 같은 일회용 명령을 복사한 다음, Google Chat에서 앱에 다이렉트 메시지로 보냅니다. 연결 코드는 10분 동안 유효하며 한 번만 사용할 수 있습니다. |
| 연결했지만 파일을 인증하지 않은 경우 | 채널 연결에서 파일 인증을 클릭하고, 기존 Google Chat 연결과 같은 Google 계정을 선택합니다. 계정이 다르면 연결을 변경하거나 자격 증명을 저장하지 않습니다. |
연결 코드는 일회용 코드 유출을 막기 위해 다이렉트 메시지로만 보낼 수 있습니다. 하나의 Google Chat 계정은 하나의 Agentic Engine 사용자에만 연결할 수 있습니다. 다른 사용자에게 이미 연결되어 있다는 메시지가 표시되면 먼저 원래 계정에서 연결을 해제하십시오.
6. 일반 사용자: 대화와 명령
다이렉트 메시지
- 연결에 성공한 후 일반 텍스트를 보내면 바로 대화를 시작할 수 있습니다.
- 봇은 먼저 답장을 생성한 다음 완전한 답변이 될 때까지 계속 업데이트합니다.
+new를 보내면 새 다이렉트 메시지 대화를 시작합니다. 실행 중이거나 답변을 기다리는 작업이 있으면 먼저 상호작용을 완료하거나 취소해야 합니다.+cancel을 보내면 현재 작업을 중지합니다.
Space와 Thread
관리자가 Google Chat Configuration에서 Join spaces and group conversations를 켠 경우에만 사용할 수 있습니다.
- Space에서 @봇 + 질문 형식으로 진입 봇을 명시적으로 호출합니다.
- 같은 Thread 안에서는 같은 대화 컨텍스트가 유지되며, 서로 다른 Thread는 서로 격리됩니다.
- 관리자가 그룹 채팅 기능 분배를 설정하면 일반 질문은 기본 Agent/Team으로 전달됩니다.
+<호출 명령> <질문>,@<호출 명령> <질문>또는 설정된 키워드로 기능을 선택할 수도 있습니다. +help또는 "기능 목록"을 보내면 현재 사용 가능한 기능을 확인할 수 있습니다.+cancel을 보내면 현재 그룹 채팅 작업을 중지합니다.- 그룹 채팅에서는
+new를 사용할 수 없습니다. 새 작업을 바로 보내거나 먼저 현재 작업을 취소하십시오.
7. 이미지와 파일
사용자가 봇에게 보내는 경우
- 기본적으로 사용자가 Google Chat에 직접 업로드한 PNG, JPEG, GIF, WebP 이미지를 지원합니다.
- 기본적으로
txt,md,csv,json,pdf,doc,docx,xls,xlsx,ppt,pptx를 지원합니다. - 기본적으로 파일당 최대 2MB, 메시지당 첨부 파일 최대 5개, 첨부 파일당 다운로드 제한 시간 10초입니다. 관리자는 서버 측 설정에서 조정할 수 있지만 시스템 하드 제한을 넘을 수는 없습니다.
- Google Chat의
UPLOADED_CONTENT만 처리합니다. Google Drive에서 공유한 파일은 건너뜁니다. - 이미지와 PDF는 실제 파일 내용을 검증하며, 선언된 타입과 파일 내용이 일치하지 않으면 처리를 거부합니다.
봇이 사용자에게 보내는 경우
- 사용자가 파일 OAuth 인증을 완료한 경우 생성 파일은 원래 다이렉트 메시지 또는 원래 Space/Thread로 전송되며, 현재 사용자가 앱을 통해 보낸 것으로 표시됩니다.
- 사용자가 인증하지 않았거나 Token 새로 고침에 실패했거나 Google 업로드에 실패하면, 시스템이 서명된 단기 HTTPS 다운로드 링크를 자동으로 보냅니다.
- 다운로드 링크는 기본적으로 10분 후 만료됩니다. 만료되었거나, 원본 메시지 또는 실행이 삭제되었거나, 파일 내용이 변경된 경우에는 다시 생성해야 합니다.
- 답변에 Markdown 표가 포함되면 시스템은 기본적으로
result.csv를 생성합니다. 답변이 기본 임계값인 6000자를 넘거나 사용자가 파일을 명시적으로 요청하면result.txt를 생성합니다.
8. 자주 묻는 질문
| 증상 | 우선 확인 사항 |
|---|---|
| 앱을 검색할 수 없음 | Google Chat과 Cloud Console이 같은 Workspace 조직 계정을 사용하는지, 계정이 Visibility에 포함되어 있는지, 앱 상태가 사용 가능인지, 설정이 저장되었는지 확인합니다. 변경 후 몇 분 정도 기다려야 할 수 있습니다. |
| 앱이 응답하지 않음 / Webhook 401 | Workspace Add-on 서비스 계정 이메일이 Configuration 페이지와 완전히 일치하는지, 기존 모드의 Authentication audience에서 HTTP endpoint를 선택했는지, Webhook URL, HTTPS, 리버스 프록시, ALLOWED_ORIGINS가 올바른지 확인합니다. |
| Webhook 404 | 채널이 비활성화되거나 삭제되었는지, URL의 채널 ID와 callback token이 여전히 유효한지, 채널을 삭제 후 다시 생성한 뒤 새 URL로 업데이트했는지 확인합니다. |
| 2xx이지만 봇 답장이 없음 | 답장용 Service Account JSON이 유효한지, Google Chat API가 활성화되어 있는지, 서버 측에서 Google OAuth Token 가져오기, Chat API 호출 또는 모델 실행 시 오류가 발생했는지 확인합니다. |
| 연결 실패 | 연결 코드를 다이렉트 메시지로 보냈는지, 10분 유효 기간 내이고 아직 사용하지 않았는지, Google Chat 신원이 다른 사용자에게 이미 연결되어 있는지, OAuth에서 Chat에 사용 중인 Google 계정과 같은 계정을 선택했는지 확인합니다. |
| 이미지 또는 문서가 파싱되지 않음 | Google Drive 파일이 아니라 사용자가 직접 업로드한 파일인지, 지원되는 타입인지, 크기, 개수 또는 다운로드 제한 시간 제한을 넘지 않았는지, 서버 측에서 파일 수신이 활성화되어 있는지 확인합니다. |
| 다운로드 링크만 받고 네이티브 첨부 파일은 받지 못함 | 관리자가 사용자 OAuth를 설정했는지, 사용자가 파일 인증을 완료했는지, OAuth Token이 만료되지 않았는지 확인합니다. 업로드에 실패하면 시스템이 자동으로 다운로드 링크로 대체합니다. |
| Space에서 응답 없음 | Join spaces and group conversations를 켰는지, 메시지에서 봇을 명시적으로 @멘션했는지, 채팅 공간과 기본 Agent/Team을 설정하고 확인했는지 확인합니다. |
관련 페이지와 다음 단계
- 다른 플랫폼의 연동 안내 보기: 채널 관리.
- 채널 연동과 계정 연동의 전체 흐름 알아보기: 채널 개요 및 연동.
- 사용할 Agent 설정: Agent.
- 플랫폼 내 대화 사용 방법 보기: 대화.