ベストプラクティス

この記事は「踏まれてしまった穴」についてまとめた記事です。 10 個以上のワークフローを作成したことがある場合は、それらに共感できるようになります。まだ書いていない場合は、まず保存して、見つけたときに戻ってきてください。

1. 本番環境に導入できるワークフローの書き方

テンプレートから始める

あなたのシナリオが独特に見えても、240 以上のテンプレートの中には「半分を流用し、半分を改変して」使えるものが必ずあります。テンプレートから始めることで、ゼロから骨組みを作る時間を大幅に節約できます。

テンプレートからインスタンス化する ほとんどのユーザーにとって最初のステップです。

最初に「バカバージョン」を実行し、次に「スマートバージョン」を実行します。

新しいワークフローの最初のバージョン:

• 変数のハードコーディングされたデフォルト値
• 条件を追加せずに、すべてを実行するだけです。
• プラットフォームの統合 LLM キーを使用するため、BYOK を心配する必要はありません
• cron をハングさせず、手動で実行してください

一通り実行した後、変数化、分岐、BYOK、cron、承認を 1 つずつ「絞り込み」ます。このようにして、すべてのステップで問題を簡単に特定できます。

変更を加えるたびに予行演習を行う

何かを変更→DAG構造と変数フローを確認するためにドライラン→再度実行。予行演習のコストはゼロです。ジャンプしないでください。

2. ステップタイプの選択

優先順位は上から下になります。選択するのが難しい場合は、上位にランクされているものを選択してください。

1. code — 決定論的ロジックを使用できる場合は、LLM を使用しないでください。速く、安く、テスト可能。
2. classifier — LLM が必要だが出力がカテゴリである場合に使用します。エージェントを自由にプレイさせるためにシングルを使用しないでください。
3. single — ほとんどのタスクは「要約/抽出/書き換え」です。
4. sub_workflow — 同一段逻辑在多个 workflow 里复用，或单 workflow > 15 个 step。
5. group_chat — タスクに複数の視点での議論が必要な場合に使用します。1 つの Agent で単独完結できる場合は single を使用します。
6. agent_based — タスクには強力な分岐特性があり、各分岐では送信先を決定するために LLM が必要です。
7. state_machine — 複数ラウンドのインタラクション/作業指示書のライフサイクルなど、明確な状態遷移があります。
8. manual_approval — オンライン/支出/外部関係者に影響を与える手順の前に追加する必要があります。

3. 変数とデータフロー

大きなフィールドは最初に抽出されてから渡されます

上流ステップが 100KB JSON を返した場合、それを下流タスクに直接送信しないでください。抽出を使用して、本当に必要なフィールドを選択します。

- id: fetch_data
  type: code
  code: |
    // 返回一个很大的 JSON
    return await heavyFetch();
  extract:
    user_count: $.data.stats.total_users
    top_3: $.data.items[:3].name

使用 |デフォルト(...) 調べます

空の可能性がある変数 (条件によってスキップされたステップの出力) を参照する場合、デフォルトを追加します。

- id: summarize
  type: single
  agent: writer
  condition: "length({{steps.classify.categories}} | default([])) > 0"
  task: "{{steps.classify.output | default('无内容可摘要')}}"

condition ブランチと on_failure の比較

混ぜないでください:

• 条件制御「通常の状況ではこのステップを実行できません」 - スキップ = SKIPPED (失敗とみなされません)
• on_failure は「エラー後の補償アクション」です - 通知の送信/代替データ ソースへのダウングレード

on_failure は通常のブランチとしてではなく、try-catch として使用します。通常のビジネス ロジックでは条件を使用します。

4. エージェントとモデル

tool_set 小さいほど良い

デフォルトのプリセットで提供されるツールは、ほとんどのステップでは使用されません。 2～3個にカットすると成功率が上がり、トークンの消費量が減ります。

タスクに応じてモデルを選択

• 推論 / コードレビュー → Claude Opus 4 / GPT-5 / DeepSeek-Reasoning
• 短い概要 / カテゴリ → Haiku / GPT-4.1-mini / DeepSeek-V3.5
• 漢文 → クロード・ソネット / キミ K2
• ロングコンテキスト (32K+) → キミ K2 / クロード 200K

温度 タスクから選ぶ

