본문으로 건너뛰기
Ankole

Signal routing 규칙

AI Agent용 안내: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/signal-bindings/index.md, 전체 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.

signal routing 규칙(Signal Binding)은 유입되는 채팅 메시지나 외부 이벤트를 어느 Agent로 전달할지 결정하며 두 가지 모드를 지원합니다.

  • ai_colleague 모드: 외부 채팅 애플리케이션이나 CloudEvents 소스를 지정한 단일 AI Colleague에 연결합니다. 한 AI Colleague에 여러 규칙을 두어 여러 채팅 플랫폼을 동시에 연결할 수도 있습니다.
  • sender_personal_assistant 모드(Lark/Feishu 및 Slack 지원, agent_uid는 null): 워크스페이스 전체에서 하나의 공유 Personal Assistant Bot을 운영하며, 1:1 DM(im_dm)을 매칭된 활성 구성원 각자의 Personal Assistant(첫 사용 시 자동 생성)로 라우팅합니다. 매핑되지 않은 발신자는 수동 검토로 보류되며 게스트 계정은 이 경로를 사용할 수 없습니다.

채팅 어댑터는 수신한 메시지를 Conversation에 기록한 뒤 해석된 대상 Agent 앞으로 Signal을 생성합니다. 이와 별도로 CloudEvents 웹훅 엔드포인트를 통해서도 외부 시스템의 이벤트를 받아 Signal로 전달할 수 있습니다.

Slack, Microsoft Teams, Lark, Feishu, DingTalk 애플리케이션을 아직 준비하지 않았다면 먼저 Quick start의 Channel Provider 설정 단계를 마친 뒤 진행하세요.

routing 규칙 만들기

  1. Console에서 Signal Routing을 열고 New routing rule을 선택합니다.
  2. 사용할 Channel Provider 어댑터와 라우팅 모드를 선택합니다. 특정 AI Colleague(ai_colleague 모드)를 지정하거나, Lark/Feishu·Slack에서 발신자의 Personal Assistant(sender_personal_assistant 모드)를 선택합니다.
  3. support-slack이나 workspace-pa-lark처럼 용도가 드러나는 명확한 규칙 이름을 입력합니다.
  4. ai_colleague 규칙은 그룹 메시지 처리 모드(group-message mode)를 선택합니다(sender_personal_assistant 규칙은 1:1 DM 전용이며 미확인 발신자에 대해 항상 수동 검토를 적용합니다).
  5. Pod → Connections(Ankole.Connectors)에 등록된 기존 애플리케이션 연결(authConfigId)을 선택해 디렉터리 동기화·SSO 로그인과 동일한 앱 자격 증명을 공유하거나, 자격 증명을 직접 입력해 Ankole.Connectors에 저장한 뒤 규칙을 저장합니다.
  6. 연결한 채팅 애플리케이션에서 봇에게 테스트 메시지를 보내 대상 Agent가 정상 응답하는지 확인합니다.

봇 페르소나마다 전용 채팅 애플리케이션과 별도의 routing 규칙을 배정하세요. 여러 AI Colleague가 각기 다른 봇 계정으로 활동해야 한다면 봇별로 독립된 애플리케이션을 등록하고, 공유 Personal Assistant Bot에도 별도 애플리케이션을 할당해 신원과 메시지 흐름이 섞이지 않도록 유지하세요.

group-message mode 선택

Console 화면에는 선택한 Channel Provider가 지원하는 모드만 표시됩니다.

모드 Agent를 멘션하지 않은 그룹 메시지 처리 방식
Addressed messages only Agent가 해당 메시지를 읽지도 않고 응답하지도 않습니다.
Observe unaddressed messages 메시지가 대화 컨텍스트에는 기록되지만 Agent를 바로 깨우지는 않습니다. 이후 누군가 Agent를 호출하면 앞선 대화를 배경 맥락으로 참고할 수 있습니다.
May intervene 대화에 끼어드는 것이 도움이 될지 Agent가 먼저 판단하며, 개입이 필요하다고 결론 내린 경우에만 응답합니다.

Slack, Microsoft Teams, Lark, Feishu는 세 가지 모드를 모두 지원합니다. 반면 DingTalk와 WeCom은 봇을 명시적으로 멘션한 그룹 메시지만 수신할 수 있으므로 첫 번째 모드만 선택할 수 있습니다. 특히 WeCom은 메시지 회수 불가, 그룹 채팅 파일 전송 불가, Agent의 선제 메시지 발송 불가 등 제약이 많으므로 첫 연동 채널로는 권장하지 않습니다. 자세한 제약은 Quick start의 WeCom 탭을 참조하세요.

