> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/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 目前处于内测阶段，专业版及以上用户可申请免费试用。请通过 [AI SRE 内测申请表](https://c9xudyniiq.feishu.cn/share/base/form/shrcn0ngCfdoygiaHnAT80BfZiH) 提交申请，审核通过后将开通白名单；内测期间功能与界面可能调整。
## 概述
***
**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、耗时等用量；点击卡片可在右侧面板里查看该次委派的完整过程。
**调用说明（instructions）是 Agent 选择信号**。AI SRE 在委派前看到的是一份「可用 Agent 清单」，每一项是 `名称：调用说明`。不要只写一句展示文案；可以在表单的多行编辑区里写有指导性的说明（例如「USE THIS FIRST for ...」「prefer-over-X when ...」），明确指出**何时应当优先选用它、它擅长什么、不适合做什么**——调用说明写得越精准，AI SRE 越能在正确的场景把任务委派给正确的 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`）。必填 |
| 范围 | 账户 / 团队 | — | 作用域：**账户**（账户内全局可见）或某个**团队**（仅该团队成员可见和可编辑）。必填，详见下文「作用域」 |
| 调用说明 | string | — | 面向 AI SRE 的 Agent 选择信号。它会进入 AI SRE 的系统提示词和「可用 Agent 清单」，用于判断何时调用该 A2A Agent。必填；建议写成有指导性的说明，表达适用场景、能力边界和不适用场景。最多 2,000 个字符 |
| Card URL | string | — | 远端 A2A Agent 的 Agent Card 地址，或仅填写遵循默认 well-known 规则的服务根地址（如 `https://agents.example.com`）。如果 URL 已带路径，平台会按该地址原样读取；如果只填服务根地址，平台按 A2A 约定查找 `/.well-known/agent-card.json`。必填。平台会校验它是合法的 http/https 地址，并拒绝指向回环、内网、链路本地或云元数据等受限地址 |
| 认证类型 | enum | `none` | 出站请求附带的凭证类型：`none`（无）/ `bearer`（Bearer Token）/ `api_key`（自定义 Header + Key） |
| 流式传输 | bool | 开 | 是否以流式方式与远端交互 |
| 用户级认证模式 | enum | `shared` | 见下表「认证模式」 |
| 跳过 TLS 证书校验 | bool | 关 | 仅当 Card URL 为 HTTPS 时显示。只在远端使用自签证书且网络受控时开启；开启后会跳过证书链和主机名校验 |
| 允许通过 HTTP 进行 OAuth 发现 | bool | 关 | 仅当选择「每用户 OAuth」且 Card URL 是非本地 HTTP 地址时需要确认。只用于受控测试环境；开启后 Safari 服务端会访问该主机的 OAuth metadata |
### 使用 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。
模板默认预填一段多行调用说明，核心路由规则如下：
* 用户正在排查明确来自 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`
* 调用说明：面向 AI SRE 的多行委派说明，指出哪些 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 模板生成的调用说明。AI SRE 是否会主动调用远端 A2A Agent，主要取决于名称与调用说明提供的选择信号；说明过短或过于泛化时，AI SRE 可能继续在本地推理，或把普通 metrics / logs 问题错误委派给 FlashAI。
### 认证模式
A2A Agent 支持三种凭证供给方式，决定不同用户调用同一个远端 Agent 时如何提供凭证：
所有用户共用同一组凭证，凭证在「认证类型」中配置（Bearer Token 或 API Key）。适合团队共享同一个远端账号的场景。
每个用户在首次调用时单独提供自己的密钥，密钥加密存储在账户级别。需在「密钥 Schema」中配置 Header 名称（必填）、占位符与帮助链接（可选），供首次调用时引导用户填写。
用户通过 OAuth 2.1 流程各自授权；首次调用该 A2A Agent 时自动弹出授权窗口，完成后凭证按用户隔离保存。
出于安全考虑，已保存的敏感字段（如 `token`、`api_key`、`client_secret`）在读取时会被**掩码**返回。编辑时若把敏感字段留空，表示「保留当前值」而非「清空」——只有当您显式修改它时才会覆盖已存储的凭证。
每用户 OAuth 的发现地址优先使用 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。**委派给它的活跃会话将会失败。** 删除有确认提示。
列表顶部的范围筛选条可在「全部」「仅账户级」「指定团队」之间切换，便于在大量资源中聚焦查看。每行还会以标签标注其范围（账户 / 团队名）。
## 作用域
***
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 的整体能力与定位。