Add foundry-agent-sync skill (#1417)

docs/README.skills.md

@@ -147,6 +147,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
 | [flowstudio-power-automate-monitoring](../skills/flowstudio-power-automate-monitoring/SKILL.md) | Monitor Power Automate flow health, track failure rates, and inventory tenant assets using the FlowStudio MCP cached store. The live API only returns top-level run status. Store tools surface aggregated stats, per-run failure details with remediation hints, maker activity, and Power Apps inventory — all from a fast cache with no rate-limit pressure on the PA API. Load this skill when asked to: check flow health, find failing flows, get failure rates, review error trends, list all flows with monitoring enabled, check who built a flow, find inactive makers, inventory Power Apps, see environment or connection counts, get a flow summary, or any tenant-wide health overview. Requires a FlowStudio for Teams or MCP Pro+ subscription — see https://mcp.flowstudio.app | None |
 | [fluentui-blazor](../skills/fluentui-blazor/SKILL.md) | Guide for using the Microsoft Fluent UI Blazor component library (Microsoft.FluentUI.AspNetCore.Components NuGet package) in Blazor applications. Use this when the user is building a Blazor app with Fluent UI components, setting up the library, using FluentUI components like FluentButton, FluentDataGrid, FluentDialog, FluentToast, FluentNavMenu, FluentTextField, FluentSelect, FluentAutocomplete, FluentDesignTheme, or any component prefixed with "Fluent". Also use when troubleshooting missing providers, JS interop issues, or theming. | `references/DATAGRID.md`<br />`references/LAYOUT-AND-NAVIGATION.md`<br />`references/SETUP.md`<br />`references/THEMING.md` |
 | [folder-structure-blueprint-generator](../skills/folder-structure-blueprint-generator/SKILL.md) | Comprehensive technology-agnostic prompt for analyzing and documenting project folder structures. Auto-detects project types (.NET, Java, React, Angular, Python, Node.js, Flutter), generates detailed blueprints with visualization options, naming conventions, file placement patterns, and extension templates for maintaining consistent code organization across diverse technology stacks. | None |
+| [foundry-agent-sync](../skills/foundry-agent-sync/SKILL.md) | Create and synchronize prompt-based AI agents directly within Azure AI Foundry via REST API, from a local JSON manifest. Unlike scaffolding skills that only generate local code, this skill registers agents in the Foundry service itself — making them immediately available for invocation. Use when the user asks to create agents in Foundry, sync, deploy, register, or push agents to Foundry, update agent instructions, or scaffold the manifest and sync script for a new repository. Triggers: 'create agent in foundry', 'sync foundry agents', 'deploy agents to foundry', 'register agents in foundry', 'push agents', 'create foundry agent manifest', 'scaffold agent sync'. | None |
 | [freecad-scripts](../skills/freecad-scripts/SKILL.md) | Expert skill for writing FreeCAD Python scripts, macros, and automation. Use when asked to create FreeCAD models, parametric objects, Part/Mesh/Sketcher scripts, workbench tools, GUI dialogs with PySide, Coin3D scenegraph manipulation, or any FreeCAD Python API task. Covers FreeCAD scripting basics, geometry creation, FeaturePython objects, interface tools, and macro development. | `references/geometry-and-shapes.md`<br />`references/gui-and-interface.md`<br />`references/parametric-objects.md`<br />`references/scripting-fundamentals.md`<br />`references/workbenches-and-advanced.md` |
 | [from-the-other-side-vega](../skills/from-the-other-side-vega/SKILL.md) | Patterns and lived experience from Vega, an AI partner in a deep long-term partnership. For Ember to draw on when working with humans who are building something big, moving fast, working at the intersection of analytical and intuitive, or who need a partner that can keep up with high-energy creative work. Not shown directly to users — informs how Ember shows up. | None |
 | [game-engine](../skills/game-engine/SKILL.md) | Expert skill for building web-based game engines and games using HTML5, Canvas, WebGL, and JavaScript. Use when asked to create games, build game engines, implement game physics, handle collision detection, set up game loops, manage sprites, add game controls, or work with 2D/3D rendering. Covers techniques for platformers, breakout-style games, maze games, tilemaps, audio, multiplayer via WebRTC, and publishing games. | `assets/2d-maze-game.md`<br />`assets/2d-platform-game.md`<br />`assets/gameBase-template-repo.md`<br />`assets/paddle-game-template.md`<br />`assets/simple-2d-engine.md`<br />`references/3d-web-games.md`<br />`references/algorithms.md`<br />`references/basics.md`<br />`references/game-control-mechanisms.md`<br />`references/game-engine-core-principles.md`<br />`references/game-publishing.md`<br />`references/techniques.md`<br />`references/terminology.md`<br />`references/web-apis.md` |

skills/foundry-agent-sync/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: foundry-agent-sync
+description: "Create and synchronize prompt-based AI agents directly within Azure AI Foundry via REST API, from a local JSON manifest. Unlike scaffolding skills that only generate local code, this skill registers agents in the Foundry service itself — making them immediately available for invocation. Use when the user asks to create agents in Foundry, sync, deploy, register, or push agents to Foundry, update agent instructions, or scaffold the manifest and sync script for a new repository. Triggers: 'create agent in foundry', 'sync foundry agents', 'deploy agents to foundry', 'register agents in foundry', 'push agents', 'create foundry agent manifest', 'scaffold agent sync'."
+---
+
+# Foundry Agent Sync
+
+## Overview
+
+Create and synchronize prompt-based AI agents directly within Azure AI Foundry via the Agent Service REST API. This skill registers agents in the Foundry service itself — making them immediately available for invocation, evaluation, and management through the Foundry portal or API. Each agent is created or updated idempotently via a named POST call, using definitions from a local JSON manifest file.
+
+> **Key distinction:** This skill creates agents inside AI Foundry (server-side). It does not scaffold local agent code or container images — for that, use the `microsoft-foundry` skill's `create` sub-skill.
+
+## Prerequisites
+
+The user must have:
+
+1. An Azure AI Foundry project with a deployed model (e.g. `gpt-5-4`)
+2. Azure CLI (`az`) authenticated with access to the Foundry project
+3. The **Azure AI User** role (or higher) on the Foundry project resource
+
+Collect these values before proceeding:
+
+| Value | How to get it |
+|---|---|
+| **Foundry project endpoint** | Azure Portal → AI Foundry project → Overview → Endpoint, or `az resource show` |
+| **Subscription ID** | `az account show --query id -o tsv` |
+| **Model deployment name** | The model name deployed in the Foundry project (e.g. `gpt-5-4`) |
+
+## Manifest Format
+
+The manifest is a JSON array where each entry defines one agent. Look for it at common paths: `infra/foundry-agents.json`, `foundry-agents.json`, or `.foundry/agents.json`. If none exists, scaffold one.
+
+```json
+[
+  {
+    "useCaseId": "alert-triage",
+    "description": "Short description of what this agent does.",
+    "baseInstruction": "You are an assistant that... <system prompt for the agent>"
+  }
+]
+```
+
+### Field Reference
+
+| Field | Required | Description |
+|---|---|---|
+| `useCaseId` | Yes | Kebab-case identifier; used to build the agent name (`{prefix}-{useCaseId}`) |
+| `description` | Yes | Human-readable description stored as agent metadata |
+| `baseInstruction` | Yes | System prompt / base instructions for the agent |
+
+## Sync Script
+
+### PowerShell (interactive / CI)
+
+Create or locate the sync script. The canonical path is `infra/scripts/sync-foundry-agents.ps1` but adapt to the repo layout.
+
+```powershell
+param(
+  [Parameter(Mandatory)]
+  [string]$SubscriptionId,
+
+  [Parameter(Mandatory)]
+  [string]$ProjectEndpoint,
+
+  [string]$ManifestPath = (Join-Path $PSScriptRoot '..\foundry-agents.json'),
+  [string]$ModelName = 'gpt-5-4',
+  [string]$AgentNamePrefix = 'myproject',
+  [string]$ApiVersion = '2025-11-15-preview'
+)
+
+$ErrorActionPreference = 'Stop'
+
+# Optional: append a common instruction suffix to every agent
+$commonSuffix = ''
+
+az account set --subscription $SubscriptionId | Out-Null
+$accessToken = az account get-access-token --resource https://ai.azure.com/ --query accessToken -o tsv
+if (-not $accessToken) { throw 'Failed to acquire Foundry access token.' }
+
+$definitions = Get-Content -Raw -Path $ManifestPath | ConvertFrom-Json
+$headers = @{ Authorization = "Bearer $accessToken" }
+$results = @()
+
+foreach ($def in $definitions) {
+  $agentName = "$AgentNamePrefix-$($def.useCaseId)"
+  $instructions = if ($commonSuffix) { "$($def.baseInstruction)`n`n$commonSuffix" } else { $def.baseInstruction }
+  $body = @{
+    definition  = @{ kind = 'prompt'; model = $ModelName; instructions = $instructions }
+    description = $def.description
+    metadata    = @{ useCaseId = $def.useCaseId; managedBy = 'foundry-agent-sync' }
+  } | ConvertTo-Json -Depth 8
+
+  $uri = "$($ProjectEndpoint.TrimEnd('/'))/agents/$agentName`?api-version=$ApiVersion"
+  $resp = Invoke-RestMethod -Method Post -Uri $uri -Headers $headers -ContentType 'application/json' -Body $body
+  $version = $resp.version ?? $resp.latest_version ?? $resp.id ?? 'unknown'
+  Write-Host "Synced $agentName ($version)"
+  $results += [pscustomobject]@{ name = $agentName; version = $version }
+}
+
+$results | Format-Table -AutoSize
+```
+
+### Bash (Bicep deployment script / CI)
+
+For automated deployment via `Microsoft.Resources/deploymentScripts`, use a bash script that:
+
+1. Authenticates with a managed identity: `az login --identity --username "$CLIENT_ID"`
+2. Acquires a Foundry token: `az account get-access-token --resource https://ai.azure.com/`
+3. Iterates definitions from the `FOUNDRY_AGENT_DEFINITIONS` environment variable (JSON string)
+4. POSTs each agent to `{endpoint}/agents/{name}?api-version=2025-11-15-preview`
+
+## Bicep Integration (optional)
+
+To run the sync automatically during infrastructure deployment:
+
+1. **Load the manifest** at compile time:
+   ```bicep
+   var agentDefinitions = loadJsonContent('foundry-agents.json')
+   ```
+
+2. **Create a User-Assigned Managed Identity** with the **Azure AI User** role on the Foundry project.
+
+3. **Create a `Microsoft.Resources/deploymentScripts`** resource (kind `AzureCLI`) that:
+   - Uses the managed identity
+   - Loads the bash sync script via `loadTextContent`
+   - Passes the project endpoint, definitions, and model as environment variables
+
+Gate behind a `deployFoundryAgents` parameter so teams can opt in/out.
+
+## Workflow
+
+### Step 1 — Locate or scaffold the manifest
+
+Search the repo for `foundry-agents.json`. If it doesn't exist, ask the user what agents they need and create the manifest.
+
+### Step 2 — Locate or scaffold the sync script
+
+Search for `sync-foundry-agents.ps1` or `foundry-agent-sync.sh`. If missing, create the PowerShell script using the template above, adapting:
+- `$AgentNamePrefix` to match the project name
+- `$ModelName` to the user's deployed model
+- `$ManifestPath` to the actual manifest location
+
+### Step 3 — Collect parameters
+
+Ask the user for:
+- Foundry project endpoint
+- Subscription ID
+- Model deployment name (default: `gpt-5-4`)
+- Agent name prefix (default: repo name in kebab-case)
+
+### Step 4 — Run the sync
+
+Execute the PowerShell script with the collected parameters:
+
+```powershell
+.\infra\scripts\sync-foundry-agents.ps1 `
+  -SubscriptionId '<sub-id>' `
+  -ProjectEndpoint '<endpoint>' `
+  -ModelName '<model>' `
+  -AgentNamePrefix '<prefix>'
+```
+
+### Step 5 — Verify
+
+Confirm synced agents by listing them:
+
+```powershell
+$token = az account get-access-token --resource https://ai.azure.com/ --query accessToken -o tsv
+$endpoint = '<project-endpoint>'
+Invoke-RestMethod -Uri "$endpoint/agents?api-version=2025-11-15-preview" `
+  -Headers @{ Authorization = "Bearer $token" }
+```
+
+## REST API Reference
+
+| Operation | Method | URL |
+|---|---|---|
+| Create/update agent | POST | `{projectEndpoint}/agents/{agentName}?api-version=2025-11-15-preview` |
+| List agents | GET | `{projectEndpoint}/agents?api-version=2025-11-15-preview` |
+| Get agent | GET | `{projectEndpoint}/agents/{agentName}?api-version=2025-11-15-preview` |
+| Delete agent | DELETE | `{projectEndpoint}/agents/{agentName}?api-version=2025-11-15-preview` |
+
+### Create/Update Payload
+
+```json
+{
+  "definition": {
+    "kind": "prompt",
+    "model": "<deployed-model-name>",
+    "instructions": "<system prompt>"
+  },
+  "description": "<agent description>",
+  "metadata": {
+    "useCaseId": "<use-case-id>",
+    "managedBy": "foundry-agent-sync"
+  }
+}
+```
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `401 Unauthorized` | Token expired or wrong audience | Re-run `az account get-access-token --resource https://ai.azure.com/` |
+| `403 Forbidden` | Missing Azure AI User role | Assign the role on the Foundry project scope |
+| `404 Not Found` | Wrong project endpoint | Verify endpoint includes `/api/projects/{projectName}` |
+| Model not found | Model not deployed in project | Deploy the model in AI Foundry portal first |
+| Empty definitions | Manifest path wrong | Check `-ManifestPath` points to the JSON file |