May intervene 모드를 선택하더라도 Agent가 모든 메시지에 일일이 답하는 것은 아닙니다. 새 메시지 묶음이 들어올 때마다 한 번씩 개입 필요성을 평가해 스스로 발화 여부를 결정합니다. 특정 그룹방에서 언제 발언해야 하는지 기준을 정해 주고 싶다면 해당 채널에서 바로 상시 지시(channel standing order)를 내려 주세요(예: “CI 빌드가 깨졌을 때만 알려 줘”). 그래도 너무 자주 개입한다면 상시 지시나 역할 지침을 먼저 더 구체적으로 다듬으세요. 개입 판정 방식과 상시 지시에 대한 자세한 내용은 Ambient intervention을 참조하세요.

명시적인 질의응답만 필요한 그룹방에는 Addressed messages only를 선택하세요.

알 수 없는 발신자 처리 선택

Ankole은 먼저 발신자의 변경되지 않는 플랫폼 사용자 ID에 연결된 활성 Human Principal을 찾습니다. 디렉터리 동기화, SSO 로그인 또는 관리자의 작업으로 이 연결을 만들 수 있습니다. 기본 수동 검토 정책에서는 채팅 프로필에 나타난 이메일이나 휴대전화 번호만으로 기존 계정에 연결하지 않습니다. 이메일 OTP(SiteCredential)로 로그인한 것만으로도 채팅 계정이 연결되지는 않습니다.

이러한 미매핑 발신자를 어떻게 처리할지는 계정 자동 매핑에 실패한 경우 설정에서 선택합니다.

옵션 동작
수동 검토(기본값) 발신자가 Console의 아이덴티티 → 대기 중인 매핑 목록에 올라갑니다. 관리자가 계정을 연결하기 전까지 Agent에게 말을 걸면 관리자에게 연락하라는 고정 안내 문구만 한 번 반환되며, 메시지 내용은 대화 컨텍스트나 Brain 학습에 반영되지 않습니다.
독립 계정 자동 생성 계정을 찾거나 생성한 뒤 바로 응답합니다. 외부 사용자도 Agent와 대화할 수 있는 개방형 채널에 적합합니다. 해당 Provider에 처음 연결하는 경우, 증명된 이메일이 활성 Human 한 명의 프로필 이메일, 검증된 개인 로그인 이메일 또는 디렉터리 연락처 별칭과 일치하면 그 Human에 연결합니다. 단, 해당 Human에게 같은 Provider의 기존 연결이 없고 오프보딩을 완료하지 않았어야 합니다. 그 외에는 플랫폼 식별자로 독립 계정을 생성합니다. 이메일이 여러 계정과 일치하거나 계정 식별자가 이미 사용 중이면 발신자를 수용하지 않으므로 관리자가 신원을 명시적으로 연결해야 합니다.

수동 검토를 기다리는 발신자가 그룹에서 Agent를 부르지 않고 나눈 일반 대화는 무시됩니다.

Telegram, Discord, LINE, WhatsApp에서는 기존 플랫폼 ID 연결이 없는 발신자를 미매핑 상태로 처리합니다. 알려진 사용자만 허용하려면 수동 검토를 유지하고 사용자별로 한 번씩 계정을 연결하세요. WhatsApp 전화번호만으로 기존 Human의 휴대전화 번호에 자동 연결되지는 않습니다.

이메일 채널은 발신자 주소를 별도의 email 네임스페이스에서 조회합니다. 명시적인 email identity 연결이나 활성 Human의 등록된 연락처 이메일과 일치하면 발신자를 수용합니다. 직원의 이메일 연결은 디렉터리 동기화나 상위 Provider 로그인으로 만들 수 있으며, 외부 연락처는 관리자가 이 Console 화면에서 연결할 수 있습니다. 이메일 OTP 로그인 주소만으로는 이메일 채널 연결이 성립하지 않습니다. Lark와 Feishu 외부 공유 그룹의 외부 테넌트 참여자에게는 사내 직원 ID가 없으므로 수동 연결이나 독립 계정 정책을 사용하세요. 이메일 OTP(SiteCredential) 사용자와 채팅 계정을 연결할 때처럼, 사용자가 첫 메시지를 보내기 전에 같은 화면에서 연결을 등록할 수도 있습니다.

채팅 내용이 Brain 지식이 되는 방식

