Azure SRE Agent — GBB Adoption Skill

Posture: upstream-first. Microsoft ships the full toolchain at microsoft/sre-agent and the plugin marketplace at Azure/sre-agent-plugins. This skill does not rebuild Bicep modules, deploy scripts, or a custom-agent library — those are MIT-licensed and actively maintained there. We add only what GBB engagements need on top: 3 GBB-shaped recipes, 2 GBB-shaped plugins, a small cross-skill data-plane helper, and the pre-flight runbook the official docs assume you don't need.

1. When to use / when NOT

Use this skill when a customer wants Azure SRE Agent (sre.azure.com, Microsoft.App/agents) deployed in a GBB engagement — typically because they already run on Azure and want an always-on operator/responder agent on top of App Insights + Log Analytics + their incident platform.

2. Use the official toolchain first

Before you write a single byte of Bicep, do this:

git clone https://github.com/microsoft/sre-agent.git
cd sre-agent/sreagent-templates

./bin/install-prerequisites.sh          # az, jq, python3, pyyaml; --all adds Terraform + azd

# Generate config from a vendor-neutral recipe
./bin/new-agent.sh --recipe minimal --non-interactive \
  --set agentName=my-sre-agent \
  --set resourceGroup=rg-my-sre-agent \
  --set location=swedencentral \
  --set targetRGs=rg-my-workload \
  -o my-agent/

./bin/deploy.sh my-agent/                # Bicep deploy, ~3 min

That's everything Microsoft considers the canonical happy path. Backends are pluggable — same my-agent/ config directory deploys via:

This skill's value is what comes next — when you need a GBB-shaped recipe or plugin that upstream doesn't ship.

3. GBB pre-flight runbook (the gotchas Learn docs assume away)

Run this BEFORE the customer Tuesday meeting:

bash scripts/preflight.sh <subscription-id>

Verifies (in order — first failure stops):

1. Microsoft.App resource provider is registered in the target sub. Fresh subs return DeploymentNotFound on az deployment group create if you skip this. Fix: az provider register --namespace Microsoft.App
2. You have Microsoft.Authorization/roleAssignments/write at the target scope. SRE Agent provisioning assigns RBAC to its UAMI; without this perm the wizard fails opaquely with "Failed to create resource."
3. You're in a supported region. Only Sweden Central, East US 2, UK South, Australia East for the public preview. Request more via https://aka.ms/sreagent/region.
4. Network ACL allows *.azuresre.ai and sre.azure.com. Zscaler and corporate proxies often block the *.azuresre.ai data-plane wildcard by default. Fix: add to allow-list — the data plane MUST be reachable for chat to work.
5. (Citadel engagements only) Foundry project's UAMI has been issued a JWT scoped to the Citadel APIM /llm/* operation. SRE Agent's defaultModel.provider: MicrosoftFoundry needs this to call the gateway-routed model — symptom is HTTP 401 on the first chat turn.

Known traps

4. GBB recipes (upstream-shaped, ready to drop into sreagent-templates/recipes/)

Three recipes live under references/recipes/. Each follows the exact microsoft/sre-agent/sreagent-templates/recipes/<name>/ shape — agent.json + connectors.json + roles.yaml + expected-config.json + README.md + config/{skills,subagents,common-prompts}/ + optional automations/scheduled-tasks/. You drop the directory in, then deploy with the official bin/deploy.sh:

# from a clone of microsoft/sre-agent
cp -r /path/to/awesome-gbb/skills/azure-sre-agent/references/recipes/citadel-routed \
      sreagent-templates/recipes/citadel-routed
./bin/new-agent.sh --recipe citadel-routed --non-interactive \
  --set agentName=sre-citadel-pilot \
  --set resourceGroup=rg-sre-pilot \
  --set location=swedencentral \
  --set targetRGs=rg-pilot-prod \
  --set citadelGatewayUrl=https://apim-citadel.contoso.net \
  --set citadelProductKey=<sub-key-or-blank-for-jwt> \
  -o sre-citadel-pilot/
./bin/deploy.sh sre-citadel-pilot/

Recipes are vendored at references/recipes/<name>/. They are not copied into the upstream repo — you (or the customer) drop them in when needed. We open PRs upstream once a customer engagement validates a recipe; see § 8.

5. GBB plugins (upstream-shaped, ready to add to Azure/sre-agent-plugins)

Two plugin packs live under references/plugins/. Each follows the exact Azure/sre-agent-plugins/plugins/<name>/ shape — plugin.json + optional .mcp.json + README.md + skills/<skill_name>/SKILL.md.

