anhhung04/tracecat-automation-best-practices

Tracecat 自動化ベストプラクティス

Slack向け自動化の場合は /skill:tracecat-slackbot-best-practices を使用してください。Tracecat Workspace Chatでは、最初に /skill:tracecat-workspace-chat を読み込んでください。そのホスト固有のツールマッピングが以下の外部MCP手順を上書きします。オンデマンドリファレンス: graph-shape、 expressions、run-python、 tables、trigger-inputs、 case-triggers、secrets、 agent-outputs、agent-presets、 workflow-editing。

ワークフロー

外部Tracecat MCP接続の場合は、推測ではなくライブコンテキストから開始します:

1. list_workspaces でワークスペースを発見します。
2. DSL構文や例が必要な場合は tracecat://platform/dsl-reference を読みます。
3. get_workflow_authoring_context を使用してアクションスキーマ、変数、シークレットを取得します。
4. 既存のワークフローの場合は get_workflow を使用し、その後対象を絞った edit_workflow パッチを適用します — workflow-editing を参照してください。run_if、depends_on、join_strategy を追加または編集する前に、ホストが公開している場合は get_workflow_graph を呼び出し、上流のすべてのアクションとその gated_by リストを最初に読み取ります。
5. validate_workflow で検証し、適切な場合はドラフトまたは公開実行を実行し、list_workflow_executions と get_workflow_execution で障害を検査します。

他のホストは異なるツール表面を公開する場合があります。これらの生のMCP名を機械的に前置するのではなく、そのアダプターに従ってください。

ワークフロー契約を変更する運用上の選択を明確にします: ワークスペース、統合/プロバイダー、シークレットソース、公開/実行動作、破壊的な副作用、承認、または受け入れ基準。リクエストがすでに十分に具体的である場合は、先に進みます。

グラフ形状

オーサリング前に形状をスケッチし、作業が許す限り1行に近づけます。並列よりも線形を、完全接続よりも読みやすさを優先します: エッジが少ないことが指標です。

• depends_on は実行順序であり、データ配線ではありません。 アクションは、直接の親だけでなく、任意の祖先から ACTIONS.<ref>.result を読み取ることができます — 検証は、refがワークフロー内に存在することを確認しますが、それが親であることは確認しません。アクションが 待つ 必要がある場合にのみエッジを追加し、値を到達可能にするためには決して追加しません。
• 一度だけゲートします。アクションの run_if は、チェーン上のその下にあるすべてのアクションもスキップするため、下流で繰り返さないでください。 すべてのアクションが同じ TRIGGER.enabled && ... ガードを持つチェーンは誤りです。最初のアクションだけが必要です。下流のアクションは、新しい 条件に対してのみ、単独で独自の run_if を持ちます。例外は結合ですが、それは罠です: 複数の親を持つタスクは、1つが存続している間は強制スキップされませんが、デフォルトの join_strategy: all は すべての 親が訪問されたことを要求するため、1つのブランチがスキップされると結合に到達できず、ワークフローが失敗します。join_strategy: any を使用するか、結合自体にブランチの条件を繰り返して、最初に自分自身をスキップさせます。
• デフォルトは単一チェーンです。本当に独立した作業で、並行して実行する価値がある場合にのみ分岐し、後続のアクションが複数のブランチからの結果を必要とする場合にのみ再結合します。
• 親は1つが標準です。複数の親がある場合は意図的な結合を意味します — 目的を持って join_strategy を選択します。
• 各 run_if は短く保ちます: 1つの新しい条件に対する1つの読みやすい比較。長い &&/|| チェーンは、通常、上流のゲートを言い換えているか、以前の変換に属しています。
• 通常のワークフローは約20ノード以下、エージェンティックワークフローは約6ノード以下に保ちます。プロセスが読まれる順序に従った読みやすい上から下へのフローと、人間が読めるrefを優先します。Tracecat MCPはアクションまたはエッジが変更されるとキャンバスを自動フォーマットするため、ノードを手動で配置するのではなく layout を省略します。

