kibana-workflows

Elastic Workflow を作成する

Elastic Workflow の YAML 定義を作成し、反復して改善します。Workflow は Kibana 内で実行される宣言型の自動化です。 Elasticsearch を検索し、データを設定し、分岐やループを行い、コネクターを呼び出し、ケースを作成し、外部システムに通知し、AI ステップを実行します。

環境設定

このスキルは elastic CLI を使って Elasticsearch の操作を実行します。 elastic CLI がインストールされていない場合は、何に必要なものかユーザーに伝えてください。認証情報を推測したり、HTTP API を直接呼び出したり、別の回避策を試したりしないでください。

このスキルでは、HTTP の省略形（例：GET /、GET /_cat/indices、GET /{index}/_mapping、 GET /{index}/_settings/index.mode、POST /_query）で操作を記載しています。このドキュメントの末尾にある 操作の表で、各省略形に対応する elastic CLI コマンドを示しています。HTTP API を直接呼び出さず、必ず CLI を使用してください。

ユーザーがドラフトまたは説明のみを求め、ライブアクセスを明示的に禁止している場合は、接続確認を省略し、CLI や API を呼び出さないでください。ドラフトが対象のデプロイメントで検証されていないことを伝えてください。

Workflow API が利用できない場合は、返されたステータスとメッセージを報告してください。よくある原因として、Kibana のバージョンが未対応であること、ライセンスまたは機能の権限が不足していること、対象プロジェクトで Workflows が提供されていないことが挙げられます。workflows:ui:enabled 設定は Kibana UI を制御しますが、公開 Workflows API を無効にはしません。

作成方法を選択する

デフォルトでは、以下の Discovery-tools パスを選択します。platform.workflows.* ツールは、Kibana 9.5 以降および Serverless でデフォルトで登録されています。次のプローブで確認してください。GET kbn:/api/agent_builder/tools を実行すると { "results": [ { "id": ... } ] } が返されます。結果をファイルに保存し、"id": "platform.workflows." を grep で検索してください。必要な場合のみ、次の 2 つのフォールバックを読み込みます。

• agent_builder エンドポイントがない（404）、または platform.workflows.* ID がない（例：Kibana 9.4）場合 → references/schema-path.md を読み、未加工の JSON Schema から手動で作成します。
• LLM コネクターが Agent Builder に接続されており、ユーザーが Kibana 独自の生成機能を希望する場合 → references/generator-path.md を読みます。

作業を進める前に、選択したパスとその理由を 1 文で伝えてください。実測したパスのベンチマークは references/path-performance.md にあります。

ガイドライン（すべてのパス）

• テストも実行として扱います。 POST kbn:/api/workflows/test はワークフローグラフを実行し、POST kbn:/api/workflows/step/test は選択したステップを実行します。実行されるすべてのアクションが読み取り専用であるか、その影響についてユーザーの許可を得ている場合にのみテストしてください。それ以外の場合は、書き込み、通知、外部への呼び出しを console に置き換えたコピーをテストし、その後実際のステップに戻して、ワークフローを無効のまま保存してください。
• エンドポイントは HTTP 形式の省略表記で引用し、トランスポートをそのまま記載しないでください。 このスキルの本文では、POST kbn:/api/workflows/test のような操作を参照します。省略表記と具体的な CLI コマンドの対応は、Operations テーブルにのみ記載します。
• 汎用の http より、目的に特化したアクションを優先してください。 Slack／Jira／PagerDuty などでは、生の http 呼び出しよりコネクタのステップタイプ（例：slack2.sendMessage）を優先してください。正確なアクションタイプは get_step_definitions（またはフォールバックパスの厳密なスキーマ）で確認してください。
• ステップの出力は steps.<name>.output で参照し、steps.<name>.with.* は使わないでください。 トリガーイベントのデータは event であり、trigger.event や triggers.event ではありません。
• コネクター ID を推測しないでください。 platform.workflows.get_connectors（Discovery-tools パス）または GET kbn:/api/workflows/connectors（Schema パス）を呼び出すか、ユーザーに確認してください。プレースホルダーには、明らかに架空の値を使用してください。
• 失敗への対応を慎重に設計してください。 ユーザーの要件に回復性が求められる場合は、再試行またはフォールバックの動作を追加してください。continue: true をどこにでも追加しないでください。失敗したアクションが隠され、ワークフローが誤って成功を報告する可能性があります。
• 制限を明示し、取り繕わないでください。 API が 403 ... not available を返した場合は、必要なライセンスまたは権限を伝えてください。黙って再試行したり、UI の設定のせいにしたりしないでください。

