본문으로 건너뛰기

문서를 읽는 일은 AI에게, 문서가 틀린 곳을 아는 일은 저희가 — 샘플과 하네스로 톡브릿지 상담 시스템 만들기

시냇물을 사이에 둔 마을 — 왼쪽에서 몸 전체가 노란 말풍선인 손님이 편지를 건네면 가운데 돌다리 캐릭터가 받아 오른쪽으로 넘겨준다. 오른쪽 강변에는 헤드셋을 쓴 상담원, 노트북을 든 곰 개발자, 작은 검수 로봇이 나란히 서서 편지를 받는다. 반대 방향으로도 답장 편지가 다리를 건너간다

그림으로 말하면 — 손님이 보낸 편지를 다리가 건네주고, 받은 쪽에서 쓴 답장을 다시 손님에게 가져다줍니다. 이 글은 저 오른쪽 강변에 여러분 방식의 창구를 세우는 이야기입니다.

이 글은 개발자(톡브릿지를 자체 시스템에 붙이는 분)를 위한 글입니다. 요즘은 개발자가 아니어도 AI에게 시켜 만드는 시대라, 각 절 머리의 그림과 그 아래 "그림으로 말하면" 박스만 따라가셔도 흐름이 잡히도록 함께 적었습니다.

• 카카오 상담을 직접 붙이려 하면 첫 수신에서 가장 오래 걸립니다. 한 통이라도 받아 보기까지가 막히면, 정작 만들고 싶었던 자동 응답이나 AI 상담은 시작조차 못 합니다. 톡브릿지는 그 문을 대신 열어 둔 서비스입니다. • 문이 열려 있어도, 주고받는 규칙을 처음부터 알고 시작하느냐는 또 다른 문제입니다. AI에게 문서를 읽혀도 한 번은 실패해 봐야 아는 것이 남습니다. • 그래서 저희가 그 규칙까지 실측으로 확인해, 동작하는 샘플 3종과 "톡브릿지 규칙을 아는 검수자"(하네스)를 한 저장소에 담았습니다. Claude Code용으로 만들었지만 스킬 호환이라 Codex에서도 그대로 씁니다. • 이 글을 따라 하면 CLI 로그인 → 샘플 실행 → AI에게 커스텀 요청 → 규칙 위반을 커밋 전에 잡기까지 갑니다. 연동하는 동안 실제 고객 문의를 놓치지 않는 수신처 조합과, 운영으로 옮기는 길도 적었습니다.

이 글의 낱말 6개

  • AI 에이전트 — 여러분이 쓰는 AI 프로그램. 문서를 읽고 코드를 써 주는 코딩 에이전트(Claude Code·Codex 등)일 수도 있고, 고객 문의에 답하는 상담 에이전트일 수도 있습니다. 이 글의 그림에서 작은 로봇으로 그린 것이 바로 이 에이전트입니다 — 실제로 돌아다니는 기계가 아니라 여러분 컴퓨터 안에서 도는 프로그램입니다.
  • 수신처 — 카카오에서 온 상담이 전달되는 곳. Discord, Slack, 웹훅 중에서 고르며, 여러 개를 함께 둘 수 있습니다.
  • 하네스 — 이 저장소의 규칙(도메인 지식)과, 그 규칙으로 코드를 검수하는 전문가 역할이 마크다운으로 적힌 폴더. AI 코딩 도구가 이것을 읽어 검수를 실행합니다.
  • 게이트웨이 — 카카오에서 온 상담을 여러분 프로그램까지 넘겨주는 중계 프로세스. 여러분 PC에서 돌리거나(로컬), 톡브릿지가 대신 돌립니다(호스티드).
  • 웹훅 — 새 상담이 오면 톡브릿지가 여러분 서버 주소로 보내 주는 알림 요청.
  • 멱등(冪等) — 톡브릿지는 알림이 유실되지 않도록 At-least-once(적어도 한 번 전송, 실패하면 재시도) 방식으로 보냅니다. 받는 서버가 성공 응답(2xx)을 돌려주지 못하면, 네트워크 끊김이나 응답 시간 초과를 포함해 같은 알림을 다시 보냅니다. 그래서 알림마다 고유 ID(X-Bridge-Delivery-Id 헤더)를 함께 실어 보냅니다. 받는 쪽에서 이 ID로 이미 처리한 알림을 건너뛰어 한 번만 처리하는 것을 멱등 처리라고 합니다.

1. 이런 순간이 있으셨나요​

첫 문이 안 열립니다​

카카오톡으로 고객 상담을 받는 서비스를 만들려다, 다른 플랫폼이나 직접 연동으로 시도하셨던 분들께 가장 많이 듣는 이야기가 이것입니다.

