채널 (Channels)¶

사용자가 이미 있는 곳에서 만나기¶

Overview에서 만든 CrewAI 에이전트는 꼭 웹 앱 뒤에 살 필요가 없습니다. 동일한 Crew나 Flow를 메신저 플랫폼 안에서 봇으로 실행할 수 있습니다. 다시 빌드할 필요도, 에이전트 로직의 두 번째 복사본도 필요 없습니다. 에이전트는 AG-UI 프로토콜을 통해 그대로 노출되고, 채널이 Slack이나 Microsoft Teams에서 그 에이전트를 구동합니다.

CopilotKit의 Channels SDK가 바로 그 채널을 제공합니다. 작은 런타임에서 createChannel을 선언하고 CrewAI 에이전트를 가리키면, CopilotKit의 관리형 Intelligence 플랫폼이 메신저 제공자와의 연결을 중개합니다.

이 섹션의 나머지와 달리 Channels는 셀프 호스팅이 아닙니다. CopilotKit Intelligence를 통해 실행됩니다 — 설계상 Channels에 필수적인 표면이며(무료 티어 사용 가능), 플랫폼 연결과 자격 증명을 보유하고 각 플랫폼 이벤트를 받아 턴을 채널 프로세스에 전달합니다. 프로세스가 에이전트를 실행하고 답변을 다시 스트리밍합니다. Slack을 Intelligence 대시보드에서 한 번 구성하면 플랫폼 자격 증명이 프로세스에 들어오지 않습니다. 에이전트, 도구, 상태는 모두 여러분의 것입니다.

어떻게 맞물리는가¶

CrewAI 에이전트 서버는 아무것도 변하지 않습니다. Overview에서와 똑같이 AG-UI를 통해 Crew나 Flow를 계속 서빙합니다. 추가되는 것은 @copilotkit/channels로 만든 별도의 장기 실행 Node 프로세스입니다. 이 프로세스가 CopilotRuntime에 채널을 등록하고, Intelligence에 연결하며, 메시지가 도착할 때마다 에이전트를 실행합니다.

Slack / Teams  ──►  CopilotKit Intelligence  ──►  channel process (Node)  ──►  CrewAI server (AG-UI)  ──►  Crew / Flow

채널 프로세스는 Intelligence 게이트웨이에 대한 지속 연결을 유지하므로 장기 실행 호스트가 필요합니다 — 서버리스 요청 핸들러는 그 연결을 소유할 수 없습니다. CrewAI 서버는 동시에 Overview의 웹 프런트엔드를 계속 서빙할 수 있습니다. 웹 앱과 채널은 하나의 AG-UI 엔드포인트에 대한 두 개의 클라이언트일 뿐입니다.

통합 가이드¶

1. Channels 패키지 설치

Channels SDK는 배터리 포함 방식입니다 — 모든 플랫폼이 하나의 패키지에 들어 있으며 별도의 플랫폼별 어댑터를 설치할 필요가 없습니다. 채널을 호스팅하는 런타임과 CrewAI AG-UI 클라이언트와 함께 설치하세요:

npm install @copilotkit/channels @copilotkit/runtime @ag-ui/crewai

2. Intelligence에서 Channel 만들기

CopilotKit 대시보드에서 Channel을 만들고 Slack을 연결하세요 — Intelligence가 Slack 앱 생성 과정을 안내하며 자격 증명을 보유합니다. 그러면 프로세스용 환경 변수 두 개가 남는데, 둘 다 대시보드에서 가져옵니다:

export INTELLIGENCE_API_KEY=...      # 런타임을 Intelligence에 인증 (무료 티어 사용 가능)
export INTELLIGENCE_CHANNEL_ID=...   # Channel ID, createChannel({ name })과 일치

3. 채널 정의하기

createChannel이 채널을 선언하고 에이전트를 붙입니다. 에이전트를 스레드별 팩토리로 만들어 각 대화가 자신만의 세션을 갖게 하고, Overview가 웹 런타임에서 쓰는 것과 동일한 CrewAIAgent를 AG-UI 엔드포인트에 가리키게 하세요. identifyUser: "platform"은 Intelligence가 각 플랫폼 사용자를 안정적인 신원에 매핑하게 합니다.

// channel.ts
import { createChannel } from "@copilotkit/channels";
import { CrewAIAgent } from "@ag-ui/crewai";