Discovery-tools パス

対象の Kibana に platform.workflows.* ツールが登録されている場合に使用します。すべての呼び出しは POST kbn:/api/agent_builder/tools/_execute に { "tool_id": "...", "tool_params": { ... } } を指定して行います。レスポンスの形式： { "results": [ { "type": "other", "data": { ... }, "tool_result_id": "..." } ] } — 必要なペイロードは .results[0].data です。リクエスト本文をファイルから送信し、レスポンスをファイルに書き込み（Operations を参照）、そのファイルに対して jq を実行します。複数行の JSON に python3 -c を直接使用しないでください。

コンテキストを小さく保ち、往復を最小限にします。 ステップカタログ全体を最初に読み込まないでください。必要な対象の詳細だけを取得し、大きなツール出力はファイルに保存して（トランスクリプトには含めず）、できるだけ少ないターンで作成します（測定に基づく根拠：references/path-performance.md）。

1. YAML を書き始める前に、ユーザーの意図を把握します。 次の項目を順に特定します。トリガー（manual／scheduled／alert）、実行時にワークフローが受け取る入力、読み取る必要があるデータソース、実行するアクション、望ましい出力です。必須の依存関係が不明な場合（例：Slack コネクター ID）は、ユーザーに確認するか、明示的にプレースホルダーを示します。

2. 使用するものだけを調べます。 このワークフローに必要な特定のステップタイプについて、次を使用します。

   • platform.workflows.get_step_definitions に正確な stepType（例："http"、"elasticsearch.esql.query"、"slack2.sendMessage"）を指定するか、search を指定して検索します。レスポンスには入力パラメーター、設定パラメーター、includeOutputSummary: true を指定した場合の outputSummary、および使用例が含まれます。簡潔な概要では不十分な場合に限り、includeFullSchema: true を指定します。
   • platform.workflows.get_trigger_definitions でトリガーイベントのスキーマを取得します。
   • platform.workflows.get_connectors でコネクターアクションに使用する実際の connector-id 値を特定します。
   • パターンの有効な YAML 形式が必要な場合は、platform.workflows.get_examples を使用します。

   各レスポンスをファイルに書き込み、必要なフィールドに対して jq を実行します。ツール出力全体をトランスクリプトに含めないでください。

3. ワークフロー全体を一度に作成します。 ワークフローには name、少なくとも 1 つのトリガー、および空でない steps 配列が必要です。インデントにはスペース 2 つを使用します。出力は steps.<name>.output.* の形式で参照します。複数のターンに分けて追記するのではなく、1 回の編集で YAML 全体を作成します。

4. 一度検証します。 { "yaml": "..." } を指定して platform.workflows.validate_workflow を呼び出します。検証に失敗すると、参照されているステップタイプのステップ定義とエラーが自動的に返されるため、通常は 2 回目の get_step_definitions 呼び出しは不要です。報告された問題をすべて 1 回の編集で修正し、再検証します。

5. テスト、保存、実行します。 下記の テスト／保存／実行 を参照してください。単一ステップの反復には platform.workflows.workflow_execute_step を使用します（安全でないステップには confirmation_body を指定します）。

Schema パス（最終手段）

platform.workflows.* ツールがない Kibana の場合に限り使用します（上記のプローブを参照）。手順全体については、 references/schema-path.md を参照してください。

テスト／保存／実行

どちらの経路でも共通の最終フェーズです。

1. 実行時に安全なドラフトのみをテストします。 YAML を workflowYaml としてインラインで指定し、実行時の inputs とともに POST kbn:/api/workflows/test を呼び出します。書き込み／通知／外部サービスの呼び出しを行うワークフローでは、まずテスト用コピー内で該当するステップを console に置き換えてから、元に戻し、ワークフローを無効にした状態で保存します。

2. 実行をポーリングします。 レスポンスには workflowExecutionId が含まれます。status が completed、failed、cancelled、timed_out のいずれかになるまで、GET kbn:/api/workflows/executions/{executionId} をポーリングします。その後、ステップごとの出力を確認するため、GET kbn:/api/workflows/executions/{executionId}/logs を取得します。成功として扱うのは status: completed の場合のみです。