💬 "카카오 상담으로 들어온 내용을 처음 받아 보는 것부터가 어려워요. 답장까지는 가 보지도 못하고 연동에만 시간이 계속 갑니다."

두 칸 그림 — 왼쪽은 굳게 닫힌 나무 문 앞에 편지가 산더미처럼 쌓여 있고, 몸 전체가 노란 말풍선인 손님이 물음표를 띄운 채 서 있으며, 담 너머에서는 검수 로봇과 곰 개발자가 할 일 없이 기다린다. 오른쪽은 같은 문이 활짝 열려 편지가 줄지어 흘러 들어가고, 로봇이 그 편지를 받아 답장을 쓰고 곰이 엄지를 든다. 돌다리 캐릭터가 문을 잡아 열고 있다

그림으로 말하면 — 첫 편지가 문을 넘어오지 못하면, 담 안에서 기다리는 자동 응답도 시작할 수가 없습니다. 문을 여는 것이 언제나 먼저입니다.

받는 것이 먼저입니다. 고객이 카카오톡에 남긴 말이 우리 쪽 코드까지 도달해야 그다음이 있습니다. 그런데 카카오 상담 채널을 직접 붙이려 하면 이 첫 구간이 길어집니다. 채널을 비즈니스 채널로 올리고, 수신 주소를 어디에 어떻게 등록하는지 확인하고, 들어온 요청이 진짜인지 판별하고, 본문은 또 어디서 가져오는지 — 하나씩 풀다 보면 "일단 한 통이라도 받아 보기"까지가 며칠이 됩니다. 답장은 그 뒤의 이야기라 손도 못 댑니다.

그리고 이 문이 닫혀 있는 동안에는 그다음 단계로 아예 진입하지 못합니다. 업무 시간 외 자동 응답이든 AI 상담이든, 대응 에이전트는 받은 말이 있어야 일을 시작하기 때문입니다. 정작 만들고 싶었던 것은 그쪽인데, 문 앞에서 시간이 다 갑니다.

톡브릿지는 바로 이 자리를 없애려고 만들었습니다. 저희가 카카오 공식 상담톡 딜러사로서 채널을 제공하고, 그 채널과 여러분 시스템 사이의 다리를 저희가 놓습니다. 여러분은 문을 뚫는 일 대신 이미 열린 문 뒤에서 무엇을 할지만 정하시면 됩니다. 순서로 적으면 이렇습니다. 최초 연결(수신)은 톡브릿지가, 에이전트 활용은 여러분이. 이 글의 따라하기가 그 순서 그대로인 이유이기도 합니다 — 6절 Step 2에서 문이 열리고, Step 4에서 에이전트를 붙입니다.

문 뒤에서 만나는 두 번째 벽​

문이 열리고 나면, 이번에는 주고받는 규칙에서 걸립니다. 카카오 상담 연동을 직접 해 보신 분이라면 익숙하실 두 가지입니다.

💬 "문서 보고 AI한테 시켰더니 서명 검증이 자꾸 실패해요."

💬 "봇이 자기 답장에 자기가 또 답해요. 밤새 돌았어요."

밤늦은 책상 — 곰 개발자가 노트북 앞에서 곤란한 표정을 짓고 있고, 옆에서는 작은 로봇이 자기가 보낸 편지를 자기가 다시 받는 동그란 순환 화살표 안에 갇혀 있다. 책상 위에는 자물쇠가 채워진 채 열리지 않는 편지 한 통이 놓여 있다

그림으로 말하면 — 밤늦게 두 가지 일이 벌어집니다. 자동 응답을 맡은 AI 에이전트가 자기가 보낸 편지를 자기가 또 받아서 끝없이 답장하고, 자물쇠가 걸린 편지는 아무리 해도 열리지 않습니다. 처음 만들 때 거의 다 한 번씩 겪는 일입니다.

둘 다 규칙을 알면 간단합니다. 첫 번째는 요청 본문을 파싱했다가 다시 직렬화한 뒤 서명을 검증해서 생기고, 두 번째는 여러분이 보낸 답장이 agent라는 종류의 알림으로 되돌아오는 것을 거르지 않아서 생깁니다. 문제는 그 규칙을 처음부터 알고 시작하느냐입니다. AI에게 문서를 읽히면 읽는 시간은 줄어들지만, 한 번은 실패해 봐야 아는 것이 남습니다.

그래서 저희가 그 두 번째 벽도 미리 넘어 두었습니다. 이 글에서 드리는 샘플은 서명 검증과 agent 되돌림 거르기가 이미 들어간 채로 동작합니다. 검수 전문가가 여러분이 고친 코드에서 그 줄이 빠지지 않았는지 대신 살펴봐 주기도 합니다.

