Foundry Agent Sync

Vue d'ensemble

Créez et synchronisez des agents IA basés sur des prompts directement dans Azure AI Foundry via l'API REST du service Agent. Cette compétence enregistre les agents dans le service Foundry lui-même — les rendant immédiatement disponibles pour l'invocation, l'évaluation et la gestion via le portail Foundry ou l'API. Chaque agent est créé ou mis à jour de manière idempotente via un appel POST nommé, en utilisant des définitions provenant d'un fichier manifeste JSON local.

Distinction clé : Cette compétence crée des agents dans AI Foundry (côté serveur). Elle ne génère pas de code agent local ni d'images de conteneur — pour cela, utilisez la sous-compétence create de la compétence microsoft-foundry.

Prérequis

L'utilisateur doit disposer de :

1. Un projet Azure AI Foundry avec un modèle déployé (par ex. gpt-5-4)
2. Azure CLI (az) authentifiée avec accès au projet Foundry
3. Le rôle Azure AI User (ou supérieur) sur la ressource du projet Foundry

Rassemblez ces valeurs avant de continuer :

Format du manifeste

Le manifeste est un tableau JSON où chaque entrée définit un agent. Cherchez-le aux chemins courants : infra/foundry-agents.json, foundry-agents.json, ou .foundry/agents.json. S'il n'existe pas, générez-en un.

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

Référence des champs

Script de synchronisation

PowerShell (interactif / CI)

Créez ou localisez le script de synchronisation. Le chemin canonique est infra/scripts/sync-foundry-agents.ps1 mais adaptez à la disposition du repo.

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 (script de déploiement Bicep / CI)

Pour un déploiement automatisé via Microsoft.Resources/deploymentScripts, utilisez un script bash qui :

1. S'authentifie avec une identité managée : az login --identity --username "$CLIENT_ID"
2. Acquiert un token Foundry : az account get-access-token --resource https://ai.azure.com/
3. Itère les définitions à partir de la variable d'environnement FOUNDRY_AGENT_DEFINITIONS (chaîne JSON)
4. Effectue un POST de chaque agent vers {endpoint}/agents/{name}?api-version=2025-11-15-preview

Intégration Bicep (optionnel)

Pour exécuter la synchronisation automatiquement lors du déploiement de l'infrastructure :

1. Chargez le manifeste au moment de la compilation :

   var agentDefinitions = loadJsonContent('foundry-agents.json')

2. Créez une identité managée affectée par l'utilisateur avec le rôle Azure AI User sur le projet Foundry.

3. Créez une ressource Microsoft.Resources/deploymentScripts (type AzureCLI) qui :

   • Utilise l'identité managée
   • Charge le script bash de synchronisation via loadTextContent
   • Transmet l'endpoint du projet, les définitions et le modèle en tant que variables d'environnement

Contrôlez l'accès via un paramètre deployFoundryAgents pour que les équipes puissent accepter ou refuser.

Flux de travail

Étape 1 — Localisez ou générez le manifeste

Recherchez foundry-agents.json dans le repo. S'il n'existe pas, demandez à l'utilisateur quels agents il a besoin et créez le manifeste.

Étape 2 — Localisez ou générez le script de synchronisation

Recherchez sync-foundry-agents.ps1 ou foundry-agent-sync.sh. S'il manque, créez le script PowerShell à l'aide du modèle ci-dessus, en adaptant :

• $AgentNamePrefix pour correspondre au nom du projet
• $ModelName au modèle déployé de l'utilisateur
• $ManifestPath à la localisation réelle du manifeste

Étape 3 — Rassemblez les paramètres

Demandez à l'utilisateur :

• Endpoint du projet Foundry
• ID de l'abonnement
• Nom du déploiement du modèle (par défaut : gpt-5-4)
• Préfixe du nom d'agent (par défaut : nom du repo en kebab-case)

Étape 4 — Exécutez la synchronisation

Exécutez le script PowerShell avec les paramètres rassemblés :

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

Étape 5 — Vérifiez

Confirmez les agents synchronisés en les listant :

$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" }

Référence de l'API REST

Charge utile de création/mise à jour

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

Dépannage