用 Kibana Workflows…

当需要编写、校验、测试、运行和排查 Kibana 中的 Elastic Workflow YAML 定义时使用。

适用场景

解决思路

1. 先探测环境：调用 `GET kbn:/api/agent_builder/tools`，把结果保存到文件并 grep `"id": "platform.workflows."`，据此选择编写路径；若返回 404 或没有 `platform.workflows.*` id（如 Kibana 9.4），改读 references/schema-path.md 走原始 JSON Schema 手写路径；若 Agent Builder 已接入 LLM connector 且用户偏好 Kibana 自带生成器，则读 references/generator-path.md。开始前用一句话说明选了哪条路径及原因。
2. 若用户只要求草稿或解释并明确禁止实时访问，则跳过连接校验，不调用 CLI 或 API，并声明该草稿未在目标部署上验证。
3. 若 workflow API 不可用，报告返回的状态码和消息；常见原因是 Kibana 版本不支持、license 或功能权限不足、或目标项目未提供 Workflows。注意 `workflows:ui:enabled` 只控制 Kibana UI，不会移除公开的 Workflows API。
4. 把测试当作真实执行：`POST kbn:/api/workflows/test` 会运行整个 workflow 图，`POST kbn:/api/workflows/step/test` 会运行所选步骤；仅当所有执行动作都是只读或用户已授权其副作用时才测试，否则先测试一份把写入、通知和外部调用替换为 `console` 的副本，再恢复真实步骤并以 disabled 状态保存 workflow。
5. 正文中一律用 HTTP 简写引用端点（如 `POST kbn:/api/workflows/test`），绝不直接写原始传输调用；Operations 表是简写绑定到具体 CLI 命令的唯一位置。
6. 优先使用专用 action 而非通用 `http`：对 Slack/Jira/PagerDuty 等优先用 connector 步骤类型（如 `slack2.sendMessage`）而不是裸 `http` 调用；通过 `get_step_definitions`（或回退路径上的严格 schema）发现确切的 action 类型。
7. 引用步骤输出时用 `steps.<name>.output`，绝不用 `steps.<name>.with.*`；触发器事件数据是 `event`，绝不用 `trigger.event` 或 `triggers.event`。
8. 不要猜 connector id：调用 `platform.workflows.get_connectors`（Discovery-tools 路径）或 `GET kbn:/api/workflows/connectors`（Schema 路径），或直接问用户；占位符要明显是假的。
9. 有意识地处理失败：在用户需求要求韧性处添加 retry 或 fallback；不要到处加 `continue: true`，它会掩盖失败动作并让 workflow 误报成功。
10. 暴露门槛而非掩盖：若 API 返回 `403 ... not available`，报告所需的 license 或权限，不要静默重试或归咎于 UI 设置。
11. Discovery-tools 路径下所有调用都走 `POST kbn:/api/agent_builder/tools/_execute`，body 为 `{ "tool_id": "...", "tool_params": { ... } }`；响应形如 `{ "results": [ { "type": "other", "data": { ... }, "tool_result_id": "..." } ] }`，所需载荷在 `.results[0].data`；请求体从文件发送、响应写入文件，再用 jq 查询该文件，不要对多行 JSON 内联 `python3 -c`。
12. 保持上下文小、减少往返：不要预先加载整个步骤目录，只拉取所需的针对性细节，把大体积工具输出留在文件里（不要进 transcript），并尽量用最少的轮次完成编写（依据见 references/path-performance.md）。
13. 写 YAML 前先捕获用户意图：按顺序确定触发器（`manual` / `scheduled` / `alert`）、workflow 运行时接收的 inputs、必须读取的数据源、必须执行的动作、期望的输出；若某个必需依赖未知（如 Slack connector id），询问用户或使用清晰标记的占位符。
14. 只查会用到的内容：对 workflow 需要的具体步骤类型，用精确 `stepType`（如 `"http"`、`"elasticsearch.esql.query"`、`"slack2.sendMessage"`）或 `search` 浏览调用 `platform.workflows.get_step_definitions`（响应含 input 参数、config 参数、传 `includeOutputSummary: true` 时的 `outputSummary` 及用法示例，仅当紧凑摘要不足时才传 `includeFullSchema: true`）；用 `platform.workflows.get_trigger_definitions` 查触发器事件 schema；用 `platform.workflows.get_connectors` 解析 connector action 的真实 `connector-id`；需要可用的 YAML 模式时用 `platform.workflows.get_examples`；把每个响应写入文件并 jq 出所需字段，不要让完整工具输出进入 transcript。
15. 一次性起草整个 workflow：workflow 需要 `name`、至少一个 trigger 和非空 `steps` 数组；用 2 空格缩进；输出引用为 `steps.<name>.output.*`；在单次编辑中构建完整 YAML，而不是跨多轮逐步增长。
16. 只校验一次：用 `{ "yaml": "..." }` 调用 `platform.workflows.validate_workflow`；失败时它会自动返回错误及所引用步骤类型的步骤定义，因此很少需要第二次 `get_step_definitions` 调用；在单次编辑中修复所有报告的问题，然后重新校验。
17. 测试、保存、运行：用内联 `workflowYaml` 和运行时 `inputs` 调用 `POST kbn:/api/workflows/test`；对任何写入/通知/调用外部服务的 workflow，先在测试副本中把这些步骤替换为 `console`，之后恢复它们并以 disabled 状态保存 workflow。
18. 轮询执行：响应带 `workflowExecutionId`，轮询 `GET kbn:/api/workflows/executions/{executionId}` 直到 `status` 为 `completed`、`failed`、`cancelled` 或 `timed_out` 之一，然后取 `GET kbn:/api/workflows/executions/{executionId}/logs` 获取逐步输出；只有 `status: completed` 才算成功。
19. 保存：用 `{ yaml, id? }` 调用 `POST kbn:/api/workflows/workflow`；有副作用的 workflow 在用户授权真实运行前以 `enabled: false` 保存；后续编辑用 `PUT kbn:/api/workflows/workflow/{id}`，可更新 `yaml`、`enabled`、`name`、`tags` 或 `description`（支持部分更新）。
20. 仅在获授权时运行：启用 workflow，然后用与测试时相同的 `inputs` 形状调用 `POST kbn:/api/workflows/workflow/{id}/run`，并通过执行和日志端点检查。
21. 用 `platform.workflows.workflow_execute_step` 迭代单个步骤（对不安全步骤使用 `confirmation_body`）。
22. 编写 YAML 时：用 `{{ ... }}` 渲染文本，用 `${{ ... }}` 让整个值保留原生类型（如 `documents: "${{ steps.search.output.hits.hits }}"`）；普通 action 步骤在严格 schema 允许时可使用 `with`、`connector-id`（仅 connector action）、`if`、`timeout`、`on-failure.retry`（`max-attempts`、`delay`）和 `on-failure.fallback` 等字段。
23. 注意 `data.set` 只为当前执行存储变量，不持久化数据；用户要求执行后保留数据时，改用 Elasticsearch 或 Kibana 写入 action。
24. Schema 路径下，`GET kbn:/api/workflows/schema?loose=false` 是权威来源，`GET kbn:/api/workflows/connectors` 列出已配置的 connector 实例；遇到不熟悉的形状时先读 references/workflow-patterns.md 和 references/generation-tips.md 再起草。
25. 多行 YAML 和 JSON 载荷优先用 `--input-file <path>` 传递而非内联 flag；`post-workflows-test` 的输入文件是 `{ "workflowYaml": "...", "inputs": {} }`（或用 `workflowId` 替代 `workflowYaml`），`post-workflows-workflow` 用 `{ "yaml": "...", "id": "..." }`（`id` 可选），`put-workflows-workflow-id` 只包含要更新的字段（`name`、`enabled`、`tags`、`yaml`、`description`）。
26. 删除默认是软删除；仅当确实要永久删除并立即复用 ID 时才用 `force=true`。Kibana API 版本为 `2023-10-31`，CLI 会自动设置。
27. 在 stdin 保持打开的 shell（某些终端和 agent 运行时）中调用只读 `get-` 命令时，追加 `</dev/null` 以避免 `EAGAIN: resource temporarily unavailable` 崩溃，例如 `elastic stack kb workflows get-workflows-executions-executionid --execution-id "{id}" </dev/null`。

适用边界 · 注意事项

• 目标 Kibana 不支持 Workflows API（版本过低、license 或权限不足、项目未提供 Workflows）时，不要静默重试或归咎于 UI 设置，应报告返回的状态和消息。
• 用户只要求草稿或解释并明确禁止实时访问时，不要做连接校验或调用 CLI/API。
• 未获用户授权时，不要对含写入、通知或外部调用的 workflow 执行真实测试或运行。