정리하면 이렇습니다.

카카오 상담을 직접 붙일 때톡브릿지로 시작할 때
① 최초 연결(수신)여러분이 뚫습니다이미 열려 있습니다
② 주고받는 규칙한 번씩 겪으며 배웁니다샘플에 들어 있습니다
③ 에이전트 활용여기까지 오기 전에 시간이 다 갑니다여기서부터 시작합니다

쉽게 말해 톡브릿지는 카카오톡으로 온 문의를 여러분 시스템으로 넘기고 답을 되돌려 보내는 다리이고, 이 글은 그 다리 위에 여러분 방식의 상담 창구를 세우는 가장 짧은 길입니다.

2. 문서를 읽는 사람이 세 번 바뀌었습니다​

세 칸 그림 — 왼쪽은 곰 개발자가 스탠드 불빛 아래 두꺼운 책을 졸며 읽는 모습, 가운데는 같은 책을 아주 빠르게 읽는 AI 에이전트(작은 로봇으로 그림) 옆에 제자리를 도는 점선 화살표가 그려진 모습, 오른쪽은 돌다리 캐릭터가 길이 이미 표시된 지도를 펼쳐 들고 그 길을 따라 곰 개발자와 에이전트가 나란히 걸어가는 모습

그림으로 말하면 — 예전에는 사람이 두꺼운 책을 읽었고, 지금은 여러분이 쓰는 AI 에이전트가 읽습니다. 빨리 읽지만 책에 없는 것은 여전히 몇 번 헤매야 압니다. 저희는 먼저 다녀와서 길을 표시한 지도를 드립니다. 지도가 있으면 사람도 에이전트도 헤매지 않습니다.

API 문서를 읽는 일이 누구의 일이었는지를 놓고 보면, 지금 저희가 드리는 저장소가 왜 그런 모양인지 설명이 됩니다.

시절누가 문서를 읽나시행착오는 어디서 나나
① AI 이전개발자가 읽고 개발합니다읽는 시간, 그리고 문서가 미처 적지 못한 것
② 지금AI가 읽고 개발합니다읽는 시간은 사라졌습니다. 문서가 미처 적지 못한 것은 그대로입니다
③ 이 저장소만든 쪽인 저희가 미리 실측으로 읽어 샘플과 지식으로 고정했습니다. AI는 그것을 기준으로 개발하고, 검수자가 규칙 위반을 잡습니다남는 것은 여러분 회사의 요구사항뿐입니다

②에서 ③으로 가려면 만든 쪽이 먼저 걸어 봐야 합니다. 그래서 저희가 저희 문서를 들고 샘플을 처음부터 만들어 봤습니다. 그 과정에서 확인이 필요한 항목 일곱 개를 찾아 적었고 — 고객 식별자 표기가 두 문서에서 달랐고, 리치 메시지 스키마가 문서에 없었습니다 — CLI에서 발견한 것들을 개선 예고 열한 건으로 정리해 그중 일곱 건을 다음 CLI 버전에 반영했습니다. 파트너가 겪었을 자리를 저희가 먼저 겪고 메워 두었다는 뜻입니다. 지금 드리는 샘플은 그 과정을 통과한 결과물입니다.

문서를 읽는 일은 AI의 일이 됐습니다. 문서가 틀리거나 비어 있는 곳을 아는 일은 아직 만든 사람의 일입니다. 그래서 그 지식을 코드와 함께 저장소에 넣었습니다.

여기서 절약되는 것은 시간만이 아닙니다. AI 코딩 도구는 문서를 읽는 데도, 읽은 것을 시도하고 실패하고 다시 시도하는 데도 토큰을 씁니다. 성공한 패턴과 그 방법이 스킬(에이전트가 읽는 지침)에 남아 있으면, 에이전트는 문서를 처음부터 읽지 않고 이미 검증된 길을 따라갑니다. 문서 읽는 시간과 시행착오의 토큰 비용이 함께 줄어듭니다.

쉽게 말해, 여행지의 공식 안내서 대신 먼저 다녀온 사람이 길 표시를 해 둔 지도와 동행 가이드를 드리는 것입니다.

3. 저장소에 무엇이 들어 있나​

뚜껑이 열린 커다란 나무 상자 — 안쪽 윗칸에는 바로 쓸 수 있는 모형 집 세 채와 둘둘 말린 지도 한 장이, 아랫칸에는 방패·체크리스트·돋보기·수첩을 각각 든 작은 검수 로봇 넷이 들어 있다. 옆에 선 돌다리 캐릭터가 상자 안을 손으로 가리킨다