routing 규칙은 메시지 전달 경로만 결정할 뿐 지식 공개 범위는 바꾸지 않습니다. Brain이 채팅 대화에서 지식을 추출해 학습할 때는 대화 유형과 확인된 발신자 신원을 기준으로 접근 범위를 정합니다.

  • 그룹 채팅: 학습된 지식은 해당 채널의 현재 member group 소속 구성원과 참여 Agent가 조회할 수 있습니다. 연결된 member group이 없는 그룹 채팅에서는 Brain 학습을 수행하지 않습니다.
  • 다이렉트 메시지: 학습된 지식은 대화 상대방과 해당 대화를 수행한 Agent(바인딩된 AI Colleague 또는 발신자의 Personal Assistant)만 조회할 수 있으며, 다른 Agent에는 기본적으로 공개되지 않습니다.

전사에 공유해도 되는 공개 사실은 테넌트 공통 지식으로 승격될 수 있고, 반대로 기밀로 지정된 내용은 발언자 본인에게만 제한할 수 있습니다. 별도 지정이 없는 일반 대화 내용은 위의 그룹 채팅 또는 다이렉트 메시지 공개 범위를 그대로 따릅니다. 필요한 모델 설정과 검색 동작은 Brain을 참조하세요.

규칙 편집, 비활성화 또는 활성화

규칙 목록에는 기본적으로 활성 상태인 규칙만 나타납니다. 비활성화해 둔 이전 규칙을 확인하거나 되살리려면 비활성 규칙 표시 토글을 켜세요.

규칙에서 편집을 누르면 시크릿을 제외한 현재 설정을 확인하고 대상 AI Colleague, group-message mode, 연결된 Ankole.Connectors 항목(authConfigId), 또는 채팅 자격 증명을 수정할 수 있습니다. ai_colleague 규칙의 대상 Agent를 바꾸면 이후 새로 들어오는 메시지부터 바뀐 Agent로 전달됩니다.

보안을 위해 서버는 저장된 토큰이나 시크릿 원문을 브라우저로 내려보내지 않습니다. 편집 시 자격 증명 입력란을 비워 두면 기존 암호화 값이 그대로 유지되므로, 키를 교체할 때만 새 값을 입력하세요.

비활성화를 선택하면 규칙 설정과 채팅 애플리케이션 연결, 기존 대화 기록은 보존한 채 새 메시지 전달만 멈춥니다. 다시 켜려면 비활성 규칙 표시를 켜고 해당 규칙에서 활성화를 선택하면 되며, 규칙을 새로 만들 필요가 없습니다.

Agent가 응답하지 않는 경우

  • Channel Provider 목록에 원하는 항목이 없음: Control Plane Plugins는 엄격히 사이트 범위(/api/v2/site/control-plane-plugins) 리소스이므로, 개별 테넌트나 Agent 범위의 Agent Library가 아니라 Site Admin Console의 전역 범위에서만 관리할 수 있습니다. Site Admin Console(/site-admin-console)을 열어 Agent Library 범위를 Global defaults로 맞춘 뒤 Control Plane Plugins 탭에서 해당 플러그인을 활성화하고, 화면 안내에 따라 control plane을 재시작하세요.
  • 봇이 그룹 메시지를 전혀 받지 못함: 채팅 플랫폼 측의 이벤트 구독(event subscription), 권한 범위, 앱 배포(release) 상태를 점검하세요. 또한 DingTalk와 WeCom 그룹방에서는 반드시 봇을 @ 멘션해야 메시지가 전달됩니다.
  • WeCom 동작이 예상과 다름: 먼저 Quick start의 WeCom 탭 안내와 설정을 대조해 보세요. 슈퍼 관리자가 아닌 계정으로 만든 봇, 누락된 신뢰 IP(trusted IP) 등록, 사용자가 아직 대화를 시작하지 않은 상태가 흔한 원인입니다.
  • 규칙은 저장되었는데 응답이 오지 않음: 대상 Agent가 활성 상태인지, 모델 프로필 구성에 오류가 없는지, 그리고 활성 규칙 목록에 해당 규칙이 정상 표시되는지 확인하세요.
  • 1:1 DM은 되는데 그룹방에서만 응답이 없음: 설정된 group-message mode를 확인하고 해당 그룹방에 봇이 실제로 초대되어 있는지 점검하세요.

플랫폼별 필수 권한, 구독 이벤트, 자격 증명 항목은 Quick start를 기준으로 확인하세요.

DingTalk 규칙에서 스트리밍 카드 응답을 쓰려면 DingTalk 카드 플랫폼에서 AI 카드 템플릿을 하나 생성해야 합니다. 구체적인 생성 절차는 Quick start의 DingTalk 탭 고급 섹션을 참조하세요.