• 0.0 – 0.3 – 推論/分類/抽出 (安定化予定)
• 0.4 – 0.7 – 要約/リライト (バランス)
• 0.7 – 0.9 – クリエイティブライティング/ブレインストーミング (クリエイティブになる)

5.冪等性と自動継続

純粋なデータ パイプラインのすべてのステップでべき等: true が追加されます。サービスは再起動後も実行を継続できます。副作用を含むステップ (メッセージの送信/注文) を追加しないでください。

詳細を見る 自動再開。

6. 分割とモジュール化

1. ワークフローには 15 を超えるステップがあるため、分割する必要があります。
2. 同じ 3 ～ 5 ステップのロジックを別のワークフローで使用する必要があります。これはモジュール (sub_workflow) に作成する必要があります。
3. モジュールリリース後、入力の削除や型の変更を行うと互換性が失われるため、MAJOR バージョンのアップグレードが必要となります。

7. コスト管理

• 最初に予行演習をする — 前述のとおり、無駄に本番実行を 1 回走らせることが最もコストを浪費するため、これが最も節約になります。
• 安価なモデルを使用した分類 — 分類子 9/10 には Opus/GPT-5 は必要ありません。
• 同時実行には上限があります — バッチ処理の場合は、sub_workflow + max_Parallel を使用して同時実行性を制御し、TPM が爆発的にならないようにします。
• キャッシュ RAG インデックス — 毎回同じコーパスを再埋め込み、結果を製品に永続化するにはコストがかかります。
• バインド予算アラーム — 在通知设置里加"单 execution cost > $1"或"当日累计 > $50"告警。

8. セキュリティとコンプライアンス

• キーを YAML に書き込まないでください。Credential Center を使用してください。
• コードステップの認証情報: リストは明示的である必要があります。必要のない認証情報をステップに与えないでください。
• 支払い/外部通信/顧客データベースの書き込みの前に、manual_approval を追加します。
• ユーザーデータを含むワークフローを開くことを検討してください 承認者コンプライアンス チームが入力する承認者のリスト。
• Webhook 用の API Key（および互換モードの signing secret）は定期的にローテーションします。

9. テストと立ち上げのプロセス

1. 新しいワークフローは、最初にテスト ワークフロー ページで予行演習されます。
2. ローカル ノード/Python でコード ステップ スクリプトを個別に実行して、出力を確認します。
3. ブレークポイント デバッガーと小さなサンプルを使用してエージェントの動作を 10 回実行し、安定性を確認します。
4. スケジュールをオンラインにする前に、「すぐに 1 回トリガー」を使用して、タイムゾーン/パラメータのプリセットを確認します。

10. コラボレーションとバージョン

• 重要な変更を加える前に、「YAML をエクスポート」してローカル バックアップを作成してください。バージョン履歴がわからない場合でも、ローカル コピーの方が信頼性が高くなります。
• 複数人での編集: 1 人がロックを取得し、変更を保存し、ロックを解放してから、次の人がロックを取得します。並行変更をサブワークフローに分割してください。
• メジャーバージョンが変更される前にチームと同期してください。他の人があなたのモジュールに依存している可能性があります。

11. 監視と警報

• 主要なワークフローの実行失敗は Slack/Feishu 通知に関連付けられており、失敗した場合はすぐにわかります。
• データ ダッシュボードを定期的に確認してください。どのワークフローが最も高価で、最も遅く、最も頻繁に失敗するか?最適化はそこから始まります。
• 監査ログを月に 1 回チェックしてください - アクセス許可に例外がないか、誰が資格情報を使用したかを確認します。

12. ワークフローのチェックリストを完了しました

1. 予行演習に合格しました
2. 成功した実行
3. 各ステップのべき等/再試行戦略が確認されています
4. 外部副作用の前に、manual_approval または明示的な条件制御があります。
5. すべての資格情報は資格情報センターから解析され、YAML には平文キーはありません。
6. cron / Webhook が関連付けられ、「次回のトリガー時間」が確認されました
7. 失敗通知を設定します (少なくとも、execution.failed を Slack にプッシュします)。
8. オフサイトバックアップのために YAML のコピーを git にエクスポートします

さらに読むことをお勧めします

• YAML 構文リファレンス — あいまいなフィールドは正確にチェックできません
• ブレークポイントのデバッグ — 複雑なプロセスの問題を特定するためのツール
• トラブルシューティング — 具体的な症状の比較