그림으로 말하면 — 상자를 열면 바로 쓸 수 있는 집 세 채와 지도 한 장, 그리고 검사를 맡는 작은 에이전트들이 들어 있습니다. 집은 상황에 맞는 것을 골라 쓰고, 검수 에이전트는 여러분이 고친 곳을 대신 살펴봅니다.

저장소는 https://github.com/BlumnAI-Playground/talk-bridge 입니다. 세 폴더로 이루어져 있습니다.

경로내용
docs/공개 매뉴얼 요약. 도메인 모델, API·CLI 스펙, 요금, 온보딩을 실측 표기와 함께
sample-project/연결 방식별로 동작하는 샘플 3종
harness/톡브릿지 규칙(지식)과 그 규칙으로 검수하는 전문가 역할, 검수 워크플로우

샘플 3종 — 어느 것을 고를까​

세 샘플은 같은 상담 화면을 서로 다른 연결 방식으로 구현합니다. 발신(여러분이 고객에게)은 어느 방식이든 같습니다. 갈리는 지점은 수신(고객이 여러분에게)입니다. 카카오에서 출발한 메시지가 여러분 코드까지 닿는 마지막 한 구간을 누가 뚫느냐가 다릅니다.

#샘플이런 때연결 방식공개 도메인
0101-cli-gatewayCLI로 기본 채팅상담 화면을 빨리 만들고 싶을 때. 노트북·사내망에서 도메인 없이 바로 검증CLI + 로컬 게이트웨이불필요
0202-api-webhook이미 운영 중인 서버에 상담을 붙일 때. 영속 전달과 넉넉한 재시도REST API + 호스티드 웹훅필요
0303-cli-knowledge-graph과거 상담을 분석하거나 자동 상담의 근거 데이터를 만들고 싶을 때01 + 상담지식 그래프 조회불필요

01은 게이트웨이 데몬이 여러분 쪽에서 밖으로 나가 톡브릿지에 붙습니다(SSE, Server-Sent Events — 서버가 열린 연결로 이벤트를 밀어 주는 방식). 외부에서 여러분 쪽으로 들어오는 연결이 없으니 공인 도메인, DNS, TLS 인증서, 방화벽 개방, 개발용 터널이 전부 필요 없습니다. 대신 데몬이 살아 있어야 수신되고, 재시도는 메모리 안에서 세 번뿐입니다. 02는 톡브릿지가 여러분 공개 주소로 직접 찾아옵니다. 그 인프라가 필요한 대신 전달이 영속되고 재시도가 다섯 번(1초→5초→30초→2분→10분)으로 넉넉합니다. 24시간 운영이고 유실이 곧 손실이면 02입니다.

둘은 갈아탈 수 있습니다. 브랜드 키, 고객 키, 알림 종류, 순번이라는 도메인 모델과 서명 방식이 양쪽에서 같아서, 수신 처리 코드는 그대로 두고 누가 전달하느냐만 바꾸면 됩니다. 실제로 02는 01의 서명·저장·실시간 전송 파일 세 개를 그대로 쓰고, 수신 처리 파일에서 본문 조회 두 줄만 바꿨습니다. 01로 검증하고 02로 승격하는 경로가 자연스러운 이유입니다.

03은 01을 손대지 않고 복제한 뒤, CLI에 내장된 상담지식 그래프를 미리 만들어 둔 조회 10종으로 탐색하는 패널을 붙인 것입니다. 데모성 구현이며 실 운영에서는 규모에 맞는 그래프 DB를 따로 두는 것을 권합니다.

검수 로봇이 돋보기를 들고 떠 있는 별자리 지도를 들여다본다. 지도의 동그란 점들은 말풍선 손님, 물음표 카드(문의), 편지(응답), 작은 이름표(언급된 낱말)이고 가느다란 선으로 이어져 있다. 로봇이 따라가는 한 갈래 길이 노란빛으로 빛난다. 아래에는 지난 상담 편지 묶음이 쌓여 그 별자리로 이어진다. 옆에서 돌다리 캐릭터가 흐뭇하게 바라본다

그림으로 말하면 — 지난 상담을 낱개로 쌓아 두지 않고 서로 이어진 지도로 만듭니다. 한 손님이 무엇을 묻고 어떤 답을 받았는지, 그 길을 따라가며 볼 수 있습니다.

하네스 — 톡브릿지 규칙을 아는 검수자​

