# Foundry Agent Sync > Azure AI Foundry agents via REST — create/sync prompt-based agents from local JSON manifest - Skill: `mouadja02/foundry-agent-sync` (Agent Skill) - Install (CLI): `npx skillmds@latest add mouadja02/foundry-agent-sync` - Raw SKILL.md: https://api.skillmd.com/api/skills/mouadja02/foundry-agent-sync/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: mouadja02 (https://skillmd.com/u/mouadja02) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mouadja02/foundry-agent-sync --- > **Attribution:** Sourced from [microsoft/skills](https://github.com/microsoft/skills) by [Microsoft](https://microsoft.com). # 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... " } ] ``` ### 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 '' ` -ProjectEndpoint '' ` -ModelName '' ` -AgentNamePrefix '' ``` ### 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 = '' 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": "", "instructions": "" }, "description": "", "metadata": { "useCaseId": "", "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 |