人間の入力 API 連携フロー

このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版を参照してください。

ワークフローが人間の入力ノードに到達すると一時停止し、ストリーミングレスポンスから human_input_required イベントが送出されます。このイベントが運ぶ form_token を使って、ワークフローが再開するまでフォームのライフサイクルを進めます。各エンドポイントのリファレンスは人間の入力 API を参照してください。

フロー

以下のフローは Workflow アプリと Chatflow アプリの両方に共通します。両者は手順 1 のエントリエンドポイントと手順 5 の再開エンドポイントだけが異なります。

アプリをストリーミングモードで起動

Workflow アプリはワークフローを実行を呼び出します。Chatflow アプリはチャットメッセージを送信を呼び出します。
SSE ストリームで human_input_required イベントを監視し、その form_token を取得します。すべてのストリームチャンクに task_id が含まれます。手順 5 で監視を再開する必要がある場合に備えて、保持しておきます。

フォーム定義を取得

form_token を指定して人間の入力フォームを取得エンドポイントを呼び出します。レスポンスにはレンダリング済みの Markdown、入力フィールド定義、利用可能なアクション、事前入力済みのデフォルト値、そして expiration_time（この時刻を過ぎるとフォームを送信できなくなります）が含まれます。フォームを受信者に表示します。

（ファイル入力時のみ）ローカルファイルをアップロード

受信者が file または file-list 入力にローカルファイルを添付する場合は、ファイルをアップロードで先にアップロードします。このエンドポイントは id を返すので、送信時に upload_file_id として参照します。実行、アップロード、送信の各呼び出しで一貫した user を使用してください。リモートファイルにアップロードは不要です。送信時に {transfer_method: remote_url, url} マッピングでインライン添付します。

応答を送信

人間の入力フォームを送信エンドポイントを呼び出し、受信者の入力値、選択された action、そして user を送ります。action は手順 2 のフォーム定義に含まれるアクションのいずれかである必要があります。ファイル入力には、{transfer_method: local_file, upload_file_id} マッピング（手順 3 の結果）と、インラインの {transfer_method: remote_url, url} マッピングのどちらも使えます。トレードオフの詳細は事前アップロードかインラインリモート URL かを参照してください。送信が成功すると確定し、フォームは閉じられ、ワークフローは該当するアクション分岐から再開するため、同じ form_token で再送信することはできません。送信が拒否された場合（無効なアクション、必須入力の欠落、リモートファイルの取得失敗）、フォームはそのまま変わりません。入力を修正し、同じ form_token で再送信してください。

ワークフローの監視を継続

元の SSE ストリームが切断されている場合は、手順 1 の task_id を使います。Workflow または Chatflow のワークフローイベントをストリームエンドポイントに再接続します。再開した実行は、一時停止しなかった実行と同じように、残りのノードイベントを完了までストリーミングします。

事前アップロードかインラインリモート URL か

ファイル入力には 2 つの送信パターンがあります。

事前アップロードしてから upload_file_id で送信（推奨）ファイルをアップロードは、ファイルサイズ・タイプ・拡張子をアップロード時に検証します。受信者はエラーをすぐに確認でき、送信前に再試行できます。
transfer_method: remote_url でインライン送信 バックエンドは送信時にファイルを取得します。実装は速いですが、サイズ・タイプ・取得の失敗があると送信全体が拒否され、他のフィールドを再入力する必要が出る場合があります。

受信者からのフィードバックが伴うインタラクティブなフォームでは、事前アップロードのパターンを推奨します。完全に自動化されたインテグレーションで、誰も再入力を待たされない場合のみ、インラインのトレードオフが見合います。

配信方法の前提

人間の入力 API は、人間の入力ノードで WebApp 配信方法が設定されたフォームのみを対象とします。メール配信のみのフォームは、API に form_token を公開しません。

例：ファイル添付付きの送信

このフォームには、feedback 段落入力、attachments ファイルリスト入力、approve / revise アクションがあるものとします。

人間の入力フォームを取得エンドポイントを呼び出してフォーム定義を取得します。
```
GET /form/human_input/<form_token>
Authorization: Bearer {api-key}
```
ローカルファイルごとにファイルをアップロードエンドポイントを呼び出します。
```
POST /files/upload
Authorization: Bearer {api-key}
Content-Type: multipart/form-data

file=<binary>
user=abc-123
```
{"id": "1a77f0df-...", ...} が返ります。

人間の入力フォームを送信エンドポイントを呼び出し、受信者の入力と選択されたアクションを送ります。

POST /form/human_input/<form_token>
Authorization: Bearer {api-key}
Content-Type: application/json

{
  "inputs": {
    "feedback": "公開して問題ありません",
    "attachments": [
      {"transfer_method": "local_file", "upload_file_id": "1a77f0df-..."}
    ]
  },
  "action": "approve",
  "user": "abc-123"
}

{} が返ります。ワークフローは approve 分岐から再開します。

​フロー

​事前アップロードかインラインリモート URL か

​配信方法の前提

​例：ファイル添付付きの送信

フロー

事前アップロードかインラインリモート URL か

配信方法の前提

例：ファイル添付付きの送信