Azure SDK documentation update: Code generation from typespec commit f6fde1c197adでまず確認すべき点は、Azure.AI.Projects.AgentsのAgentEndpointがAgentEndpointConfigへ名称変更されたことです。Hosted AgentやAgent endpointをC# SDKで作成・更新しているコードでは、単なるドキュメント更新として流さず、型名、CreateAgentVersion周辺の呼び出し、サンプルコード、CIのビルド結果を確認してください。
今回の更新は、Azure SDK for .NETリポジトリのPR #58927「Code generation from typespec commit f6fde1c197ad」によるものです。PRはAzure/azure-sdk-for-netのmainへマージされ、TypeSpecの参照コミットをf6fde1c197adf274a4b344ea27ec26490841ab68に更新し、API view、サンプル、Changelogなどを反映しています。GitHub上では2026年5月1日にマージされており、日本時間では2026年5月2日頃に確認対象となる更新です。(GitHub)
Azure SDK documentation updateでまず確認すべき変更点
今回の変更は、Azure SDK全体を使っている全員に大きな修正を迫るものではありません。影響が大きいのは、Azure AI FoundryのAgent関連、特にHosted AgentやAgent endpointを.NETのAzure SDKで扱っている開発者です。
| 確認項目 | 変更内容 | 対応の優先度 |
|---|---|---|
AgentEndpointの型名 | AgentEndpointConfigへ名称変更 | 高 |
PatchAgentOptions.AgentEndpointを使うコード | 代入するオブジェクトの型を確認 | 高 |
CreateAgentVersion / CreateAgentVersionAsync | メソッド自体ではなく、引数の渡し方を確認 | 中〜高 |
Azure.AI.Projects / Azure.AI.Projects.Agents / Azure.AI.Extensions.OpenAI | TypeSpec参照コミットが更新 | 中 |
| サンプル・テストコード | AgentEndpointConfigを使う形に更新 | 中 |
| 本番環境の設定 | endpoint、認証、RBAC、protocol、version selectorを確認 | 中〜高 |
PRの説明では、Breaking ChangeとしてAgentEndpointからAgentEndpointConfigへのリネームが明記されています。さらに、Azure.AI.Projects、Azure.AI.Projects.Agents、Azure.AI.Extensions.OpenAIのTypeSpec参照コミットが更新対象に含まれています。(GitHub)
今回の更新は「パッケージリリース」ではなく「mainへのコード生成反映」として見る
実務で最初に切り分けるべきなのは、「NuGetで今すぐ自分の環境に入る変更なのか」「リポジトリ上の次期反映なのか」です。
Azure.AI.Projects.AgentsのChangelogでは、2.1.0-beta.2がUnreleasedとして記載され、そのBreaking ChangesにAgentEndpointからAgentEndpointConfigへのリネームが入っています。つまり、少なくとも確認時点では「main上に反映された次期更新」として扱い、手元のSDKバージョン、参照しているプレビュー版、CIで取得しているパッケージの条件を分けて確認するのが安全です。(GitHub)
特に--prereleaseや浮動バージョンを使っているプロジェクトでは、ある日ビルド環境だけが新しいAPI surfaceを拾うことがあります。開発端末では通るのにCIで落ちる、またはその逆になる典型的なパターンです。
影響を受ける可能性が高い人
次のいずれかに当てはまる場合は、今回のAzure SDK documentation updateを確認すべきです。
| 対象 | 確認理由 |
|---|---|
C#でAzure.AI.Projects.Agentsを使っている | Breaking Changeがこのパッケージに集中している |
| Hosted Agentを作成・更新している | サンプルがAgentEndpointConfigを使う形へ更新されている |
PatchAgentObject / PatchAgentObjectAsyncでendpoint設定を更新している | AgentEndpoint設定オブジェクトの型名変更に当たりやすい |
CreateAgentVersion / CreateAgentVersionAsyncを使っている | 直接ProjectsAgentDefinitionを渡していたコードは修正が必要になる可能性がある |
| SDKのAPI view差分を追っているライブラリ管理者 | API surfaceの変更として検知される |
| Azure AI Foundryのプレビュー機能を検証している | Hosted Agent周辺はプレビュー更新の影響を受けやすい |
一方、Azure.AI.Projectsでデータセット、接続、モデル一覧などだけを扱っており、Agent endpointを作成・更新していない場合は、直接の修正は少ない可能性があります。ただし、同じソリューション内でAgent管理コードが混在している場合は、検索して確認してください。
AgentEndpointはAgentEndpointConfigへ置き換える
最も分かりやすい変更は型名です。更新前のAPI viewではAgentEndpointクラスが存在していましたが、更新後のAPI viewではAgentEndpointConfigクラスが確認できます。(GitHub)
変更前のイメージ
AgentEndpoint config = new()
{
VersionSelector = new([
new FixedRatioVersionSelectionRule(
agentVersion: agentVersion.Version,
trafficPercentage: 100)
]),
Protocols = { AgentEndpointProtocol.Responses }
};
PatchAgentOptions patchOptions = new()
{
AgentEndpoint = config,
};変更後のイメージ
AgentEndpointConfig config = new()
{
VersionSelector = new([
new FixedRatioVersionSelectionRule(
agentVersion: agentVersion.Version,
trafficPercentage: 100)
]),
Protocols = { AgentEndpointProtocol.Responses }
};
PatchAgentOptions patchOptions = new()
{
AgentEndpoint = config,
};ポイントは、PatchAgentOptions側のプロパティ名まで機械的に変えないことです。サンプルではAgentEndpointConfig config = new()を作成し、PatchAgentOptionsのAgentEndpointへ代入しています。つまり、変更すべき中心は設定オブジェクトの型名であり、AgentEndpointProtocolのような別の型まで一括置換しないようにしてください。(GitHub)
CreateAgentVersionは「メソッドが消えた」と早合点しない
今回のPRやコミットメッセージには、CreateAgentVersion / CreateAgentVersionAsyncのconvenience overloadに関する記載があります。ただし、更新後のAPI viewを見ると、CreateAgentVersion / CreateAgentVersionAsync自体は残っています。残っている形は、主にProjectsAgentVersionCreationOptionsまたはBinaryContentを受け取るメソッドです。(GitHub)
実務上の読み方としては、「CreateAgentVersionが全面的に削除された」と考えるのではなく、「ProjectsAgentDefinitionを直接渡していた呼び出しがあるか」を確認するのが正確です。更新前のAPI viewには、ProjectsAgentDefinition definitionを直接受け取るCreateAgentVersion / CreateAgentVersionAsyncが確認できますが、更新後に同じシグネチャは見つかりません。(GitHub)
直接definitionを渡していた場合の修正方針
HostedAgentDefinition agentDefinition = GetAgentDefinition(dockerImage);
ProjectsAgentVersionCreationOptions creationOptions = new(agentDefinition);
creationOptions.Metadata["enableVnextExperience"] = "true";
ProjectsAgentVersion agentVersion =
await projectClient.AgentAdministrationClient.CreateAgentVersionAsync(
agentName: "myHostedAgent",
options: creationOptions);更新後のサンプルでも、HostedAgentDefinitionをProjectsAgentVersionCreationOptionsで包み、CreateAgentVersionAsyncのoptionsへ渡す形が使われています。(GitHub)
移行時に使える確認手順
既存プロジェクトでは、まずコード検索で影響範囲を絞り込むのが早道です。Visual Studioの検索でも構いませんが、リポジトリ全体を機械的に確認するならrgやgit grepが便利です。
| 手順 | コマンド例 | 見るポイント | |
|---|---|---|---|
| 型名の利用箇所を探す | rg "\bAgentEndpoint\b" | new AgentEndpoint()が残っていないか | |
| endpoint設定の代入箇所を探す | rg "PatchAgentOptions | AgentEndpoint =" | AgentEndpointConfigを代入しているか | |
| version作成の呼び出しを探す | rg "CreateAgentVersion" | ProjectsAgentDefinitionを直接渡していないか | |
| サンプルとの差分を見る | rg "AgentEndpointConfig" | 新しい書き方にそろっているか | |
| ビルドで検出する | dotnet build | 型名変更、引数不一致、曖昧なオーバーロードを確認 |
特に注意したいのは、AgentEndpointという語が「型名」「プロパティ名」「概念名」として混在することです。単純な全置換を行うと、PatchAgentOptions.AgentEndpointやドキュメント文言まで不自然に変えてしまう可能性があります。
設定確認で見るべきポイント
コード修正だけで終わらせると、ビルドは通ってもAgent endpointの動作確認でつまずくことがあります。今回の更新は型名変更が目立ちますが、Hosted Agent周辺ではendpoint、protocol、version selector、認証、RBACも合わせて確認してください。
endpointと認証
Azure AI Projectsの.NETクライアントは、AIProjectClientを作成し、DefaultAzureCredentialなどのAzure Identity系の資格情報で認証する構成が一般的です。Microsoft LearnのAzure AI Projects client library for .NETでも、FOUNDRY_PROJECT_ENDPOINTを読み取り、AIProjectClientを作成する例が示されています。(Microsoft Learn)
確認すべき環境変数の例は次の通りです。
| 変数・設定 | 用途 | 失敗例 |
|---|---|---|
FOUNDRY_PROJECT_ENDPOINT | Azure AI Foundry Projectのエンドポイント | 古いproject endpointや別環境のendpointを参照している |
| コンテナイメージ関連の設定 | Hosted Agent作成時のイメージ指定 | dev用イメージを本番CIで使ってしまう |
| Azure認証情報 | DefaultAzureCredentialなどで利用 | ローカルでは通るがCIのManaged Identityに権限がない |
| protocol設定 | AgentEndpointProtocol.Responsesなど | endpointを作成しても想定protocolで呼び出せない |
| version selector | トラフィックを向けるversionの指定 | 新versionを作成したがtrafficが向いていない |
更新後のHosted Agentサンプルでは、FOUNDRY_PROJECT_ENDPOINTやイメージ関連の環境変数を読み込み、DefaultAzureCredentialでAIProjectClientを作成したうえで、Agent version作成、Active状態の待機、endpoint設定のpatchを行っています。(GitHub)
Hosted Agent全体の移行も同時に確認する
Hosted Agentを利用している場合、今回の型名変更だけでなく、Azure AI Foundry側の刷新されたプレビューへの移行観点も見ておくべきです。Microsoftの移行ガイドでは、Agentごとの専用Entra ID、Agentごとの専用endpoint、新しいprotocol、ライフサイクル管理APIなどが説明されています。(Microsoft Learn)
特に本番に近い環境では、次の確認を後回しにしないでください。
| 観点 | 確認内容 |
|---|---|
| RBAC | downstreamのAzureリソースに対して、Agent専用IDへ必要な権限を付与しているか |
| 呼び出し先endpoint | 共有project endpoint前提のコードが残っていないか |
| protocol version | 旧形式の"v1"と新しい"1.0.0"の扱いが混在していないか |
| 再デプロイ | 新しいversionがActiveになってからtrafficを向けているか |
| 監視 | log streamやsession単位の確認方法が現行の仕様に合っているか |
Microsoftの移行ガイドでも、RBAC更新、SDK/API/CLI呼び出しの更新、再デプロイ、Active状態の確認が移行手順として整理されています。(Microsoft Learn)
変更後に起きやすいエラーと対処
| エラー・症状 | 原因になりやすい箇所 | 対処 |
|---|---|---|
AgentEndpointが見つからない | 型名変更後のSDKを参照している | AgentEndpointConfigへ変更する |
CreateAgentVersionAsyncの引数が合わない | ProjectsAgentDefinitionを直接渡している | ProjectsAgentVersionCreationOptionsで包む |
| endpoint作成後に応答が取れない | protocolまたはversion selectorの設定不足 | ProtocolsとVersionSelectorを確認する |
| ローカルだけ成功する | Azure認証がローカルユーザー依存 | CI/CDのManaged IdentityやService Principalの権限を確認する |
| trafficが旧versionに向いたまま | patchは通ったがselectorが意図通りでない | trafficPercentageと対象versionを確認する |
| 旧サンプルのまま動かしている | サンプルコードが更新前 | 新しいAgentEndpointConfig版のサンプルに合わせる |
移行では、型名の修正だけを最短で済ませたくなります。しかしAgent endpointは「versionを作る」「Activeになるまで待つ」「endpoint設定をpatchする」「Responsesなどのprotocolで呼び出す」という流れで成立します。1ステップだけ通っても、全体の動作確認を省略すると不具合を見落とします。
実務での判断基準
今回のAzure SDK documentation updateに対して、すぐに対応すべきかどうかは次の基準で判断してください。
| 状況 | 推奨対応 |
|---|---|
すでにAzure.AI.Projects.AgentsでHosted Agentを管理している | すぐにコード検索とビルド確認を行う |
| プレビュー版SDKをCIで自動取得している | バージョン固定を検討し、更新時のビルド確認を必須にする |
| Agent endpointをpatchしている | AgentEndpointConfigへの移行を優先する |
Agent作成でProjectsAgentDefinitionを直接渡している | ProjectsAgentVersionCreationOptionsへ変更する |
| まだ検証段階で本番利用していない | 新しいサンプルに合わせて実装し直す |
| Agent以外のAzure AI Projects機能だけを使っている | 影響は限定的だが、依存パッケージ更新時のビルド確認は行う |
プレビュー機能を使うプロジェクトでは、「コンパイルが通るか」だけでなく、「実行時に意図したAgent versionへtrafficが向くか」「Azureリソースへのアクセス権がAgent専用IDに移っているか」まで確認すると、後の障害を減らせます。
最後に確認するチェックリスト
公開前、またはSDK更新前に次の項目を確認してください。
| チェック | 完了 |
|---|---|
new AgentEndpoint()が残っていない | |
AgentEndpointConfigへ移行した | |
AgentEndpointProtocolなど、変更不要な型を誤って置換していない | |
CreateAgentVersion / CreateAgentVersionAsyncの引数を確認した | |
ProjectsAgentDefinition直接渡しをProjectsAgentVersionCreationOptionsへ直した | |
dotnet buildをCIとローカルの両方で確認した | |
Hosted AgentのversionがActiveになるまで待機している | |
| endpointのprotocolとversion selectorを確認した | |
| Azure認証とRBACを確認した | |
| 旧サンプルや社内テンプレートを更新した |
今回の変更で最優先に見るべきなのは、AgentEndpointからAgentEndpointConfigへのリネームです。次に、CreateAgentVersion周辺で古い引数の渡し方が残っていないかを確認します。最後に、Hosted Agent全体のendpoint、protocol、version selector、RBACを動作確認すれば、単なるビルド修正で終わらず、実運用で安全に移行できます。
コメント