프론트엔드 개요 (Frontend Overview)¶
에이전트에 사용자 인터페이스를 더하기¶
CrewAI는 에이전트를 돌아가게 합니다. 그리고 CopilotKit이 그 에이전트에 프론트엔드를 붙여 줍니다. 둘이 만나면 사용자가 Crew나 Flow와 채팅하고, 에이전트가 일하는 모습을 실시간으로 지켜보고, 결정을 승인하고, 결과가 텍스트 벽 대신 살아있는 UI로 렌더링되는 애플리케이션을 만들 수 있어요.
둘은 AG-UI 프로토콜로 이어집니다. ag-ui-crewai 패키지가 모든 Crew나 Flow를 AG-UI 엔드포인트로 노출하고, CopilotKit의 React 훅과 컴포넌트가 그 엔드포인트를 소비하는 구조죠. 이 조합 덕분에 단순한 채팅창을 넘어선 경험을 만들 수 있어요.
- Generative UI — 에이전트의 도구 호출과 상태를 나만의 React 컴포넌트로 렌더링하기
- Human-in-the-Loop — 실행 중간에 에이전트를 멈추고 사용자의 승인이나 입력을 받기
- Shared State — 에이전트 상태와 앱 UI를 양방향으로 동기화하기
- Channels — 같은 에이전트를 Slack, Discord, Teams 봇으로도 돌리기
이 가이드는 Crew나 Flow를 Next.js 프론트엔드와 끝까지 연결하는 과정을 다룹니다. 이 섹션의 나머지 문서들은 여기서 만든 앱을 바탕으로 이어져요.
아키텍처¶
세 가지 조각이 있습니다.
- CrewAI 에이전트 서버 — Crew나 Flow를 AG-UI로 서빙하는 Python 프로세스입니다 (FastAPI +
ag-ui-crewai). - CopilotKit 런타임 — 에이전트를 등록하고 에이전트로의 요청을 프록시하는 Next.js 라우트입니다.
- React 프론트엔드 —
<CopilotKit>프로바이더와 채팅·Generative UI 컴포넌트입니다.
이 가이드는 셀프 호스팅 경로를 다룹니다. 즉
ag-ui-crewai로 CrewAI 에이전트 서버를 직접 실행하고, 관리형 서비스 없이 로컬에서 동작하게 만드는 방식이에요.CrewAI는 AG-UI 뒤에서 세 가지 모습으로 동작합니다. 이 가이드 전반에서 쓰는 일반적인 Flow, 네이티브하고 세션을 인식하며 턴 기반이고 기능이 완전히 동등한 Conversational Flow, 그리고 기본 채팅을 위한 Crew가 있어요. 이 섹션의 프론트엔드는 세 경우 모두 동일하고, 달라지는 건 백엔드를 어떻게 작성하고 등록하는지뿐입니다.
통합 가이드¶
1. 에이전트를 AG-UI로 서빙하기¶
CrewAI 프로젝트에 통합 패키지를 설치합니다.
그리고 FastAPI 앱에서 에이전트를 노출합니다. Flow는 add_crewai_flow_fastapi_endpoint를, Crew는 add_crewai_crew_fastapi_endpoint를 씁니다. 원하는 만큼 여러 개를 등록할 수 있고, 각각 자기 경로를 갖습니다.
# server.py — Flow
from fastapi import FastAPI
from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint
from my_agents.recipe_flow import RecipeFlow
app = FastAPI(title="CrewAI Agent Server")
add_crewai_flow_fastapi_endpoint(
app=app,
flow=RecipeFlow(),
path="/recipe",
)
# server.py — Crew
from fastapi import FastAPI
from ag_ui_crewai.endpoint import add_crewai_crew_fastapi_endpoint
from my_agents.research_crew import ResearchCrew
app = FastAPI(title="CrewAI Agent Server")
add_crewai_crew_fastapi_endpoint(
app=app,
crew=ResearchCrew().crew(),
path="/research",
)
서버를 실행합니다.
서버를 시작하기 전에 LLM 제공자의 환경 변수(예:
OPENAI_API_KEY)를 설정해 두세요.
2. Next.js 앱 만들기¶
아직 프론트엔드가 없다면 먼저 스캐폴딩합니다.
그 다음 CopilotKit과 CrewAI AG-UI 클라이언트를 설치합니다.
3. CopilotKit 런타임 추가하기¶
CrewAI 에이전트를 CopilotKit 런타임에 등록하는 라우트를 만듭니다. 각 에이전트는 CrewAIAgent를 통해 Python 서버의 경로 하나를 가리킵니다.
// app/api/copilotkit/route.ts
import {
CopilotRuntime,
InMemoryAgentRunner,
createCopilotEndpoint,
} from "@copilotkit/runtime/v2";
import { CrewAIAgent } from "@ag-ui/crewai";
import { handle } from "hono/vercel";
const runtime = new CopilotRuntime({
agents: {
recipe: new CrewAIAgent({ url: "http://localhost:8000/recipe" }),
},
runner: new InMemoryAgentRunner(),
});
const app = createCopilotEndpoint({
runtime,
basePath: "/api/copilotkit",
});
const handler = handle(app);
export const GET = handler;
export const POST = handler;
4. 앱을 프로바이더로 감싸기¶
<CopilotKit>을 런타임 라우트에 연결하고 등록한 에이전트의 이름을 지정합니다.
5. 실행하기¶
두 프로세스를 시작하고 앱을 엽니다. 사이드바에서 채팅을 시작하면 이제 Crew나 Flow가 돌아갑니다.
채팅 UI 옵션¶
CopilotKit은 서로 바꿔 쓸 수 있는 세 가지 채팅 표면을 제공합니다. 컴포넌트만 바꾸면 되고, 연결 방식은 동일해요.
// Sidebar
import { CopilotSidebar } from "@copilotkit/react-core/v2";
<CopilotSidebar agentId="recipe" />
// Popup
import { CopilotPopup } from "@copilotkit/react-core/v2";
<CopilotPopup agentId="recipe" />
다음으로 어디로 갈까¶
- Generative UI — 도구 호출과 에이전트 상태를 나만의 컴포넌트로 렌더링하기
- Frontend Actions — 브라우저에서 실행되는 함수를 에이전트가 호출하게 하기
- Human-in-the-Loop — 에이전트의 동작을 사용자 승인 뒤에 두기
- Predictive State — 에이전트가 작업하는 동안 진행 중인 상태를 UI로 실시간 스트리밍하기