foundry-agent-sync

Foundry Agent Sync

概述

通过 Agent Service REST API 直接在 Azure AI Foundry 中创建并同步基于提示词的 AI Agent。此技能会在 Foundry 服务本身中注册 Agent——使其可立即通过 Foundry 门户或 API 进行调用、评估和管理。每个 Agent 都通过一次具名 POST 调用以幂等方式创建或更新，使用本地 JSON 清单文件中的定义。

关键区别： 此技能在 AI Foundry 内部（服务端）创建 Agent。它不会搭建本地 Agent 代码或容器镜像——如需该功能，请使用 microsoft-foundry 技能的 create 子技能。

先决条件

用户必须拥有：

1. 一个已部署模型的 Azure AI Foundry 项目（例如 gpt-5-4）
2. 已通过身份验证并可访问该 Foundry 项目的 Azure CLI（az）
3. 在 Foundry 项目资源上具有 Azure AI User 角色（或更高）

继续之前，请收集以下值：

值	获取方式
Foundry 项目终结点	Azure Portal → AI Foundry 项目 → 概述 → 终结点，或 az resource show
订阅 ID	az account show --query id -o tsv
模型部署名称	在 Foundry 项目中部署的模型名称（例如 gpt-5-4）

清单格式

清单是一个 JSON 数组，其中每个条目定义一个 Agent。请在常见路径中查找它：infra/foundry-agents.json、foundry-agents.json 或 .foundry/agents.json。如果都不存在，请搭建一个。

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

字段参考

字段	是否必需	描述
useCaseId	是	Kebab-case 标识符；用于构建 Agent 名称（{prefix}-{useCaseId}）
description	是	作为 Agent 元数据存储的人类可读描述
baseInstruction	是	Agent 的系统提示词 / 基础指令

同步脚本

PowerShell（交互式 / CI）

创建或定位同步脚本。规范路径为 infra/scripts/sync-foundry-agents.ps1，但请根据仓库布局进行调整。

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 部署脚本 / CI）

若要通过 Microsoft.Resources/deploymentScripts 进行自动部署，请使用满足以下条件的 bash 脚本：

1. 使用托管标识进行身份验证：az login --identity --username "$CLIENT_ID"
2. 获取 Foundry 令牌：az account get-access-token --resource https://ai.azure.com/
3. 遍历来自 FOUNDRY_AGENT_DEFINITIONS 环境变量（JSON 字符串）的定义
4. 将每个 Agent POST 到 {endpoint}/agents/{name}?api-version=2025-11-15-preview

Bicep 集成（可选）

要在基础设施部署期间自动运行同步：

1. 在编译时加载清单：

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

2. 创建一个用户分配的托管标识，并在 Foundry 项目上为其授予 Azure AI User 角色。

3. 创建一个 Microsoft.Resources.deploymentScripts 资源（类型为 AzureCLI），该资源：

   • 使用该托管标识
   • 通过 loadTextContent 加载 bash 同步脚本
   • 将项目终结点、定义和模型作为环境变量传入

将其置于 deployFoundryAgents 参数之后，以便团队可以选择启用/停用。

工作流

步骤 1 — 定位或搭建清单

在仓库中搜索 foundry-agents.json。如果它不存在，请询问用户需要哪些 Agent 并创建该清单。

步骤 2 — 定位或搭建同步脚本

搜索 sync-foundry-agents.ps1 或 foundry-agent-sync.sh。如果缺失，请使用上述模板创建 PowerShell 脚本，并调整：

• $AgentNamePrefix 以匹配项目名称
• $ModelName 以匹配用户部署的模型
• $ManifestPath 以匹配实际的清单位置

步骤 3 — 收集参数

向用户询问：

• Foundry 项目终结点
• 订阅 ID
• 模型部署名称（默认：gpt-5-4）
• Agent 名称前缀（默认：以 kebab-case 表示的仓库名称）

步骤 4 — 运行同步

使用收集到的参数执行 PowerShell 脚本：

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

步骤 5 — 验证

通过列出已同步的 Agent 来确认：

$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 参考

操作	方法	URL
创建/更新 Agent	POST	{projectEndpoint}/agents/{agentName}?api-version=2025-11-15-preview
列出 Agent	GET	{projectEndpoint}/agents?api-version=2025-11-15-preview
获取 Agent	GET	{projectEndpoint}/agents/{agentName}?api-version=2025-11-15-preview
删除 Agent	DELETE	{projectEndpoint}/agents/{agentName}?api-version=2025-11-15-preview

创建/更新请求体

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

故障排除

症状	原因	修复方法
401 Unauthorized	令牌过期或受众错误	重新运行 az account get-access-token --resource https://ai.azure.com/
403 Forbidden	缺少 Azure AI User 角色	在 Foundry 项目范围内分配该角色
404 Not Found	项目端点错误	确认端点包含 /api/projects/{projectName}
找不到模型	模型未在项目中部署	先在 AI Foundry 门户中部署该模型
定义为空	清单路径错误	检查 -ManifestPath 是否指向该 JSON 文件