harness/ 안에는 두 가지가 있습니다. 하나는 지식입니다. 수신 웹훅 계약(서명·신뢰성·도메인 모델), CLI 스펙, REST 스펙, 상담지식 그래프 스키마, 샘플 이식 제약, 로컬 개발 터널 절차, Windows 셸에서 한글이 깨지는 경로 같은 것이 실측으로 적혀 있습니다. 다른 하나는 그 지식을 기준으로 코드를 검수하는 전문가 역할입니다.

전문가보는 것
웹훅 경비대장서명 검증, 시크릿 취급, 멱등, 인젝션, agent 되돌림 무한 루프
이식 감독관의존성 0, Node 18+, Windows/macOS/Linux, README와 실행의 일치
문서 대조관공개 매뉴얼 요약 ↔ README ↔ 코드의 스펙 드리프트
개선 수집관실측으로 드러난 CLI·API·문서의 결함과 제약을 다음 개선 예고 스펙으로

이 하네스는 Claude Code 플러그인 형태로 만들어졌습니다. 그런데 실체는 마크다운으로 적힌 스킬(에이전트 지침)이라, 스킬을 읽는 다른 코딩 에이전트에서도 그대로 씁니다. Codex에서 같은 저장소를 열고 harness/를 읽히면 같은 규칙으로 같은 검수를 시킬 수 있습니다. 슬래시 명령 이름이 다를 뿐, 지식과 검수 기준은 하나입니다.

4. 연동하는 동안 들어오는 고객 문의는 누가 받나​

왼쪽에서 몸 전체가 노란 말풍선인 손님이 편지 한 통을 부치면, 가운데 돌다리 캐릭터가 그 편지를 똑같이 세 통으로 만들어 세 갈래 길로 동시에 보낸다. 위쪽 길 끝에는 헤드셋을 쓴 상담원이 답장을 써서 되돌려 보내고, 가운데 길 끝에는 비계가 둘러쳐진 공사 중인 집에서 곰 개발자가 노트북으로 작업 중이며, 아래쪽 길 끝에서는 검수 로봇이 편지를 읽고 수첩에 적기만 한다. 되돌아오는 화살표는 위쪽 길에만 있다

그림으로 말하면 — 손님이 보낸 편지를 다리가 여러 장으로 똑같이 나눠 줍니다. 사람이 있는 곳, 공사 중인 우리 집, 기록만 하는 보조 에이전트에게 동시에 갑니다. 답장은 그중 한 곳에서만 보냅니다.

채널 연동에는 오래된 딜레마가 있습니다. 카카오 채널을 열고 상담 시스템을 붙이는 동안에도 고객은 기다려 주지 않습니다. 개발 중인 시스템으로 실제 문의가 들어오면 대응을 못 합니다. 그래서 지금까지는 두 가지 우회를 써 왔습니다. 채널이 검색되지 않게 막아 두고 개발하거나, 별도 환경에서 연동을 끝낸 뒤 운영 채널로 옮기는 것입니다. 옮기는 쪽은 새 키 발급, 채널 재설정, 배포 사이클까지 따라옵니다. 같은 일을 한 번 더 겪는 셈입니다.

톡브릿지에서는 이 딜레마를 수신처 구조로 풉니다. 센터의 상담 수신처는 Discord, Slack, 웹훅 중 하나만 고르는 자리가 아닙니다. 여러 개를 함께 둘 수 있고, 들어온 상담은 설정된 수신처 모두에 팬아웃됩니다. 하나가 실패해도 나머지는 계속 받습니다. 그래서 연동 순서를 이렇게 잡을 수 있습니다.

  1. 먼저 Discord 또는 Slack을 수신처로 연결합니다. 코드 없이 설치 버튼으로 끝나고, 이 순간부터 실제 고객 문의는 그 채널의 스레드에서 사람이 받습니다.
  2. 그 상태에서 웹훅(또는 01의 게이트웨이)을 두 번째 수신처로 붙이고 개발합니다. 같은 문의가 개발 중인 시스템에도 들어오니 실제 데이터로 검증하면서, 고객 응대는 Discord/Slack에서 끊기지 않습니다.
  3. 개발이 끝나면 어느 쪽에서 답할지 정합니다. 키를 새로 받거나 채널을 다시 설정하지 않습니다. 이미 연결된 것 중에서 고르는 일입니다.

운영에 들어가면 답하는 창구는 하나만 두시기를 권합니다. 기능의 제약이 아닙니다. 같은 문의에 두 곳에서 답하면 상담이 단일 지점에서 이루어지지 않는 운영 혼선의 문제입니다. 다만 "답하는 곳"이 하나라는 뜻이지 "연결"이 하나라는 뜻은 아닙니다. 연결에 제약이 없다는 점을 쓰면 조합이 나옵니다.

