Chat SDK로 사용자에게 에이전트를 제공하세요

올해 1월 초, 우리는 회사 전체에 하나의 과제를 던졌습니다. 각자의 생산성을 몇 배로 끌어올릴 방법을 찾아보라는 것이었습니다.

사람들은 에이전트를 만들기 시작했습니다. 대부분 챗봇이었지만, 단순한 챗봇이 아니라 실제 업무 흐름을 개선하기 위해 특정 목적에 맞춰 설계된 전용 에이전트였습니다. 사람이 직접 하면 지루하고 시간이 오래 걸리는 작업을 에이전트가 자동으로 처리해 주었습니다.

처음에는 각자 에이전트마다 개별 인터페이스를 만들었고, AI SDK 덕분에 모델 통합과 AI Elements를 활용한 UI 설계가 수월했습니다.

그러다 제약에 부딪혔습니다. 사람들이 Slack에서 에이전트와 소통하고 싶어 했고, 결국 모두가 Slack API 연동 방법을 각자 알아내야 했습니다.

문제는 더 심해졌습니다. Slack에 에이전트를 연결하고 나니, Discord, GitHub, Linear 같은 이슈 트래커까지 더 많은 플랫폼과 통합하고 싶어 했습니다. 플랫폼이 하나 추가될 때마다 에이전트마다 새로운 연동 작업이 필요했습니다.

그때 깨달았습니다. 사람들에게 에이전트를 찾아오라고 할 게 아니라, 사람들이 이미 일하고 있는 곳으로 에이전트를 보내야 한다는 것을.

채팅에는 통합 추상화가 필요하다

에이전트를 만드는 건 쉬워졌지만, 여러 플랫폼에 걸쳐 에이전트를 확장하고 도입하는 과정은 여전히 어렵다는 사실을 깨달았습니다.

이건 모든 기업에 해당하는 문제입니다. 사람들은 이미 Microsoft Teams, WhatsApp, Telegram, Google Chat을 사용하고 있으며, 에이전트는 이 모든 곳에서 이용 가능해야 합니다.

Chat SDK가 하는 일이 바로 이것입니다. 기업용·일반 사용자용 채팅 플랫폼 전반에 에이전트를 제공하는 것입니다.

AI SDK가 여러 모델 제공자의 API를 하나의 인터페이스로 통합한 것처럼, Chat SDK는 각 메시징 API의 복잡한 차이를 추상화하여 개발자와 코딩 에이전트가 사용할 수 있는 간결한 프레임워크로 만들었습니다.

이제 개발자는 플랫폼마다 스트리밍 방식이 어떻게 다른지, 포매팅·분기 로직·리액션 처리를 각 API에 맞춰 어떻게 구현해야 하는지 고민할 필요가 없습니다.

한 번 작성하면 어디서든 배포

Chat SDK는 하나의 코드베이스로 Slack, Microsoft Teams, Google Chat, Discord, Telegram, GitHub, Linear에서 동작하는 봇을 만들 수 있는 TypeScript 라이브러리입니다. 핵심 chat 패키지가 이벤트 라우팅과 애플리케이션 로직을 담당하고, 플랫폼별 동작은 어댑터가 처리합니다. 배포 대상이 바뀌어도 핸들러 코드를 수정할 필요가 없습니다.

기본적인 봇의 구조는 다음과 같습니다:

각 어댑터는 환경 변수에서 인증 정보를 자동으로 감지하므로, 별도의 설정 없이 바로 시작할 수 있습니다. Slack에서 Discord로 전환할 때 봇을 다시 작성할 필요 없이 어댑터만 교체하면 됩니다.

플랫폼 간 차이, 알아서 처리

플랫폼마다 동작 방식이 크게 다릅니다. Chat SDK는 이 차이를 무시하거나 억지로 통일하지 않습니다. 대신 어댑터 계층에서 처리하여 애플리케이션 코드가 이를 신경 쓰지 않아도 되게 합니다.

스트리밍을 예로 들어 보겠습니다. Slack은 네이티브 스트리밍 경로를 지원하여 응답이 도착하는 대로 굵게, 기울임, 목록 등의 서식을 실시간으로 렌더링합니다. 다른 플랫폼은 폴백 스트리밍 경로를 사용하여, 스트리밍되는 텍스트를 중간 편집 단계마다 각 어댑터의 마크다운→네이티브 변환 파이프라인을 통해 처리합니다.

Chat SDK 도입 전에는 어댑터가 원시 마크다운 문자열을 그대로 받았기 때문에, Discord나 Teams 사용자는 최종 메시지가 완성될 때까지 **bold** 문법이 그대로 노출되었습니다. 이제 이 변환은 자동으로 이루어집니다.

