foundry-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:

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.

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

Field Reference

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.

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:

   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:

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

Step 5 — Verify

Confirm synced agents by listing them:

$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

Create/Update Payload

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

Troubleshooting