過剰接続の書き換え、結合戦略、エラーエッジ、およびscatterが分岐ではない理由については、graph-shape を参照してください。

アクション優先順位

ジョブを実行する最も具体的なアクションを選択します:

1. 統合アクション (tools.<integration_slug>.*) — 呼び出す製品用。API呼び出しを書く前に、短い製品名またはアクション名の部分文字列（例 query="okta"）で list_actions を検索するか、既知の tools.<integration_slug> 名前空間を参照します。検索はリテラル部分文字列を一致させ、キーワードを分離しません。最初のページに適切なアクションがない場合、has_more が true の間 next_cursor に従います。get_action_context で候補を検査し、必要な資格情報と引数を比較します。
2. コアアクション: 統合アクションのない製品またはエンドポイント用の core.http_request / core.http_paginate、整形用の core.transform.*、およびプラットフォームデータ用の core.table.* / core.cases.*。
3. core.script.run_python — 他のアクションでカバーされない自己完結型のステップにのみ使用します。統合アクションやHTTPアクションが呼び出しを行える場合は、PythonからAPIを呼び出さないでください。

tools.* 名を発明しないでください。汎用リクエストが複数の統合に適合する場合は、最初に候補を表示します。

エージェントとPythonの選択

作業の 種類 に基づいて決定し、保守性と可読性のためにワークフロー全体を最適化します — ジョブを実行するための最小限のアクションと最小限のコード。

• エージェンティックな作業 → エージェントを使用 (ai.agent / ai.preset_agent)。判断、調査、ルーティング、エンリッチメントの選択、要約、メッセージの作成、Slackへの投稿などが必要なものすべて。プリセットの actions 許可リストまたはスキルの metadata.tools にツールを付与し、エージェントにそれらを任せます。エージェント、プロンプト、スキルを優先します — それらは、決定論的ノードのグラフよりもはるかに少ない可動部分で創造的思考を担います。
• 決定論的なデータ配線 → Pythonを使用 (core.script.run_python)。行の変換、正規化、編集、結合、バッチ処理をテーブルに行います。これはまさにPythonの用途です — 悪い兆候ではありません。1つの明確な run_python アクションは、同じ作業を多くのノードに分散するよりも優れています。API呼び出しはデータ配線ではありません: それらは統合アクションまたは core.http_* アクションに属します（アクション優先順位を参照）。

悪い兆候は、エージェンティック な部分にPythonを使用することです — 例えば、エージェントにSlackツールを与える代わりに、スクリプトからエージェントのSlackメッセージを作成または送信すること。

プロンプトサイズのガードレール: プロンプトに動作を合理的なサイズまで押し込みます。単一のプロンプトが大きくなりすぎて読みやすさを保てない場合は、1つの巨大なプロンプトを膨らませるのではなく、サブエージェントまたはスキル に分解します。

エージェントファースト自動化

ユーザーがエージェンティックワークフロー、エージェントプリセットを要求した場合、またはエージェントの使用を指示した場合、エージェントを作業のプライマリオーナーにします。必要なツールを与え、調査、判断、ルーティング、メッセージの作成、および行動を信頼します。デフォルトは薄い形状です: trigger -> reshape/redact -> upsert event record -> ai.agent（または ai.preset_agent）。

エージェントの実行前に正規化されたイベントを永続化します。イベントがSIEM、ログプラットフォーム、SaaSウェブフックストリーム、監査証跡、またはクラウドサービスから発生する場合、最初にTracecatテーブルに正規化されたペイロードとレビューステータスを、決定論的なupsertとともに保存します。これにより、リトライ、重複ウェブフック、リプレイに耐久性のある真実のソースが提供されます。保存された行をエージェントにポイントすると、ワークフロー — エージェントではない — がイベントの最初の耐久性のあるレコードを所有します。

