Lark Bot 연동
Multica 에이전트를 Lark(飞书) 봇에 바인딩하면, Lark에서 직접 대화할 수 있습니다 — 개인 메시지나 그룹에서 @로 멘션하거나, 자연스럽게 대화하거나, /issue를 입력해 Lark를 벗어나지 않고 Multica 이슈를 생성하세요.
아무 에이전트나 Lark(飞书) 봇에 바인딩하면, 팀이 Lark 안에서 바로 그 에이전트를 사용할 수 있습니다 — 봇에게 개인 메시지를 보내거나, 그룹에서 @로 멘션하거나, /issue를 입력해 앱을 열지 않고도 Multica 이슈를 생성하세요. 에이전트의 답변은 실시간 카드로 채팅에 돌아오며, 작업이 진행되는 동안 계속 업데이트됩니다.
각 봇은 하나의 Multica 에이전트와 일대일로 바인딩됩니다. 두 번째 에이전트를 바인딩하면 두 번째 봇이 생성되며, 하나의 에이전트가 두 개의 봇을 갖는 일은 없습니다.
연동이 하는 일
| 위치 | 동작 |
|---|---|
| 에이전트 → Integrations | 에이전트 상세 페이지에 Integrations 탭이 있습니다(왼쪽 사이드바에도 대응하는 섹션이 있습니다). owner와 admin에게는 여기에 Bind to Lark가 보이며, 바인딩되면 Connected to Lark 배지와 Manage in Lark 링크로 바뀝니다. |
| 봇에게 개인 메시지 | 워크스페이스 멤버가 Lark에서 봇에게 직접 메시지를 보냅니다. 각 대화는 그 에이전트와의 Multica chat 세션이 되며, 에이전트는 해당 스레드에서 답변합니다. |
그룹에서 @ 멘션 | 봇을 Lark 그룹에 추가하고 @로 멘션하세요. 멘션한 메시지만 읽으며, 봇이 그룹 전체를 듣지는 않습니다. |
/issue 명령 | /issue <제목>(본문 추가 가능)을 입력하면 워크스페이스에 새 Multica 이슈가 생성되고, 당신 이름으로 귀속됩니다. |
| 실시간 답변 카드 | 봇은 인터랙티브 카드를 게시하고 에이전트가 실행되는 동안 계속 갱신합니다 — 진행 상황, 최종 답변, 또는 오류. |
에이전트 바인딩하기 (owner / admin)
바인딩은 스캔하여 설치하는 방식입니다 — 복사할 앱 시크릿도, 개발자 콘솔 작업도 없습니다.
- Agents → 당신의 에이전트에서 에이전트를 엽니다.
- Integrations 탭으로 이동하거나(또는 왼쪽 사이드바의 Integrations 섹션 사용) Bind to Lark를 클릭합니다.
- QR 코드가 나타납니다. 휴대폰에서 Lark → 스캔을 열고, 새로 생긴 PersonalAgent 봇을 인증하세요.
- 스캔이 완료되면 대화상자가 닫히고 에이전트에 Connected to Lark가 표시됩니다. 당신의 Lark 신원이 자동으로 Multica 계정에 바인딩되므로, 곧바로 봇과 대화를 시작할 수 있습니다.
QR 코드는 일회용이며 짧은 시간 후에 만료됩니다. 인증하기 전에 만료되면 Scan again을 클릭해 새 코드를 받으세요.
에이전트가 연결되면 Bind to Lark 버튼이 Manage in Lark 링크로 바뀝니다. 권한 범위를 조정하거나, 이름을 바꾸거나, 추가 권한을 요청해야 할 때 이 링크로 Lark에서 봇의 앱 페이지를 여세요 — 기존 봇이 고아가 되지 않도록 재스캔은 의도적으로 비활성화되어 있습니다.
봇 사용하기 (멤버)
첫 메시지: Lark 신원 바인딩하기
봇에게 처음 메시지를 보내면, Lark 신원을 바인딩하라는 카드로 답합니다. 링크를 탭하고 Multica에 로그인하면, 당신의 Lark 계정이 Multica 멤버십에 연결됩니다. 바로 이 단계가 에이전트로 하여금 당신을 대신해 행동하게 합니다 — 예를 들어 /issue는 이슈를 당신 이름으로 생성합니다.
워크스페이스 멤버만 봇을 사용할 수 있습니다. 멤버가 아니거나 신원 바인딩을 건너뛰면 봇은 응답하지 않으며, 메시지는 폐기됩니다(감사 목적으로 기록되며, 내용은 저장하지 않습니다).
대화와 /issue
- 무엇이든 에이전트에게 물어보기 — 봇에게 개인 메시지를 보내거나 그룹에서
@로 멘션하세요. 이 대화는 일반적인 에이전트 chat 세션이며, 에이전트는 카드에서 답변합니다. - 이슈 생성 —
/issue 로그인 리디렉션 수정을 보내면 Multica가 워크스페이스에 그 이슈를 생성하며, 새 이슈가 으레 할당되는 방식 그대로 처리됩니다. 제목 뒤에 줄을 더 추가하면 설명이 됩니다. - 작업 지켜보기 — 답변 카드는 에이전트가 실행되는 동안 스스로 갱신되므로, 진행 상황과 결과를 그 자리에서 볼 수 있습니다.
에이전트가 오프라인(런타임이 연결되지 않음)이거나 보관됨 상태라면, 봇은 메시지를 조용히 폐기하는 대신 짧은 상태 안내로 답합니다.
관리 및 연결 해제
워크스페이스 전체 관리는 설정 → Integrations에 있습니다.
- Connected bots는 워크스페이스 내 모든 봇과 각 봇이 바인딩된 에이전트를 나열합니다. 이 목록은 모든 멤버에게 보입니다.
- Disconnect는 owner / admin 전용입니다. 연결을 해제하면 봇이 Lark 메시지 수신을 멈추고 연결이 해체됩니다. 설치 기록은 감사용으로 유지되며, 이후 같은 에이전트를 다시 바인딩할 수 있습니다.
권한
- 바인딩 / 연결 해제에는 워크스페이스 owner 또는 admin이 필요합니다. 멤버에게는 connected-bots 목록은 보이지만 바인딩이나 연결 해제 컨트롤은 보이지 않습니다.
- 봇과 대화하기에는 Lark 신원이 바인딩된 워크스페이스 멤버여야 합니다. 그 외의 사람은 모두 폐기됩니다.
- 연동은 폐기된 메시지의 본문을 절대 저장하지 않으며 — 감사용 폐기 사유만 기록합니다.
자체 호스팅 설정
Multica Cloud에서는 연동이 이미 사용 가능합니다 — 이 섹션은 건너뛰세요.
자체 호스팅의 경우, at-rest 암호화 키를 설정하기 전까지 Lark는 꺼져 있습니다. 이 키는 각 봇의 앱 시크릿이 데이터베이스에 닿기 전에 암호화합니다.
-
32바이트 키를 생성해 API 서버에 설정합니다.
MULTICA_LARK_SECRET_KEY=<base64-encoded 32-byte key> -
API를 재시작하세요. 키가 설정되기 전까지 설정 → Integrations에는 "Lark integration not enabled" 안내가 표시되고, Bind to Lark 진입점은 숨겨진 채로 유지됩니다.
국제판 테넌트. 연동은 기본적으로 중국 본토 호스트(open.feishu.cn)를 사용합니다. 당신의 조직이 Lark 국제판 테넌트에 있다면, 전송 계층을 그쪽으로 가리키게 하세요.
MULTICA_LARK_HTTP_BASE_URL=https://open.larksuite.com