MENU
ながみえ

【Dify】システム変数の種類と使い方一覧

ながみえ

Difyでアプリを作っていると、プロンプトや分岐条件のところで sys. から始まる変数を見かけることがあります。

「これって何？」「どこで使えるの？」「値が入らないのはなぜ？」と、最初はかなり混乱しやすいポイントです。

でも逆に言うと、システム変数（sys.）を理解すると、Difyアプリは一気に“実務っぽく”なります。

この記事では、Difyのシステム変数を「まず迷わない」ことを目標に、種類と使い方を整理していきます。

読み終わる頃には以下の内容を理解し、sys.系の変数が出てきても落ち着いて扱えるようになります。

  • Difyのシステム変数（sys.）が何を表しているのか
  • Chatflow / Workflowでの扱いの違い（ざっくり全体像）
  • sys.files・sys.user_id などのよく使う変数の活用イメージ
  • 値が入らないときにまず確認するポイント
Difyの教科書｜生成AIアプリ開発の基礎から実践まで

現在、当サイトではDifyを用いた生成AIアプリ開発の学習カリキュラムを制作中です。

完全な素人でもアプリを作れるようになり、業務の効率化や副業での小遣い稼ぎに活用できることを目指します。

ご期待ください^^

システム変数（sys.）とは？

システム変数は、ひと言でいうと 「Difyが最初から用意してくれている“状況情報”」 です。

ユーザーが入力した内容、会話のID、ユーザーID、アップロードファイルの情報など、アプリが動いている “今この瞬間の状態” を参照できます。

Difyのシステム変数の特徴

特徴は大きく2つあります。

まず、変数名が sys. で始まることです。

たとえば sys.user_id や sys.files のように、「この値はDifyのシステム側が持っている情報なんだな」と判断できます。

もう1つは、基本的に 自分で値を入れるのではなく「参照して使う」 ものだという点です。

もちろんフローの中で加工したり、条件分岐に使ったりはできますが、出発点としては「最初から入ってくる値」だと思っておくと理解しやすいです。

なお、DifyにはChatflowとWorkflowがあり、どちらでもシステム変数は登場しますが、使える変数や出てくるタイミングが少し違うことがあります。

ここはこの後の章で、一覧とセットでわかりやすく整理します。

ほかの変数との違い｜入力変数・会話変数・環境変数

Difyにはシステム変数以外にもいくつか種類の「変数」があり、混ざると一気にややこしくなります。ここでは、最低限の見分け方だけ押さえておきましょう。

ポイントは、「その値はどこから来たのか？」です。ざっくり次のように整理できます。

変数名意味
システム変数（sys.）Difyが最初から持っている情報です。
ユーザーIDや会話ID、ファイルなど“状況”を知るために使います。
入力変数（User Inputなど）ユーザーに入力してもらって集めた値です。
フォームの入力やファイル添付などがここに入ります。
会話変数会話の途中で「この内容を覚えておいて、後でも使う」ための変数です。
Lesson4-2 の主役になります。
環境変数APIキーなど、外に漏れてほしくない設定値を安全に扱うための仕組みです。

ここまでを押さえるだけでも、「sys.ってどこで入れたんだっけ？」という混乱がかなり減ります。

次の章では、いよいよ Difyのシステム変数一覧（Chatflow / Workflow別） を、使い方と注意点つきでまとめていきます。

システム変数一覧｜ChatflowとWorkflow別に整理

ここからは「結局どれが使えるの？」を最短で把握するために、ChatflowとWorkflowに分けてシステム変数（sys.）を整理します。

まずはこの章の表をブックマークしておくと、後でフローを組むときに迷いにくくなります。

Chatflowで使えるシステム変数一覧

Chatflowは「会話が中心」のアプリなので、会話に関する変数（sys.query や sys.dialogue_count、sys.conversation_id）が揃っています。

変数名型何が入る？良くある使いどころ注意点
sys.queryStringユーザーが最初に入力した内容初回入力をそのまま要約・分類・整形に使う「初回の入力」なので、途中の追加入力とは区別して考える
sys.filesArray[File]ユーザーがアップロードしたファイル（画像等）PDF/画像などの処理の入口（Document Extractorにつなぐ等）アップロード機能をアプリの「機能」から有効化が必要
sys.dialogue_countNumber会話のターン数（ラウンド数）1ターン目だけ案内を出す、3ターン目で途中要約を入れる各ラウンド後に自動で+1される
sys.conversation_idString会話セッションのIDログの整理、同じ会話の流れを追う会話を同じグループとして扱うための識別子
sys.user_idStringユーザーIDユーザーごとに挙動を変える、利用状況を追うWebAppとService APIで会話履歴が共有されない点に注意
sys.app_idStringアプリID複数アプリ運用時のログ・分析開発者向けの識別子として説明されている
sys.workflow_idStringワークフローIDどのフロー構成が動いたか追跡開発者向け（ノード情報の追跡）
sys.workflow_run_idString実行ID「この実行」をログで追跡する過去実行の追跡に使える

Workflowで使えるシステム変数一覧

Workflowは「業務フローが中心」なので、会話よりも「実行・ログ・識別」に寄った変数がメインです。