테이블 렌더링도 같은 방식으로 동작합니다. Table() 컴포넌트는 모든 어댑터에서 테이블을 렌더링할 수 있는 조합형(composable) API를 제공합니다. 헤더와 행을 전달하면 나머지는 Chat SDK가 알아서 처리합니다. Slack은 Block Kit 테이블 블록으로, Teams와 Discord는 GFM 마크다운 테이블로, Google Chat은 고정폭 텍스트 위젯으로, Telegram은 코드 블록으로 변환합니다. GitHub과 Linear는 기존 마크다운 파이프라인을 그대로 사용합니다.

카드, 모달, 버튼도 마찬가지입니다.

JSX로 요소를 한 번만 작성하면 각 어댑터가 해당 플랫폼이 네이티브로 지원하는 형식에 맞춰 렌더링합니다. 특정 요소를 지원하지 않는 플랫폼에서는 자연스럽게 폴백 처리됩니다.

단일 플랫폼만 사용하더라도 Chat SDK가 필요한 이유

에이전트가 Slack 하나만 지원하더라도 Chat SDK는 실질적인 문제를 해결해 줍니다. 채널명과 사용자명이 자동으로 일반 텍스트로 변환되어 에이전트가 대화 맥락을 정확히 이해할 수 있습니다.

이 변환은 양방향으로 동작합니다. 에이전트가 일반 텍스트로 누군가를 멘션하면, Chat SDK가 Slack에서 실제 알림이 발생하도록 처리해 줍니다.

에이전트가 제대로 동작하려면 충분한 컨텍스트가 필요합니다. Chat SDK는 링크 미리보기 콘텐츠, 참조된 게시물, 이미지를 에이전트 프롬프트에 자동으로 포함합니다. 또한 모델은 표준 마크다운을 생성하지만, Slack은 표준 마크다운을 네이티브로 지원하지 않습니다.

Chat SDK는 표준 마크다운을 Slack 전용 형식으로 자동 변환합니다. 이 변환은 Slack의 네이티브 append-only 스트리밍 API를 사용하는 경우에도 실시간으로 이루어집니다.

AI 스트리밍 기본 내장

post() 함수는 AI SDK 텍스트 스트림을 직접 받을 수 있어, 스트리밍 LLM 응답을 별도 연결 작업 없이 모든 채팅 플랫폼으로 전달할 수 있습니다:

어댑터 계층이 해당 스트림의 플랫폼별 렌더링을 처리하며, 플랫폼이 지원하는 경우 실시간 서식 적용까지 포함됩니다.

확장 가능한 상태 관리

스레드 구독, 분산 잠금, 키-값 캐시 상태는 플러거블 상태 어댑터를 통해 관리됩니다. Redis와 ioredis는 출시 초기부터 지원되었습니다. 이제 PostgreSQL도 프로덕션 수준의 옵션으로 지원되므로, 이미 Postgres를 운영 중인 팀은 Redis를 추가하지 않고도 봇 상태를 영속적으로 관리할 수 있습니다.

PostgreSQL 어댑터는 pg(node-postgres)와 raw SQL을 사용하며, 최초 연결 시 필요한 테이블을 자동으로 생성합니다. TTL 기반 캐싱, 다중 인스턴스 간 분산 잠금, 설정 가능한 키 접두사를 통한 네임스페이스 상태 관리를 지원합니다. 커뮤니티 기여자 @bai 님이 PR #154에서 기반 작업을 해주셨습니다.

WhatsApp, 그리고 그 너머로

Chat SDK가 이제 WhatsApp을 지원합니다. '한 번 작성하면 어디서든 배포' 모델이 세계 최대 메시징 플랫폼 중 하나로 확장된 것입니다.

WhatsApp 어댑터는 메시지, 리액션, 자동 분할, 읽음 확인, 멀티미디어 다운로드(이미지, 음성 메시지, 스티커), Google Maps URL을 활용한 위치 공유를 지원합니다. 카드는 최대 3개 옵션의 인터랙티브 답장 버튼으로 렌더링되며, 필요한 경우 서식이 적용된 텍스트로 폴백됩니다.

WhatsApp은 24시간 메시징 윈도우를 적용하므로, 봇은 해당 기간 내에서만 응답할 수 있습니다. 이 어댑터는 메시지 기록 조회, 편집, 삭제를 지원하지 않습니다. 커뮤니티 기여자 @ghellach 님이 PR #102에서 기반 작업을 해주셨습니다.

시작하기

코딩 에이전트를 강화하려면 Chat 스킬을 설치하세요:

아래 스타터 프롬프트를 수정하여 활용할 수도 있습니다:

Chat SDK 문서에서 시작 가이드, 플랫폼 어댑터 설정, 상태 설정, 그리고 Next.js와 Redis를 활용한 Slack 봇, Nuxt 기반 Discord 지원 봇, Hono를 사용한 GitHub 코드 리뷰 봇 등 주요 패턴별 가이드를 확인할 수 있습니다.

Chat SDK는 오픈소스이며 현재 퍼블릭 베타로 제공됩니다. 팀이 구축한 에이전트를 하나의 플랫폼에 묶어둘 필요가 없습니다. 사용자가 실제로 있는 곳으로 보내세요.