> ## Documentation Index > Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Agent > Agent 资源让 AI SRE 接入外部 Agent 生态。当前支持 A2A（Agent-to-Agent）类型——既可把任务委派给远端 Agent，也能对外暴露 Agent Card 供外部客户端反向调用，用于故障 / 作战室联动与双向事件流。 **公测功能**：AI SRE 已全量开放公测，无需申请，登录控制台即可直接使用，公测期间免费。功能与界面可能继续调整。 ## 概述 *** **Agent** 是把 AI SRE 接入外部 Agent 生态的资源类别。当前支持的类型是 **A2A（Agent-to-Agent）**——一套让不同 Agent 相互调用的标准协议（后续可能扩展更多 Agent 类型）。A2A 把 AI SRE 接入外部 Agent，有两个方向： 在列表中注册的**远端 A2A Agent**。AI SRE 通过标准 A2A 协议把任务**委派**给它们——例如一个专精指标分析、或对接某个内部系统的外部 Agent。 本平台的 AI SRE 自身也是一个 A2A Agent，对外暴露一张 **Agent Card**。外部 A2A 客户端把该 Card 地址填入即可**反向调用** Flashduty 的 AI SRE，用于故障 / 作战室联动与双向事件流。 委派后无需等待：AI SRE 把任务交给远端 Agent 后会立即继续当前对话，您可以继续工作或同时委派多个任务；远端完成后，其结果作为一条新消息出现在对话中。每次 A2A 委派在对话流里以一张**任务卡片**呈现，卡片带 `A2A` 徽标，显示远端 Agent 名、本次任务意图、运行状态（初始化 / 进行中 / 等待输入 / 等待授权 / 完成 / 失败（含孤儿任务）/ 中断 / 已终止）以及工具调用数、Token、耗时等用量；点击卡片可在右侧面板里查看该次委派的完整过程。 **调用说明分两层，是 Agent 选择信号**。AI SRE 委派前看到的「可用 Agent 清单」里，每一项只有 `名称：简介`——简介来自调用说明开头的 `summary:` 一行（不写则自动截取正文开头），AI SRE 靠它判断**要不要、什么时候**把任务派给这个 Agent，务必写清楚何时优先选用它、擅长什么、不适合做什么。简介之后的正文不会常驻清单，只在**首次委派给这个 Agent 时**才完整送达——放心写长、写细（操作步骤、硬性规则、示例），不会拖慢日常对话。写法详见下文「[调用说明的写法](#调用说明的写法)」。 A2A Agent 的列表与管理入口在 **插件 → Agents** 页面（菜单标签为 **Agents**）。 **Agents 涵盖两类不同的概念。** 本页（Agents）当前管理的是 **A2A Agent**（外部 Agent 互调）。另一类是 **Subagent（任务子代理）**——平台内置、由 AI SRE 在会话中按需派发的任务执行器，没有创建 / 编辑入口，只能在会话中观察其行为，详见下文「[Subagent 任务子代理](#subagent-任务子代理)」。 ## Subagent 任务子代理 *** **Subagent** 是平台**内置**的任务执行器。AI SRE 在排障过程中，可以把一个自包含的子任务\*\*派发（dispatch）\*\*给一个 Subagent 去独立完成——派发统一通过单一的长时运行工具 `agent_dispatch` 进行，而不是为每个 Subagent 生成一个独立工具。 平台预置了若干**引导（bootstrap）Subagent**，开箱即用： | 名称 | 角色 | | --------- | --------------------------------------------------------------------------------- | | `general` | 通用执行器，拥有完整工具权限，适合把中间步骤会污染主对话上下文的工作（长报告、多文件改动、端到端构建、反复探查）整体外包出去；可并行派发多个处理相互独立的工作单元 | | `explore` | 只读调查器，仅限 `grep` / `glob` / `read`，不能写入或执行；返回浓缩摘要而非原始搜索输出，适合在代码库或知识转储中定位证据 | **会话中的呈现**：每次派发在对话流里同样以一张**任务卡片**呈现，与 A2A 委派共用同一套状态生命周期（初始化 / 进行中 / 等待输入 / 等待授权 / 完成 / 失败（含孤儿任务）/ 中断 / 已终止）。区别在于徽标——Subagent 任务卡片带 `Agent` 徽标，而 A2A 委派带 `A2A` 徽标。 **运行约束**： * **并发上限**：每个会话**最多同时运行 20 个 Subagent**（`TaskMaxConcurrentPerSession = 20`）。这里限制的是「同一时刻并发运行」的数量而非会话累计派发数——每完成一个就释放一个名额，因此会话整体可完成的工作量不受限。达到上限时再派发会报错（`too many active subagents (… running, limit 20)`），提示模型先停下等待运行中的任务完成、再派发其余的。 * **嵌套深度**：派发链**最多嵌套 3 层**（`TaskMaxNestingDepth = 3`），防止 Subagent 无限自我派生。 **Subagent 目前没有面向用户的创建 / 管理界面。** 它是一项内置运行能力：您可以在会话中观察 Subagent 任务卡片及其子会话过程，但无法像 A2A Agent 那样新增、编辑或删除 Subagent。本页（Agents）当前管理的仅是 A2A Agent。 ## 注册出站 A2A Agent *** 在 A2A Agents 列表页点击 **添加 A2A Agent**，在表单中填写： | 字段 | 类型 | 默认值 | 说明 | | ----------------------------- | ----------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 名称 | string | — | A2A Agent 标识（如 `metrics-analyzer`）。必填 | | 范围 | 共享 / 团队 | — | 作用域：**共享**（即账户级，账户内全局可见）或某个**团队**（仅该团队成员可见和可编辑）。必填，详见下文「作用域」 | | 执行环境 | 云端环境 / BYOC Runner（可多选） | 所有环境 | 决定该 A2A Agent 在哪些执行环境中可用。可以选择云端环境和一个或多个当前可见的 BYOC Runner；不选择时默认在所有环境可用。它不指定委派调用路由：A2A 调用仍在当前 AI SRE 会话自身的执行环境中运行。若远端 Agent 只在某个内网可访问，请只选择能访问它的 Runner | | 调用说明 | string | — | 面向 AI SRE 的 Agent 选择信号，是**一份文档**：可选的 `summary:` frontmatter + 正文。简介（`summary`）进入「可用 Agent 清单」，正文在首次委派时才完整送达。必填；整份文档最多 50 KB，`summary` 最多 1,024 个字符且不能包含 `<` `>`。写法见下文「[调用说明的写法](#调用说明的写法)」 | | Card URL | string | — | 远端 A2A Agent 的 Agent Card 地址，或仅填写遵循默认 well-known 规则的服务根地址（如 `https://agents.example.com`）。如果 URL 已带路径，平台会按该地址原样读取；如果只填服务根地址，平台按 A2A 约定查找 `/.well-known/agent-card.json`。必填。平台只校验 URL 格式合法（scheme 为 http/https、host 非空），不做主机或 IP 分类；实际的网络可达性与出站限制取决于发起委派的 AI SRE 会话所在执行环境，上面的执行环境字段只限制该 Agent 在哪些环境中可用。远端 Agent 需实现 A2A Protocol 1.0，见下文「[协议版本与 Agent Card 要求](#协议版本与-agent-card-要求)」 | | 服务授权 | enum | `none` | AI SRE 作为**服务**访问远端 Agent 时使用的身份（字段 `auth_type`）：`none`（无）/ `bearer`（Bearer Token）/ `api_key`（自定义 Header + Key）。表单中标记为**推荐**。详见下文「[授权模式](#授权模式)」 | | 流式传输 | bool | 开 | 是否以流式方式与远端交互 | | 成员授权 | enum | `shared`（无） | 每位成员各自持有的身份（字段 `auth_mode`）：`shared`（无）/ `per_user_secret`（密钥（Header））/ `per_user_oauth`（OAuth 2.1）。详见下文「[授权模式](#授权模式)」 | | 跳过 TLS 证书校验 | bool | 关 | 仅当 Card URL 为 HTTPS 时显示。只在远端使用自签证书且网络受控时开启；开启后会跳过证书链和主机名校验 | | 允许通过 HTTP 获取 OAuth 配置（仅限测试环境） | bool | 关 | 仅当**成员授权**选择「OAuth 2.1」且 Card URL 是非本地 HTTP 地址时需要确认。只用于受控测试环境；开启后 AI SRE 服务端会访问该主机的 OAuth metadata | ### 协议版本与 Agent Card 要求 平台作为 A2A 客户端调用远端 Agent，实现的是 **A2A Protocol 1.0**（`JSONRPC` 或 `HTTP+JSON` 协议绑定）。**0.x 及其他大版本协议不受支持**：远端 Agent 的 Agent Card 必须是 1.0 格式，否则委派调用会失败。 1.0 格式的 Agent Card 通过 `supportedInterfaces` 数组声明接入点，其中至少一项需包含 `url`、`protocolBinding`（`JSONRPC` 或 `HTTP+JSON`）和 `protocolVersion: "1.0"`。一张最小合法卡片如下： ```json theme={null} { "name": "metrics-analyzer", "description": "Analyzes metrics for a target service", "supportedInterfaces": [ { "url": "https://agents.example.com/a2a", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" } ], "capabilities": { "streaming": true }, "skills": [ { "id": "analyze_metrics", "name": "Analyze Metrics", "description": "Query and summarize metrics within a time window", "tags": ["metrics"] } ], "defaultInputModes": ["text"], "defaultOutputModes": ["text"] } ``` 卡片里的 `version` 字段是 **Agent 自身的版本号**，不是协议版本；协议版本由 `supportedInterfaces` 各项中的 `protocolVersion` 声明。 **从 0.x 迁移到 1.0**：如果您的 Agent Card 仍是 0.x 旧格式，请按下表调整后再接入： | 0.x 旧格式 | 1.0 格式 | | -------------------------------------------------------- | -------------------------------------------------------------------------- | | 顶层 `url` + `preferredTransport` + `additionalInterfaces` | `supportedInterfaces` 数组，每项含 `url` / `protocolBinding` / `protocolVersion` | | `authentication` | `securitySchemes` + `security` | ### 调用说明的写法 调用说明是**一份文档**，最多分两部分：开头一段可选的 YAML frontmatter（只有一个 `summary` 字段），后面是正文。 ```yaml theme={null} --- summary: 一句话简介，AI 据此决定是否派发 --- 正文：给 AI 的详细调用说明…… ``` * **简介（`summary`）驱动路由**：AI SRE 每次决定要不要委派时，看到的只是「可用 Agent 清单」里的一行 `名称：简介`。简介就是这一行的内容，务必写清楚**什么时候该优先选它、擅长什么、不擅长什么**——用具体的能力词（产品名、动词、场景），不要写空泛的宣传语。简介过长会在清单里被截断，重要信息往前写。 * **正文按需送达，不常驻清单**：正文不会一直占着 AI SRE 的上下文；只有当 AI SRE **第一次把任务委派给这个 Agent** 时，正文才会完整发给它（渐进式加载）。这意味着正文可以放心写得很长、很细——操作步骤、硬性规则（HARD RULE）、示例——不用担心拖慢日常对话。 * **不写 `summary` 也兼容**：如果调用说明整段是纯文本、不以 `---` 开头，全部内容都会被当作正文，AI SRE 自动截取开头一段作为简介（会被截断），旧版本写的调用说明无需改动即可继续用。但强烈建议显式写一段 `summary`，路由效果更可控。 * **硬性限制**：整份调用说明（frontmatter + 正文）不超过 **50 KB**；`summary` 不超过 **1,024 个字符**，且不能包含 `<` 或 `>`；正文不能为空。 * 如果开头写了 `---`，就必须再用一行 `---` 把 frontmatter 闭合，否则保存会失败。 下文「[使用 FlashAI 模板](#使用-flashai-模板)」的调用说明就是一份实际生效的范例，可以参考它的结构。 ### 使用 FlashAI 模板 **FlashAI** 是 Flashcat / 快猫星云体系内的可观测分析产品，也可以作为远端 A2A Agent 供 AI SRE 调用。在 A2A Agents 页面展开 **连接 FlashAI 可观测分析** 折叠卡片，即可使用 FlashAI 模板创建 A2A Agent。 FlashAI 模板的定位不是「所有可观测查询都走 FlashAI」，而是把 FlashAI 配置为 **Flashcat / 快猫星云来源告警与故障排查** 的委派目标。对于来自 Flashcat 的事件墙 / Event Wall、灭火图 / Firemap、北极星 / Polaris 等告警或故障，AI SRE 应优先把分析任务委派给 FlashAI。 模板默认预填一份调用说明文档，开头是一行 `summary:` 简介： ```yaml theme={null} summary: Flashcat/快猫星云 observability & ops — Firemap 灭火图, Polaris 北极星/northstar, logs 日志检索/报表, metrics 指标, traces 链路/拓扑, inspections 巡检/拨测, alert rules & dashboards. Call for ANY Flashcat task; MUST dispatch first whenever integration_type is "n9e.alert". ``` 这行简介会出现在 AI SRE 的「可用 Agent 清单」里，是 FlashAI 被优先选中的直接原因；summary 之后是正文，核心路由规则如下： * 用户正在排查明确来自 Flashcat / 快猫星云的告警、故障、事件或告警组时，优先调用 FlashAI。 * 事件墙 / Event Wall 上的告警事件、故障和告警组属于正向触发信号。 * 灭火图 / Firemap 故障属于正向触发信号，常见字段包括 `fault_type=firemap` 或 `rule_prod=firemap`。 * 北极星 / Polaris 故障属于正向触发信号，常见字段包括 `fault_type=polaris`、`rule_prod=polaris` 或内部标识 `rule_prod=northstar`。 * 来自 `n9e.alert` 的 Flashcat 告警如果带有 `rule_prod`、`rule_config.detail_url`、`workspace`、`fault_type`、`fault_workspace`、`fault_detail_url`、`fault_condition` 等故障元数据，也应优先委派给 FlashAI。 * 如果用户只是泛泛询问 metrics、logs、traces、topology 或性能问题，但没有 Flashcat / 快猫星云告警上下文、URL、产品标识或上述故障字段，不应默认调用 FlashAI；应使用当前可用工具或客户实际接入的可观测数据源。 FlashAI 侧需要先完成以下配置： FlashAI 需为 `release-24` 或更新版本。 在 FlashAI / Flashcat 控制台打开 `/config` 页面（例如 `https://demo.flashcat.cloud/config`），添加 `a2a_server_base_url`，值填写当前 FlashAI 的访问域名，例如 `https://demo.flashcat.cloud`。 如果 FlashAI 使用内网地址，只有部署在该网络内的 BYOC Runner 可以访问；如果希望云 Sandbox 也能调用 FlashAI，请使用公网可达域名，并按需配置白名单。这个限制与 MCP SSE 地址在 Sandbox 中的网络可达性要求一致。 完成 FlashAI 侧配置后，在折叠卡片中填写 **FlashAI 域名**（例如 `demo.flashcat.cloud`），点击 **使用此模板**。页面会打开 **添加 A2A Agent** 表单并预填： * 名称：根据域名生成，例如 `flashai-demo` * 调用说明：开头一行 `summary:` 简介 + 正文，正文列出哪些 Flashcat 告警/故障应优先调用 FlashAI、哪些泛化可观测问题不应调用。 * Card URL：根据域名自动生成： ```text theme={null} https://demo.flashcat.cloud/api/fc-model/a2a/.well-known/agent-card.json ``` 模板只负责预填通用信息；你仍需在表单中选择**范围**（共享或团队）并按需配置认证。A2A Agent 可以按不同范围安装多次，因此 FlashAI 折叠卡片不会因为已有某个 FlashAI Agent 就自动消失。Agent 名称在账户内仍需唯一；如果同一个 FlashAI 域名需要安装多次，请在表单里调整名称。 不建议删除 FlashAI 模板生成的调用说明，尤其是开头的 `summary:` 简介——注册后 FlashAI 一定会出现在「可用 Agent 清单」里，但 AI SRE 是否把任务派给它，直接依据就是这行简介。说明过短或过于泛化时，AI SRE 可能继续在本地推理，或把普通 metrics / logs 问题错误委派给 FlashAI。 ### 授权模式 A2A Agent 的身份由两条**互相独立**的轴决定，两条轴可以同时配置： * **服务授权**（`auth_type`）：AI SRE 作为一个服务去访问远端 Agent 时使用的身份，账户内共用一份。可选 `none`（无）、`bearer`（Bearer Token）、`api_key`（自定义 Header + Key）。表单中标记为**推荐**——配置一次即可覆盖全部场景。 * **成员授权**（`auth_mode`）：每位成员各自持有的身份。可选 `shared`（无）、`per_user_secret`（密钥（Header））、`per_user_oauth`（OAuth 2.1）。 这两条轴不是三选一。您可以只配服务授权、只配成员授权，也可以两者都配。两者都配时，由下面的「身份使用顺序」决定每个场景实际用哪一个。 #### 身份使用顺序 | 场景 | 使用的身份 | | ----------------------- | -------------------------- | | 个人会话（控制台、IM 单聊、个人范围自动化） | 优先使用**成员授权** | | IM 群聊 / 团队范围会话 | 使用**服务授权** | | 自动化（Automations） | 跟随会话范围：个人范围用成员授权，团队范围用服务授权 | 表单底部的「身份使用顺序」面板会随两个下拉框的选择实时给出结论： * **只配了服务授权**：所有场景都使用服务授权。 * **只配了成员授权**：IM 群聊会逐轮使用发言成员的个人授权。如果远端系统不接受同一会话内多人轮流的身份（会因身份校验失败而拒绝），请补配服务授权。 * **两条轴都为「无」**：调用不携带任何身份。保存时会弹出确认框「该 Agent 将不携带身份调用，确认保存？」。远端需要认证时，推荐配置服务授权。 服务授权意味着账户内任何团队范围会话与 IM 群聊都能以这个服务身份调用远端系统。若该系统涉及成员个人数据或高危写操作，建议同时启用成员授权。 #### 成员授权的两种形式 每位成员在首次调用时单独提供自己的密钥，密钥加密存储在账户级别。选择此模式需在「密钥 Schema」中填写 **Header 名称**（必填，凭证注入到哪个 HTTP header）与**帮助链接**（可选，指向「如何获取该密钥」的文档），供首次调用时引导成员填写。成员在 A2A Agent 列表的「成员授权」列各自填写并管理自己的密钥。 成员通过 OAuth 2.1 流程各自授权；首次调用该 A2A Agent 时自动弹出授权窗口，完成后凭证按成员隔离保存。授权前需在凭证对话框选择**执行环境**：可选云端 Sandbox 或在线的 BYOC Runner，不能使用「自动」。OAuth 请求从所选环境发起；远端 OAuth 服务仅在内网可达时，请选择能够访问它的 BYOC Runner。 OAuth 2.1 只出现在**成员授权**这条轴上。服务授权是账户内共用的一份静态凭证，只提供 Bearer Token 与 API Key 两种形式。 出于安全考虑，已保存的敏感字段（如 `token`、`api_key`、`client_secret`）在读取时会被**掩码**返回。编辑时若把敏感字段留空，表示「保留当前值」而非「清空」——只有当您显式修改它时才会覆盖已存储的凭证。 成员授权（OAuth 2.1）的发现地址优先使用 HTTPS。只有在受控测试环境中，才为非本地 HTTP Card URL 勾选「允许通过 HTTP 获取 OAuth 配置（仅限测试环境）」。如果 HTTPS 端点使用自签证书，也只应在可信网络内临时开启「跳过 TLS 证书校验」。 ## 入站：让外部 Agent 调用 AI SRE *** 在 A2A Agents 页面顶部展开「**让外部 Agent 调用 Flashduty 的 AI SRE**」面板，即可获取本账户 AI SRE 的 **Agent Card** 地址： ``` https://api.flashcat.cloud/safari/a2a/ai-sre/agent-card ``` 把该地址填入任意 A2A 客户端，即可经 A2A 协议调用 Flashduty 的 AI SRE Agent。 **鉴权**：在请求头加上 `Fd-App-Key: <你的 app_key>`（或使用 `?app_key=` 查询参数）。Agent Card 对外声明的能力包括： | 能力（Skill） | 说明 | | ---------------------- | ------------------------------------- | | `investigate_incident` | 端到端地为一个 Flashduty 故障定位根因，关联日志、指标与近期变更 | | `analyze_logs` | 在指定时间窗内查询并总结目标服务的日志 | | `analyze_metrics` | 在指定时间窗内查询并总结目标服务的指标 | Agent Card 同时声明了 Flashduty 的「运行选项」A2A 扩展：调用方可在 `message.metadata` 中按需覆盖 `incognito`（是否在会话列表中隐藏，默认隐藏）、`visibility`（`private` / `account`）、以及运行环境（`cloud` / `byoc` 与具体 `environment_id`）。该扩展为可选项，朴素的 A2A 客户端无需理会即可正常调用。 ### 故障与作战室联动 当一个会话**经由故障路由进入**（例如从故障或作战室触发 AI SRE）时，平台会把对应的故障绑定到本次会话，并作为上下文带入，让排障从一开始就锚定在正确的故障上。基于此，AI SRE 可在对话中借助内置 Skill 进一步操作故障——读取故障详情、查询时间线、创建 / 查看作战室、关联变更等。IM 侧的作战室自动诊断详见 [IM 集成](/zh/ai-sre/im)。 A2A 与故障的**自动联动**目前在概念上受支持、并在持续演进中：故障自动绑定尚未完整可用，跨 Agent 的双向事件流会随版本逐步完善。请勿将其视为已完整可用的能力——公测期间以实际开通的功能为准。 ## 创建与管理 *** A2A Agent 的完整生命周期可在 **插件 → Agents** 页面管理。 点击 **添加 A2A Agent**，填写名称、范围、调用说明、Card URL、认证等并保存。创建时需选定一个明确的作用域（共享或团队），未选定前提交按钮保持禁用。 用列表中的开关切换 A2A Agent 的启用状态。仅**已启用**的 Agent 会进入 AI SRE 的可用清单、可被委派任务；禁用后立即对委派不可见。 点击列表中的任意一行打开表单，可查看与编辑名称、调用说明、范围、Card URL、服务授权、成员授权与流式设置。无编辑权限时表单显示为**只读**。 从当前范围移除一个 A2A Agent。**委派给它的活跃会话将会失败。** 删除有确认提示。 列表顶部的范围筛选条可在「全部」「共享」「指定团队」之间切换，便于在大量资源中聚焦查看。每行还会以标签标注其范围（共享 / 团队名）。筛选条右侧的搜索框支持按名称、调用说明或 Card URL 中的关键词过滤列表。 ## 作用域 *** A2A Agent 与其他资源（Skill、知识库、MCP、运行环境）共用同一套**两级作用域**模型，分为账户级与团队级。控制台界面中，账户级这一档显示为「**共享**」/「**共享范围**」，与账户级同义（整个账户内可见）： | 作用域 | 可见性 | | --- | --------- | | 账户级 | 账户内所有成员可见 | | 团队级 | 仅该团队成员可见 | **编辑权限**：团队级 Agent 仅该团队的成员可以操作，组织管理员也需要先加入该团队；账户级 Agent 仅账户所有者或管理员可以操作；没有「创建者保留权限」这一例外。无编辑权限时，列表对应行显示为**只读**。 **创建与改归属**：创建新的团队级 Agent 时，您必须是目标团队成员；账户级创建仅限账户所有者或管理员。编辑已有 Agent 时，账户所有者或管理员可以把它移动到任意团队，用于恢复空团队或离职成员留下的资源；普通成员只能移动到自己所属的团队。 **运行时可见性**：会话开始时，AI SRE 的可用 Agent 清单中只会呈现**账户级**资源，以及**当前会话所绑定团队**的资源（如故障 / 作战室带入的团队，或界面上显式选择的团队）。当 Agent 在排障中读取另一个团队的知识后，该团队的 Skill、MCP 与 A2A Agent 才会被按需挂载进当前会话。**账户是运行时唯一的安全边界，团队只是归属与编辑的标记。** ## 相关页面 *** 在会话中观察 A2A 委派的任务卡片及其子会话面板。 为 Agent 接入外部工具，扩展其在任务中的能力边界。 用 DUTY.md 与知识包为 Agent 提供团队上下文与排障经验。 在 IM 群里 @ AI SRE，并了解故障作战室的自动诊断。 了解 AI SRE 的整体能力与定位。