また sys.files は [LEGACY]（互換目的） とされている点が重要で、新規開発ではStartノードでファイル入力を設計していくのが安心です。

変数名型何が入る？良くある使いどころ注意点
sys.filesArray[File]初回利用時にアップされたファイル（画像等）既存フローの互換対応[LEGACY] 扱い。新規はStartでファイル入力を作るのがおすすめ
sys.user_idStringユーザーIDユーザー別の処理・ログワークフロー利用時に自動付与される説明
sys.app_idStringアプリID複数アプリの識別、基本情報の記録開発者向けの識別子として説明されている
sys.workflow_idStringワークフローIDどの構成が動いたか追跡ノード情報の追跡用途として説明
sys.workflow_run_idString実行ID実行ログの追跡、障害調査過去実行の追跡用途
sys.timestampNumber実行開始時刻定期実行・監査ログで「いつ動いたか」を残すWorkflow実行の開始時刻として説明

次の章では、これらのシステム変数を「どこで参照するのか」「If/Else分岐でどう使うのか」「値が入っているかをどう確認するのか」を、実際の作り方に寄せて説明していきます。

使い方：どこで参照できる？

システム変数は「一覧を眺めて終わり」ではなく、フローの中で必要な場所に差し込んで初めて価値が出ます。

ここでは、初心者がまず使うことになる3か所（プロンプト／条件分岐／デバッグ）に絞って、迷わない使い方をまとめます。

プロンプト内（LLMノードなど）で参照する

いちばんシンプルなのは、LLMノードのプロンプトにシステム変数を入れて、AIに状況を伝える使い方です。

たとえば「会話回数に応じて説明を短くする」「アップロードされたファイルがある前提で指示を変える」といった制御ができます。

操作としては難しくなく、基本は「変数を挿入する → 文章として読める形にする」の順番です。

具体的には次の流れでOKです。

  • プロンプト編集欄で「変数を挿入（変数ピッカー）」を開く
  • sys. で始まる変数を選んで挿入する（手入力よりミスが減ります）
  • 変数の前後に、AIが理解しやすい説明文を添える

たとえば、プロンプト内ではこのように書くイメージです。

  • ユーザーID：{{sys.user_id}}
  • 会話回数：{{sys.dialogue_count}}
  • アップロードファイル：{{sys.files}}

ここでのコツは、「変数だけポンと置かない」ことです。

AIは変数の中身を読めますが、それが何の情報なのかが文章で添えられている方が、出力が安定します。

If/Elseで条件分岐に使う

Difyで “アプリっぽさ” が一気に上がるのが、If/Else（条件分岐）でシステム変数を使う方法です。

ここができるようになると、「ファイルがある時だけ処理する」「初回だけ丁寧に説明する」といった実務的な動きが作れます。

代表例を2つだけ紹介します。まず、会話回数で出し分けする例です。

  • sys.dialogue_count が 1 のとき：最初だけ使い方ガイドを表示
  • それ以外：通常の回答だけ返す（ガイドは省略）

次に、ファイル有無で分岐する例です。

  • sys.files が空（または存在しない）なら：
    「PDFをアップロードしてください」と案内して終了
  • sys.files に入っているなら：
    Document Extractorなど次の処理へ進む

初心者のうちは、条件分岐を作っても「いつも同じルートに行ってしまう」ことがあります。

その場合は、条件式が間違っているより先に “そもそもその変数に値が入っているか” を疑うのが近道です。

次の見出しのデバッグ方法が役立ちます。

値の確認（デバッグ）でつまずきを減らす

システム変数で一番多い詰まりポイントは、「変数名は合っているのに、値が入っていない」ケースです。

このときに頼りになるのが、プレビュー実行中に変数の中身を確認する機能（Variable Inspectのような確認ビュー）です。

確認の手順は難しくありません。ざっくり次の流れで見ていきます。

  • フローをプレビュー実行する（テスト入力やファイルを入れて実行）
  • 実行結果の画面で、各ノードの入力・出力や変数の値を確認する
  • sys.files や sys.query など、狙っている変数に値が入っているかを見る

ここで値が空なら、原因はだいたい次のどれかです。

  • そもそもテスト時に、ファイルをアップロードしていない
  • アプリ側でファイルアップロード機能が有効になっていない
  • Chatflowで使うつもりの変数を、Workflow側で見ている（またはその逆）

まとめ

システム変数（sys.）は、Difyアプリが動いている“今の状況”を教えてくれる便利な材料でした。

まずは「どんな種類があるか」を押さえたうえで、プロンプト・条件分岐・デバッグの3点セットで使えるようになると、アプリ開発がぐっと楽になります。

ここまで読んだら、まずは自分のDifyアプリで sys.files と sys.dialogue_count を一度だけでも触ってみてください。

実際に値を確認できると、今後のレッスンがかなり楽になります。

Difyの教科書｜生成AIアプリ開発の基礎から実践まで

現在、当サイトではDifyを用いた生成AIアプリ開発の学習カリキュラムを制作中です。

完全な素人でもアプリを作れるようになり、業務の効率化や副業での小遣い稼ぎに活用できることを目指します。

ご期待ください^^

記事URLをコピーしました