決定論的ノードは、薄く、直接的で、監査が容易であり、エージェントが所有すべきでない作業を行うことによってその地位を獲得します: エージェントがデータを見る前にシークレットを編集、スキーマを正規化、イベント行をupsert、重複排除チェックで高価なエージェント実行をガード、バインドされたバッチを準備、または耐久性のある状態をチェックポイントします。判断、ルーティング、エンリッチメント、メッセージ構成、ソフト承認決定、および最終通知動作はエージェントに保持します。承認質問自体に判断が必要な場合、エージェントに決定させるか、リクエストをドラフトさせます。

2つの異なるメカニズムがリスクをカバーし、それらはプリセット所有のツールと競合しません。ワークフロー自体が実行する不可逆的な外部効果に対して決定論的ゲートを使用します — グラフがそのノードが実行されるかどうかを決定します。エージェントが保持するリスクのあるツールに対しては、プリセットでツールごとの tool_approvals を使用します: エージェントはツールを保持し、その特定の呼び出しが行われる前に人間のために実行が一時停止します。

多くの小さな決定論的ノードよりも、1つの適切に指示されたエージェントまたは再利用可能なプリセットを優先します。エージェントのツールは通常、プリセットの actions 許可リスト、または複数のエージェントがグループを共有する場合はアタッチされたスキルの metadata.tools に存在します。これにより、エージェントはWorkspace Chatとそれを呼び出すすべてのワークフローで同じツールを持ちます。命令は許可ではなく動作を運びます: 出力契約、Slackスタイル、重複排除ルール、テナント境界、許可された副作用はプリセット命令に入れられ、エージェントはリポジトリファイルの代わりにそれを読み取ります。エージェントがツールを必要とする場合、そこに狭いツールを付与することは、通常、同じ呼び出しをワークフローアクションでラップするよりも優れています。

ai.preset_agent ノードは通常、preset と user_prompt のみを運び、実行固有のコンテキスト用のオプションの instructions 追加を伴います。その actions 引数は、その実行のためにプリセットおよびそのスキルのレジストリツールを置き換え、追加はしません — MCPツールはアタッチされたままになり、空のリストは無視されます — そのため、テストまたは評価でプリセットを異なるツールセットで試すのに適しています。出荷ワークフローに残されたリストは、プリセットのスキルが貢献するレジストリツールも削除しますが、これは作者が意図したものではほとんどありません。

エージェント命令は、禁止ではなく目標、コンテキスト、理由として記述します。包括的なルールは、エージェントに与えられたツールをキャンセルする可能性があります: ある呼び出し元が「提供された証拠のみを使用する」と追加し、エージェントは付与された単一のポリシールックアップツールをスキップしました。ハードルールは不可逆的または外部向けのアクションのために予約し、それらの背後に tool_approvals または決定論的ゲートを、プロンプトの文言に依存するのではなく配置します。

プリセットのランタイムは list_actions が示すよりも多くの機能を持っています: 実際のシェルとファイルツール、Python、curl、jq、DuckDB。推定される制限を補うためにワークフローヘルパーを追加する前に、プリセット/ランタイムコンテキストを検査します — agent-presets を参照してください。

オーサリングデフォルト

