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。

bash
pip install --upgrade "flowhunt>=4,<5"

PHP

Packagist 上的软件包是 flowhunt/flowhunt-php-sdk。它需要 PHP 8.1 或更高版本。

bash
composer require flowhunt/flowhunt-php-sdk:^4.0

分四步迁移#

  1. 升级软件包

    按上述方式安装 4.0.0。升级后你现有的 v2 调用仍然可用,因此可以一次迁移一个调用。请在 2026 年 11 月 30 日之前完成。

  2. 重命名每个会话调用

    在 Python 方法名后加 _v3,或在 PHP 方法名后加 V3。方法对照表列出了所有对应关系。

  3. 通过请求头参数传入 session id

    session id 参数现在叫 x_fh_session_id。在 Python 中,请使用关键字参数传入它。在 PHP 中,有三个方法把它从第一个参数改为第二个参数。参见三个方法的参数顺序有变。

  4. 检查已移除的方法

    如果你调用了在 4.0.0 中移除的方法,请改用替代方法或删除该调用。

方法对照#

Python 方法位于 flowhunt.FlowsApi,相同的 v3 方法也存在于 flowhunt.V3Api。PHP 方法位于 FlowHunt\Api\FlowsApi。

用途v2 HTTPv3 HTTP(session id 位于 X-FH-Session-Id)Python 3.x → 4.0PHP 3.x → 4.0
启动流程会话(API key)POST /v2/flows/sessions/from_flow/createPOST /v3/flows/sessions/from_flow/createcreate_flow_session → create_flow_session_v3createFlowSession → createFlowSessionV3
启动聊天机器人会话(匿名)POST /v2/flows/sessions/createPOST /v3/flows/sessions/createcreate_chatbot_session → create_chatbot_session_v3createChatbotSession → createChatbotSessionV3
发送消息POST /v2/flows/sessions/{id}/invokePOST /v3/flows/sessions/invokeinvoke_flow_response → invoke_flow_response_v3invokeFlowResponse → invokeFlowResponseV3
轮询事件POST /v2/flows/sessions/{id}/invocation_response/{from_timestamp}POST /v3/flows/sessions/invocation_response/{from_timestamp}poll_flow_response → poll_flow_response_v3pollFlowResponse → pollFlowResponseV3
取消运行POST /v2/flows/sessions/{id}/cancelPOST /v3/flows/sessions/cancelcancel_flow_session → cancel_flow_session_v3cancelFlowSession → cancelFlowSessionV3
返回上一个锚点POST /v2/flows/sessions/{id}/backPOST /v3/flows/sessions/backgo_back → go_back_v3goBack → goBackV3
触发聊天钩子POST /v2/flows/sessions/{id}/hookPOST /v3/flows/sessions/hookfire_chat_hook → fire_chat_hook_v3fireChatHook → fireChatHookV3
恢复等待中的钩子POST /v2/flows/sessions/{id}/resume-hookPOST /v3/flows/sessions/resume-hookresume_hook → resume_hook_v3resumeHook → resumeHookV3
设置流程变量PATCH /v2/flows/sessions/{id}/variablesPATCH /v3/flows/sessions/variablesupdate_session_variables → update_session_variables_v3updateSessionVariables → updateSessionVariablesV3
列出附件GET /v2/flows/sessions/{id}/attachmentsGET /v3/flows/sessions/attachmentsget_attachments → get_attachments_v3getAttachments → getAttachmentsV3
上传附件POST /v2/flows/sessions/{id}/attachmentsPOST /v3/flows/sessions/attachmentsupload_attachments → upload_attachments_v3uploadAttachments → uploadAttachmentsV3
删除附件DELETE /v2/flows/sessions/{id}/attachments/{file_id}DELETE /v3/flows/sessions/attachments/{file_id}delete_attachment → delete_attachment_v3deleteAttachment → deleteAttachmentV3
消息反馈POST /v2/flows/sessions/{id}/feedbackPOST /v3/flows/sessions/feedbackcreate_message_feedback → create_message_feedback_v3createMessageFeedback → createMessageFeedbackV3
读取 artifactGET /v2/flows/sessions/{id}/artefacts/{artefact_id}GET /v3/flows/sessions/artefacts/{artefact_id}get_artefact_content → get_artefact_content_v3getArtefactContent → getArtefactContentV3
输入即搜索(新增,无 v2 版本)无POST /v3/flows/sessions/searchinvoke_search_v3invokeSearchV3

下载附件(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

Python,SDK 3.x
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)
Python,SDK 4.0
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:
            break

PHP

PHP,SDK 3.x
$session = $flows->createFlowSession($workspaceId, $request);
$invocation = $flows->invokeFlowResponse($session->getSessionId(), $invokeRequest);
$events = $flows->pollFlowResponse($session->getSessionId(), $fromTimestamp);
PHP,SDK 4.0
<?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。

启动会话(API key)
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 中按位置传参时,如果不调整顺序,这三个调用会因类型错误而失败,或者不报错地发送错误的值。

v2v3
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_previewGET /v2/agent_grids/{agent_grid_id}/preview删除该调用。
CustomModelsApi.get_available_modelsGET /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_rechargePUT /v2/workspaces/{workspace_id}/auto-recharge删除该调用。
FlowBatchApi.export_csvGET /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 或静态分析工具会给出提示。