Migrations des SDK
Migrer vers le SDK 4.0 et l'API de session v3
Faites passer le code Python et PHP des appels de session de flux v2 à la v3, qui envoie l’id de session dans un en-tête.
L'API de session v2 arrive en fin de vie le 30 novembre 2026
Le SDK 4.0.0 déprécie les appels de session de flux v2, comme create_flow_session, invoke_flow_response et poll_flow_response. Les routes de session v2 arrivent en fin de vie le 30 novembre 2026. Migrez votre code vers les appels v3 présentés sur cette page avant cette date.
La version 4.0.0 des SDK Python et PHP de FlowHunt ajoute l’API de session de flux v3. Y passer permet de garder vos id de session de chat hors des URL, et l’essentiel du travail consiste à renommer des méthodes. Cette page présente ce qui a changé, quels appels renommer, et le code avant et après.
Ce qui a changé#
Les appels de session v3 transmettent l’id de session dans l’en-tête X-FH-Session-Id, jamais dans l’URL. Les corps de requête et de réponse sont identiques à ceux de la v2. Les routes de session v2 sont dépréciées et arrivent en fin de vie le 30 novembre 2026.
En v2, chaque appel de chat place l’id de session dans le chemin, par exemple /v2/flows/sessions/{session_id}/invoke. L’id de session est le seul identifiant dont dispose une session de chat anonyme, et les URL finissent dans les journaux d’accès, les journaux de proxy, l’historique du navigateur et les en-têtes Referer. Un en-tête, non.
Installer la version 4.0.0#
Python
Le paquet sur PyPI est flowhunt.
pip install --upgrade "flowhunt>=4,<5"PHP
Le paquet sur Packagist est flowhunt/flowhunt-php-sdk. Il nécessite PHP 8.1 ou une version plus récente.
composer require flowhunt/flowhunt-php-sdk:^4.0Migrer en quatre étapes#
Mettre à jour le paquet
Installez la version 4.0.0 comme indiqué ci-dessus. Vos appels v2 existants continuent de fonctionner après la mise à jour, vous pouvez donc migrer un appel à la fois. Terminez avant le 30 novembre 2026.
Renommer chaque appel de session
Ajoutez
_v3au nom de la méthode Python ouV3à celui de la méthode PHP. La correspondance des méthodes liste toutes les paires.Passer l’id de session comme argument d’en-tête
L’argument d’id de session est désormais
x_fh_session_id. En Python, passez-le par mot-clé. En PHP, trois méthodes le prennent en deuxième position au lieu de la première. Voir l’ordre des arguments modifié pour trois méthodes.Vérifier les méthodes supprimées
Si vous appelez l’une des méthodes supprimées dans la 4.0.0, passez à la méthode de remplacement ou supprimez l’appel.
Correspondance des méthodes#
Les méthodes Python se trouvent sur flowhunt.FlowsApi, et les mêmes méthodes v3 existent aussi sur flowhunt.V3Api. Les méthodes PHP se trouvent sur FlowHunt\Api\FlowsApi.
| Élément | HTTP v2 | HTTP v3 (id de session dans X-FH-Session-Id) | Python 3.x → 4.0 | PHP 3.x → 4.0 |
|---|---|---|---|---|
| Démarrer une session de flux (clé API) | POST /v2/flows/sessions/from_flow/create | POST /v3/flows/sessions/from_flow/create | create_flow_session → create_flow_session_v3 | createFlowSession → createFlowSessionV3 |
| Démarrer une session de chatbot (anonyme) | POST /v2/flows/sessions/create | POST /v3/flows/sessions/create | create_chatbot_session → create_chatbot_session_v3 | createChatbotSession → createChatbotSessionV3 |
| Envoyer un message | POST /v2/flows/sessions/{id}/invoke | POST /v3/flows/sessions/invoke | invoke_flow_response → invoke_flow_response_v3 | invokeFlowResponse → invokeFlowResponseV3 |
| Interroger les événements | 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 |
| Annuler une exécution | POST /v2/flows/sessions/{id}/cancel | POST /v3/flows/sessions/cancel | cancel_flow_session → cancel_flow_session_v3 | cancelFlowSession → cancelFlowSessionV3 |
| Revenir à l’ancre précédente | POST /v2/flows/sessions/{id}/back | POST /v3/flows/sessions/back | go_back → go_back_v3 | goBack → goBackV3 |
| Déclencher un hook de chat | POST /v2/flows/sessions/{id}/hook | POST /v3/flows/sessions/hook | fire_chat_hook → fire_chat_hook_v3 | fireChatHook → fireChatHookV3 |
| Reprendre un hook en attente | POST /v2/flows/sessions/{id}/resume-hook | POST /v3/flows/sessions/resume-hook | resume_hook → resume_hook_v3 | resumeHook → resumeHookV3 |
| Définir les variables du flux | PATCH /v2/flows/sessions/{id}/variables | PATCH /v3/flows/sessions/variables | update_session_variables → update_session_variables_v3 | updateSessionVariables → updateSessionVariablesV3 |
| Lister les pièces jointes | GET /v2/flows/sessions/{id}/attachments | GET /v3/flows/sessions/attachments | get_attachments → get_attachments_v3 | getAttachments → getAttachmentsV3 |
| Envoyer une pièce jointe | POST /v2/flows/sessions/{id}/attachments | POST /v3/flows/sessions/attachments | upload_attachments → upload_attachments_v3 | uploadAttachments → uploadAttachmentsV3 |
| Supprimer une pièce jointe | DELETE /v2/flows/sessions/{id}/attachments/{file_id} | DELETE /v3/flows/sessions/attachments/{file_id} | delete_attachment → delete_attachment_v3 | deleteAttachment → deleteAttachmentV3 |
| Avis sur un message | POST /v2/flows/sessions/{id}/feedback | POST /v3/flows/sessions/feedback | create_message_feedback → create_message_feedback_v3 | createMessageFeedback → createMessageFeedbackV3 |
| Lire un artefact | GET /v2/flows/sessions/{id}/artefacts/{artefact_id} | GET /v3/flows/sessions/artefacts/{artefact_id} | get_artefact_content → get_artefact_content_v3 | getArtefactContent → getArtefactContentV3 |
| Recherche à la saisie (nouveau, pas de v2) | aucune | POST /v3/flows/sessions/search | invoke_search_v3 | invokeSearchV3 |
Le téléchargement d’une pièce jointe (GET /v2/flows/sessions/{id}/attachments/{file_id}) n’a pas de version v3. C’est un appel authentifié du tableau de bord et il ne fait pas partie de cette migration.
Seuls les deux appels de création demandent votre clé API. from_flow/create démarre une session pour un flux de votre espace de travail et exige la clé. create est la session de chatbot anonyme utilisée par le widget de chat intégré, elle ne prend donc pas de clé. Les deux renvoient session_id et created_at avec un code HTTP 201. Tous les autres appels de session v3 n’ont besoin que de l’en-tête X-FH-Session-Id.
Envoyez les pièces jointes en HTTP pour l'instant
Dans la 4.0.0, upload_attachments_v3 et uploadAttachmentsV3 ne peuvent pas envoyer de fichier. L’API renvoie 422 « Expected UploadFile » et la méthode Python rejette les octets avant même l’envoi de la requête. Les méthodes d’envoi de la 3.x ont le même problème. En attendant une correction, envoyez le fichier en multipart/form-data vers POST /v3/flows/sessions/attachments avec l’en-tête X-FH-Session-Id. L’onglet HTTP ci-dessous montre l’appel.
Avant et après#
Cet exemple démarre une session pour un flux publié, envoie « Hello » et affiche la réponse du flux. Chaque onglet montre d’abord le code 3.x, puis le code 4.0 que nous avons exécuté contre https://api.flowhunt.io. Le code 4.0 lit la clé API, l’id de l’espace de travail et l’id du flux dans les variables d’environnement FLOWHUNT_API_KEY, FLOWHUNT_WORKSPACE_ID et 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 # à garder secret, ne jamais le journaliser
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(); // à garder secret, ne jamais le journaliser
$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);
// Attention à l'ordre : d'abord l'horodatage, ensuite l'id de session.
$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
Seul l’appel de création envoie la clé API. Chaque appel suivant envoie l’id de session dans l’en-tête X-FH-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"Auparavant, l’id de session faisait partie de chaque chemin, par exemple /v2/flows/sessions/$SESSION_ID/invoke. Un appel v3 sans l’en-tête renvoie 401.
Fonctionnement de l’interrogation#
from_timestampest exprimé en millisecondes depuis l’époque Unix. L’interrogation renvoie les événements dontcreated_at_timestampest strictement supérieur.- Partez du
created_atde la réponse d’invocation, qui est une valeur en millisecondes envoyée sous forme de chaîne : convertissez-la en entier. Utilisez0pour obtenir toute la session. N’utilisez pas lecreated_atde la réponse de création, qui est une date et une heure, et non des millisecondes. - Après chaque interrogation, positionnez
from_timestampsur la valeurcreated_at_timestampde l’événement le plus récent moins 1 et ignorez les événements dont vous avez déjà vu l’event_id. Des événements créés dans la même milliseconde peuvent arriver lors d’interrogations différentes. Le widget de chat FlowHunt interroge de la même manière. - Chaque événement possède un
event_type(ai,humanousystem), unaction_type(message,loading,tool_call,failed,hook_waiting_for_inputet d’autres) et desmetadata. Le texte de la réponse se trouve dansmetadata.messagedes événementsaide typemessage.
FlowHunt n’envoie pas d’événement distinct de type « exécution terminée ». Lorsque nous avons exécuté les exemples contre un flux à une seule étape, l’interrogation a renvoyé un événement system de type loading, puis un événement ai de type message contenant la réponse, et rien ensuite. C’est pourquoi les exemples s’arrêtent à la première interrogation qui n’apporte aucun nouvel événement après l’arrivée d’une réponse, et lèvent une exception sur failed. Si votre flux envoie plusieurs messages ou attend une saisie avec hook_waiting_for_input, définissez votre propre condition d’arrêt.
Ordre des arguments modifié pour trois méthodes#
Réordonnez ces trois appels
Les méthodes v3 placent les paramètres de chemin avant l’en-tête d’id de session. En PHP, et en Python lorsque vous passez les arguments par position, ces trois appels échouent avec une erreur de type ou envoient silencieusement de mauvaises valeurs si vous ne les réordonnez pas.
| 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) |
En Python, passez des arguments par mot-clé partout, par exemple x_fh_session_id=session_id, et l’ordre n’a plus d’importance. La version 4.0 vérifie aussi les types d’arguments en Python : from_timestamp doit être un int. Passer la chaîne "0" déclenche une ValidationError de pydantic.
Autres changements incompatibles dans la 4.0.0#
Ces méthodes existaient en 3.19.1 et ont disparu en 4.0.0, car les points de terminaison d’API sur lesquels elles reposaient ont été supprimés ou modifiés. Les noms de méthodes PHP sont la forme camelCase des noms Python ; par exemple, get_available_models devient getAvailableModels.
| Méthode supprimée | Point de terminaison | Que faire |
|---|---|---|
AgentGridsApi.get_agent_grid_preview | GET /v2/agent_grids/{agent_grid_id}/preview | Supprimez l’appel. |
CustomModelsApi.get_available_models | GET /v2/custom-models/available | Supprimez l’appel. |
FineTuningsApi.create_image_ft, delete_image_ft, search_image_fts, update_image_ft | /v2/photo_ai/images/... | Supprimez les appels. |
WorkspacesApi.update_workspace_auto_recharge | PUT /v2/workspaces/{workspace_id}/auto-recharge | Supprimez l’appel. |
FlowBatchApi.export_csv | GET /v2/flows/{flow_id}/batch/{batch_run_id}/export-csv | Appelez start_export_csv (POST, même chemin), puis get_export_csv_status (GET .../export-csv/{task_id}). |
Les méthodes pour les webhooks du canal Zendesk, de la facturation Shopify, de Replicate et du pingback SERP ont également été supprimées. Ce sont des webhooks entrants destinés aux propres serveurs de FlowHunt, pas des appels effectués par votre code.
Gardez l’id de session secret#
L'id de session est un identifiant d'authentification
Quiconque possède un id de session peut lire cette conversation et la poursuivre. Ne le journalisez pas, ne le placez pas dans des URL ou des chaînes de requête et ne l’envoyez pas à des outils d’analyse. Traitez-le comme un mot de passe à durée de vie courte.
Et la v2 ?#
Les routes de session v2 sont dépréciées depuis le SDK 4.0.0 et arrivent en fin de vie le 30 novembre 2026. D’ici là, elles continuent de fonctionner et sont signalées comme dépréciées dans la référence de l’API. Le SDK 4.0.0 inclut encore les méthodes v2. En Python, en appeler une lève un DeprecationWarning. En PHP, elles sont marquées @deprecated dans le code, ce que votre IDE ou votre analyse statique signalera.