Conversational Flow Chat API

개요

배포된 conversational Flow는 자동화 URL에 채팅 세션 API를 노출합니다. 단일 /kickoff 실행 대신 세션을 만들고, 사용자 메시지를 턴으로 보내며, 선택적으로 토큰과 런타임 이벤트를 스트리밍하고, 턴에 사람 피드백이 필요할 때 HITL 일시중지를 재개합니다.

Conversational Flow 채팅은 experimental입니다. 엔드포인트는 배포된 Flow가 GET /inspect에서 conversational: true와 handle_turn: true를 모두 보고할 때만 사용할 수 있습니다.

Flow 자체 구현(conversational = True, handle_turn, 라우터, 트레이싱)은 오픈소스 Conversational Flows 가이드를 참고하세요.

사전 요구 사항

conversational 턴(handle_turn)을 구현한 Flow 자동화를 배포합니다.
자동화 Status 탭에서 bearer 토큰을 복사합니다(/kickoff와 동일한 토큰).
아래 /inspect로 채팅이 활성화되어 있는지 확인합니다.

모든 요청은 다음을 사용합니다:

Authorization: Bearer YOUR_FLOW_TOKEN

이 가이드의 기본 URL 예시는 https://your-flow-url.crewai.com입니다.

채팅 기능 확인

curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/inspect

flow.chat를 확인하세요:

{
  "flow": {
    "chat": {
      "conversational": true,
      "handle_turn": true,
      "transports": ["webhook"],
      "experimental": true
    }
  }
}

둘 중 하나라도 false이면 채팅 엔드포인트는 "Conversational flow chat is not available"와 함께 404를 반환합니다.

엔드투엔드 채팅 루프

세션 시작

채팅 세션을 만듭니다. 선택적으로 세션 수명 동안 completed-turn 웹훅과 이벤트 웹훅을 등록합니다.

curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "completedTurnWebhookUrl": "https://your-server.com/webhooks/completed-turn",
    "webhooks": {
      "url": "https://your-server.com/webhooks/events",
      "events": ["*"],
      "realtime": false,
      "authentication": {
        "strategy": "bearer",
        "token": "my-secret-token"
      }
    }
  }' \
  https://your-flow-url.crewai.com/chat/start

응답:

{ "session_id": "11111111-2222-3333-4444-555555555555" }

웹훅이 필요 없으면 빈 body({} 또는 body 없음)도 유효합니다.

사용자 메시지 보내기

세션에 턴을 큐에 넣습니다:

curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Where is my order?",
    "stream": true
  }' \
  https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/message

응답:

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "queued"
}

필드	설명
`message`	필수. 이 턴의 현재 사용자 메시지.
`stream`	기본값 `true`. `true`이면 WebSocket/SSE 클라이언트용 토큰/이벤트 프레임이 게시됩니다.
`messageHistory`	선택적 fallback 트랜스크립트(`[{ "role", "content" }, ...]`). 서버 측 세션 기록이 권위 있으며, 저장된 기록이 비어 있을 때만 사용됩니다.

messageHistory에서 허용되는 role: user, assistant, system, tool.

턴 완료 대기

반환된 kickoff_id로 턴을 폴링합니다(일반 Flow kickoff와 동일한 status API):

curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/status/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

세션당 활성 턴은 하나만 가능합니다. active_kickoff_id가 설정된 상태에서 두 번째 /message는 409를 반환합니다:

{
  "detail": {
    "code": "session_busy",
    "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

다음 메시지를 보내기 전에 history에서 active_kickoff_id: null이 되거나 턴이 종료/일시중지 상태가 될 때까지 기다립니다.

세션 history 읽기

curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/history

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "messages": [
    { "role": "user", "content": "Where is my order?" },
    { "role": "assistant", "content": "Your order is on the way." }
  ],
  "active_kickoff_id": null
}

턴 스트리밍

스트리밍은 선택 사항입니다. UI가 턴 실행 중 토큰이나 런타임 이벤트가 필요할 때 사용합니다. 프레임은 항상 라이프사이클 타입(turn_started, turn_completed, turn_failed, token, error)을 포함합니다. 추가 event 프레임은 events 쿼리 파라미터(* 또는 쉼표로 구분된 목록)로 필터링할 수 있습니다.

옵션 A: HTTP 메시지 + SSE attach

"stream": true로 POST /chat/{session_id}/message를 호출합니다.
활성 턴에 attach합니다:

curl -N \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  "https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/stream/events?events=*&last_event_id=0-0"

SSE는 text/event-stream JSON 프레임(data: {...})과 keepalive 코멘트를 반환합니다. 스트림은 turn_completed 또는 turn_failed에서 종료됩니다. 활성 턴이 없으면 이 엔드포인트는 409(No active chat turn)를 반환합니다.

옵션 B: WebSocket (attach 또는 전송)

wss://your-flow-url.crewai.com/chat/{session_id}/stream?token=YOUR_FLOW_TOKEN&events=*&last_event_id=0-0

인증: bearer 토큰을 token 쿼리 파라미터로 전달하거나, 클라이언트가 WebSocket 헤더를 지원하면 Authorization: Bearer ... 헤더를 사용합니다. 동작:

이미 활성 턴이 실행 중 — 소켓이 attach되고 먼저 data.status: "attached"인 turn_started를 보낸 뒤, terminal 타입까지 프레임을 스트리밍합니다.
활성 턴 없음 — JSON 메시지로 턴을 큐에 넣은 뒤 스트림을 소비합니다:

{
  "message": "Where is my order?",
  "messageHistory": [],
  "events": "*",
  "lastEventId": "0-0"
}

서버는 turn_started(status: "queued")로 응답한 뒤 해당 kickoff_id의 스트림 프레임을 보냅니다. 연결이 끊긴 뒤에는 last_event_id / lastEventId로 재개하세요.

스트림 프레임 예시

{
  "type": "turn_started",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "status": "queued" }
}

