Azure SDKの「Azure SDK documentation update: Add AgentVoiceAssistant and MCPVoiceAssistant samples」は、既存アプリをすぐ壊す破壊的変更というより、Azure VoiceLive SDK for .NETのサンプル整備と参照モデル名の見直しが中心です。特に確認すべきなのは、gpt-realtime-preview を参照しているサンプルや設定、Agent V2を使う音声エージェント、MCPサーバー連携を試しているプロジェクトです。PR #58777では、gpt-realtime-preview から gpt-realtime への参照変更、Agent V2/MCPサンプルの追加、サンプル配置の整理が明記されています。(GitHub)
ただし、2026年5月5日時点のPR情報では、レビュー中の指摘も残っていました。記事公開時点で実装やサンプル構成が最終化されているとは限らないため、実務では「自分のコードに影響する設定だけ先に確認し、正式に取り込まれた差分は改めて追う」という進め方が安全です。(GitHub)
Azure SDK documentation update: Add AgentVoiceAssistant and MCPVoiceAssistant samplesで変わったこと
今回の更新は、Azure SDK for .NETのリポジトリにおけるAzure VoiceLive関連サンプルの追加・整理です。PR #58777の説明では、主な変更として次の3点が示されています。
| 変更点 | 内容 | 実務で見るべきポイント |
|---|---|---|
gpt-realtime-preview 参照の変更 | サンプル内の参照を gpt-realtime に変更 | 設定ファイル、環境変数、README、CI用サンプルに古いモデル名が残っていないか確認する |
| Agent V2サンプルの追加 | Azure AI Foundry agentとVoiceLiveを接続する AgentVoiceAssistant サンプルを追加 | Agent Serviceを使う音声アシスタントでは、Entra ID認証やプロジェクト名・エージェント名の設定を確認する |
| MCPサンプルの追加 | MCPサーバーをVoiceLiveセッションに接続する MCPVoiceAssistant サンプルを追加 | MCPサーバーURL、許可ツール、承認モード、APIバージョンを確認する |
| サンプル配置の整理 | /samples/voicelive/ 配下にスタンドアロンのサンプルとして移動・整理 | サンプルをコピーして社内テンプレート化している場合、パスや依存関係の参照方法を見直す |
PRのファイル一覧では、samples/voicelive/agent-voice-assistant、samples/voicelive/mcp-voice-assistant、既存の basic-voice-assistant、customer-service-bot などが並び、Azure VoiceLive SDK for .NETのサンプル群として整理されています。(GitHub)
影響を受けやすい人、受けにくい人
今回のAzure SDK documentation updateで優先的に確認すべきなのは、Azure VoiceLiveを使ってリアルタイム音声エージェントを開発しているチームです。Voice Live APIは、音声認識、生成AI、テキスト読み上げを統合し、低遅延の音声対音声体験を作るためのマネージドサービスとして説明されています。(Microsoft Learn)
| 対象 | 影響度 | 対応の目安 |
|---|---|---|
| Azure.AI.VoiceLiveのC#サンプルを参照している開発者 | 高 | サンプルパス、モデル名、認証方式、APIバージョンを確認 |
| Azure AI Foundry Agent Serviceで音声エージェントを作るチーム | 高 | Agent V2サンプルの設定項目を確認 |
| MCPサーバー連携をVoiceLiveで試しているチーム | 高 | MCPサーバー定義、承認モード、APIバージョンを確認 |
gpt-realtime-preview を設定ファイルに残しているプロジェクト | 中〜高 | gpt-realtime への移行可否を検証 |
| VoiceLiveを使っていないAzure SDK利用者 | 低 | 直接対応は不要。ただしAzure SDKリポジトリのサンプルを流用している場合は確認 |
| ドキュメント・社内ハンズオン資料の管理者 | 中 | 画面キャプチャ、コマンド、サンプル配置を更新 |
既存の本番アプリがVoiceLiveサンプルを直接使っていない場合、今回のPRだけで即時の障害が起きる可能性は高くありません。一方で、ハンズオン資料やPoCコードはサンプル由来の設定をそのまま使いがちです。まずはリポジトリ内で古いモデル名を検索するのが早道です。
rg "gpt-realtime-preview" .
rg "samples/voicelive|AgentVoiceAssistant|MCPVoiceAssistant" .gpt-realtime-previewからgpt-realtimeへの変更で確認すること
もっとも分かりやすい変更は、サンプル参照が gpt-realtime-preview から gpt-realtime に変わった点です。これは「すべての環境で無条件に置換すればよい」という意味ではなく、VoiceLiveのサンプルや検証コードで現在のモデル名に合わせる必要がある、という読み方が安全です。
Microsoft LearnのVoice Live API概要では、サポートされるモデル例としてGPT-RealtimeやGPT-5、GPT-4.1、Phiなどが挙げられ、価格カテゴリにも gpt-realtime と gpt-realtime-mini が掲載されています。(Microsoft Learn) また、Voice Live APIの使用方法では、WebSocketエンドポイント例の model パラメーターに gpt-realtime が使われています。(Microsoft Learn)
実務では、次の順番で確認してください。
| 確認対象 | 見る場所 | 判断基準 |
|---|---|---|
| モデル名 | appsettings.json、.env、README、CI変数 | gpt-realtime-preview が残っていれば、サンプル更新との差分を確認 |
| リージョン | Azureリソースのリージョン | 対象モデルやVoiceLive機能が利用できるか確認 |
| APIバージョン | 接続URL、SDKオプション、環境変数 | MCP連携では 2026-01-01-preview 以降が必要とされている |
| 課金・価格帯 | 選択モデル | gpt-realtime と gpt-realtime-mini ではコストや用途が異なる可能性がある |
| 音声入力・出力 | モデル、音声、文字起こし設定 | 日本語や多言語対応の品質を検証環境で確認 |
モデル名だけを置き換えても、リージョンやAPIバージョン、認証方式が合っていないと接続に失敗します。特にPoCから本番に近い検証へ進む段階では、「モデル名」「APIバージョン」「認証」「ロール」「音声デバイス」を1つのチェックリストとして扱うと、原因切り分けが楽になります。
AgentVoiceAssistantサンプルの見どころ
AgentVoiceAssistant は、Azure AI Foundry agentとVoiceLiveを接続するサンプルです。PR内のREADMEでは、事前構成されたAzure AI Foundry agentに接続し、全二重の音声会話、エージェント応答、ツール利用、セッションライフサイクル管理を示すサンプルとして説明されています。(GitHub)
このサンプルが役立つのは、音声アプリ側に毎回プロンプトやツール定義を直接書くのではなく、Azure AI Foundry上のエージェントに会話設計やツール構成を持たせたいケースです。Microsoft Learnでも、エージェントを使うと、セッションコードではなくエージェント側で管理されるプロンプトや構成を利用でき、クライアントコードを変更せずに会話フローを更新しやすいと説明されています。(Microsoft Learn)
Agent V2利用時に必ず確認したい設定
Agent Voice Assistantを試す前に、次の項目を確認してください。
| 項目 | 確認内容 | よくある失敗 |
|---|---|---|
| Foundryリソース | サポート対象リージョンにMicrosoft Foundryリソースがあるか | Speechリソースだけで進めようとしてAgent統合が使えない |
| ロール | ユーザーまたはマネージドIDに必要なロールがあるか | 権限不足でセッション開始に失敗する |
| 認証方式 | AgentモードでEntra ID認証を使っているか | APIキーでAgent呼び出しをしようとして失敗する |
| エージェント情報 | AGENT_NAME、PROJECT_NAME、必要なら AGENT_VERSION | エージェント名とプロジェクト名の取り違え |
| エンドポイント | VOICELIVE_ENDPOINT が正しいか | FoundryプロジェクトのエンドポイントとVoiceLiveエンドポイントを混同する |
| 会話継続 | CONVERSATION_ID を使うか | 検証時に前回の会話コンテキストが混ざる |
特に重要なのは認証です。Microsoft LearnのC#向けAgentクイックスタートでは、エージェント統合にはEntra ID認証が必要で、キーベース認証はAgentモードではサポートされないと説明されています。(Microsoft Learn)
MCPVoiceAssistantサンプルの見どころ
MCPVoiceAssistant は、VoiceLiveの音声会話にMCPサーバーを接続し、外部ツールやデータソースを使えるようにするサンプルです。PR内のREADMEでは、MCPサーバーの設定、ツール検出、音声会話中のツール呼び出し、複数ツールのワークフロー管理を示すサンプルとして説明されています。(GitHub)
MCP連携で重要なのは、「モデルに何を許可するか」を明確にすることです。Microsoft LearnのMCPサーバー構成リファレンスでは、server_label と server_url が必須、allowed_tools、require_approval、headers、authorization は任意の設定として整理されています。(Microsoft Learn)
MCP連携で確認すべき設定
| 設定 | 役割 | 実務上の判断基準 |
|---|---|---|
ServerLabel / server_label | MCPサーバーの表示名 | ログで識別しやすい名前にする |
ServerUrl / server_url | MCPエンドポイントURL | 社内ネットワークや認証方式から到達可能か確認 |
AllowedTools / allowed_tools | 使えるツールを制限 | 本番に近い環境では原則として明示的に絞る |
RequireApproval / require_approval | ツール実行前の承認要否 | 副作用のある操作は "always" を基本にする |
headers / authorization | MCPサーバーへの追加認証 | トークンをコードに直書きしない |
| APIバージョン | MCP対応の前提 | 2026-01-01-preview 以降が必要 |
Microsoft Learnでは、MCPのC#向け前提条件として .NET 8.0 SDK 以降、Azure.AI.VoiceLive 1.1.0-beta.3以降、APIバージョン 2026-01-01-preview が示されています。(Microsoft Learn) また、承認モードは "never" なら自動実行、"always" なら実行前にクライアント側の承認が必要とされています。(Microsoft Learn)
サンプル配置の変更で注意したいこと
今回のPRでは、サンプルがAzure SDKリポジトリの標準に合うように整理されています。レビューコメントでは、/sdk 配下のサンプルにはmarkdown-with-snippet方式が必要であり、スタンドアロンサンプルは /samples/voicelive に移動し、Azure Samples browserが扱える形にする必要があると指摘されています。(GitHub)
この指摘は、社内でサンプルをテンプレート化しているチームにも関係します。ローカルのAzure SDKリポジトリ内でだけ動く ProjectReference を残したまま配布すると、サンプル単体をダウンロードした開発者の環境ではビルドできません。実際にレビューでも、サンプルがAzure Samples browserから取得された場合、リポジトリ内の相対パスにはアクセスできないため、パッケージ参照にする必要があると指摘されています。(GitHub)
社内サンプルを整備するなら、次の方針が安全です。
| やること | 理由 |
|---|---|
| SDK開発用サンプルと利用者向けサンプルを分ける | ProjectReference と PackageReference の混在を避ける |
| 利用者向けサンプルはNuGetパッケージ参照にする | リポジトリ外でもビルドできるようにする |
READMEの前提条件を実際の .csproj と合わせる | .NETバージョン不一致による初回失敗を防ぐ |
appsettings.development.json や .env をコミットしない | APIキーやエンドポイント情報の漏えいを防ぐ |
dotnet restore と dotnet run をクリーン環境で確認する | 自分のローカルだけで動くサンプルを避ける |
移行・設定確認の進め方
今回のAzure SDK documentation updateに対応するなら、まずコードの全面改修ではなく、参照と設定の棚卸しから始めるのが現実的です。
まず検索する
rg "gpt-realtime-preview" .
rg "AgentVoiceAssistant|MCPVoiceAssistant|AgentSessionConfig|VoiceLiveMcpServerDefinition" .
rg "ProjectReference.*Azure.AI.VoiceLive" .gpt-realtime-preview が見つかった場合は、用途を確認します。VoiceLiveのサンプルや検証コードであれば、gpt-realtime への更新候補です。一方、別サービスの古い検証コードやコメントに残っているだけなら、機械的に置換せず、動作確認できる箇所から進めます。
設定を確認する
{
"VoiceLive": {
"Model": "gpt-realtime",
"ApiVersion": "2026-01-01-preview",
"Endpoint": "https://<your-resource>.services.ai.azure.com"
}
}上記は考え方を示す例です。実際のキー名はサンプルや自社アプリの構成に合わせてください。Voice Live APIのWebSocket接続では、モデルを使う場合は model パラメーター、エージェントサービスを使う場合は agent_id や project_id に相当する情報が重要になります。(Microsoft Learn)
AgentとMCPは別々に検証する
Agent V2とMCPを同時に入れると、接続失敗時の原因が分かりにくくなります。まずAgentVoiceAssistantで「エージェントに音声で接続できるか」を確認し、その後MCPVoiceAssistantで「外部ツールを安全に呼び出せるか」を確認する順番がおすすめです。
検証ログには、最低限次の情報を残します。
| ログ項目 | 目的 |
|---|---|
| 使用モデル名 | gpt-realtime などの設定ミスを発見する |
| APIバージョン | MCP対応の有無を切り分ける |
| エージェント名・プロジェクト名 | Foundry側の設定ミスを発見する |
| MCPサーバーラベル | どの外部ツールで失敗したか追跡する |
| 承認モード | 自動実行と手動承認の挙動を確認する |
| 音声入力・出力デバイス | アプリではなく端末側の問題を切り分ける |
本番適用前に避けたい失敗
AgentモードでAPIキー認証を使ってしまう
通常のVoiceLive接続ではAPIキーを使える場面がありますが、Agentモードでは別です。C#向けクイックスタートでは、Voice LiveのAgentモードでキーベース認証はサポートされず、Microsoft Entra IDを使う必要があると説明されています。(Microsoft Learn)
MCPツールを広く許可しすぎる
allowed_tools を省略すると、MCPサーバー上のすべてのツールが許可される可能性があります。読み取り専用の検索ツールなら大きな問題になりにくいものの、チケット作成、データ更新、メール送信、外部API実行のような副作用のあるツールでは危険です。まずは allowed_tools で絞り、require_approval は "always" を基本にするのが安全です。(Microsoft Learn)
サンプルの相対パスをそのまま配布する
Azure SDKリポジトリ内で動くサンプルを、社内ポータルや研修資料にそのまま置くと、ProjectReference の相対パスが壊れることがあります。スタンドアロンで動かすサンプルは、NuGetの PackageReference を使い、クリーンなフォルダーで dotnet restore から確認してください。
プレビュー機能を本番前提で扱う
Foundry Agent Serviceを使ったVoice Liveの音声エージェントは、Microsoft Learn上でパブリックプレビューとして説明され、SLAなしで提供される旨が記載されています。(Microsoft Learn) 本番導入を検討する場合は、代替フロー、障害時の手動対応、ログ保存、レート制限、コスト上限を事前に決めておくべきです。
まとめ：まずはモデル名、認証、APIバージョン、サンプル参照を確認する
今回のAzure SDK documentation update: Add AgentVoiceAssistant and MCPVoiceAssistant samplesは、Azure VoiceLive SDK for .NETを使う開発者にとって、Agent V2とMCP連携を始めやすくする更新です。一方で、gpt-realtime-preview から gpt-realtime への参照変更、AgentモードのEntra ID認証、MCPの 2026-01-01-preview 要件、スタンドアロンサンプルのパッケージ参照など、見落とすと初回実行でつまずきやすい点もあります。
次に取るべき行動はシンプルです。自分のリポジトリで gpt-realtime-preview、AgentSessionConfig、VoiceLiveMcpServerDefinition、ProjectReference を検索し、該当箇所ごとに「モデル名」「認証方式」「APIバージョン」「サンプルの依存関係」を確認してください。VoiceLiveを使っていない場合は大きな対応は不要ですが、社内ハンズオンやPoCコードでAzure SDKサンプルを流用しているなら、古い設定が残っていないかだけでも早めに点検しておくと安心です。
コメント