연결맡는 일고객에게 답하나
Discord / Slack개발 중 응대, 운영 후에는 폴백개발 중에는 예. 운영 후에는 커스텀 시스템이 내려갔을 때만
웹훅(02) 또는 게이트웨이(01)여러분 회사 방식의 상담 시스템운영 후 예
CLI 게이트웨이 + 보조 에이전트상담 요약, 분류, 태그, 그래프 적재 같은 보조 업무아니오. 읽기만 합니다
  • 폴백. 커스텀 시스템을 계속 개발하면서도 Discord/Slack 연결을 그대로 두면, 배포 중이거나 시스템이 내려간 동안에도 문의는 그 채널에 도착합니다. 두 연결을 상호 운영하는 방식입니다.
  • 보조 에이전트. 응대는 한 곳에서 하고, 다른 연결에는 답하지 않는 에이전트를 붙입니다. 상담이 끝날 때마다 요약을 남기거나, 문의를 분류하거나, 03 샘플처럼 그래프에 적재하는 일입니다. 조회는 과금되지 않으니 읽기만 하는 에이전트는 상담 건수를 쓰지 않습니다.
  • 레고 블록처럼. 답하는 창구 하나, 폴백 채널 하나, 보조 에이전트는 필요한 만큼. 필요한 기능을 끼우고 빼는 단위가 수신처입니다.

