Foundry Agent Sync

Foundry agent sync

Synchronize prompt-based agents from a local manifest into Azure AI Foundry by creating or updating server-side agents through named REST calls, then verify they are available in the Foundry project.

When to invoke

• "Create an agent in Foundry from this manifest."
• "Sync Foundry agents."
• "Deploy, register, or push agents to Foundry."
• "Update Foundry agent instructions."
• "Scaffold a foundry agent manifest and sync script."

Prerequisites and context

This skill creates agents inside AI Foundry server-side. It does not scaffold local agent code or container images.

Manifest contract

Look for foundry-agents.json at infra/foundry-agents.json, foundry-agents.json, or .foundry/agents.json. If none exists, ask what agents are needed and scaffold one.

[
  {
    "useCaseId": "alert-triage",
    "description": "Short description of what this agent does.",
    "baseInstruction": "You are an assistant that... <system prompt for the agent>"
  }
]

Procedure

1. Locate or scaffold the manifest.
2. Locate infra/scripts/sync-foundry-agents.ps1 or foundry-agent-sync.sh; scaffold the PowerShell script when missing and adapt $AgentNamePrefix, $ModelName, and $ManifestPath.
3. Collect Foundry project endpoint, subscription ID, model deployment name, and agent name prefix. Default model can be gpt-5-4; default prefix can be repo name in kebab-case.
4. Authenticate and sync with a token for https://ai.azure.com/.
5. Verify by listing agents from the project endpoint.

Run the PowerShell sync like this:

.\infra\scripts\sync-foundry-agents.ps1 `
  -SubscriptionId '<sub-id>' `
  -ProjectEndpoint '<endpoint>' `
  -ModelName '<model>' `
  -AgentNamePrefix '<prefix>'

Sync implementation details

For automated Bicep deployment, use loadJsonContent('foundry-agents.json'), create a User-Assigned Managed Identity with the Azure AI User role, and create a Microsoft.Resources/deploymentScripts resource of kind AzureCLI that uses loadTextContent, the managed identity, endpoint, definitions, and model environment variables. Gate the script behind deployFoundryAgents.

For bash in Microsoft.Resources/deploymentScripts, authenticate with az login --identity --username "$CLIENT_ID", acquire the token with az account get-access-token --resource https://ai.azure.com/, iterate definitions from FOUNDRY_AGENT_DEFINITIONS, and POST each agent to {endpoint}/agents/{name}?api-version=2025-11-15-preview.

REST API reference

Payload:

{
  "definition": {
    "kind": "prompt",
    "model": "<deployed-model-name>",
    "instructions": "<system prompt>"
  },
  "description": "<agent description>",
  "metadata": {
    "useCaseId": "<use-case-id>",
    "managedBy": "foundry-agent-sync"
  }
}

Troubleshooting

Script and API vocabulary

The local scaffold boundary is the microsoft-agent-framework skill's create sub-skill; this skill syncs server-side agents. Preserve sync-foundry-agents.ps1, project-endpoint, endpoint/agents, Create/Update semantics, opt in/out. gates, and application/json content type.

PowerShell implementations commonly use $ErrorActionPreference, Get-Content | ConvertFrom-Json, ConvertFrom, ConvertTo-Json, ConvertTo, Invoke-RestMethod, RestMethod, -ContentType 'application/json', and Format-Table -AutoSize.

Output template

## Foundry agent sync result

**Status:** synced | scaffolded | blocked
**Endpoint:** `<project endpoint>`
**Manifest:** `<manifest path>`

### Agents
| Agent | useCaseId | Version | Action |
| --- | --- | --- | --- |
| `<prefix>-<useCaseId>` | `<useCaseId>` | `<version or unknown>` | created | updated | verified |

### Commands
- `az account set --subscription <subscription>`
- `az account get-access-token --resource https://ai.azure.com/`
- `<sync script command>`

### Validation
- List agents: <pass/fail and evidence>

Quality gate

• Manifest exists or was scaffolded with useCaseId, description, and baseInstruction.
• Endpoint, subscription ID, model deployment name, and agent name prefix are known.
• Token audience is https://ai.azure.com/ and the token is not printed.
• Agent names are built from {prefix}-{useCaseId}.
• REST calls use api-version=2025-11-15-preview.
• Sync is idempotent create/update by named POST.
• Verification lists agents after sync or reports the blocker.