3. 保存します。 { yaml, id? } を指定して POST kbn:/api/workflows/workflow を呼び出します。副作用のあるワークフローは、ユーザーが実際の実行を許可するまで enabled: false で保存します。以降の編集では PUT kbn:/api/workflows/workflow/{id} を使用し、yaml、enabled、name、tags、description を更新できます（一部の項目のみの更新にも対応しています）。

4. 許可された場合のみ実行します。 ワークフローを有効にしてから、テスト時と同じ inputs の形式で POST kbn:/api/workflows/workflow/{id}/run を呼び出します。実行とログのエンドポイントで確認します。

ワークフロー YAML クイックリファレンス

version: "1"
name: Manual Hello Workflow
description: Logs a hello message from a manual workflow
enabled: true
tags: ["demo", "workflow"]

triggers:
  - type: manual
    inputs:
      properties:
        name:
          type: string
          description: Name to greet
          default: "world"

steps:
  - name: log_hello
    type: console
    with:
      message: "Hello {{ inputs.name }}"

通常のアクションステップでは、厳密なスキーマで許可されている場合、次のようなフィールドを使用できます。

- name: unique_step_name
  type: step_type
  with:
    param: value
  connector-id: connector-id-for-connector-actions # connector actions only
  if: "steps.previous.output.ok: true"
  timeout: "30s"
  on-failure:
    retry:
      max-attempts: 3
      delay: "5s"
    fallback:
      - name: handle_error
        type: console
        with:
          message: "Step failed"

テキストをレンダリングする場合は {{ ... }} を使用します。値全体のネイティブ型を維持する必要がある場合は、たとえば documents: "${{ steps.search.output.hits.hits }}" のように ${{ ... }} を使用します。

一般的なステップタイプには、次のものがあります。

ステップタイプ	用途
console	テスト中のデバッグログ
elasticsearch.search	Query DSL で Elasticsearch にクエリ
elasticsearch.esql.query	ES|QL で Elasticsearch にクエリ
elasticsearch.bulk	一括インデックス登録
kibana.request	Kibana API の呼び出し
data.set	variables 配下への値の設定
if	KQL 形式の条件による分岐
foreach	コレクションのループ処理
wait	実行の一時停止
http	汎用 HTTP リクエスト
workflow.execute	保存済みの別のワークフローを実行

この一覧は、互換性のあるステップをすべて網羅しているわけではありません。Discovery ツール経由の経路では、platform.workflows.get_step_definitions が「ステップ X が存在するか、またどのような値を受け取るか」に回答します。スキーマ経由の経路では、GET kbn:/api/workflows/schema?loose=false が信頼できる情報源であり、GET kbn:/api/workflows/connectors で設定済みのコネクターインスタンスを一覧表示できます。

data.set は現在の実行用の変数を保存しますが、永続データは保存しません。実行後もデータを保持するようユーザーから求められた場合は、Elasticsearch または Kibana の書き込みアクションを使用します。

例

手動の hello（可能な限り小さなドラフト）：「hello をログに記録するワークフローを作成して。」→ 手動トリガー + Hello {{ inputs.name | default: "world" }} を出力する 1 つの console ステップ。
POST kbn:/api/workflows/test でテストします。デモのテストループを参照してください。

スケジュールされたヘルスチェック：「5 分ごとに https://api.example.com/health に ping を送信し、レスポンスをログに記録して。」→ scheduled トリガー（every: 5m）+ http ステップ + console。正確な with の形式は get_step_definitions("http") で確認します。要望があれば、上限付きのリトライを追加します。

アラートをトリガーとするケース作成 + Slack 通知：「Security アラートが発生したら、ケースを作成して #soc-incidents に投稿して。」→ alert トリガー + event.alerts に対する foreach + コネクターアクション。get_step_definitions("cases.createCase") と get_step_definitions(search: "slack")（現在のフィクスチャでは cases.createCase と slack2.sendMessage を使用）を使い、次に実際の connector-id を get_connectors で取得します。ワークフローパターンを参照してください。

スキーマパスで見慣れない形式を扱う場合は、ドラフトを作成する前にワークフローパターンと生成のヒントを読んでください。

操作

上記の本文にある HTTP 簡略表記の参照は、以下の elastic CLI コマンドに対応しています。複数行の YAML および JSON ペイロードは、インラインフラグとして渡すよりも --input-file <path> で渡すほうが簡単です。

ワークフロー API（どちらのパスでも使用できます）。