쉽게 말해, 상담이 도착하는 문은 여러 개 열어 두고 답장은 한 문으로만 내보내는 것입니다. 수신처 설정은 톡브릿지 센터에서 바꿉니다(https://api.talkbridge.io/center/setup-status/).

한 가지만 주의하시면 됩니다. 여러분이 어느 연결에서 답하든 그 답장은 agent 알림으로 모든 수신처에 되돌아옵니다. 보조 에이전트도 그 알림을 걸러야 합니다. 7절의 첫 번째 항목이 여기서도 적용됩니다.

5. 준비물​

준비물어디서 확인하나
Node.js 18 이상node -v
톡브릿지 센터 브랜드, 카카오 채널 연결과 상담 활성화센터의 설정 5단계(브랜드 생성 → 채널 등록 → 채널 인증 → 수신처 연결 → 상담 활성화). https://api.talkbridge.io/center/setup-status/
Discord 또는 Slack 수신처 (권장)위 5단계의 네 번째, 수신처 연결에서 먼저 골라 둡니다. 연동하는 동안 고객 문의를 받는 자리입니다 (4절)
톡브릿지 CLInpm install -g @blumn-ai/talkbridge-cli
AI 코딩 도구Claude Code(플러그인 설치) 또는 Codex 같은 스킬 호환 에이전트
공인 HTTPS 주소 또는 터널02로 옮길 때만. 01은 필요 없습니다

카카오 채널의 비즈니스 심사가 아직이라면, 센터는 멈춘 단계를 저장해 두니 심사가 끝난 뒤 이어서 진행하시면 됩니다.

6. 따라하기​

다섯 개의 넓은 계단을 노트북을 든 곰 개발자가 왼쪽에서 오른쪽으로 올라간다. 첫 계단에는 열쇠, 둘째 계단에는 켜진 작은 화면, 셋째 계단에는 방패를 든 검수 로봇, 넷째 계단에는 스패너가 들어 있는 말풍선, 다섯째 계단에는 집과 이삿짐 수레가 놓여 있다. 계단 꼭대기에서 돌다리 캐릭터가 손을 흔들며 기다린다

그림으로 말하면 — 열쇠를 받고, 화면을 띄우고, 검수 에이전트를 부르고, 원하는 기능을 말하고, 새 집으로 옮깁니다. 계단 다섯 개입니다. 한 계단씩 올라가면 됩니다.

Step 1 — CLI 로그인, 브랜드 키 확인​

npm install -g @blumn-ai/talkbridge-cli
talkbridge login      # 브라우저 페어링
talkbridge whoami     # 브랜드 키 확인

확인: whoami에 브랜드 키가 보이면 된 것입니다. 이 키 하나로 CLI, MCP(Model Context Protocol, AI 앱에 외부 도구를 붙이는 표준 규격), API를 모두 씁니다.

Step 2 — 샘플 01 띄우기​

git clone https://github.com/BlumnAI-Playground/talk-bridge
cd talk-bridge/sample-project/01-cli-gateway
cp .env.example .env                 # TB_BRAND, TB_WEBHOOK_SECRET 채우기
npm run doctor                       # 진단
npm run gateway:setup && npm run gateway:start
npm start                            # http://127.0.0.1:8787/

TB_BRAND에는 방금 확인한 브랜드 키를, TB_WEBHOOK_SECRET에는 긴 무작위 문자열을 넣습니다. gateway:setup이 그 시크릿을 CLI 게이트웨이에 그대로 넘겨서 양쪽이 같은 값으로 서명하고 검증합니다.

곰 개발자가 책상 앞 큰 모니터를 보고 있다. 화면은 세 칸으로 나뉘어 왼쪽에는 차례를 기다리는 말풍선 손님 목록, 가운데에는 주고받는 대화 말풍선, 오른쪽 좁은 칸에는 편지가 실시간으로 하나씩 쌓인다. 모니터 옆에서 돌다리 캐릭터가 새 편지를 화면 안으로 넣어 준다

그림으로 말하면 — 여기까지 하면 화면이 하나 뜹니다. 왼쪽은 기다리는 손님, 가운데는 주고받은 말, 오른쪽은 방금 도착한 편지입니다. 이 화면이 여러분 상담 창구의 출발점입니다.

확인: 브라우저에 상담방 목록, 대화, 수신 로그 세 패널이 뜹니다. 카카오톡에서 여러분 채널로 메시지를 보내면 오른쪽 로그에 message 이벤트가 쌓이면 된 것입니다. 1절에서 말한 첫 문이 여기서 열립니다. 뚫으신 게 아니라 이미 놓인 다리를 건너신 것이고, 그다음은 전부 이 위에 얹는 일입니다. 4절대로 Discord/Slack을 먼저 연결해 두셨다면 같은 메시지가 그 채널 스레드에도 동시에 도착합니다. 팬아웃이 되는지 여기서 함께 확인하시면 됩니다. 여기까지 도메인도 터널도 열지 않았습니다.

Step 3 — 하네스 검수자 부르기​

Claude Code라면 플러그인을 설치하고 정원지기(하네스를 관리하는 기본 에이전트)를 부릅니다.

/plugin marketplace add psmon/harness-kakashi
/plugin install harness-kakashi@harness-kakashi-skills

/harness-creator                ← 현재 상태와 사용법 안내
/harness-creator 전체 점검해      ← 전문가가 샘플 전체를 검수하고 종합 보고

한 번 부른 뒤에는 슬래시 없이 보안 점검해, 문서 검증해처럼 말하면 됩니다. Codex 등 다른 에이전트라면 저장소를 연 뒤 harness/docs/README.md와 harness/knowledge/를 읽히고 같은 요청을 하면 됩니다. 지침이 마크다운이라 읽는 쪽이 누구든 같은 기준이 적용됩니다.

확인: 전문가별 보고서가 심각도(P0 복사하면 사고 ~ P3 가독성)와 함께 나오면 된 것입니다. 첫 실행은 이미 검수를 통과한 샘플이라 문제가 없어야 정상입니다. 이것이 기준선입니다.

Step 4 — 커스텀 요청​

이제 여러분 회사의 요구사항을 말합니다. 저장소 README에 있는 예시를 그대로 옮깁니다.

sample-project/01-cli-gateway 에 업무시간 외 자동 응답을 넣어줘
  → schedule 밖 시간에 message 가 오면 안내 문구를 send 하고,
    agent echo 는 응답 대상에서 제외

sample-project/01-cli-gateway 를 기반으로 AI 상담봇을 만들어줘
  → webhook.js 본문 보강 직후 LLM 호출,
    사람 이관 키워드가 오면 상담원 화면으로 넘김

에이전트는 하네스의 지식(웹훅 계약, CLI 스펙, 이식 제약)을 기준으로 구현합니다. 구현이 끝나면 한 마디 더 합니다.

변경 점검해

확인: 보고서가 agent 되돌림 필터, 서명 검증, 활성 세션 밖 발신을 점검했다고 적혀 있으면 된 것입니다. 1절의 두 번째 벽이 나오는 자리가 바로 여기이고, 커밋 전에 잡힙니다. 이 단계 내내 Discord/Slack 수신처가 고객 응대를 이어 가고 있으니, 커스텀 시스템이 몇 번 죽어도 문의는 놓치지 않습니다.

Step 5 — 운영으로 옮기기​

상시 운영이라면 02로 승격합니다. 이때도 키를 새로 받거나 채널을 다시 설정하지 않습니다. 02를 수신처로 하나 더 붙이고, 답하는 창구를 02로 옮기고, Discord/Slack은 폴백으로 남깁니다. 수신 처리 파일은 그대로 두고 webhook.js의 본문 조회 두 줄만 CLI에서 REST로 바꿉니다. 그리고 샘플이 메시지를 프로세스 메모리에만 담아 두는 것을 데이터베이스로 바꾸는 요청이 첫 단계입니다.

sample-project/01-cli-gateway 의 인메모리 저장소를 SQLite 로 바꿔줘
  → delivery_id UNIQUE 멱등 테이블 + 메시지 테이블

확인: 02 폴더에서 npm run doctor가 통과하고, 호스티드 게이트웨이에서 답장 1건에 agent 되돌림이 두 번 오는 것을 로그로 봅니다. 즉시 오는 것은 발신 접수 신호(seq 없음), 약 1초 뒤 오는 것은 저널 항목(seq 있음)입니다. 재시도로 생긴 중복과는 별개로 원래 두 단계로 오도록 된 동작이고, 02 README §6.5에 실측이 있습니다.

7. 이렇게 하면 막힙니다​

구불구불한 길 위에 표지판이 세워진 네 군데의 위험 지점 — 편지가 제자리를 도는 순환 화살표, 봉인이 깨진 편지, 자물쇠가 걸린 문 앞에 기대선 편지, 불 꺼진 가로등 옆에서 잠든 검수 로봇. 길 입구에 선 돌다리 캐릭터가 표지판들을 가리킨다

그림으로 말하면 — 길에 미리 세워 둔 표지판입니다. 편지가 제자리를 도는 곳, 봉인이 깨지는 곳, 문이 잠긴 곳, 지킴이가 잠든 곳. 이 네 군데만 조심하시면 됩니다.

  1. kind: "agent"를 거르지 않은 자동응답. 여러분이 보낸 답장이 알림으로 되돌아옵니다. 거르지 않으면 봇이 자기 답장에 답하는 무한 루프입니다. 샘플은 걸러 두었으니 커스텀할 때 그 줄을 지우지 마세요. 수신처가 여럿이면 이 알림은 모든 수신처에 갑니다.
  2. 파싱한 본문으로 서명 검증. 서명은 받은 그대로의 원문 바이트로 계산해야 합니다. JSON으로 파싱했다가 다시 문자열로 만들면 공백 하나 차이로 실패합니다.
  3. 처리 실패에 4xx 응답. 4xx도 재시도 대상입니다. 정상 처리는 무조건 2xx를 먼저 돌려주고, 실제 처리는 그 뒤에 비동기로 합니다.
  4. 세션이 끝난 고객에게 발신. 카카오 상담톡은 활성화된 세션에만 보낼 수 있습니다. 그리고 발신은 상담 건수를 씁니다. 상담 1건은 하루에 응대한 고객 1명입니다. 조회와 설정은 과금되지 않습니다.
  5. 01 게이트웨이 데몬이 죽어 있음. 데몬이 없으면 수신이 멈춥니다. 재기동하면 그동안의 이벤트를 다시 재생하지만, 상시 운영이라면 02로 가세요.
  6. Windows에서 npm 셸 래퍼로 CLI 호출. (Windows에서 개발하지 않으시면 건너뛰셔도 됩니다.) 자동화 스크립트는 바이너리를 직접 실행하세요. 한글 메시지가 깨지는 경로가 있어서, 안전한 경로를 하네스 지식(windows-shell-encoding.md)에 표로 적어 두었습니다.
  7. knowledge <하위명령> --help. 지금 버전에서는 도움말이 아니라 명령이 실행됩니다. knowledge help를 쓰세요. 이런 알려진 한계와 우회는 harness/knowledge/cli-feat/README.md에 한 표로 있습니다. 설계 전에 한 번 훑어보시면 됩니다.
  8. 수신처를 하나만 걸고 개발 시작. 개발 중에 들어온 실제 문의를 받을 곳이 없습니다. 4절대로 Discord/Slack을 먼저 연결하고, 운영 후에도 폴백으로 남겨 두세요. 반대로 운영에서 두 곳이 동시에 답하는 것도 피하세요.

8. 다음 단계​

  • 과거 상담을 그래프로 보고 싶다면 03 샘플을 열어 보세요. 여러분 채널에 쌓인 실제 상담으로 고객·문의·응답 그래프를 만들고, 미리 준비된 조회로 탐색해 볼 수 있습니다.
  • 코드 없이 Claude나 ChatGPT 대화창에서 카카오 상담을 답하는 방법(MCP와 브릿지 스킬)은 운영자편으로 준비하고 있습니다.
  • 막히는 곳이 있으면 저장소 이슈나 Discord로 알려 주세요. 개선 수집관이 모으는 다음 개선 예고에 파트너의 실측이 그대로 들어갑니다.

톡브릿지 센터에서 카드 등록 없이 시작하실 수 있습니다. 30일 동안 상담 3건이 무료입니다. https://console.talkbridge.io/ · 문서 https://api.talkbridge.io/ · 막히시면 help@talkbridge.io

참고​