• エージェンティックワークフローの場合、ほとんどの動作をエージェントプロンプト/プリセットにプッシュします。イベント駆動型ワークフローの場合、エージェントの前の単一のreshape/redact/upsertアクションが通常適切な決定論的境界です。
• エージェンティックな作業には ai.agent / ai.preset_agent を使用します。決定論的なAPI呼び出しには製品の tools.* アクション（存在しない場合は core.http_request）を使用します。決定論的なデータ作業には core.script.run_python を使用しますが、インライン式、run_if、または core.transform.* アクションが除外された後に限ります — expressions および run-python を参照してください。
• バルクテーブル書き込みの場合、行がすでに整形されている場合は、ネイティブの core.table.insert_rows アクションを1回使用することを優先します（バッチあたり最大1000行）。整形、チャンク化、またはテーブル/ケース書き込みの混合が必要な場合は、core.script.run_python をインポートされたヘルパーとバウンドバッチとともに使用し、多くのDBバックアップアクションを分散させる代わりにします。
• ユーザーが明示的に広範なネットワーク機能を受け入れない限り、core.http_request をエージェントに与えないでください。決定論的HTTPはワークフローグラフまたは厳密にスコープされたサブフローに配置します。
• 実際のオーケストレーション境界、再利用可能な子ワークフロー、個別の実行履歴、承認、長時間実行アクション、または独立したチェックポイントがある場合にのみサブフローに分割します。core.workflow.execute を使用し、ハードコードされたIDよりも workflow_alias を優先します。サブフローバルクデフォルト: loop_strategy: batch、batch_size: 32、fail_strategy: isolated、wait_strategy: wait（親が子の結果を必要としない場合のみ detach を使用）。
• run-pythonおよびエージェントの出力を小さく保ちます: 下流の行、サマリーカウント、バウンドされたエラーサンプル。
• インラインの ai.agent よりも再利用可能なエージェントプリセットを優先し、非推奨のトップレベル model_name/model_provider よりも model オブジェクトを優先します — agent-presets を参照してください。

よくある間違い

• エージェンティック な部分にPythonを使用する — エージェントのSlackメッセージを作成または投稿する、またはスクリプトでルーティング/判断呼び出しを行う。エージェントはメッセージ構成、投稿（Slackツール経由）、判断を所有します。Pythonは決定論的なデータ配線を所有します。
• グラフを過剰接続する: すべてのプロデューサーからすべてのコンシューマーへのエッジ。祖先から読み取り、1つのチェーンを維持します（graph-shapeを参照）。
• チェーンに沿って run_if を繰り返す、祖先がすでに強制した条件を言い換える。スキップは自動的に伝播します — 上部で一度ゲートし、下流のアクションには、それだけが導入する新しい条件に対してのみ run_if を与えます（graph-shapeを参照）。
• ワークフローアクション名はMCPツール名ではありません。ワークフローを管理するには create_workflow などのMCPツールを使用し、アクション名（core.http_request など）はワークフローYAML内でのみ使用します。
• tools.* アクション名を発明する。list_actions でアクションを発見し、get_action_context で正確なスキーマを検査します。
• 適切な tools.* アクションが存在する場合に、core.script.run_python（requests、httpx）または生の core.http_request から製品のAPIを呼び出す。最初に製品の list_actions を検索およびページングします。
• 通常のループ管理に for_each を使用する、またはデータ集約型のバッチ処理、フィルタリング、結合、テーブル書き込みにscatter/gatherを使用する。ワークフローレベルのループにはデフォルトでscatterを使用します。下流のステップが結合された結果を必要とする場合にのみgatherを追加し、それ以外の場合は省略します。10を超える分散DBバックアップテーブル/ケースアクションには特に注意してください。Postgres接続スロットを枯渇させる可能性があります。Scatterのオプションの間隔は作業を分散できますが、DB書き込みをバッチ処理しません。データ集約型のバッチ処理、フィルタリング、結合、テーブル書き込みには、1つの core.table.insert_rows または1つのwell-scoped core.script.run_python アクションを使用します。
• core.workflow.execute サブフロー呼び出しの loop_strategy をデフォルトの batch から変更せずに、for_each を items として使用する。items はサブフローの繰り返しを制御します。for_each がなくても、サブフローは依然としてバッチ処理されたアイテムごとに1回実行されます。for_each を追加すると、バッチ処理の上に追加のループがネストされます。
• 複数行にわたって run_if 条件内でYAMLマルチライン文字列または >- / |- ブロックスカラーを使用する。これらは1行に保ちます。
• プリセットの actions 引数が、その実行のためにプリセットのスキルからのレジストリツールを置き換える（追加しない）ことを忘れる。MCPツールは影響を受けません。
• 各ワークフローは1つのトリガーしか持てないことを忘れる。複数のトリガー入力が必要な場合は、異なるトリガーを持つ複数のワークフローが必要です。