diff --git a/api-reference/monitors.openapi.en.json b/api-reference/monitors.openapi.en.json index 8b5aaf9..e63d6b6 100644 --- a/api-reference/monitors.openapi.en.json +++ b/api-reference/monitors.openapi.en.json @@ -2711,7 +2711,7 @@ "Monitors/Diagnostics" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- Use `target_locator` to identify the target; `target_kind` is optional and is auto-inferred when omitted. Built-in target kinds are `host` and `mysql`.\n- If multiple kinds match the same locator, the response is HTTP 200 with `data.error.code = \"ambiguous_target_kind\"` and a `target_kinds` list — retry with an explicit `target_kind`.\n- The catalog is a *candidate capability* view, not an execution guarantee. The target Agent may go offline between catalog and invoke, or local Agent policy may block individual tools at invoke time.\n- Set `include_output_shape: true` to additionally receive each tool's `output_shape`. Default is `false` to keep the response small for LLM consumption.\n- Business errors (`target_unavailable`, `unknown_toolset_hash`, `ambiguous_target_kind`) come back as HTTP 200 with `data.error` present and `data.tools = []`. Only protocol / auth / internal errors use the standard error envelope.\n- The response uses **sparse fields**: on success `error` is omitted rather than sent as `null`, and `target` is omitted when the locator could not be uniquely resolved. `tools` is always present.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- Use `target_locator` to identify the target; `target_kind` is optional and is inferred from current target routing when omitted.\n- If multiple kinds match the same locator, the response is HTTP 200 with `data.error.code = \"ambiguous_target_kind\"` and a `target_kinds` list — retry with an explicit `target_kind`.\n- The catalog is a candidate capability view, not an execution guarantee. The target Agent may go offline between catalog and invoke, or local Agent policy may block individual tools at invoke time.\n- Each tool entry exposes only `name`, `target_kind`, `description`, and `input_schema`. It does not expose tool versions, output contracts, catalog revisions, or execution limits.\n- Business errors (`target_unavailable`, `timeout`, `forward_failed`, `invalid_tool_result`, `ambiguous_target_kind`) return HTTP 200 with `data.error` present and `data.tools = []`. Only protocol, authentication, and internal errors use the standard error envelope.\n- The response uses **sparse fields**: on success `error` is omitted rather than sent as `null`, and `target` is omitted when the locator could not be uniquely resolved. `tools` is always present.", "href": "/en/api-reference/monitors/diagnostics/monit-read-tools-catalog", "metadata": { "sidebarTitle": "List target tool catalog" @@ -2726,8 +2726,7 @@ }, "example": { "account_id": 10001, - "target_locator": "web-01", - "include_output_shape": true + "target_locator": "web-01" } } } @@ -2768,144 +2767,6 @@ "type": "object", "additionalProperties": false, "properties": {} - }, - "output_shape": { - "properties": { - "data": { - "properties": { - "cpu": { - "type": "object" - }, - "degradation_reasons": { - "items": { - "type": "string" - }, - "minItems": 1, - "type": "array" - }, - "disk": { - "description": "Filesystems sorted by used_pct desc; rootfs always present; capped at host.disk.top_n. Sizes are in GB; used_pct/inode_used_pct in percent.", - "type": "array" - }, - "disk_errors": { - "description": "Mount points whose statfs returned a syscall error (EACCES / ENOENT / EIO / stale, etc.); each entry is `: `.", - "type": "array" - }, - "disk_io": { - "description": "Per-device disk I/O rates (util_pct, IOPS, throughput, await). Sorted by util_pct desc; capped at host.disk_io.top_n. Only whole-disk devices shown.", - "type": "object" - }, - "disk_timeouts": { - "description": "Mount points whose statfs hit per-mount timeout.", - "type": "array" - }, - "load": { - "type": "object" - }, - "memory": { - "description": "Memory and swap sizes are in MB; percentages are 0..100. Swap fields are always present when memory collection succeeds, including zero when swap is not configured.", - "properties": { - "available_mb": { - "type": "integer" - }, - "swap_configured": { - "description": "True when the kernel reports a non-zero SwapTotal.", - "type": "boolean" - }, - "swap_total_mb": { - "type": "integer" - }, - "swap_used_mb": { - "type": "integer" - }, - "swap_used_pct": { - "type": "number" - }, - "total_mb": { - "type": "integer" - }, - "used_mb": { - "type": "integer" - }, - "used_pct": { - "type": "number" - } - }, - "required": [ - "total_mb", - "available_mb", - "used_mb", - "used_pct", - "swap_configured", - "swap_total_mb", - "swap_used_mb", - "swap_used_pct" - ], - "type": "object" - }, - "network_io": { - "description": "Per-interface network throughput and error rates. Sorted by total traffic desc; capped at host.network_io.top_n. Virtual/container interfaces excluded by default.", - "type": "object" - }, - "procs": { - "type": "object" - }, - "sample_interval_sec": { - "description": "Shared sampling interval for CPU, disk_io, network_io counter-diff calculations.", - "type": "number" - }, - "tcp_connections": { - "description": "TCP connection state distribution via netlink SOCK_DIAG. Shows counts per state (established, time_wait, close_wait, listen, syn_recv, other, total).", - "type": "object" - }, - "uptime_sec": { - "type": "number" - }, - "vmstat": { - "description": "Sparse cumulative counters since the current boot; use them as historical clues, not current rates.", - "properties": { - "oom_kill_since_boot": { - "description": "OOM kills accumulated since boot; omitted when this kernel does not expose the counter.", - "type": "integer" - }, - "pgmajfault_since_boot": { - "description": "Major page faults accumulated since boot.", - "type": "integer" - } - }, - "required": [ - "pgmajfault_since_boot" - ], - "type": "object" - } - }, - "required": [ - "sample_interval_sec" - ], - "type": "object" - }, - "summary": { - "minLength": 1, - "type": "string" - }, - "truncated": { - "additionalProperties": false, - "properties": { - "reason": { - "minLength": 1, - "type": "string" - } - }, - "required": [ - "reason" - ], - "type": "object" - } - }, - "required": [ - "data" - ], - "type": "object" } }, { @@ -2927,65 +2788,6 @@ "type": "integer" } } - }, - "output_shape": { - "properties": { - "data": { - "properties": { - "avg_ms": { - "type": "number" - }, - "max_ms": { - "type": "number" - }, - "min_ms": { - "type": "number" - }, - "probes": { - "items": { - "properties": { - "error": { - "type": "string" - }, - "latency_ms": { - "type": "number" - } - }, - "type": "object" - }, - "type": "array" - }, - "reachable": { - "type": "boolean" - }, - "resolved_ip": { - "type": "string" - } - }, - "type": "object" - }, - "summary": { - "minLength": 1, - "type": "string" - }, - "truncated": { - "additionalProperties": false, - "properties": { - "reason": { - "minLength": 1, - "type": "string" - } - }, - "required": [ - "reason" - ], - "type": "object" - } - }, - "required": [ - "data" - ], - "type": "object" } } ] @@ -3018,7 +2820,7 @@ "Monitors/Diagnostics" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- Up to **8** tools per call (`MaxToolsPerInvoke`); larger batches must be split client-side. The 8-tool cap aligns with the per-target agent concurrency.\n- Tools execute in parallel on the agent; webapi returns `results[]` aligned with the request `tools[]` order.\n- Long-running: set client timeouts to **at least 35 s**. The endpoint is intended for AI-SRE / human-RCA flows, not interactive UI.\n- Request-level errors (`target_unavailable`, `ambiguous_target_kind`, `unknown_toolset_hash`, `forward_failed`) appear as HTTP 200 with `data.error` set and `data.results = []`.\n- Per-tool failures appear as HTTP 200 with `data.error` absent and `results[i].error` populated — always check **all three** layers (outer envelope `error`, `data.error`, then each `results[i].error`).\n- The response uses **sparse fields**: absent means empty. On success `error` is omitted entirely rather than sent as `null`; on failure `data`, `summary` and `truncated` are omitted. Do not key logic off placeholder `null` fields, and do not expect `target` when the locator could not be uniquely resolved.\n- `results[i].data` is the tool payload with the monit-agent result envelope **already unwrapped** — there is no nested `data.data`. The one-line distillation is `results[i].summary`, and `results[i].truncated` (carrying a `reason`) appears only when the result was genuinely truncated.\n- `results[i].params` echoes the params webapi received for that tool, so batched calls stay correlatable even when an individual tool fails.\n- Construct `tools[].params` against the `input_schema` returned by `/monit/tools/catalog`. For no-arg tools always pass `params: {}` explicitly.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- Up to **8** tools per call (`MaxToolsPerInvoke`); larger batches must be split client-side. The 8-tool cap aligns with the per-target agent concurrency.\n- Tools execute in parallel on the agent; webapi returns `results[]` aligned with the request `tools[]` order.\n- Long-running: set client timeouts to **at least 35 s**. The endpoint is intended for AI-SRE / human-RCA flows, not interactive UI.\n- Request-level errors (`target_unavailable`, `ambiguous_target_kind`, `forward_failed`) appear as HTTP 200 with `data.error` set and `data.results = []`.\n- Per-tool failures appear as HTTP 200 with `data.error` absent and `results[i].error` populated — always check **all three** layers (outer envelope `error`, `data.error`, then each `results[i].error`).\n- The response uses **sparse fields**: absent means empty. On success `error` is omitted entirely rather than sent as `null`; on failure `data`, `summary` and `truncated` are omitted. Do not key logic off placeholder `null` fields, and do not expect `target` when the locator could not be uniquely resolved.\n- `results[i].data` is the tool payload with the monit-agent result envelope **already unwrapped** — there is no nested `data.data`. The one-line distillation is `results[i].summary`, and `results[i].truncated` (carrying a `reason`) appears only when the result was genuinely truncated.\n- `results[i].params` echoes the params webapi received for that tool, so batched calls stay correlatable even when an individual tool fails.\n- Construct `tools[].params` against the `input_schema` returned by `/monit/tools/catalog`. For no-arg tools always pass `params: {}` explicitly.", "href": "/en/api-reference/monitors/diagnostics/monit-read-tools-invoke", "metadata": { "sidebarTitle": "Invoke target tools" @@ -5559,12 +5361,7 @@ }, "target_kind": { "type": "string", - "description": "Optional target kind. When omitted webapi auto-infers across currently known kinds. Built-in kinds: `host`, `mysql`. Required on retry when the previous call returned `ambiguous_target_kind`." - }, - "include_output_shape": { - "type": "boolean", - "description": "When true, each tool entry includes its `output_shape` JSON Schema. Defaults to false to keep responses small for LLM consumption.", - "default": false + "description": "Optional target kind. When omitted, webapi infers it from current target routing. If the call returns `ambiguous_target_kind`, retry with a value from `target_kinds`." } } }, @@ -5605,11 +5402,6 @@ "input_schema": { "type": "object", "description": "JSON Schema for `tools[].params`." - }, - "output_shape": { - "type": "object", - "description": "JSON Schema of the tool result. Returned only when the request set `include_output_shape` to true.", - "x-flashduty-preserve-absence": true } } } @@ -5622,7 +5414,9 @@ "type": "string", "enum": [ "target_unavailable", - "unknown_toolset_hash", + "timeout", + "forward_failed", + "invalid_tool_result", "ambiguous_target_kind" ] }, @@ -5749,7 +5543,7 @@ "properties": { "code": { "type": "string", - "description": "Common values: `timeout`, `target_unavailable`, `edge_unsupported`, `invalid_tool_result`, `internal`, `invalid_args`, `unknown_tool`, `unknown_tool_version`, `unknown_toolset_hash`, `target_not_owned`, `wrong_agent`, `overloaded`, `denied`, `permission_denied`, `credential_unavailable`, `target_unreachable`." + "description": "Common WebAPI codes: `timeout`, `target_unavailable`, `invalid_tool_result`, `internal`, `invalid_args`, `unsupported_syntax`, `path_not_found`, and `catalog_changed`. Agent-specific tool errors may also be returned unchanged." }, "message": { "type": "string" @@ -5768,7 +5562,6 @@ "type": "string", "enum": [ "target_unavailable", - "unknown_toolset_hash", "forward_failed", "ambiguous_target_kind" ] diff --git a/api-reference/monitors.openapi.zh.json b/api-reference/monitors.openapi.zh.json index 592bc0b..c7b7a33 100644 --- a/api-reference/monitors.openapi.zh.json +++ b/api-reference/monitors.openapi.zh.json @@ -2711,7 +2711,7 @@ "Monitors/诊断分析" ], "x-mint": { - "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 使用 `target_locator` 标识监控对象;`target_kind` 可选,省略时自动推断。内置的 target kind 包括 `host` 与 `mysql`。\n- 若同一 locator 匹配多个 kind,响应为 HTTP 200,`data.error.code = \"ambiguous_target_kind\"`,并附带 `target_kinds` 列表——请带上显式的 `target_kind` 重试。\n- 工具能力清单是*候选能力*视图,并非执行保证。目标 Agent 可能在拿到清单与发起调用之间下线,本地 Agent 策略也可能在调用时拦截某些工具。\n- 设置 `include_output_shape: true` 可额外返回每个工具的 `output_shape`。默认为 `false`,以便为 LLM 消费保持响应精简。\n- 业务错误(`target_unavailable`、`unknown_toolset_hash`、`ambiguous_target_kind`)以 HTTP 200 返回,`data.error` 存在且 `data.tools = []`。只有协议 / 鉴权 / 内部错误才使用标准错误信封。\n- 响应采用**稀疏字段**:成功时 `error` 直接省略而非返回 `null`;当 locator 无法唯一解析时 `target` 不输出。`tools` 字段恒存在。", + "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 使用 `target_locator` 标识监控对象;`target_kind` 可选,省略时按当前监控对象路由自动推断。\n- 若同一 locator 匹配多个 kind,响应为 HTTP 200,`data.error.code = \"ambiguous_target_kind\"`,并附带 `target_kinds` 列表——请带上显式的 `target_kind` 重试。\n- 工具能力清单是候选能力视图,并非执行保证。目标 Agent 可能在拿到清单与发起调用之间下线,本地 Agent 策略也可能在调用时拦截某些工具。\n- 每个工具条目只返回 `name`、`target_kind`、`description` 和 `input_schema`,不会暴露工具版本、输出契约、目录版本或执行限制。\n- 业务错误(`target_unavailable`、`timeout`、`forward_failed`、`invalid_tool_result`、`ambiguous_target_kind`)以 HTTP 200 返回,`data.error` 存在且 `data.tools = []`。只有协议、鉴权和内部错误才使用标准错误信封。\n- 响应采用**稀疏字段**:成功时 `error` 直接省略而非返回 `null`;当 locator 无法唯一解析时,`target` 不输出。`tools` 字段恒存在。", "href": "/zh/api-reference/monitors/diagnostics/monit-read-tools-catalog", "metadata": { "sidebarTitle": "查询监控对象工具能力清单" @@ -2726,8 +2726,7 @@ }, "example": { "account_id": 10001, - "target_locator": "web-01", - "include_output_shape": true + "target_locator": "web-01" } } } @@ -2768,144 +2767,6 @@ "type": "object", "additionalProperties": false, "properties": {} - }, - "output_shape": { - "properties": { - "data": { - "properties": { - "cpu": { - "type": "object" - }, - "degradation_reasons": { - "items": { - "type": "string" - }, - "minItems": 1, - "type": "array" - }, - "disk": { - "description": "Filesystems sorted by used_pct desc; rootfs always present; capped at host.disk.top_n. Sizes are in GB; used_pct/inode_used_pct in percent.", - "type": "array" - }, - "disk_errors": { - "description": "Mount points whose statfs returned a syscall error (EACCES / ENOENT / EIO / stale, etc.); each entry is `: `.", - "type": "array" - }, - "disk_io": { - "description": "Per-device disk I/O rates (util_pct, IOPS, throughput, await). Sorted by util_pct desc; capped at host.disk_io.top_n. Only whole-disk devices shown.", - "type": "object" - }, - "disk_timeouts": { - "description": "Mount points whose statfs hit per-mount timeout.", - "type": "array" - }, - "load": { - "type": "object" - }, - "memory": { - "description": "Memory and swap sizes are in MB; percentages are 0..100. Swap fields are always present when memory collection succeeds, including zero when swap is not configured.", - "properties": { - "available_mb": { - "type": "integer" - }, - "swap_configured": { - "description": "True when the kernel reports a non-zero SwapTotal.", - "type": "boolean" - }, - "swap_total_mb": { - "type": "integer" - }, - "swap_used_mb": { - "type": "integer" - }, - "swap_used_pct": { - "type": "number" - }, - "total_mb": { - "type": "integer" - }, - "used_mb": { - "type": "integer" - }, - "used_pct": { - "type": "number" - } - }, - "required": [ - "total_mb", - "available_mb", - "used_mb", - "used_pct", - "swap_configured", - "swap_total_mb", - "swap_used_mb", - "swap_used_pct" - ], - "type": "object" - }, - "network_io": { - "description": "Per-interface network throughput and error rates. Sorted by total traffic desc; capped at host.network_io.top_n. Virtual/container interfaces excluded by default.", - "type": "object" - }, - "procs": { - "type": "object" - }, - "sample_interval_sec": { - "description": "Shared sampling interval for CPU, disk_io, network_io counter-diff calculations.", - "type": "number" - }, - "tcp_connections": { - "description": "TCP connection state distribution via netlink SOCK_DIAG. Shows counts per state (established, time_wait, close_wait, listen, syn_recv, other, total).", - "type": "object" - }, - "uptime_sec": { - "type": "number" - }, - "vmstat": { - "description": "Sparse cumulative counters since the current boot; use them as historical clues, not current rates.", - "properties": { - "oom_kill_since_boot": { - "description": "OOM kills accumulated since boot; omitted when this kernel does not expose the counter.", - "type": "integer" - }, - "pgmajfault_since_boot": { - "description": "Major page faults accumulated since boot.", - "type": "integer" - } - }, - "required": [ - "pgmajfault_since_boot" - ], - "type": "object" - } - }, - "required": [ - "sample_interval_sec" - ], - "type": "object" - }, - "summary": { - "minLength": 1, - "type": "string" - }, - "truncated": { - "additionalProperties": false, - "properties": { - "reason": { - "minLength": 1, - "type": "string" - } - }, - "required": [ - "reason" - ], - "type": "object" - } - }, - "required": [ - "data" - ], - "type": "object" } }, { @@ -2927,65 +2788,6 @@ "type": "integer" } } - }, - "output_shape": { - "properties": { - "data": { - "properties": { - "avg_ms": { - "type": "number" - }, - "max_ms": { - "type": "number" - }, - "min_ms": { - "type": "number" - }, - "probes": { - "items": { - "properties": { - "error": { - "type": "string" - }, - "latency_ms": { - "type": "number" - } - }, - "type": "object" - }, - "type": "array" - }, - "reachable": { - "type": "boolean" - }, - "resolved_ip": { - "type": "string" - } - }, - "type": "object" - }, - "summary": { - "minLength": 1, - "type": "string" - }, - "truncated": { - "additionalProperties": false, - "properties": { - "reason": { - "minLength": 1, - "type": "string" - } - }, - "required": [ - "reason" - ], - "type": "object" - } - }, - "required": [ - "data" - ], - "type": "object" } } ] @@ -3018,7 +2820,7 @@ "Monitors/诊断分析" ], "x-mint": { - "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 单次调用至多 **8** 个工具(`MaxToolsPerInvoke`);超出需在客户端拆分。8 个工具的上限与单监控对象 Agent 的并发能力对齐。\n- 工具在 Agent 上并行执行;webapi 返回的 `results[]` 与请求中的 `tools[]` 顺序对齐。\n- 长耗时:客户端超时至少设置 **35 秒**。该接口面向 AI-SRE / 人工排障流程,不适用于交互式 UI。\n- 请求级错误(`target_unavailable`、`ambiguous_target_kind`、`unknown_toolset_hash`、`forward_failed`)以 HTTP 200 返回,`data.error` 不为空,`data.results = []`。\n- 单工具失败以 HTTP 200 返回,`data.error` 不输出,`results[i].error` 被填充——务必同时检查**三层**(外层信封 `error`、`data.error`、再到每个 `results[i].error`)。\n- 响应采用**稀疏字段**:字段不存在即表示为空。成功时 `error` 直接省略而非返回 `null`;失败时 `data`、`summary`、`truncated` 均不输出。不要依赖占位的 `null` 字段做判断;当 locator 无法唯一解析时,`target` 同样不会出现。\n- `results[i].data` 是 Tool 的业务数据,monit-agent 的 result envelope **已被解开**——不会出现嵌套的 `data.data`。一行摘要位于 `results[i].summary`;`results[i].truncated`(内含 `reason`)仅在结果确实被截断时出现。\n- `results[i].params` 回显 webapi 收到的该 Tool 调用参数,便于在批量调用中关联结果——即使其中某个 Tool 失败也能对上号。\n- 按 `/monit/tools/catalog` 返回的 `input_schema` 构造 `tools[].params`。对于无参工具,务必显式传 `params: {}`。", + "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 单次调用至多 **8** 个工具(`MaxToolsPerInvoke`);超出需在客户端拆分。8 个工具的上限与单监控对象 Agent 的并发能力对齐。\n- 工具在 Agent 上并行执行;webapi 返回的 `results[]` 与请求中的 `tools[]` 顺序对齐。\n- 长耗时:客户端超时至少设置 **35 秒**。该接口面向 AI-SRE / 人工排障流程,不适用于交互式 UI。\n- 请求级错误(`target_unavailable`、`ambiguous_target_kind`、`forward_failed`)以 HTTP 200 返回,`data.error` 不为空,`data.results = []`。\n- 单工具失败以 HTTP 200 返回,`data.error` 不输出,`results[i].error` 被填充——务必同时检查**三层**(外层信封 `error`、`data.error`、再到每个 `results[i].error`)。\n- 响应采用**稀疏字段**:字段不存在即表示为空。成功时 `error` 直接省略而非返回 `null`;失败时 `data`、`summary`、`truncated` 均不输出。不要依赖占位的 `null` 字段做判断;当 locator 无法唯一解析时,`target` 同样不会出现。\n- `results[i].data` 是 Tool 的业务数据,monit-agent 的 result envelope **已被解开**——不会出现嵌套的 `data.data`。一行摘要位于 `results[i].summary`;`results[i].truncated`(内含 `reason`)仅在结果确实被截断时出现。\n- `results[i].params` 回显 webapi 收到的该 Tool 调用参数,便于在批量调用中关联结果——即使其中某个 Tool 失败也能对上号。\n- 按 `/monit/tools/catalog` 返回的 `input_schema` 构造 `tools[].params`。对于无参工具,务必显式传 `params: {}`。", "href": "/zh/api-reference/monitors/diagnostics/monit-read-tools-invoke", "metadata": { "sidebarTitle": "调用监控对象工具" @@ -5559,12 +5361,7 @@ }, "target_kind": { "type": "string", - "description": "可选的 target kind。省略时 webapi 在当前已知的 kind 中自动推断。内置 kind:`host`、`mysql`。上次返回 `ambiguous_target_kind` 时,重试必须传入此字段。" - }, - "include_output_shape": { - "type": "boolean", - "description": "为 true 时,每个工具条目额外返回其 `output_shape` JSON Schema。默认 false,以便为 LLM 消费保持响应精简。", - "default": false + "description": "可选的 target kind。省略时 webapi 会按当前监控对象路由自动推断。若返回 `ambiguous_target_kind`,请从 `target_kinds` 中选择一个值重试。" } } }, @@ -5605,11 +5402,6 @@ "input_schema": { "type": "object", "description": "用于 `tools[].params` 的 JSON Schema。" - }, - "output_shape": { - "type": "object", - "description": "Tool 结果的 JSON Schema。仅当请求将 `include_output_shape` 置为 true 时返回。", - "x-flashduty-preserve-absence": true } } } @@ -5622,7 +5414,9 @@ "type": "string", "enum": [ "target_unavailable", - "unknown_toolset_hash", + "timeout", + "forward_failed", + "invalid_tool_result", "ambiguous_target_kind" ] }, @@ -5749,7 +5543,7 @@ "properties": { "code": { "type": "string", - "description": "常见取值:`timeout`、`target_unavailable`、`edge_unsupported`、`invalid_tool_result`、`internal`、`invalid_args`、`unknown_tool`、`unknown_tool_version`、`unknown_toolset_hash`、`target_not_owned`、`wrong_agent`、`overloaded`、`denied`、`permission_denied`、`credential_unavailable`、`target_unreachable`。" + "description": "常见 WebAPI 错误码:`timeout`、`target_unavailable`、`invalid_tool_result`、`internal`、`invalid_args`、`unsupported_syntax`、`path_not_found` 和 `catalog_changed`。Agent 特有的工具错误也可能原样返回。" }, "message": { "type": "string" @@ -5768,7 +5562,6 @@ "type": "string", "enum": [ "target_unavailable", - "unknown_toolset_hash", "forward_failed", "ambiguous_target_kind" ] diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index bf4362c..4449c31 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -20065,7 +20065,7 @@ "Monitors/Diagnostics" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- Use `target_locator` to identify the target; `target_kind` is optional and is auto-inferred when omitted. Built-in target kinds are `host` and `mysql`.\n- If multiple kinds match the same locator, the response is HTTP 200 with `data.error.code = \"ambiguous_target_kind\"` and a `target_kinds` list — retry with an explicit `target_kind`.\n- The catalog is a *candidate capability* view, not an execution guarantee. The target Agent may go offline between catalog and invoke, or local Agent policy may block individual tools at invoke time.\n- Set `include_output_shape: true` to additionally receive each tool's `output_shape`. Default is `false` to keep the response small for LLM consumption.\n- Business errors (`target_unavailable`, `unknown_toolset_hash`, `ambiguous_target_kind`) come back as HTTP 200 with `data.error` present and `data.tools = []`. Only protocol / auth / internal errors use the standard error envelope.\n- The response uses **sparse fields**: on success `error` is omitted rather than sent as `null`, and `target` is omitted when the locator could not be uniquely resolved. `tools` is always present.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- Use `target_locator` to identify the target; `target_kind` is optional and is inferred from current target routing when omitted.\n- If multiple kinds match the same locator, the response is HTTP 200 with `data.error.code = \"ambiguous_target_kind\"` and a `target_kinds` list — retry with an explicit `target_kind`.\n- The catalog is a candidate capability view, not an execution guarantee. The target Agent may go offline between catalog and invoke, or local Agent policy may block individual tools at invoke time.\n- Each tool entry exposes only `name`, `target_kind`, `description`, and `input_schema`. It does not expose tool versions, output contracts, catalog revisions, or execution limits.\n- Business errors (`target_unavailable`, `timeout`, `forward_failed`, `invalid_tool_result`, `ambiguous_target_kind`) return HTTP 200 with `data.error` present and `data.tools = []`. Only protocol, authentication, and internal errors use the standard error envelope.\n- The response uses **sparse fields**: on success `error` is omitted rather than sent as `null`, and `target` is omitted when the locator could not be uniquely resolved. `tools` is always present.", "href": "/en/api-reference/monitors/diagnostics/monit-read-tools-catalog", "metadata": { "sidebarTitle": "List target tool catalog" @@ -20080,8 +20080,7 @@ }, "example": { "account_id": 10001, - "target_locator": "web-01", - "include_output_shape": true + "target_locator": "web-01" } } } @@ -20122,144 +20121,6 @@ "type": "object", "additionalProperties": false, "properties": {} - }, - "output_shape": { - "properties": { - "data": { - "properties": { - "cpu": { - "type": "object" - }, - "degradation_reasons": { - "items": { - "type": "string" - }, - "minItems": 1, - "type": "array" - }, - "disk": { - "description": "Filesystems sorted by used_pct desc; rootfs always present; capped at host.disk.top_n. Sizes are in GB; used_pct/inode_used_pct in percent.", - "type": "array" - }, - "disk_errors": { - "description": "Mount points whose statfs returned a syscall error (EACCES / ENOENT / EIO / stale, etc.); each entry is `: `.", - "type": "array" - }, - "disk_io": { - "description": "Per-device disk I/O rates (util_pct, IOPS, throughput, await). Sorted by util_pct desc; capped at host.disk_io.top_n. Only whole-disk devices shown.", - "type": "object" - }, - "disk_timeouts": { - "description": "Mount points whose statfs hit per-mount timeout.", - "type": "array" - }, - "load": { - "type": "object" - }, - "memory": { - "description": "Memory and swap sizes are in MB; percentages are 0..100. Swap fields are always present when memory collection succeeds, including zero when swap is not configured.", - "properties": { - "available_mb": { - "type": "integer" - }, - "swap_configured": { - "description": "True when the kernel reports a non-zero SwapTotal.", - "type": "boolean" - }, - "swap_total_mb": { - "type": "integer" - }, - "swap_used_mb": { - "type": "integer" - }, - "swap_used_pct": { - "type": "number" - }, - "total_mb": { - "type": "integer" - }, - "used_mb": { - "type": "integer" - }, - "used_pct": { - "type": "number" - } - }, - "required": [ - "total_mb", - "available_mb", - "used_mb", - "used_pct", - "swap_configured", - "swap_total_mb", - "swap_used_mb", - "swap_used_pct" - ], - "type": "object" - }, - "network_io": { - "description": "Per-interface network throughput and error rates. Sorted by total traffic desc; capped at host.network_io.top_n. Virtual/container interfaces excluded by default.", - "type": "object" - }, - "procs": { - "type": "object" - }, - "sample_interval_sec": { - "description": "Shared sampling interval for CPU, disk_io, network_io counter-diff calculations.", - "type": "number" - }, - "tcp_connections": { - "description": "TCP connection state distribution via netlink SOCK_DIAG. Shows counts per state (established, time_wait, close_wait, listen, syn_recv, other, total).", - "type": "object" - }, - "uptime_sec": { - "type": "number" - }, - "vmstat": { - "description": "Sparse cumulative counters since the current boot; use them as historical clues, not current rates.", - "properties": { - "oom_kill_since_boot": { - "description": "OOM kills accumulated since boot; omitted when this kernel does not expose the counter.", - "type": "integer" - }, - "pgmajfault_since_boot": { - "description": "Major page faults accumulated since boot.", - "type": "integer" - } - }, - "required": [ - "pgmajfault_since_boot" - ], - "type": "object" - } - }, - "required": [ - "sample_interval_sec" - ], - "type": "object" - }, - "summary": { - "minLength": 1, - "type": "string" - }, - "truncated": { - "additionalProperties": false, - "properties": { - "reason": { - "minLength": 1, - "type": "string" - } - }, - "required": [ - "reason" - ], - "type": "object" - } - }, - "required": [ - "data" - ], - "type": "object" } }, { @@ -20281,65 +20142,6 @@ "type": "integer" } } - }, - "output_shape": { - "properties": { - "data": { - "properties": { - "avg_ms": { - "type": "number" - }, - "max_ms": { - "type": "number" - }, - "min_ms": { - "type": "number" - }, - "probes": { - "items": { - "properties": { - "error": { - "type": "string" - }, - "latency_ms": { - "type": "number" - } - }, - "type": "object" - }, - "type": "array" - }, - "reachable": { - "type": "boolean" - }, - "resolved_ip": { - "type": "string" - } - }, - "type": "object" - }, - "summary": { - "minLength": 1, - "type": "string" - }, - "truncated": { - "additionalProperties": false, - "properties": { - "reason": { - "minLength": 1, - "type": "string" - } - }, - "required": [ - "reason" - ], - "type": "object" - } - }, - "required": [ - "data" - ], - "type": "object" } } ] @@ -20372,7 +20174,7 @@ "Monitors/Diagnostics" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- Up to **8** tools per call (`MaxToolsPerInvoke`); larger batches must be split client-side. The 8-tool cap aligns with the per-target agent concurrency.\n- Tools execute in parallel on the agent; webapi returns `results[]` aligned with the request `tools[]` order.\n- Long-running: set client timeouts to **at least 35 s**. The endpoint is intended for AI-SRE / human-RCA flows, not interactive UI.\n- Request-level errors (`target_unavailable`, `ambiguous_target_kind`, `unknown_toolset_hash`, `forward_failed`) appear as HTTP 200 with `data.error` set and `data.results = []`.\n- Per-tool failures appear as HTTP 200 with `data.error` absent and `results[i].error` populated — always check **all three** layers (outer envelope `error`, `data.error`, then each `results[i].error`).\n- The response uses **sparse fields**: absent means empty. On success `error` is omitted entirely rather than sent as `null`; on failure `data`, `summary` and `truncated` are omitted. Do not key logic off placeholder `null` fields, and do not expect `target` when the locator could not be uniquely resolved.\n- `results[i].data` is the tool payload with the monit-agent result envelope **already unwrapped** — there is no nested `data.data`. The one-line distillation is `results[i].summary`, and `results[i].truncated` (carrying a `reason`) appears only when the result was genuinely truncated.\n- `results[i].params` echoes the params webapi received for that tool, so batched calls stay correlatable even when an individual tool fails.\n- Construct `tools[].params` against the `input_schema` returned by `/monit/tools/catalog`. For no-arg tools always pass `params: {}` explicitly.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **600 requests/minute**; **10 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n\n## Usage\n\n- Up to **8** tools per call (`MaxToolsPerInvoke`); larger batches must be split client-side. The 8-tool cap aligns with the per-target agent concurrency.\n- Tools execute in parallel on the agent; webapi returns `results[]` aligned with the request `tools[]` order.\n- Long-running: set client timeouts to **at least 35 s**. The endpoint is intended for AI-SRE / human-RCA flows, not interactive UI.\n- Request-level errors (`target_unavailable`, `ambiguous_target_kind`, `forward_failed`) appear as HTTP 200 with `data.error` set and `data.results = []`.\n- Per-tool failures appear as HTTP 200 with `data.error` absent and `results[i].error` populated — always check **all three** layers (outer envelope `error`, `data.error`, then each `results[i].error`).\n- The response uses **sparse fields**: absent means empty. On success `error` is omitted entirely rather than sent as `null`; on failure `data`, `summary` and `truncated` are omitted. Do not key logic off placeholder `null` fields, and do not expect `target` when the locator could not be uniquely resolved.\n- `results[i].data` is the tool payload with the monit-agent result envelope **already unwrapped** — there is no nested `data.data`. The one-line distillation is `results[i].summary`, and `results[i].truncated` (carrying a `reason`) appears only when the result was genuinely truncated.\n- `results[i].params` echoes the params webapi received for that tool, so batched calls stay correlatable even when an individual tool fails.\n- Construct `tools[].params` against the `input_schema` returned by `/monit/tools/catalog`. For no-arg tools always pass `params: {}` explicitly.", "href": "/en/api-reference/monitors/diagnostics/monit-read-tools-invoke", "metadata": { "sidebarTitle": "Invoke target tools" @@ -42856,12 +42658,7 @@ }, "target_kind": { "type": "string", - "description": "Optional target kind. When omitted webapi auto-infers across currently known kinds. Built-in kinds: `host`, `mysql`. Required on retry when the previous call returned `ambiguous_target_kind`." - }, - "include_output_shape": { - "type": "boolean", - "description": "When true, each tool entry includes its `output_shape` JSON Schema. Defaults to false to keep responses small for LLM consumption.", - "default": false + "description": "Optional target kind. When omitted, webapi infers it from current target routing. If the call returns `ambiguous_target_kind`, retry with a value from `target_kinds`." } } }, @@ -42902,11 +42699,6 @@ "input_schema": { "type": "object", "description": "JSON Schema for `tools[].params`." - }, - "output_shape": { - "type": "object", - "description": "JSON Schema of the tool result. Returned only when the request set `include_output_shape` to true.", - "x-flashduty-preserve-absence": true } } } @@ -42919,7 +42711,9 @@ "type": "string", "enum": [ "target_unavailable", - "unknown_toolset_hash", + "timeout", + "forward_failed", + "invalid_tool_result", "ambiguous_target_kind" ] }, @@ -43046,7 +42840,7 @@ "properties": { "code": { "type": "string", - "description": "Common values: `timeout`, `target_unavailable`, `edge_unsupported`, `invalid_tool_result`, `internal`, `invalid_args`, `unknown_tool`, `unknown_tool_version`, `unknown_toolset_hash`, `target_not_owned`, `wrong_agent`, `overloaded`, `denied`, `permission_denied`, `credential_unavailable`, `target_unreachable`." + "description": "Common WebAPI codes: `timeout`, `target_unavailable`, `invalid_tool_result`, `internal`, `invalid_args`, `unsupported_syntax`, `path_not_found`, and `catalog_changed`. Agent-specific tool errors may also be returned unchanged." }, "message": { "type": "string" @@ -43065,7 +42859,6 @@ "type": "string", "enum": [ "target_unavailable", - "unknown_toolset_hash", "forward_failed", "ambiguous_target_kind" ] diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 3b7c9fe..edf9ac6 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -20057,7 +20057,7 @@ "Monitors/诊断分析" ], "x-mint": { - "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 使用 `target_locator` 标识监控对象;`target_kind` 可选,省略时自动推断。内置的 target kind 包括 `host` 与 `mysql`。\n- 若同一 locator 匹配多个 kind,响应为 HTTP 200,`data.error.code = \"ambiguous_target_kind\"`,并附带 `target_kinds` 列表——请带上显式的 `target_kind` 重试。\n- 工具能力清单是*候选能力*视图,并非执行保证。目标 Agent 可能在拿到清单与发起调用之间下线,本地 Agent 策略也可能在调用时拦截某些工具。\n- 设置 `include_output_shape: true` 可额外返回每个工具的 `output_shape`。默认为 `false`,以便为 LLM 消费保持响应精简。\n- 业务错误(`target_unavailable`、`unknown_toolset_hash`、`ambiguous_target_kind`)以 HTTP 200 返回,`data.error` 存在且 `data.tools = []`。只有协议 / 鉴权 / 内部错误才使用标准错误信封。\n- 响应采用**稀疏字段**:成功时 `error` 直接省略而非返回 `null`;当 locator 无法唯一解析时 `target` 不输出。`tools` 字段恒存在。", + "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 使用 `target_locator` 标识监控对象;`target_kind` 可选,省略时按当前监控对象路由自动推断。\n- 若同一 locator 匹配多个 kind,响应为 HTTP 200,`data.error.code = \"ambiguous_target_kind\"`,并附带 `target_kinds` 列表——请带上显式的 `target_kind` 重试。\n- 工具能力清单是候选能力视图,并非执行保证。目标 Agent 可能在拿到清单与发起调用之间下线,本地 Agent 策略也可能在调用时拦截某些工具。\n- 每个工具条目只返回 `name`、`target_kind`、`description` 和 `input_schema`,不会暴露工具版本、输出契约、目录版本或执行限制。\n- 业务错误(`target_unavailable`、`timeout`、`forward_failed`、`invalid_tool_result`、`ambiguous_target_kind`)以 HTTP 200 返回,`data.error` 存在且 `data.tools = []`。只有协议、鉴权和内部错误才使用标准错误信封。\n- 响应采用**稀疏字段**:成功时 `error` 直接省略而非返回 `null`;当 locator 无法唯一解析时,`target` 不输出。`tools` 字段恒存在。", "href": "/zh/api-reference/monitors/diagnostics/monit-read-tools-catalog", "metadata": { "sidebarTitle": "查询监控对象工具能力清单" @@ -20072,8 +20072,7 @@ }, "example": { "account_id": 10001, - "target_locator": "web-01", - "include_output_shape": true + "target_locator": "web-01" } } } @@ -20114,144 +20113,6 @@ "type": "object", "additionalProperties": false, "properties": {} - }, - "output_shape": { - "properties": { - "data": { - "properties": { - "cpu": { - "type": "object" - }, - "degradation_reasons": { - "items": { - "type": "string" - }, - "minItems": 1, - "type": "array" - }, - "disk": { - "description": "Filesystems sorted by used_pct desc; rootfs always present; capped at host.disk.top_n. Sizes are in GB; used_pct/inode_used_pct in percent.", - "type": "array" - }, - "disk_errors": { - "description": "Mount points whose statfs returned a syscall error (EACCES / ENOENT / EIO / stale, etc.); each entry is `: `.", - "type": "array" - }, - "disk_io": { - "description": "Per-device disk I/O rates (util_pct, IOPS, throughput, await). Sorted by util_pct desc; capped at host.disk_io.top_n. Only whole-disk devices shown.", - "type": "object" - }, - "disk_timeouts": { - "description": "Mount points whose statfs hit per-mount timeout.", - "type": "array" - }, - "load": { - "type": "object" - }, - "memory": { - "description": "Memory and swap sizes are in MB; percentages are 0..100. Swap fields are always present when memory collection succeeds, including zero when swap is not configured.", - "properties": { - "available_mb": { - "type": "integer" - }, - "swap_configured": { - "description": "True when the kernel reports a non-zero SwapTotal.", - "type": "boolean" - }, - "swap_total_mb": { - "type": "integer" - }, - "swap_used_mb": { - "type": "integer" - }, - "swap_used_pct": { - "type": "number" - }, - "total_mb": { - "type": "integer" - }, - "used_mb": { - "type": "integer" - }, - "used_pct": { - "type": "number" - } - }, - "required": [ - "total_mb", - "available_mb", - "used_mb", - "used_pct", - "swap_configured", - "swap_total_mb", - "swap_used_mb", - "swap_used_pct" - ], - "type": "object" - }, - "network_io": { - "description": "Per-interface network throughput and error rates. Sorted by total traffic desc; capped at host.network_io.top_n. Virtual/container interfaces excluded by default.", - "type": "object" - }, - "procs": { - "type": "object" - }, - "sample_interval_sec": { - "description": "Shared sampling interval for CPU, disk_io, network_io counter-diff calculations.", - "type": "number" - }, - "tcp_connections": { - "description": "TCP connection state distribution via netlink SOCK_DIAG. Shows counts per state (established, time_wait, close_wait, listen, syn_recv, other, total).", - "type": "object" - }, - "uptime_sec": { - "type": "number" - }, - "vmstat": { - "description": "Sparse cumulative counters since the current boot; use them as historical clues, not current rates.", - "properties": { - "oom_kill_since_boot": { - "description": "OOM kills accumulated since boot; omitted when this kernel does not expose the counter.", - "type": "integer" - }, - "pgmajfault_since_boot": { - "description": "Major page faults accumulated since boot.", - "type": "integer" - } - }, - "required": [ - "pgmajfault_since_boot" - ], - "type": "object" - } - }, - "required": [ - "sample_interval_sec" - ], - "type": "object" - }, - "summary": { - "minLength": 1, - "type": "string" - }, - "truncated": { - "additionalProperties": false, - "properties": { - "reason": { - "minLength": 1, - "type": "string" - } - }, - "required": [ - "reason" - ], - "type": "object" - } - }, - "required": [ - "data" - ], - "type": "object" } }, { @@ -20273,65 +20134,6 @@ "type": "integer" } } - }, - "output_shape": { - "properties": { - "data": { - "properties": { - "avg_ms": { - "type": "number" - }, - "max_ms": { - "type": "number" - }, - "min_ms": { - "type": "number" - }, - "probes": { - "items": { - "properties": { - "error": { - "type": "string" - }, - "latency_ms": { - "type": "number" - } - }, - "type": "object" - }, - "type": "array" - }, - "reachable": { - "type": "boolean" - }, - "resolved_ip": { - "type": "string" - } - }, - "type": "object" - }, - "summary": { - "minLength": 1, - "type": "string" - }, - "truncated": { - "additionalProperties": false, - "properties": { - "reason": { - "minLength": 1, - "type": "string" - } - }, - "required": [ - "reason" - ], - "type": "object" - } - }, - "required": [ - "data" - ], - "type": "object" } } ] @@ -20364,7 +20166,7 @@ "Monitors/诊断分析" ], "x-mint": { - "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 单次调用至多 **8** 个工具(`MaxToolsPerInvoke`);超出需在客户端拆分。8 个工具的上限与单监控对象 Agent 的并发能力对齐。\n- 工具在 Agent 上并行执行;webapi 返回的 `results[]` 与请求中的 `tools[]` 顺序对齐。\n- 长耗时:客户端超时至少设置 **35 秒**。该接口面向 AI-SRE / 人工排障流程,不适用于交互式 UI。\n- 请求级错误(`target_unavailable`、`ambiguous_target_kind`、`unknown_toolset_hash`、`forward_failed`)以 HTTP 200 返回,`data.error` 不为空,`data.results = []`。\n- 单工具失败以 HTTP 200 返回,`data.error` 不输出,`results[i].error` 被填充——务必同时检查**三层**(外层信封 `error`、`data.error`、再到每个 `results[i].error`)。\n- 响应采用**稀疏字段**:字段不存在即表示为空。成功时 `error` 直接省略而非返回 `null`;失败时 `data`、`summary`、`truncated` 均不输出。不要依赖占位的 `null` 字段做判断;当 locator 无法唯一解析时,`target` 同样不会出现。\n- `results[i].data` 是 Tool 的业务数据,monit-agent 的 result envelope **已被解开**——不会出现嵌套的 `data.data`。一行摘要位于 `results[i].summary`;`results[i].truncated`(内含 `reason`)仅在结果确实被截断时出现。\n- `results[i].params` 回显 webapi 收到的该 Tool 调用参数,便于在批量调用中关联结果——即使其中某个 Tool 失败也能对上号。\n- 按 `/monit/tools/catalog` 返回的 `input_schema` 构造 `tools[].params`。对于无参工具,务必显式传 `params: {}`。", + "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | **600 次/分钟**;**10 次/秒** 每账户 |\n| 权限 | 任意有效的 `app_key`(只读;不受特定权限分类约束) |\n\n## 使用说明\n\n- 单次调用至多 **8** 个工具(`MaxToolsPerInvoke`);超出需在客户端拆分。8 个工具的上限与单监控对象 Agent 的并发能力对齐。\n- 工具在 Agent 上并行执行;webapi 返回的 `results[]` 与请求中的 `tools[]` 顺序对齐。\n- 长耗时:客户端超时至少设置 **35 秒**。该接口面向 AI-SRE / 人工排障流程,不适用于交互式 UI。\n- 请求级错误(`target_unavailable`、`ambiguous_target_kind`、`forward_failed`)以 HTTP 200 返回,`data.error` 不为空,`data.results = []`。\n- 单工具失败以 HTTP 200 返回,`data.error` 不输出,`results[i].error` 被填充——务必同时检查**三层**(外层信封 `error`、`data.error`、再到每个 `results[i].error`)。\n- 响应采用**稀疏字段**:字段不存在即表示为空。成功时 `error` 直接省略而非返回 `null`;失败时 `data`、`summary`、`truncated` 均不输出。不要依赖占位的 `null` 字段做判断;当 locator 无法唯一解析时,`target` 同样不会出现。\n- `results[i].data` 是 Tool 的业务数据,monit-agent 的 result envelope **已被解开**——不会出现嵌套的 `data.data`。一行摘要位于 `results[i].summary`;`results[i].truncated`(内含 `reason`)仅在结果确实被截断时出现。\n- `results[i].params` 回显 webapi 收到的该 Tool 调用参数,便于在批量调用中关联结果——即使其中某个 Tool 失败也能对上号。\n- 按 `/monit/tools/catalog` 返回的 `input_schema` 构造 `tools[].params`。对于无参工具,务必显式传 `params: {}`。", "href": "/zh/api-reference/monitors/diagnostics/monit-read-tools-invoke", "metadata": { "sidebarTitle": "调用监控对象工具" @@ -42847,12 +42649,7 @@ }, "target_kind": { "type": "string", - "description": "可选的 target kind。省略时 webapi 在当前已知的 kind 中自动推断。内置 kind:`host`、`mysql`。上次返回 `ambiguous_target_kind` 时,重试必须传入此字段。" - }, - "include_output_shape": { - "type": "boolean", - "description": "为 true 时,每个工具条目额外返回其 `output_shape` JSON Schema。默认 false,以便为 LLM 消费保持响应精简。", - "default": false + "description": "可选的 target kind。省略时 webapi 会按当前监控对象路由自动推断。若返回 `ambiguous_target_kind`,请从 `target_kinds` 中选择一个值重试。" } } }, @@ -42893,11 +42690,6 @@ "input_schema": { "type": "object", "description": "用于 `tools[].params` 的 JSON Schema。" - }, - "output_shape": { - "type": "object", - "description": "Tool 结果的 JSON Schema。仅当请求将 `include_output_shape` 置为 true 时返回。", - "x-flashduty-preserve-absence": true } } } @@ -42910,7 +42702,9 @@ "type": "string", "enum": [ "target_unavailable", - "unknown_toolset_hash", + "timeout", + "forward_failed", + "invalid_tool_result", "ambiguous_target_kind" ] }, @@ -43037,7 +42831,7 @@ "properties": { "code": { "type": "string", - "description": "常见取值:`timeout`、`target_unavailable`、`edge_unsupported`、`invalid_tool_result`、`internal`、`invalid_args`、`unknown_tool`、`unknown_tool_version`、`unknown_toolset_hash`、`target_not_owned`、`wrong_agent`、`overloaded`、`denied`、`permission_denied`、`credential_unavailable`、`target_unreachable`。" + "description": "常见 WebAPI 错误码:`timeout`、`target_unavailable`、`invalid_tool_result`、`internal`、`invalid_args`、`unsupported_syntax`、`path_not_found` 和 `catalog_changed`。Agent 特有的工具错误也可能原样返回。" }, "message": { "type": "string" @@ -43056,7 +42850,6 @@ "type": "string", "enum": [ "target_unavailable", - "unknown_toolset_hash", "forward_failed", "ambiguous_target_kind" ]