Install a plugin onto an SRE Agent

Two paths, pick one:

(A) Upstream marketplace clone (recommended for production — survives plugin updates from us via the standard git pull workflow):

# fork or clone Azure/sre-agent-plugins
cp -r /path/to/awesome-gbb/skills/azure-sre-agent/references/plugins/gbb-citadel plugins/
# Register in YOUR fork's .github/plugin/marketplace.json (see upstream README)
# Then follow upstream install steps documented in the marketplace

(B) Direct data-plane push (recommended for pilot demos — single command):

python3 scripts/data_plane.py install-plugin \
  --agent /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.App/agents/<name> \
  --plugin references/plugins/gbb-citadel

This walks the plugin's skills/<skill_name>/SKILL.md, base64-encodes the content, and PUTs each into /subagents/{name}/skills/{skill}?api-version=2025-05-01-preview.

6. Cross-skill integration

6.1 Posting Threadlight incidents into a customer's SRE Agent

A Threadlight pilot can post incidents (HITL escalations, eval-fail alerts, cron-job failures) into the customer's SRE Agent via the data plane's HTTP trigger:

from skills.azure_sre_agent.scripts.data_plane import SREAgentClient

client = SREAgentClient.from_arm(agent_resource_id)
trigger = client.create_http_trigger(
    name="threadlight-incident",
    prompt="Investigate the linked Threadlight HITL escalation: {{payload}}.",
)
# trigger.webhook_url → public; no auth required. Save to KV; pass to ACA cron.

This is what enables a Threadlight pilot to degrade gracefully into existing customer ops — the moment something escalates, the customer's SRE Agent picks it up, with full agent-memory context from the pilot's SPEC and runbooks.

6.2 Routing defaultModel.provider: MicrosoftFoundry through a Citadel APIM

Set defaultModelProvider: Azure OpenAI in the recipe agent.json, then configure the Foundry connection to point at the Citadel APIM gateway, and grant the SRE Agent's UAMI the Citadel llm:read access contract (via citadel-spoke-onboarding). The citadel-routed recipe (§ 4) wires all of this.

6.3 Aligning auto-created App Insights with foundry-observability

SRE Agent auto-creates its own App Insights resource by default. If you've already established a project-wide AppIn via foundry-observability, pass --set existingAgentAppInsightsId=<arm-id> to bin/new-agent.sh so SRE Agent reuses it instead of fragmenting telemetry.

7. Cost notes

SRE Agent bills in Azure Agent Units (AAU). Two flows:

• Always-on flow — 4 AAU/hour baseline per agent, regardless of usage. ~$0.10/hr at preview pricing.
• Active flow — token-based when the agent actually processes a query. Charged against the recipe's monthlyAgentUnitLimit cap.

Set monthlyAgentUnitLimit in the recipe's agent.json to a deliberate cap — the upstream minimal recipe defaults to 10,000 AAU/month which is reasonable for a pilot. For production, model from https://aka.ms/sreagent/pricing.

Always-on flow is the biggest hidden cost surprise — leaving 4 demo agents running over a 2-week disco workshop adds up. Either:

• ./bin/deploy.sh my-agent/ --stop between sessions (sets powerState: Stopped), or
• az resource delete the whole RG when the pilot is over.

8. Upstream contribution path

When a customer engagement validates a GBB-authored recipe or plugin:

1. Fork microsoft/sre-agent (recipe) or Azure/sre-agent-plugins (plugin)
2. Copy references/recipes/<name>/ or references/plugins/<name>/ to the fork
3. Scrub any GBB-specific references (this skill keeps them generic, but double-check)
4. Add marketplace.json entry (plugins) or update the upstream README recipe table (recipes)
5. Open PR with a customer testimonial in the description (anonymized per AGENTS.md § 2.1)

License is MIT on both upstream repos — same as ours. No license conflict. Microsoft welcomes recipe / plugin contributions; the recipe request issue template at https://github.com/microsoft/sre-agent/issues/new?template=recipe_request.md is the right entry point for triage.

Cross-references

• Upstream toolchain: https://github.com/microsoft/sre-agent
• Upstream plugins: https://github.com/Azure/sre-agent-plugins
• Product home: https://www.azure.com/sreagent
• Portal: https://sre.azure.com · aka.ms/sreagent
• Docs: https://aka.ms/sreagent/newdocs
• API reference: https://learn.microsoft.com/en-us/azure/sre-agent/api-reference
• Region requests: https://aka.ms/sreagent/region
• Pricing: https://aka.ms/sreagent/pricing
• Pin file: references/upstream-pin.md