Skip to content

프론트엔드 대화형 플로우 (Frontend Conversational Flows)

세 가지 실행 형태, 하나의 브리지

AG-UI 브리지 뒤에서 CrewAI 백엔드는 세 가지 형태 중 하나를 취할 수 있어요. 어느 형태를 제공하고 있는지 아는 것이 프론트엔드를 만드는 방식이 아니라 백엔드를 작성하는 방식을 결정합니다.

형태 무엇인가 어떻게 진입하나
일반 플로우 (Regular Flows) 작성자가 제어하는 @start/@listen/@router 그래프. 이 가이드 전반에서 기본으로 사용돼요. kickoff / astream
대화형 플로우 (Conversational Flows) 관리되는 대화 상태를 가진, 세션을 인식하고 턴 기반으로 동작하는 네이티브 플로우. stream_turn(message, session_id=...)
Crews 폐쇄된 자율 태스크/에이전트 루프. 기본 채팅만 가능한 별도의 호환 경로예요. 여기서는 다루지 않아요.

대화형 플로우는 CrewAI의 비교적 새로운 기능인데, 시작부터 분명히 하고 싶은 점이 하나 있어요. 이것은 Crew가 아니라 Flow입니다. 이제 일반 플로우와 완전한 기능 동등성(feature parity)으로 동작해요. 이 페이지에서는 대화형 플로우를 소개하고, 나머지 프론트엔드 가이드와 어떻게 맞물리는지 보여드릴게요.

stream_turn에서 턴과 상태 처리를 직접 연결하는 대신, CrewAI가 세션 상태와 히스토리를 관리해 주면서 네이티브 멀티턴 대화가 필요할 때 대화형 플로우를 사용하면 돼요. 처음 오셨다면, 기본 서버·런타임·프로바이더 설정을 위해 프론트엔드 개요부터 시작하시는 걸 권해요.

대화형 플로우 등록하기

대화형 플로우는 다른 플로우와 동일한 엔드포인트 헬퍼로 등록하는데, 인자가 하나 더 붙어요. 바로 conversational=True예요.

# server.py
from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint

add_crewai_flow_fastapi_endpoint(
    app,
    flow,
    "/conversation",
    conversational=True,
)

이것이 동작하려면 두 가지 요건이 충족돼야 해요.

  • 플로우 인스턴스가 conversational = True를 선언한다.
  • 플로우가 CrewAI의 공개 호출 가능 메서드인 stream_turn(message, session_id=...)를 노출한다.

감지는 버전 기준이 아니라 기능 기준(capability-based) 이에요. 브리지는 플로우가 실제로 턴 기반 대화를 제공하는지 확인하지, 버전 번호로 판단하지 않아요.

이 요건이 충족되지 않으면 요청은 RUN_ERROR(코드 AGUI_CREWAI_CONVERSATIONAL_FLOW_UNSUPPORTED)와 함께 큰 소리로 실패해요. 일반 kickoff 의미론으로 조용히 폴백하는 일은 없으니, 지금 어느 경로를 타고 있는지 항상 정확히 알 수 있어요.

플로우 자체를 작성하는 방법, stream_turn을 어떻게 구현하는지는 CrewAI의 대화형 플로우 문서에 속해요. 이 페이지는 등록과 통합 경계까지만 다룹니다.

세션과 상태

대화형 플로우는 턴을 걸쳐 세션 상태와 히스토리를 대신 관리해요. 히스토리를 직접 다시 전달할 필요가 없어요.

  • AG-UI의 threadId가 바로 CrewAI 대화의 session_id예요. 같은 스레드는 같은 대화예요.
  • 각 턴 전에 브리지가 플로우의 상태와 대화 히스토리를 수화(hydrate)한 뒤 stream_turn을 호출해요. CrewAI는 저장된 세션 상태를 복원하고, 요청별 오버레이가 들어오는 AG-UI 상태와 히스토리를 다시 적용해서 브라우저의 최신 편집이 낡은 저장 값보다 우선하도록 해요.

그 결과로, 백엔드 작성자 입장에서는 각 턴이 이미 대화의 상태를 담고 도착하고, CrewAI가 다음 턴을 위해 당신이 쓴 것을 유지해 줍니다.

프론트엔드 동등성 (Frontend parity)

여기서 딱 하나 잡고 가야 할 포인트예요. 대화형 플로우는 일반 플로우와 동일한 이벤트 파이프라인을 타기 때문에, 프론트엔드 코드는 완전히 동일합니다. 대화형 플로우 전용 프론트엔드 API는 존재하지 않아요. 이 가이드의 모든 기능은 대화형 플로우에서도 일반 플로우와 똑같이 동작하고, 같은 훅과 컴포넌트를 사용해요.

차이는 백엔드뿐이에요. 어떻게 플로우를 작성하는지(관리되는 세션 상태를 가진 턴 기반 stream_turn)와 conversational=True 등록이 그 차이예요. 엔드포인트가 올라가고 나면, 프론트엔드를 만드는 데 이미 알고 있는 모든 것이 그대로 적용돼요.

관련 자료