foundry-agent-sync

Foundry エージェントの同期

概要

Agent Service REST API を介して、Azure AI Foundry 内でプロンプトベースの AI エージェントを直接作成し、同期します。このスキルは Foundry サービス自体にエージェントを登録するため、Foundry ポータルまたは API を通じて、すぐに呼び出し、評価、管理できるようになります。各エージェントは、ローカルの JSON マニフェストファイルの定義を使用し、名前付きの POST 呼び出しによって冪等に作成または更新されます。

重要な違い： このスキルは AI Foundry 内（サーバー側）にエージェントを作成します。ローカルのエージェントコードやコンテナーイメージはスキャフォールドしません。その場合は、microsoft-foundry スキルの create サブスキルを使用してください。

前提条件

ユーザーには次のものが必要です。

1. デプロイ済みモデル（例：gpt-5-4）がある Azure AI Foundry プロジェクト
2. Foundry プロジェクトへのアクセス権で認証された Azure CLI（az）
3. Foundry プロジェクトのリソースに対する Azure AI User ロール（またはそれ以上）

続行する前に、次の値を収集してください。

値	取得方法
Foundry プロジェクトのエンドポイント	Azure Portal → AI Foundry プロジェクト → Overview → Endpoint、または az resource show
サブスクリプション ID	az account show --query id -o tsv
モデルのデプロイ名	Foundry プロジェクトにデプロイされたモデル名（例：gpt-5-4）

マニフェスト形式

マニフェストは、各エントリが 1 つのエージェントを定義する JSON 配列です。一般的なパスとして、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	はい	ケバブケースの識別子です。エージェント名（{prefix}-{useCaseId}）の生成に使用します
description	はい	エージェントのメタデータとして保存される、人が読める説明です
baseInstruction	はい	エージェントのシステムプロンプト／基本指示です

同期スクリプト

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. マネージド ID で認証します：az login --identity --username "$CLIENT_ID"
2. Foundry トークンを取得します：az account get-access-token --resource https://ai.azure.com/
3. FOUNDRY_AGENT_DEFINITIONS 環境変数（JSON 文字列）から定義を順に処理します
4. 各エージェントを {endpoint}/agents/{name}?api-version=2025-11-15-preview に POST します

Bicep との統合（任意）

インフラストラクチャのデプロイ時に同期を自動実行するには、次の手順に従います。

1. コンパイル時にマニフェストを読み込みます：

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

2. Foundry プロジェクトに Azure AI User ロールを付与した ユーザー割り当てマネージド ID を作成します。

3. Microsoft.Resources/deploymentScripts リソース（kind AzureCLI）を作成します。このリソースは次の処理を行います。

   • マネージド ID を使用します
   • loadTextContent を介して bash 同期スクリプトを読み込みます
   • プロジェクトのエンドポイント、定義、モデルを環境変数として渡します

チームがオプトイン／オプトアウトできるよう、deployFoundryAgents パラメーターで制御してください。

ワークフロー

ステップ 1 — マニフェストを確認またはスキャフォールドする

リポジトリ内で foundry-agents.json を検索します。存在しない場合は、必要なエージェントをユーザーに尋ね、マニフェストを作成します。

ステップ 2 — 同期スクリプトを確認またはスキャフォールドする

sync-foundry-agents.ps1 または foundry-agent-sync.sh を検索します。見つからない場合は、上記のテンプレートを使用して PowerShell スクリプトを作成し、次の値を調整します。

• $AgentNamePrefix をプロジェクト名に合わせます
• $ModelName をユーザーがデプロイしたモデルに合わせます
• $ManifestPath を実際のマニフェストの場所に合わせます

ステップ 3 — パラメーターを収集する

ユーザーに次の情報を尋ねます。

• Foundry プロジェクトのエンドポイント
• サブスクリプション ID
• モデルのデプロイ名（デフォルト：gpt-5-4）
• エージェント名のプレフィックス（デフォルト：ケバブケースにしたリポジトリ名）

ステップ 4 — 同期を実行する

収集したパラメーターを使って PowerShell スクリプトを実行します。

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

ステップ 5 — 検証する

エージェントを一覧表示して、同期されたことを確認します。

$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
エージェントの作成／更新	POST	{projectEndpoint}/agents/{agentName}?api-version=2025-11-15-preview
エージェントの一覧表示	GET	{projectEndpoint}/agents?api-version=2025-11-15-preview
エージェントの取得	GET	{projectEndpoint}/agents/{agentName}?api-version=2025-11-15-preview
エージェントの削除	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 ファイルを指していることを確認します