Sincronização de Agentes Foundry

Visão Geral

Crie e sincronize agentes de IA baseados em prompts diretamente no Azure AI Foundry via API REST do Serviço de Agentes. Esta habilidade registra agentes no próprio serviço Foundry — tornando-os imediatamente disponíveis para invocação, avaliação e gerenciamento através do portal ou API do Foundry. Cada agente é criado ou atualizado de forma idempotente através de uma chamada POST nomeada, usando definições de um arquivo de manifesto JSON local.

Distinção chave: Esta habilidade cria agentes dentro do AI Foundry (lado do servidor). Ela não gera código de agente local ou imagens de contêiner — para isso, use a habilidade microsoft-foundry do create.

Pré-requisitos

O usuário deve ter:

1. Um projeto Azure AI Foundry com um modelo implantado (ex: gpt-5-4)
2. Azure CLI (az) autenticado com acesso ao projeto Foundry
3. A função Usuário Azure AI (ou superior) no recurso do projeto Foundry

Colete estes valores antes de prosseguir:

Formato do Manifesto

O manifesto é um array JSON onde cada entrada define um agente. Procure-o em caminhos comuns: infra/foundry-agents.json, foundry-agents.json, ou .foundry/agents.json. Se nenhum existir, gere um.

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

Referência de Campo

Script de Sincronização

PowerShell (interativo / CI)

Crie ou localize o script de sincronização. O caminho canônico é infra/scripts/sync-foundry-agents.ps1, mas adapte à estrutura do repositório.

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 implantação Bicep / CI)

Para implantação automatizada via Microsoft.Resources/deploymentScripts, use um script bash que:

1. Autentica com uma identidade gerenciada: az login --identity --username "$CLIENT_ID"
2. Adquire um token Foundry: az account get-access-token --resource https://ai.azure.com/
3. Itera definições da variável de ambiente FOUNDRY_AGENT_DEFINITIONS (string JSON)
4. POSTa cada agente para {endpoint}/agents/{name}?api-version=2025-11-15-preview

Integração com Bicep (opcional)

Para executar a sincronização automaticamente durante a implantação da infraestrutura:

…