From d13e502ed53e4e456f23ac5ecb0062bf4b38be89 Mon Sep 17 00:00:00 2001 From: ysyneu Date: Fri, 26 Jun 2026 10:06:32 +0800 Subject: [PATCH] docs: document FlashAI A2A setup --- en/ai-sre/agents.mdx | 32 +++++++++++++++++++++++++++++++- zh/ai-sre/agents.mdx | 32 +++++++++++++++++++++++++++++++- 2 files changed, 62 insertions(+), 2 deletions(-) diff --git a/en/ai-sre/agents.mdx b/en/ai-sre/agents.mdx index b1154bff..5c5d0989 100644 --- a/en/ai-sre/agents.mdx +++ b/en/ai-sre/agents.mdx @@ -71,11 +71,41 @@ On the A2A Agents list page, click **Add A2A Agent** and fill in the form: | Name | string | — | A2A agent identifier (e.g., `metrics-analyzer`). Required | | Scope | Account / Team | — | Scope: **Account** (visible account-wide) or a specific **Team** (visible and editable only to members of that team). Required — see "Scope" below | | Description | string | — | A brief description of this A2A agent's capabilities. It appears in AI SRE's available-agent list as the selection signal — write it as a prescriptive imperative | -| Card URL | string | — | The base URL of the remote A2A agent (e.g., `https://flashai.flashcat.cloud`). Required. The platform validates that it is a legitimate http/https address and rejects loopback, private, link-local, or cloud-metadata addresses | +| Card URL | string | — | The Agent Card URL of the remote A2A agent, or just the service origin for agents that follow the default well-known location (for example, `https://agents.example.com`). If the URL includes a path, the platform reads that exact URL; if only an origin is provided, it resolves `/.well-known/agent-card.json` by A2A convention. Required. The platform validates that it is a legitimate http/https address and rejects loopback, private, link-local, or cloud-metadata addresses | | Auth Type | enum | `none` | Credential type attached to outbound requests: `none` / `bearer` (Bearer Token) / `api_key` (custom Header + Key) | | Streaming | bool | on | Whether to communicate with the remote agent in streaming mode | | User Auth Mode | enum | `shared` | See "Auth Modes" below | +### FlashAI Official Integration + +If the remote A2A agent is **FlashAI**, choose **FlashAI official integration** at the top of the add form. The form treats the row as a FlashAI preset: + +- Name is prefilled as `flashai`. +- Description is prefilled with delegation guidance for AI SRE, telling it to call FlashAI when the task depends on FlashAI observability data such as metrics, logs, traces, flame graphs, topology, or Flashcat monitoring context. +- After you enter the **FlashAI domain** (for example, `demo.flashcat.cloud`), the Card URL is generated automatically: + +```text +https://demo.flashcat.cloud/api/fc-model/a2a/.well-known/agent-card.json +``` + +FlashAI must be prepared first: + + + + FlashAI must be `release-24` or later. + + + In FlashAI `/config`, add `a2a_server_base_url` and set it to the customer's own FlashAI access domain, for example `https://demo.flashcat.cloud`. + + + Flashduty AI SRE currently reaches the FlashAI A2A address from the cloud, so the domain must be reachable from Flashduty's cloud egress. If FlashAI is only reachable inside a customer private network, first expose a reachable domain and configure the allowlist. After A2A egress is moved to Runner / envd, it will be able to reach private-network FlashAI the same way MCP does. + + + + + Do not remove the description generated by the FlashAI template unless you have a more precise one. Whether AI SRE proactively calls a remote A2A agent depends mainly on the selection signal provided by the name and description; when the description is too generic, AI SRE may keep reasoning locally instead of delegating the task to FlashAI. + + ### Auth Modes A2A agents support three credential-supply modes that determine how credentials are provided when different users call the same remote agent: diff --git a/zh/ai-sre/agents.mdx b/zh/ai-sre/agents.mdx index 84ccac1c..1b710a32 100644 --- a/zh/ai-sre/agents.mdx +++ b/zh/ai-sre/agents.mdx @@ -71,11 +71,41 @@ A2A Agent 的列表与管理入口在 **插件 → Agents** 页面（菜单标 | 名称 | string | — | A2A Agent 标识（如 `metrics-analyzer`）。必填 | | 范围 | 账户 / 团队 | — | 作用域：**账户**（账户内全局可见）或某个**团队**（仅该团队成员可见和可编辑）。必填，详见下文「作用域」 | | 描述 | string | — | 简要描述此 A2A Agent 的功能。它会进入 AI SRE 的「可用 Agent 清单」，是选择信号——建议写成有指导性的祈使句 | -| Card URL | string | — | 远端 A2A Agent 的基础 URL（如 `https://flashai.flashcat.cloud`）。必填。平台会校验它是合法的 http/https 地址，并拒绝指向回环、内网、链路本地或云元数据等受限地址 | +| 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` | 见下表「认证模式」 | +### FlashAI 官方集成 + +如果远端 A2A Agent 是 **FlashAI**，在添加表单顶部选择 **FlashAI 官方集成**。表单会把该 Agent 作为 FlashAI 预设处理： + +- 名称预填为 `flashai`。 +- 描述预填为面向 AI SRE 的委派提示，告诉 AI SRE 在需要 FlashAI 可观测数据（指标、日志、Trace、火焰图、拓扑、Flashcat 监控上下文）时优先调用它。 +- 填写 **FlashAI 域名**（例如 `demo.flashcat.cloud`）后，Card URL 会自动生成： + +```text +https://demo.flashcat.cloud/api/fc-model/a2a/.well-known/agent-card.json +``` + +FlashAI 侧需要先完成以下配置： + + + + FlashAI 需为 `release-24` 或更新版本。 + + + 在 FlashAI 的 `/config` 中添加 `a2a_server_base_url`，值填写用户自己的 FlashAI 访问域名，例如 `https://demo.flashcat.cloud`。 + + + 当前 Flashduty AI SRE 会从云端访问 FlashAI 的 A2A 地址，因此该域名需要能被 Flashduty 云端访问。若 FlashAI 只在客户内网可达，请先使用可公网访问的域名并配置白名单；后续 A2A 出网迁移到 Runner / envd 后，才能像 MCP 一样从客户网络内访问内网 FlashAI。 + + + + + 不建议删除 FlashAI 模板生成的描述。AI SRE 是否会主动调用远端 A2A Agent，主要取决于名称与描述提供的选择信号；描述过于泛化时，AI SRE 可能继续在本地推理，而不会把任务委派给 FlashAI。 + + ### 认证模式 A2A Agent 支持三种凭证供给方式，决定不同用户调用同一个远端 Agent 时如何提供凭证：