> ## 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
> The Agent resource lets AI SRE connect to external agent ecosystems. The currently supported type is A2A (Agent-to-Agent) — delegating tasks to remote agents as well as exposing an Agent Card so external clients can call Flashduty's AI SRE in reverse, enabling incident / war-room integration and bidirectional event streams.
**Public beta**: AI SRE is now open to all accounts — no application needed. Sign in to the console and start using it; it's free during the public beta. Features and the UI may continue to evolve.
## Overview
***
**Agent** is the resource category that connects AI SRE to external agent ecosystems. The currently supported type is **A2A (Agent-to-Agent)** — a standard protocol that lets different agents call one another (more agent types may be added later). A2A works in two directions:
**Remote A2A agents** registered in the list. AI SRE **delegates** tasks to them via the standard A2A protocol — for example, an external agent specializing in metrics analysis or integrated with an internal system.
AI SRE itself is also an A2A agent and exposes an **Agent Card**. External A2A clients can fill in that Card URL to **call Flashduty's AI SRE in reverse**, enabling incident / war-room integration and bidirectional event streams.
Delegation does not make you wait: after AI SRE hands a task to a remote agent, the conversation continues immediately, so you can keep working or delegate several tasks at once. When the remote agent finishes, its result appears in the conversation as a new message. Each A2A delegation appears in the conversation stream as a **task card** carrying an `A2A` badge, showing the remote agent name, task intent, run status (initializing / in progress / awaiting input / awaiting authorization / completed / failed (including orphaned) / interrupted / killed), and usage metrics such as tool call count, tokens, and elapsed time. Click the card to view the full delegation trace in the right-hand panel.
**Instructions have two levels and act as the agent-selection signal.** Before delegating, AI SRE sees a list of available agents where each entry is just `name: summary` — the summary comes from a `summary:` line at the top of the instructions (if omitted, the beginning of the body is excerpted automatically). AI SRE uses it to decide **whether and when** to delegate to this agent, so state clearly when to prefer it, what it excels at, and what it is not suited for. The body that follows the summary is not kept in the list — it is delivered to AI SRE in full only the **first time it delegates to this agent**, so you can write it as long and detailed as needed (procedures, hard rules, examples) without slowing down everyday conversations. See "[Writing Instructions](#writing-instructions)" below for the format.
The A2A agent list and management entry point are on the **Plugins → Agents** page (menu tab labeled **Agents**).
**Agents covers two distinct concepts.** This page (Agents) currently manages **A2A Agents** (external agent-to-agent calls). The other concept is the **Subagent** — a platform-built-in task executor that AI SRE dispatches on demand within a session. Subagents have no create / edit entry point; you only observe their behavior in sessions. See "[Subagent](#subagent)" below.
## Subagent
***
A **Subagent** is a platform **built-in** task executor. During an investigation, AI SRE can **dispatch** a self-contained subtask to a Subagent that completes it independently — dispatch always goes through the single long-running tool `agent_dispatch`, rather than exposing a separate tool per Subagent.
The platform ships several **bootstrap Subagents** that work out of the box:
| Name | Role |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `general` | General-purpose worker with full tool access. Use it to offload work whose intermediate steps would otherwise pollute the parent's context (long reports, multi-file edits, end-to-end builds, repeated probing). Dispatch several in parallel for independent units of work |
| `explore` | Read-only investigator restricted to `grep` / `glob` / `read`; it cannot write or execute. Returns a compact summary rather than raw search output — ideal for locating evidence inside a codebase or knowledge dump |
**In the conversation**: each dispatch also appears as a **task card** in the conversation stream and shares the same status lifecycle as an A2A delegation (initializing / in progress / awaiting input / awaiting authorization / completed / failed (including orphaned) / interrupted / killed). The difference is the badge — a Subagent task card carries an `Agent` badge, whereas an A2A delegation carries an `A2A` badge.
**Runtime limits**:
* **Concurrency cap**: a session runs **at most 20 Subagents concurrently** (`TaskMaxConcurrentPerSession = 20`). This caps how many run at the same instant, not how many a session dispatches over its lifetime — completing one frees a slot, so total work is unbounded. Dispatching past the cap errors (`too many active subagents (… running, limit 20)`), prompting the model to stop and wait for the running ones to finish before dispatching the rest.
* **Nesting depth**: a dispatch chain nests **at most 3 levels deep** (`TaskMaxNestingDepth = 3`), preventing a Subagent from spawning itself indefinitely.
**Subagents currently have no user-facing create / management UI.** They are a built-in runtime capability: you can observe Subagent task cards and their sub-session traces within a session, but you cannot add, edit, or delete a Subagent the way you can an A2A Agent. This page (Agents) currently manages only A2A Agents.
## Registering an Outbound A2A Agent
***
On the A2A Agents list page, click **Add A2A Agent** and fill in the form:
| Field | Type | Default | Description |
| ----------------------------------------------------------- | ------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | string | — | A2A agent identifier (e.g., `metrics-analyzer`). Required |
| Scope | Shared / Team | — | Scope: **Shared** (i.e., account level — visible account-wide) or a specific **Team** (visible and editable only to members of that team). Required — see "Scope" below |
| Execution Environment | Cloud / BYOC Runners (multiple) | All environments | Controls where this A2A agent is available. Select Cloud and one or more visible BYOC Runners; leave empty to make it available everywhere. It does not route delegated calls: an A2A call still runs in the current AI SRE session's environment. For a remote agent available only on a private network, select only the Runner(s) that can reach it |
| Instructions | string | — | The agent-selection signal shown to AI SRE, as **a single document**: an optional `summary:` frontmatter block plus a body. The summary appears in the available-agent list; the body is delivered in full only on first delegation. Required; the whole document is at most 50 KB, and `summary` is at most 1,024 characters and must not contain `<` or `>`. See "[Writing Instructions](#writing-instructions)" below for the format |
| 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 only validates that the URL is well-formed (scheme is http/https, host is non-empty) — it does not classify hosts or IPs; actual network reachability and egress restrictions depend on the current AI SRE session's execution environment. The Execution Environment field above only limits where this agent is available. The remote agent must implement A2A Protocol 1.0 — see "[Protocol Version and Agent Card Requirements](#protocol-version-and-agent-card-requirements)" below |
| Service authorization | enum | `none` | The identity AI SRE uses when calling the remote agent **as a service** (field `auth_type`): `none` / `bearer` (Bearer Token) / `api_key` (custom Header + Key). Marked **Recommended** in the form. See "[Authorization Modes](#authorization-modes)" below |
| Streaming | bool | on | Whether to communicate with the remote agent in streaming mode |
| Member authorization | enum | `shared` (none) | The identity each member holds individually (field `auth_mode`): `shared` (none) / `per_user_secret` (Secret (Header)) / `per_user_oauth` (OAuth 2.1). See "[Authorization Modes](#authorization-modes)" below |
| Skip TLS certificate verification | bool | off | Shown only when the Card URL uses HTTPS. Enable only when the remote endpoint uses a self-signed certificate inside a controlled network; this skips certificate-chain and hostname verification |
| Allow fetching OAuth configuration over HTTP (testing only) | bool | off | Required only when **Member authorization** is set to "OAuth 2.1" and the Card URL is a non-local HTTP URL. Use only in controlled test environments; after you enable it, the AI SRE service can fetch OAuth metadata from that host |
### Protocol Version and Agent Card Requirements
When calling a remote agent as an A2A client, the platform implements **A2A Protocol 1.0** (with the `JSONRPC` or `HTTP+JSON` protocol binding). **Protocol 0.x and other major versions are not supported**: the remote agent's Agent Card must be in the 1.0 format, or delegated calls will fail.
A 1.0-format Agent Card declares its endpoints via the `supportedInterfaces` array, where at least one entry must contain `url`, `protocolBinding` (`JSONRPC` or `HTTP+JSON`), and `protocolVersion: "1.0"`. A minimal valid card looks like this:
```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"]
}
```
The `version` field on the card is the **agent's own version number**, not the protocol version. The protocol version is declared by `protocolVersion` in each `supportedInterfaces` entry.
**Migrating from 0.x to 1.0**: if your Agent Card still uses the 0.x format, adjust it as follows before connecting:
| 0.x format | 1.0 format |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Top-level `url` + `preferredTransport` + `additionalInterfaces` | `supportedInterfaces` array, each entry with `url` / `protocolBinding` / `protocolVersion` |
| `authentication` | `securitySchemes` + `security` |
### Writing Instructions
Instructions are **a single document** with up to two parts: an optional YAML frontmatter block at the top (a single `summary` field), followed by the body.
```yaml theme={null}
---
summary: One-line summary — AI SRE uses this to decide whether to delegate
---
Body: detailed instructions for the agent…
```
* **The summary drives routing.** Every time AI SRE decides whether to delegate, all it sees is one line in the available-agent list: `name: summary`. That summary is exactly this field's content, so state clearly **when to prefer this agent, what it excels at, and what it is not suited for** — use concrete capability words (product names, verbs, scenarios), not marketing slogans. Overlong summaries get truncated in the list, so front-load the important part.
* **The body is delivered on demand, not kept in the list.** The body does not occupy AI SRE's context all the time. It is sent to AI SRE in full only the **first time it delegates to this agent** (progressive loading). That means the body can be as long and detailed as you need — procedures, hard rules, examples — without bloating everyday conversations.
* **Plain text without a `summary` still works.** If the instructions are plain text that doesn't start with `---`, the whole content is treated as the body, and AI SRE automatically excerpts the beginning as the summary (truncated) — this keeps older-style instructions working unchanged. Writing an explicit `summary` is still strongly recommended for more predictable routing.
* **Hard limits**: the whole document (frontmatter + body) is at most **50 KB**; `summary` is at most **1,024 characters** and must not contain `<` or `>`; the body must be non-empty.
* If the document starts with `---`, that frontmatter block must be closed with another `---` line, or saving fails.
The instructions used by "[Using the FlashAI Template](#using-the-flashai-template)" below are a working example — see its structure for reference.
### Using the FlashAI Template
**FlashAI** is the observability analysis product in the Flashcat / 快猫星云 family. It can also be connected as a remote A2A agent for AI SRE. On the A2A Agents page, expand the **Connect FlashAI observability analysis** panel to create an A2A agent from the FlashAI template.
The FlashAI template is not a blanket rule that sends every observability question to FlashAI. It configures FlashAI as the delegation target for **Flashcat / 快猫星云-originated alert and incident investigation**. For alerts or incidents from Flashcat products such as Event Wall / 事件墙, Firemap / 灭火图, and Polaris / 北极星, AI SRE should prefer delegating analysis to FlashAI.
The template prefills an instructions document that opens with a `summary:` line:
```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".
```
That summary is what shows up in AI SRE's available-agent list, and it's the direct reason FlashAI gets picked first. The body that follows the summary carries the core routing rules:
* Prefer FlashAI when the user is investigating an alert, incident, fault, or alert group that clearly originates from Flashcat / 快猫星云.
* Event Wall / 事件墙 alert events, incidents, and alert groups are positive routing signals.
* Firemap / 灭火图 faults are positive routing signals, especially fields such as `fault_type=firemap` or `rule_prod=firemap`.
* Polaris / 北极星 faults are positive routing signals, especially fields such as `fault_type=polaris`, `rule_prod=polaris`, or the internal marker `rule_prod=northstar`.
* Flashcat alerts from `n9e.alert` should also be delegated to FlashAI when they carry fault metadata such as `rule_prod`, `rule_config.detail_url`, `workspace`, `fault_type`, `fault_workspace`, `fault_detail_url`, or `fault_condition`.
* Do not use FlashAI by default for generic metrics, logs, traces, topology, or performance questions that do not include Flashcat / 快猫星云 alert context, a Flashcat URL, product markers, or the fault fields above. Use the available local tools or the customer's actual observability source instead.
Prepare FlashAI first:
FlashAI must be `release-24` or later.
Open `/config` in the FlashAI / Flashcat console (for example, `https://demo.flashcat.cloud/config`), add `a2a_server_base_url`, and set it to the current FlashAI access domain, for example `https://demo.flashcat.cloud`.
If FlashAI uses a private-network address, only a BYOC Runner deployed in that network can reach it. If cloud Sandbox also needs to call FlashAI, use a publicly reachable domain and configure an allowlist as needed. This is the same network-reachability rule used for MCP SSE endpoints in Sandbox.
After FlashAI is prepared, enter the **FlashAI domain** in the panel (for example, `demo.flashcat.cloud`) and click **Use this template**. The page opens the **Add A2A Agent** form and prefills:
* Name: generated from the domain, for example `flashai-demo`
* Instructions: a `summary:` line plus a body — the body lists which Flashcat alerts/incidents should prefer FlashAI and which generic observability questions should not.
* Card URL: generated from the domain:
```text theme={null}
https://demo.flashcat.cloud/api/fc-model/a2a/.well-known/agent-card.json
```
The template only prefills common values. You still choose the **Scope** (Shared or Team) and configure authentication in the form. A2A agents can be installed multiple times for different scopes, so the FlashAI panel does not disappear just because one FlashAI agent already exists. Agent names must still be unique within the account; if the same FlashAI domain needs to be installed more than once, adjust the name in the form.
Do not remove the instructions generated by the FlashAI template, especially the `summary:` line at the top — once registered, FlashAI always appears in the available-agent list, but whether AI SRE actually delegates to it hinges directly on that summary line. When the instructions are too short or too generic, AI SRE may keep reasoning locally or incorrectly delegate ordinary metrics / logs questions to FlashAI.
### Authorization Modes
An A2A agent's identity is determined by two **independent** axes, and both can be configured at the same time:
* **Service authorization** (`auth_type`): the identity AI SRE uses when calling the remote agent as a service. One credential shared account-wide. Choose `none`, `bearer` (Bearer Token), or `api_key` (custom Header + Key). The form marks it **Recommended** — configure it once and it covers every scenario.
* **Member authorization** (`auth_mode`): the identity each member holds individually. Choose `shared` (none), `per_user_secret` (Secret (Header)), or `per_user_oauth` (OAuth 2.1).
These two axes are not a three-way choice. You can set only the service authorization, only the member authorization, or both. When both are set, the identity resolution order below decides which one each scenario actually uses.
#### Identity resolution order
| Scenario | Identity used |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| Personal sessions (console, IM direct chats, personal-scope automations) | **Member authorization** first |
| IM group chats / team-scope sessions | **Service authorization** |
| Automations | Follows the session scope: personal scope uses member authorization, team scope uses service authorization |
The "Identity resolution order" panel at the bottom of the form updates live as you change the two selects:
* **Service authorization only**: all calls use the service authorization.
* **Member authorization only**: IM group chats use the speaking member's own authorization, turn by turn. If the remote system rejects several identities taking turns within one conversation (its identity check fails), add a service authorization.
* **Both axes set to none**: calls carry no identity. Saving prompts for confirmation — "This Agent will call without any identity. Save anyway?". Configure a service authorization when the remote endpoint requires authentication.
A service authorization means any team-scope session or IM group chat in the account can call the remote system as that service identity. If the system exposes members' personal data or allows high-risk writes, enable member authorization as well.
#### The two forms of member authorization
Each member provides their own key on first use; the key is encrypted and stored at the account level. Configure the **Header name** (required — which HTTP header the credential is injected into) and a **help link** (optional — documentation on how to obtain the key) in the Key Schema to guide members on first call. Members fill in and manage their own key from the "Member authorization" column of the A2A agent list.
Each member authorizes via the OAuth 2.1 flow; an authorization window pops up automatically on the first call to this A2A agent, and credentials are stored per member after completion. Before authorizing, choose an **execution environment** in the Credential dialog: a Cloud Sandbox or an online BYOC Runner; **Auto** is unavailable. OAuth requests run from the selected environment, so choose a BYOC Runner that can reach the service when its OAuth endpoint is private.
OAuth 2.1 appears only on the **member authorization** axis. The service authorization is a single static credential shared account-wide, and offers only Bearer Token and API Key.
For security reasons, saved sensitive fields (such as `token`, `api_key`, and `client_secret`) are returned **masked** when read. When editing, leaving a sensitive field blank means "keep the current value" — not "clear it." The stored credential is only overwritten when you explicitly change it.
Use HTTPS for member authorization (OAuth 2.1) discovery whenever possible. Enable "Allow fetching OAuth configuration over HTTP (testing only)" for a non-local HTTP Card URL only in controlled test environments. If an HTTPS endpoint uses a self-signed certificate, enable "Skip TLS certificate verification" only temporarily and only inside a trusted network.
## Inbound: Letting External Agents Call AI SRE
***
Expand the "**Let External Agents Call Flashduty's AI SRE**" panel at the top of the A2A Agents page to get the **Agent Card** URL for this account's AI SRE:
```
https://api.flashcat.cloud/safari/a2a/ai-sre/agent-card
```
Add that URL to any A2A client to call Flashduty's AI SRE agent via the A2A protocol.
**Authentication**: add `Fd-App-Key: ` in the request header (or use the `?app_key=` query parameter). The capabilities declared on the Agent Card include:
| Capability (Skill) | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------ |
| `investigate_incident` | End-to-end root-cause analysis for a Flashduty incident, correlating logs, metrics, and recent changes |
| `analyze_logs` | Query and summarize logs for a target service within a specified time window |
| `analyze_metrics` | Query and summarize metrics for a target service within a specified time window |
The Agent Card also declares Flashduty's "run options" A2A extension: callers can override `incognito` (whether to hide the session from the session list; hidden by default), `visibility` (`private` / `account`), and the environment (`cloud` / `byoc` and a specific `environment_id`) in `message.metadata`. This extension is optional — plain A2A clients can ignore it and call normally.
### Incident and War-Room Integration
When a session **enters via an incident route** (e.g., AI SRE is triggered from an incident or war room), the platform binds the corresponding incident to the session and brings it in as context, anchoring troubleshooting to the correct incident from the start. Based on this, AI SRE can use built-in skills during the conversation to further act on the incident — reading incident details, querying the timeline, creating / viewing war rooms, linking changes, and more. For automatic war-room diagnosis on the IM side, see [IM Integration](/en/ai-sre/im).
**Automatic incident integration** for A2A is currently supported conceptually and is under active development: automatic incident binding is not yet fully available, and bidirectional event streams across agents will be progressively completed with each release. Do not treat this as a fully available capability — during the public beta, only features that have been explicitly enabled should be relied upon.
## Creating and Managing
***
The full lifecycle of A2A agents is managed on the **Plugins → Agents** page.
Click **Add A2A Agent**, fill in the name, scope, instructions, Card URL, auth settings, and save. You must select a definite scope (shared or team) before submitting — the submit button remains disabled until a scope is chosen.
Use the toggle in the list to switch an A2A agent's enabled state. Only **enabled** agents appear in AI SRE's available-agent list and can receive delegated tasks; disabling one makes it immediately invisible to delegation.
Click any row in the list to open the form, where you can view and edit the name, instructions, scope, Card URL, service authorization, member authorization, and streaming. The form is **read-only** when you do not have edit permission.
Remove an A2A agent from the current scope. **Active sessions that delegated to it will fail.** Deletion requires confirmation.
The scope filter bar at the top of the list lets you switch between "All", "Shared", and "Specific team", making it easy to focus on relevant resources when managing many. Each row also has a label showing its scope (shared / team name). The search box to the right of the filter bar filters the list by keywords in the name, instructions, or Card URL.
## Scope
***
A2A agents share the same **two-level scope** model as other resources (skills, Knowledge Packs, MCP, environments), divided into account level and team level. In the console UI, the account-level option is labeled "**Shared**" / "**Shared scope**" — synonymous with account level (visible account-wide):
| Scope | Visibility |
| ------------- | ------------------------------------- |
| Account level | Visible to all members in the account |
| Team level | Visible only to members of that team |
**Edit permissions**: team-level agents can be acted on only by members of that team — organization admins must join the team first; account-level agents can be acted on only by the account owner or account admin; there is no creator-retains-rights exception. When you do not have edit permission, the corresponding row in the list is **read-only**.
**Create and reassign**: to create a new team-level agent, you must belong to the target team; account-level creation is limited to the account owner or admins. When editing an existing agent, the account owner or admins can move it to any team to recover resources left behind by empty teams or departed members; regular members can move it only to teams they belong to.
**Runtime visibility**: at session start, AI SRE's available-agent list shows only **account-level** resources plus resources belonging to the **team bound to the current session** (e.g., the team carried in by an incident / war room, or explicitly selected in the UI). A team's skills, MCP servers, and A2A agents are only mounted into the current session on demand after the agent reads that team's knowledge during an investigation. **The account is the only security perimeter at runtime; team is simply an ownership and editing tag.**
## Related Pages
***
Observe A2A delegation task cards and their sub-session panels within a session.
Connect external tools to agents to expand their capability boundary during tasks.
Use DUTY.md and Knowledge Packs to provide agents with team context and troubleshooting experience.
@ AI SRE in an IM group and learn about automatic war-room incident diagnosis.
Understand AI SRE's overall capabilities and positioning.