SDK 迁移
迁移到 SDK 4.0 与 v3 会话 API
将 Python 和 PHP 代码从 v2 的流程会话(flow-session)调用迁移到 v3,v3 通过请求头传递 session id。
v2 会话 API 将于 2026 年 11 月 30 日停止服务
SDK 4.0.0 弃用了 v2 的流程会话调用,例如 create_flow_session、invoke_flow_response 和 poll_flow_response。v2 会话路由将于 2026 年 11 月 30 日 停止服务。请在此之前将你的代码迁移到本页介绍的 v3 调用。
FlowHunt Python 和 PHP SDK 的 4.0.0 版本新增了 v3 流程会话 API。迁移到它可以避免聊天 session id 出现在 URL 中,而且大部分工作只是重命名方法。本页介绍有哪些变化、需要重命名哪些调用,以及迁移前后的代码。
变化内容#
v3 会话调用通过 X-FH-Session-Id 请求头传递 session id,绝不放 URL。请求体和响应体与 v2 相同。v2 会话路由已弃用,并将于 2026 年 11 月 30 日停止服务。
在 v2 中,每个聊天调用都把 session id 放在路径里,例如 /v2/flows/sessions/{session_id}/invoke。session 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。方法对照表列出了所有对应关系。通过请求头参数传入 session id
session id 参数现在叫
x_fh_session_id。在 Python 中,请使用关键字参数传入它。在 PHP 中,有三个方法把它从第一个参数改为第二个参数。参见三个方法的参数顺序有变。检查已移除的方法
如果你调用了在 4.0.0 中移除的方法,请改用替代方法或删除该调用。
方法对照#
Python 方法位于 flowhunt.FlowsApi,相同的 v3 方法也存在于 flowhunt.V3Api。PHP 方法位于 FlowHunt\Api\FlowsApi。
| 用途 | v2 HTTP | v3 HTTP(session id 位于 X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| 启动流程会话(API key) | 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 |
| 读取 artifact | 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 key。from_flow/create 会为你工作区中的某个流程启动会话,需要 API key。create 是嵌入式聊天组件使用的匿名聊天机器人会话,因此不需要 API key。两者都会返回 session_id 和 created_at,HTTP 状态码为 201。其他所有 v3 会话调用只需要 X-FH-Session-Id 请求头。
暂时请通过 HTTP 上传附件
在 4.0.0 中,upload_attachments_v3 和 uploadAttachmentsV3 无法发送文件。API 会返回 422 “Expected UploadFile”,而 Python 方法会在发送请求之前就拒绝字节数据。3.x 的上传方法有同样的问题。在问题修复之前,请以 multipart/form-data 形式把文件发送到 POST /v3/flows/sessions/attachments,并带上 X-FH-Session-Id 请求头。下方的 HTTP 标签页展示了该调用。
迁移前后#
这个示例为一个已发布的流程启动会话、发送“Hello”,并打印流程的回答。每个标签页先展示 3.x 的代码,然后是我们在 https://api.flowhunt.io 上实际运行过的 4.0 代码。4.0 代码从环境变量 FLOWHUNT_API_KEY、FLOWHUNT_WORKSPACE_ID 和 FLOWHUNT_FLOW_ID 读取 API key、workspace id 和 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);
// 注意顺序:时间戳在前,session 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 key。其后的每个调用都通过 X-FH-Session-Id 请求头发送 session 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"以前,session 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 方法把路径参数放在 session 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 方法名的小驼峰形式,例如 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 pingback webhook 的方法也已被移除。那些是 FlowHunt 自己服务器接收的入站 webhook,而不是你的代码发起的调用。
请妥善保管 session id#
session id 是一种凭据
任何拿到 session id 的人都可以读取并继续该对话。不要把它记录到日志,不要把它放进 URL 或查询字符串,也不要把它发送给分析服务。请像对待短期密码一样对待它。
v2 怎么办?#
v2 会话路由自 SDK 4.0.0 起已弃用,并将于 2026 年 11 月 30 日停止服务。在此之前它们仍可正常工作,并且已在API 参考中标记为弃用。SDK 4.0.0 仍包含 v2 方法。在 Python 中,调用其中之一会引发 DeprecationWarning。在 PHP 中,它们在代码中被标记为 @deprecated,你的 IDE 或静态分析工具会给出提示。