SDK 마이그레이션
SDK 4.0 및 v3 세션 API로 마이그레이션
Python 및 PHP 코드를 v2 플로우 세션 호출에서 세션 ID를 헤더로 보내는 v3로 옮깁니다.
v2 세션 API는 2026년 11월 30일에 지원이 종료됩니다
SDK 4.0.0은 create_flow_session, invoke_flow_response, poll_flow_response와 같은 v2 플로우 세션 호출을 더 이상 사용하지 않도록 표시합니다. v2 세션 라우트는 2026년 11월 30일에 지원이 종료됩니다. 그 전에 코드를 이 페이지의 v3 호출로 옮기세요.
FlowHunt Python 및 PHP SDK의 4.0.0 버전에는 v3 플로우 세션 API가 추가되었습니다. 이를 사용하면 채팅 세션 ID가 URL에 노출되지 않으며, 작업의 대부분은 메서드 이름을 바꾸는 것입니다. 이 페이지에서는 무엇이 바뀌었는지, 어떤 호출의 이름을 바꿔야 하는지, 그리고 변경 전후 코드를 보여 줍니다.
변경 사항#
v3 세션 호출은 세션 ID를 URL이 아니라 X-FH-Session-Id 헤더로 전달합니다. 요청 및 응답 본문은 v2와 동일합니다. v2 세션 라우트는 더 이상 사용하지 않도록 표시되었고 2026년 11월 30일에 지원이 종료됩니다.
v2에서는 모든 채팅 호출이 세션 ID를 경로에 넣습니다. 예를 들어 /v2/flows/sessions/{session_id}/invoke와 같습니다. 세션 ID는 익명 채팅 세션이 가진 유일한 자격 증명이며, URL은 액세스 로그, 프록시 로그, 브라우저 기록, Referer 헤더에 남습니다. 헤더는 그렇지 않습니다.
4.0.0 설치#
Python
PyPI의 패키지는 flowhunt입니다.
pip install --upgrade "flowhunt>=4,<5"PHP
Packagist의 패키지는 flowhunt/flowhunt-php-sdk입니다. PHP 8.1 이상이 필요합니다.
composer require flowhunt/flowhunt-php-sdk:^4.0네 단계로 마이그레이션#
패키지 업그레이드
위와 같이 4.0.0을 설치하세요. 기존 v2 호출은 업그레이드 후에도 계속 작동하므로 한 번에 하나씩 옮길 수 있습니다. 2026년 11월 30일 전에 마치세요.
각 세션 호출의 이름 바꾸기
Python 메서드 이름에는
_v3를, PHP 메서드 이름에는V3를 추가하세요. 메서드 매핑에 모든 쌍이 나와 있습니다.세션 ID를 헤더 인수로 전달
세션 ID 인수는 이제
x_fh_session_id입니다. Python에서는 키워드 인수로 전달하세요. PHP에서는 세 개의 메서드가 세션 ID를 첫 번째가 아닌 두 번째 인수로 받습니다. 세 개의 메서드에서 인수 순서가 변경되었습니다를 참고하세요.제거된 메서드 확인
4.0.0에서 제거된 메서드 중 하나를 호출하고 있다면 대체 메서드로 바꾸거나 호출을 제거하세요.
메서드 매핑#
Python 메서드는 flowhunt.FlowsApi에 있으며, 동일한 v3 메서드가 flowhunt.V3Api에도 있습니다. PHP 메서드는 FlowHunt\Api\FlowsApi에 있습니다.
| 대상 | v2 HTTP | v3 HTTP (X-FH-Session-Id의 세션 ID) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| 플로우 세션 시작(API 키) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| 챗봇 세션 시작(익명) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| 메시지 보내기 | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| 이벤트 폴링 | POST /v2/flows/sessions/{id}/invocation_response/{from_timestamp} | POST /v3/flows/sessions/invocation_response/{from_timestamp} | poll_flow_response → poll_flow_response_v3 | pollFlowResponse → pollFlowResponseV3 |
| 실행 중단 | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| 이전 앵커로 돌아가기 | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| 채팅 훅 실행 | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| 대기 중인 훅 재개 | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| 플로우 변수 설정 | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| 첨부 파일 목록 조회 | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| 첨부 파일 업로드 | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| 첨부 파일 삭제 | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| 메시지 피드백 | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| 아티팩트 읽기 | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| 입력 중 검색(신규, v2 없음) | 없음 | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
첨부 파일 다운로드(GET /v2/flows/sessions/{id}/attachments/{file_id})에는 v3 버전이 없습니다. 이는 로그인한 대시보드 호출이며 이 마이그레이션의 범위가 아닙니다.
API 키가 필요한 것은 두 개의 create 호출뿐입니다. from_flow/create는 워크스페이스의 플로우에 대한 세션을 시작하며 키가 필요합니다. create는 임베디드 채팅 위젯이 사용하는 익명 챗봇 세션이므로 키가 필요하지 않습니다. 두 호출 모두 HTTP 201과 함께 session_id와 created_at을 반환합니다. 그 밖의 모든 v3 세션 호출에는 X-FH-Session-Id 헤더만 있으면 됩니다.
지금은 HTTP로 첨부 파일을 업로드하세요
4.0.0에서 upload_attachments_v3와 uploadAttachmentsV3는 파일을 전송할 수 없습니다. API는 422 “Expected UploadFile"을 반환하고, Python 메서드는 요청이 전송되기 전에 bytes를 거부합니다. 3.x 업로드 메서드에도 같은 문제가 있습니다. 수정될 때까지는 X-FH-Session-Id 헤더와 함께 POST /v3/flows/sessions/attachments로 파일을 multipart/form-data로 전송하세요. 아래 HTTP 탭에 해당 호출이 나와 있습니다.
변경 전과 후#
이 예제는 게시된 플로우의 세션을 시작하고, “Hello"를 보내고, 플로우의 답변을 출력합니다. 각 탭에는 3.x 코드가 먼저 나오고, 그다음에 https://api.flowhunt.io를 대상으로 실행한 4.0 코드가 나옵니다. 4.0 코드는 API 키, 워크스페이스 ID, 플로우 ID를 환경 변수 FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID, FLOWHUNT_FLOW_ID에서 읽습니다.
Python
session = flows.create_flow_session(workspace_id, flowhunt.FlowSessionCreateFromFlowRequest(flow_id=FLOW_ID))
invocation = flows.invoke_flow_response(session.session_id, flowhunt.FlowSessionInvokeRequest(message="Hello"))
events = flows.poll_flow_response(session.session_id, from_timestamp)import os
import time
import flowhunt
config = flowhunt.Configuration(host="https://api.flowhunt.io")
config.api_key["APIKeyHeader"] = os.environ["FLOWHUNT_API_KEY"]
with flowhunt.ApiClient(config) as client:
flows = flowhunt.FlowsApi(client)
session = flows.create_flow_session_v3(
workspace_id=os.environ["FLOWHUNT_WORKSPACE_ID"],
flow_session_create_from_flow_request=flowhunt.FlowSessionCreateFromFlowRequest(
flow_id=os.environ["FLOWHUNT_FLOW_ID"]
),
)
session_id = session.session_id # 비밀로 유지하고 절대 로그에 남기지 마세요
invocation = flows.invoke_flow_response_v3(
x_fh_session_id=session_id,
flow_session_invoke_request=flowhunt.FlowSessionInvokeRequest(message="Hello"),
)
since, seen, answered = int(invocation.created_at), set(), False
for _ in range(60):
time.sleep(2)
events = flows.poll_flow_response_v3(
x_fh_session_id=session_id, from_timestamp=since
)
new_events = [e for e in events if e.event_id not in seen]
for event in new_events:
seen.add(event.event_id)
since = max(since, int(float(event.created_at_timestamp)) - 1)
if event.action_type == "failed":
raise RuntimeError("The flow run failed")
if event.event_type == "ai" and event.action_type == "message":
print(event.metadata.to_dict()["message"])
answered = True
if answered and not new_events:
breakPHP
$session = $flows->createFlowSession($workspaceId, $request);
$invocation = $flows->invokeFlowResponse($session->getSessionId(), $invokeRequest);
$events = $flows->pollFlowResponse($session->getSessionId(), $fromTimestamp);<?php
require 'vendor/autoload.php';
$config = FlowHunt\Configuration::getDefaultConfiguration()
->setHost('https://api.flowhunt.io')
->setApiKey('Api-Key', getenv('FLOWHUNT_API_KEY'));
$flows = new FlowHunt\Api\FlowsApi(new GuzzleHttp\Client(), $config);
$session = $flows->createFlowSessionV3(
getenv('FLOWHUNT_WORKSPACE_ID'),
new FlowHunt\Model\FlowSessionCreateFromFlowRequest(['flow_id' => getenv('FLOWHUNT_FLOW_ID')])
);
$sessionId = $session->getSessionId(); // 비밀로 유지하고 절대 로그에 남기지 마세요
$invocation = $flows->invokeFlowResponseV3(
$sessionId,
new FlowHunt\Model\FlowSessionInvokeRequest(['message' => 'Hello'])
);
$since = (int) $invocation->getCreatedAt();
$seen = [];
$answered = false;
for ($i = 0; $i < 60; $i++) {
sleep(2);
// 순서에 주의하세요: 타임스탬프가 먼저, 세션 ID가 두 번째입니다.
$events = $flows->pollFlowResponseV3($since, $sessionId);
$newEvents = array_filter($events, fn ($e) => !isset($seen[$e->getEventId()]));
foreach ($newEvents as $event) {
$seen[$event->getEventId()] = true;
$since = max($since, (int) $event->getCreatedAtTimestamp() - 1);
if ($event->getActionType() === 'failed') {
throw new RuntimeException('The flow run failed');
}
if ($event->getEventType() === 'ai' && $event->getActionType() === 'message') {
echo $event->getMetadata()->getMessage(), PHP_EOL;
$answered = true;
}
}
if ($answered && !$newEvents) {
break;
}
}HTTP
API 키를 보내는 호출은 create 호출뿐입니다. 그 이후의 모든 호출은 X-FH-Session-Id 헤더로 세션 ID를 보냅니다.
curl -X POST "https://api.flowhunt.io/v3/flows/sessions/from_flow/create?workspace_id=$WORKSPACE_ID" \
-H "Api-Key: $FLOWHUNT_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"flow_id\": \"$FLOW_ID\"}"curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invoke" \
-H "X-FH-Session-Id: $SESSION_ID" \
-H "Content-Type: application/json" \
-d '{"message": "Hello"}'curl -X POST "https://api.flowhunt.io/v3/flows/sessions/invocation_response/$FROM_TIMESTAMP" \
-H "X-FH-Session-Id: $SESSION_ID"curl -X POST "https://api.flowhunt.io/v3/flows/sessions/attachments" \
-H "X-FH-Session-Id: $SESSION_ID" \
-F "file=@invoice.jpg;type=image/jpeg"이전에는 세션 ID가 각 경로의 일부였습니다. 예를 들어 /v2/flows/sessions/$SESSION_ID/invoke와 같습니다. 헤더가 없는 v3 호출은 401을 반환합니다.
폴링 방식#
from_timestamp는 에포크 이후의 밀리초입니다. 폴링은created_at_timestamp가 이 값보다 엄격히 큰 이벤트를 반환합니다.- 시작 값은 invoke 응답의
created_at입니다. 이 값은 문자열로 전송되는 밀리초 값이므로 정수로 변환하세요. 세션 전체를 가져오려면0을 사용하세요. create 응답의created_at은 밀리초가 아닌 날짜와 시간이므로 사용하지 마세요. - 폴링할 때마다
from_timestamp를 가장 최근 이벤트의created_at_timestamp에서 1을 뺀 값으로 옮기고, 이미 본event_id를 가진 이벤트는 건너뛰세요. 같은 밀리초에 생성된 이벤트는 서로 다른 폴링에서 도착할 수 있습니다. FlowHunt 채팅 위젯도 같은 방식으로 폴링합니다. - 각 이벤트에는
event_type(ai,human,system),action_type(message,loading,tool_call,failed,hook_waiting_for_input등)과metadata가 있습니다. 답변 텍스트는ai유형의message이벤트에 있는metadata.message에 있습니다.
FlowHunt는 별도의 “실행 완료” 이벤트를 보내지 않습니다. 단일 단계 플로우를 대상으로 샘플을 실행했을 때, 폴링은 system 유형의 loading 이벤트를 반환하고, 이어서 답변이 담긴 ai 유형의 message 이벤트를 하나 반환했으며, 그 이후에는 아무것도 반환하지 않았습니다. 그래서 샘플은 답변이 도착한 뒤 새 이벤트가 없는 첫 번째 폴링에서 멈추고, failed가 발생하면 예외를 던집니다. 플로우가 여러 메시지를 보내거나 hook_waiting_for_input으로 입력을 기다린다면 종료 조건은 직접 정해야 합니다.
세 개의 메서드에서 인수 순서가 변경되었습니다#
이 세 호출의 인수 순서를 바꾸세요
v3 메서드는 경로 매개변수를 세션 ID 헤더보다 앞에 둡니다. PHP에서는, 그리고 Python에서도 인수를 위치로 전달하는 경우에는 이 세 호출이 타입 오류로 실패하거나 순서를 바꾸지 않으면 조용히 잘못된 값을 전송합니다.
| v2 | v3 |
|---|---|
pollFlowResponse($session_id, $from_timestamp) | pollFlowResponseV3($from_timestamp, $x_fh_session_id) |
deleteAttachment($session_id, $file_id) | deleteAttachmentV3($file_id, $x_fh_session_id) |
getArtefactContent($session_id, $artefact_id) | getArtefactContentV3($artefact_id, $x_fh_session_id) |
Python에서는 모든 인수를 키워드 인수로 전달하세요. 예를 들어 x_fh_session_id=session_id처럼 하면 순서는 더 이상 중요하지 않습니다. Python 4.0은 인수 타입도 검사하므로 from_timestamp는 int여야 합니다. 문자열 "0"을 전달하면 pydantic ValidationError가 발생합니다.
4.0.0의 기타 호환성 깨짐 변경#
다음 메서드는 3.19.1에는 있었지만 4.0.0에서는 제거되었습니다. 이 메서드들이 사용하는 API 엔드포인트가 제거되거나 변경되었기 때문입니다. PHP 메서드 이름은 Python 메서드의 camelCase 형태입니다. 예를 들어 get_available_models는 getAvailableModels가 됩니다.
| 제거된 메서드 | 엔드포인트 | 해야 할 일 |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | 호출을 제거하세요. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | 호출을 제거하세요. |
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft | /v2/photo_ai/images/... | 호출을 제거하세요. |
WorkspacesApi.update_workspace_auto_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | 호출을 제거하세요. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | start_export_csv(POST, 같은 경로)를 호출한 다음 get_export_csv_status(GET .../export-csv/{task_id})를 호출하세요. |
Zendesk 채널, Shopify 결제, Replicate, SERP 핑백 웹훅용 메서드도 제거되었습니다. 이들은 FlowHunt 자체 서버로 들어오는 웹훅이며 여러분의 코드가 호출하는 대상이 아닙니다.
세션 ID를 비밀로 유지하세요#
세션 ID는 자격 증명입니다
세션 ID를 가진 사람은 누구나 해당 대화를 읽고 이어갈 수 있습니다. 세션 ID를 로그에 남기지 말고, URL이나 쿼리 문자열에 넣지 말고, 분석 도구로 보내지 마세요. 짧은 수명의 비밀번호처럼 다루세요.
v2는 어떻게 되나요?#
v2 세션 라우트는 SDK 4.0.0부터 더 이상 사용하지 않도록 표시되었으며 2026년 11월 30일에 지원이 종료됩니다. 그때까지는 계속 작동하며, API 레퍼런스에서도 사용 중단(deprecated)으로 표시되어 있습니다. SDK 4.0.0에는 여전히 v2 메서드가 포함되어 있습니다. Python에서는 호출 시 DeprecationWarning이 발생합니다. PHP에서는 코드에 @deprecated로 표시되어 있어 IDE나 정적 분석 도구가 이를 알려 줍니다.