{
  "type": "token",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "content": "Your order" }
}

{
  "type": "turn_completed",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": {}
}

채팅 세션 내 HITL

턴이 사람 피드백을 위해 일시중지되면(status / 상태 PAUSED), 일반 Flow와 동일한 resume 엔드포인트로 재개합니다:

curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "FLOW_OR_SESSION_ID",
    "feedback": "approved"
  }' \
  https://your-flow-url.crewai.com/resume_feedback

응답의 resume kickoff_id를 폴링한 뒤, /history에서 active_kickoff_id: null이 될 때까지 기다렸다가 다음 채팅 메시지를 보내세요. 플랫폼 검토 UX는 HITL 워크플로와 Flow HITL 관리를 참고하세요.

API 레퍼런스

메서드	Path	용도
`GET`	`/inspect`	conversational 채팅 활성화 여부 확인
`POST`	`/chat/start`	채팅 세션 생성
`POST`	`/chat/{session_id}/message`	사용자 턴 큐잉
`GET`	`/chat/{session_id}/history`	메시지 및 활성 턴 id 조회
`GET`	`/chat/{session_id}/stream/events`	활성 턴 SSE 스트림
`WS`	`/chat/{session_id}/stream`	WebSocket 스트림 (attach 또는 전송 + 스트림)
`GET`	`/status/{kickoff_id}`	턴(또는 resume) 실행 상태 폴링
`POST`	`/resume_feedback`	일시중지된 HITL 턴 재개

일반적인 오류

Status	상황
`400`	빈 `message`
`404`	이 배포에서 채팅이 비활성화되었거나 알 수 없는 `session_id`
`409`	세션에 이미 활성 턴이 있음(`session_busy`), 또는 활성 턴 없이 SSE attach
`422`	`session_id`가 유효한 UUID가 아님
`503`	채팅 세션 또는 스트림 스토리지를 사용할 수 없음

Conversational Flows

handle_turn, 라우터, 트레이싱으로 멀티 턴 Flow를 구축하세요.

Kickoff Crew / Flow

배포 URL에서 단일 실행 kickoff 및 상태 폴링.

Webhook Streaming

이벤트 웹훅 페이로드 형식과 인증 옵션.

Flow HITL 관리

일시중지된 Flow 단계에 대한 이메일 우선 인간 검토.

시작 안내

빌드

운영

관리

통합 문서

How-To Guides

트리거

학습 자원

Conversational Flow Chat API

개요

사전 요구 사항

채팅 기능 확인

엔드투엔드 채팅 루프

턴 스트리밍

옵션 A: HTTP 메시지 + SSE attach

옵션 B: WebSocket (attach 또는 전송)

스트림 프레임 예시

채팅 세션 내 HITL

API 레퍼런스

일반적인 오류

관련 문서

Conversational Flows

Kickoff Crew / Flow

Webhook Streaming

Flow HITL 관리

​개요

​사전 요구 사항

​채팅 기능 확인

​엔드투엔드 채팅 루프

​턴 스트리밍

​옵션 A: HTTP 메시지 + SSE attach

​옵션 B: WebSocket (attach 또는 전송)

​스트림 프레임 예시

​채팅 세션 내 HITL

​API 레퍼런스

​일반적인 오류

​관련 문서

Conversational Flows

Kickoff Crew / Flow

Webhook Streaming

Flow HITL 관리

개요

사전 요구 사항

채팅 기능 확인

엔드투엔드 채팅 루프

턴 스트리밍

옵션 A: HTTP 메시지 + SSE attach

옵션 B: WebSocket (attach 또는 전송)

스트림 프레임 예시

채팅 세션 내 HITL

API 레퍼런스

일반적인 오류

관련 문서