> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashcat.cloud/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 目前处于内测阶段，仅对受邀账户开放。如需参与白名单测试，请联系 Flashduty 商务团队申请开通；内测期间功能与界面可能调整。
## 概述
***
**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 委派在对话流里以一张**任务卡片**（🛰️）呈现，显示远端 Agent 名、本次任务意图、运行状态（初始化 / 进行中 / 完成 / 失败 / 中断）以及工具调用数、Token、耗时等用量；点击卡片可在右侧面板里查看该次委派的完整过程。
**描述（description）是 Agent 选择的核心信号**。AI SRE 在委派前看到的是一份「可用 Agent 清单」，每一项是 `名称：描述`。描述应写成有指导性的祈使句（例如「USE THIS FIRST for ...」「prefer-over-X when ...」），明确指出**何时应当优先选用它、它擅长什么、不适合做什么**——描述写得越精准，AI SRE 越能在正确的场景把任务委派给正确的 Agent。
A2A Agent 的列表与管理入口在 **插件 → Agents** 页面（菜单标签为 **Agents**）。
## 注册出站 A2A Agent
***
在 A2A Agents 列表页点击 **添加 A2A Agent**，在表单中填写：
| 字段 | 类型 | 默认值 | 说明 |
| -------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| 名称 | string | — | A2A Agent 标识（如 `metrics-analyzer`）。必填 |
| 范围 | 账户 / 团队 | — | 作用域：**账户**（账户内全局可见）或某个**团队**（仅该团队成员可见和可编辑）。必填，详见下文「作用域」 |
| 描述 | string | — | 简要描述此 A2A Agent 的功能。它会进入 AI SRE 的「可用 Agent 清单」，是选择信号——建议写成有指导性的祈使句 |
| Card URL | string | — | 远端 A2A Agent 的基础 URL（如 `https://flashai.flashcat.cloud`）。必填。平台会校验它是合法的 http/https 地址，并拒绝指向回环、内网、链路本地或云元数据等受限地址 |
| 认证类型 | enum | `none` | 出站请求附带的凭证类型：`none`（无）/ `bearer`（Bearer Token）/ `api_key`（自定义 Header + Key） |
| 流式传输 | bool | 开 | 是否以流式方式与远端交互 |
| 用户级认证模式 | enum | `shared` | 见下表「认证模式」 |
### 认证模式
A2A Agent 支持三种凭证供给方式，决定不同用户调用同一个远端 Agent 时如何提供凭证：
所有用户共用同一组凭证，凭证在「认证类型」中配置（Bearer Token 或 API Key）。适合团队共享同一个远端账号的场景。
每个用户在首次调用时单独提供自己的密钥，密钥加密存储在账户级别。需在「密钥 Schema」中配置 Header 名称（必填）、占位符与帮助链接（可选），供首次调用时引导用户填写。
用户通过 OAuth 2.1 流程各自授权；首次调用该 A2A Agent 时自动弹出授权窗口，完成后凭证按用户隔离保存。
出于安全考虑，已保存的敏感字段（如 `token`、`api_key`、`client_secret`）在读取时会被**掩码**返回。编辑时若把敏感字段留空，表示「保留当前值」而非「清空」——只有当您显式修改它时才会覆盖已存储的凭证。
## 入站：让外部 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；没有「创建者保留权限」这一例外。无编辑权限时，列表对应行显示为**只读**。
**运行时可见性**：会话开始时，AI SRE 的可用 Agent 清单中只会呈现**账户级**资源，以及**当前会话所绑定团队**的资源（如故障 / 作战室带入的团队，或界面上显式选择的团队）。当 Agent 在排障中读取另一个团队的知识后，该团队的 Skill、MCP 与 A2A Agent 才会被按需挂载进当前会话。**账户是运行时唯一的安全边界，团队只是归属与编辑的标记。**
## 相关页面
***
在会话中观察 A2A 委派的任务卡片及其子会话面板。
为 Agent 接入外部工具，扩展其在任务中的能力边界。
用 DUTY.md 与知识包为 Agent 提供团队上下文与排障经验。
在 IM 群里 @ AI SRE，并了解故障作战室的自动诊断。
了解 AI SRE 的整体能力与定位。