HTTP API（省略形）	elastic CLI コマンド
GET /	elastic es info
GET kbn:/api/workflows	elastic stack kb workflows get-workflows
GET kbn:/api/workflows/workflow/{id}	elastic stack kb workflows get-workflows-workflow-id --id <id>
POST kbn:/api/workflows/workflow	elastic stack kb workflows post-workflows-workflow --input-file <path>
PUT kbn:/api/workflows/workflow/{id}	elastic stack kb workflows put-workflows-workflow-id --id <id> --input-file <path>
DELETE kbn:/api/workflows/workflow/{id}	elastic stack kb workflows delete-workflows-workflow-id --id <id>
DELETE kbn:/api/workflows/workflow/{id}?force=true	elastic stack kb workflows delete-workflows-workflow-id --id <id> --force true
POST kbn:/api/workflows/test	elastic stack kb workflows post-workflows-test --input-file <path>
POST kbn:/api/workflows/workflow/{id}/run	elastic stack kb workflows post-workflows-workflow-id-run --id <id> --inputs <json>
POST kbn:/api/workflows/step/test	elastic stack kb workflows post-workflows-step-test --input-file <path>
GET kbn:/api/workflows/executions/{executionId}	elastic stack kb workflows get-workflows-executions-executionid --execution-id <id>
GET kbn:/api/workflows/executions/{executionId}/logs	elastic stack kb workflows get-workflows-executions-executionid-logs --execution-id <id>
POST kbn:/api/workflows/executions/{executionId}/cancel	elastic stack kb workflows post-workflows-executions-executionid-cancel --execution-id <id>
POST kbn:/api/workflows/executions/{executionId}/resume	elastic stack kb workflows post-workflows-executions-executionid-resume --execution-id <id>
GET kbn:/api/workflows/workflow/{workflowId}/executions	elastic stack kb workflows get-workflows-workflow-workflowid-executions --workflow-id <id>
GET kbn:/api/workflows/schema?loose=false	elastic stack kb workflows get-workflows-schema --loose false
GET kbn:/api/workflows/connectors	elastic stack kb workflows get-workflows-connectors

Agent Builder ツール（Discovery-tools パス）。

以下のすべてのツールは、同じ実行エンドポイントを通じて呼び出します。--input-file に、次の形式の JSON ファイルを指定します。 { "tool_id": "...", "tool_params": { ... } }

HTTP API（省略形）	elastic CLI コマンド
GET kbn:/api/agent_builder/tools	elastic stack kb agent-builder get-agent-builder-tools
POST kbn:/api/agent_builder/tools/_execute	elastic stack kb agent-builder post-agent-builder-tools-execute --input-file <path>

ワークフロー関連の tool_id：

tool_id	目的
platform.workflows.validate_workflow	YAML 文字列を検証します。失敗時のレスポンスには、参照されたステップタイプのステップ定義が含まれます。
platform.workflows.workflow_execute_step	実際の環境に対して 1 つのステップを実行します（安全でないステップではユーザーの確認を伴います）。
platform.workflows.get_step_definitions	ステップタイプのパラメータ、出力、例を検索します。完全一致には stepType、キーワードには search を使用します。
platform.workflows.get_trigger_definitions	トリガーの完全なイベントスキーマを検索します。
platform.workflows.get_connectors	ターゲットに設定されているコネクタインスタンスを一覧表示します。
platform.workflows.get_examples	同梱のサンプルライブラリから動作する YAML パターンを検索します。

注意事項。

post-workflows-test の場合、入力ファイルは { "workflowYaml": "...", "inputs": {} } という形式の JSON です（workflowYaml の代わりに workflowId を使用することもできます）。post-workflows-workflow の場合は { "yaml": "...", "id": "..." } を使用します — id は省略可能です。put-workflows-workflow-id の場合は、name、enabled、tags、yaml、description のうち更新するフィールドのみを含めてください。削除はデフォルトでソフト削除です。force=true は、完全削除と ID の即時再利用を意図する場合にのみ使用してください。Kibana API のバージョンは 2023-10-31 です。CLI はこれを自動的に設定します。

stdin を開いたままにするシェル（一部のターミナルやエージェントランタイムはこれを行います）から読み取り専用の get- コマンドを呼び出す場合は、EAGAIN: resource temporarily unavailable クラッシュを避けるために </dev/null を末尾に追加してください — 例: elastic stack kb workflows get-workflows-executions-executionid --execution-id "{id}" </dev/null。