kibana-workflows

编写 Elastic 工作流

创建并迭代 Elastic 工作流 YAML 定义。工作流是运行在 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 命令——始终使用 CLI，而不要直接调用 HTTP API。

如果用户只要求起草或解释，并明确禁止实时访问，请跳过连接验证，不要调用 CLI 或 API。说明该草稿未经目标部署验证。

如果工作流 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": ... } ] }；将其保存到文件，并 grep "id": "platform.workflows."。有两种备用路径，均仅在需要时加载：

• 没有 agent_builder 端点（404）或没有 platform.workflows.* ID（例如 Kibana 9.4）→ 阅读 references/schema-path.md，并根据原始 JSON Schema 手动编写。
• Agent Builder 中已接入 LLM 连接器，且用户倾向使用 Kibana 自带的生成器 → 阅读 references/generator-path.md。

继续之前，用一句话说明选择了哪条路径以及原因。实测路径基准数据见 references/path-performance.md。

准则（适用于所有路径）

• 将测试视为执行操作。 POST kbn:/api/workflows/test 会运行工作流图，POST kbn:/api/workflows/step/test 会运行选定的步骤。仅当所有执行的操作均为只读操作，或用户已授权其影响时，才进行测试。否则，测试一个副本，将其中的写入操作、通知和外部调用替换为 console，然后恢复实际步骤，并以禁用状态保存工作流。
• 使用 HTTP 简写引用端点，绝不使用原始传输方式。 本技能的正文使用 POST kbn:/api/workflows/test 之类的操作形式。Operations 表是将简写对应到具体 CLI 命令的唯一位置。
• 优先使用专用操作，而非通用 http。 对于 Slack/Jira/PagerDuty 等服务，优先使用连接器步骤类型（例如 slack2.sendMessage），而非原始 http 调用。通过 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 设置。

发现工具路径

当目标 Kibana 上注册了 platform.workflows.* 工具时使用。所有调用都通过 POST kbn:/api/agent_builder/tools/_execute，请求体为 { "tool_id": "...", "tool_params": { ... } }。响应结构： { "results": [ { "type": "other", "data": { ... }, "tool_result_id": "..." } ] }——所需的负载位于 .results[0].data。从文件发送请求体，并将响应写入文件（参见操作），然后使用 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、至少一个触发器，以及非空的 steps 数组。使用 2 个空格缩进。通过 steps.<name>.output.* 引用输出。一次编辑完成完整 YAML，不要分多轮逐步添加。

4. 验证一次。 使用 { "yaml": "..." } 调用 platform.workflows.validate_workflow。如果失败，它会自动返回错误以及所引用步骤类型的定义，因此通常无需再次调用 get_step_definitions。一次编辑修复所有报告的问题，然后重新验证。

5. 测试、保存并运行。 请参见下方的测试 / 保存 / 运行。使用 platform.workflows.workflow_execute_step 对单个步骤进行迭代（对于不安全的步骤，使用 confirmation_body）。

架构路径（最后手段）

仅适用于没有 platform.workflows.* 工具的 Kibana（参见上方的探测步骤）。完整操作流程： references/schema-path.md。

测试 / 保存 / 运行

两种路径共用的最后阶段。

1. 仅测试可安全执行的草稿。 使用 YAML 内联作为 workflowYaml，并传入运行时 inputs，调用 POST kbn:/api/workflows/test。对于会写入数据 / 发送通知 / 调用外部服务的工作流，先在测试副本中将这些步骤替换为 console，然后恢复这些步骤并以禁用状态保存工作流。

2. 轮询执行状态。 响应中包含 workflowExecutionId。轮询 GET kbn:/api/workflows/executions/{executionId}，直到 status 为 completed、failed、cancelled 或 timed_out 之一；然后调用 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。通过执行状态和日志端点检查运行情况。

Workflow 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-tools 路径中，platform.workflows.get_step_definitions 可回答“步骤 X 是否存在，以及它需要哪些参数”。在架构路径中，GET kbn:/api/workflows/schema?loose=false 是 权威来源，而 GET kbn:/api/workflows/connectors 会列出已配置的连接器实例。

data.set 会为当前执行存储变量；它不会持久化数据。若用户要求在执行结束后保留数据，请使用 Elasticsearch 或 Kibana 写入操作。

示例

手动问候（最简草稿）：“创建一个记录问候语的工作流。” → 手动触发器 + 一个 console 步骤，用于打印 Hello {{ inputs.name | default: "world" }}。使用 POST kbn:/api/workflows/test 进行测试。参见 Demo Test Loop。

定时运行状况检查：“每 5 分钟 ping 一次 https://api.example.com/health 并记录响应。” → scheduled 触发器（every: 5m）+ http 步骤 + console。使用 get_step_definitions("http") 查询确切的 with 结构。如果有要求，添加有限次重试。

告警触发的案例 + Slack 通知：“当 Security 告警触发时，创建一个案例并向 #soc-incidents 发消息。” → alert 触发器 + 遍历 event.alerts 的 foreach + 连接器操作。使用 get_step_definitions("cases.createCase") 和 get_step_definitions(search: "slack")（当前 fixtures 使用 cases.createCase 和 slack2.sendMessage），然后 使用 get_connectors 获取真实的 connector-id。参见 Workflow Patterns。

对于架构路径中不熟悉的结构，起草前请阅读 Workflow Patterns 和 Generation Tips。

操作

正文中的 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 路径）。

以下每个工具都通过同一个执行端点调用。将包含 { "tool_id": "...", "tool_params": { ... } } 的 JSON 文件传递给 --input-file。

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	在真实环境中执行单个步骤（对于不安全的步骤，会要求用户确认）。
platform.workflows.get_step_definitions	查询步骤类型的参数、输出和示例。使用 stepType 精确匹配，使用 search 按关键词搜索。
platform.workflows.get_trigger_definitions	查询触发器的完整事件架构。
platform.workflows.get_connectors	列出目标上配置的连接器实例。
platform.workflows.get_examples	在内置示例库中搜索可用的 YAML 模式。

注意事项。

对于 post-workflows-test，输入文件为以下形式的 JSON：{ "workflowYaml": "...", "inputs": {} }（也可以用 workflowId 替代 workflowYaml）。对于 post-workflows-workflow，使用 { "yaml": "...", "id": "..." }——id 为可选项。对于 put-workflows-workflow-id，仅包含要更新的字段：name、enabled、tags、yaml 和 description。默认情况下，删除操作为软删除。仅当需要永久删除并立即复用 ID 时，才使用 force=true。Kibana API 版本为 2023-10-31；CLI 会自动设置该版本。

从会保持 stdin 打开的 Shell（某些终端和 Agent 运行时会这样）调用只读的 get- 命令时，请附加 </dev/null，以避免出现 EAGAIN: resource temporarily unavailable 崩溃，例如： elastic stack kb workflows get-workflows-executions-executionid --execution-id "{id}" </dev/null。