const channel = createChannel({
  name: process.env.INTELLIGENCE_CHANNEL_ID!, // Intelligence의 Channel ID와 일치해야 함
  identifyUser: "platform",
  // 대화당 새 에이전트, CrewAI AG-UI 엔드포인트를 가리킴.
  agent: (threadId) => {
    const agent = new CrewAIAgent({ url: "http://localhost:8000/recipe" });
    agent.threadId = threadId;
    return agent;
  },
});

// 멘션은 스레드를 구독하고 에이전트를 실행; 이후 구독된 스레드의
// 모든 메시지는 다시 멘션할 필요 없이 실행됩니다.
channel.onMention(async ({ thread }) => {
  await thread.subscribe();
  await thread.runAgent();
});

channel.onMessage(async ({ thread }) => {
  if (await thread.isSubscribed()) await thread.runAgent();
});

export { channel };

4. 런타임에 채널 등록하기

Intelligence 게이트웨이와 채널로 CopilotRuntime을 만들고 createCopilotNodeListener로 서빙하세요. agents 맵은 비워 두세요 — 채널이 자체 에이전트를 제공합니다. 채널이 준비될 때까지 기다리면 잘못된 설정이 시작 시 큰 소리로 실패하게 됩니다.

// server.ts
import { createServer } from "node:http";
import { CopilotRuntime, CopilotKitIntelligence } from "@copilotkit/runtime/v2";
import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";
import { channel } from "./channel";

const runtime = new CopilotRuntime({
  agents: {}, // 채널이 자체 에이전트를 제공; 웹용 에이전트 불필요
  intelligence: new CopilotKitIntelligence({
    apiKey: process.env.INTELLIGENCE_API_KEY!, // 무료 티어 사용 가능
  }),
  channels: [channel],
});

const listener = createCopilotNodeListener({ runtime });
await listener.channels?.ready({ timeoutMs: 15_000 });

createServer(listener).listen(3123, () => {
  console.log("Channels runtime listening on port 3123");
});

5. 채널 런타임 실행하기

CrewAI 에이전트 서버와 함께 실행하세요:

uvicorn server:app --port 8000   # 터미널 1 — CrewAI 에이전트 서버
npx tsx server.ts                 # 터미널 2 — Channels 런타임

Slack이나 Teams에서 봇을 멘션하면 Crew나 Flow를 실행하고 답변을 스레드로 다시 스트리밍합니다. 스레드는 구독 상태로 유지되므로 이후 메시지는 다시 멘션할 필요 없이 실행됩니다.

이벤트 모델¶

채널은 핸들러로 플랫폼 이벤트에 반응하며, 각 핸들러는 몇 가지 메서드로 구동하는 thread를 받습니다:

channel.onMention — 사용자가 봇을 @멘션할 때 발생합니다. thread.subscribe()를 호출해 스레드에 참여한 뒤 thread.runAgent()로 CrewAI 에이전트를 멘션에 대해 실행하세요.
channel.onMessage — 봇이 볼 수 있는 스레드의 모든 메시지에서 발생합니다. thread.isSubscribed()로 게이트를 쳐 에이전트가 참여한 곳에서만 응답하게 한 뒤 thread.runAgent()를 호출하세요.
thread.runAgent() — 현재 턴에 대해 연결된 CrewAI 에이전트를 실행하고 출력을 채널로 다시 스트리밍합니다. { prompt }를 전달하면 에이전트가 실행할 텍스트를 재정의할 수 있습니다.

에이전트는 평범한 AG-UI RunAgentInput을 받고 평범한 AG-UI 이벤트를 내보냅니다. 플랫폼 메커니즘은 채널 뒤에 숨어 있으므로 동일한 Crew나 Flow가 모든 플랫폼에서 변경 없이 실행됩니다. 채널은 또한 환영(welcome), 인터럽트, 명령, 반응, 모달용 핸들러를 제공합니다 — 전체 표면은 Channel 참조를 보세요.

플랫폼 지원¶

관리형 Intelligence 경로는 오늘 Slack과 Microsoft Teams를 다룹니다 — 동일한 채널 코드가 둘 중 어느 쪽에서도 실행되며, message.platform/thread.platform이 원래 출처를 보고합니다. 다른 플랫폼(Discord, Telegram, WhatsApp)은 관리형 경로가 아니라 개발자 운영 직접 어댑터로 접근합니다 — 여러분의 프로세스가 플랫폼 자격 증명과 전송을 보유합니다. 현재 플랫폼 목록과 플랫폼별 설정은 CopilotKit Channels 문서를 확인하세요.

D-SKET Canvas가
정식 런칭되었습니다.