2026年5月5日前後の Microsoft Copilot documentation update で最も重要なのは、foundry-agent invoke skill が Invocations Protocolを「固定スキーマのチャットAPI」ではなく、コンテナ開発者が入出力を定義するパススルー方式として明確化したことです。既存の Responses Protocol を使うチャット型エージェントには大きな変更はありませんが、Microsoft Foundry の Hosted Agents を invocations で呼び出している開発者は、リクエスト本文、セッションID、会話履歴の扱いを見直す必要があります。GitHubの該当PRでは、invocations は bytes in / bytes out で、プラットフォーム側が入力や出力を変換しないこと、OpenAPI仕様の確認を優先すること、conversationId や stream が invocations には適用されないことが整理されています。(GitHub)
Microsoft Copilot documentation updateで確認すべき結論
今回の更新は、Microsoft CopilotやGitHub Copilot for Azureを使って Microsoft Foundry のエージェント操作を行う際の「案内ドキュメントの明確化」と捉えるのが適切です。少なくとも提示ソース上では、ランタイムそのものが急に別仕様へ変わったというより、これまで曖昧だった foundry-agent invoke skill の説明を、実際の Invocations Protocol の考え方に合わせて修正した内容です。(GitHub)
特に確認すべきポイントは次の4つです。
| 確認項目 | 今回のポイント | 実務での対応 |
|---|---|---|
| 入力形式 | invocations はプラットフォーム固定のJSONスキーマではない | コンテナ側のOpenAPI仕様や実装を確認する |
| 出力形式 | レスポンス形状もコンテナ実装が決める | JSON、SSE、NDJSONなどをクライアント側で正しく処理する |
| 会話履歴 | conversationId は invocations の会話継続には使えない | 必要なら自前で状態管理するか Responses Protocol を使う |
| セッション | セッションIDはサンドボックス再利用のためのもの | agent_session_id の渡し方をプロトコル別に確認する |
対象範囲は「Copilot一般利用者」ではなくFoundry Hosted Agentsの開発・運用者
この更新は、Microsoft 365 Copilotで文書作成やチャットをしている一般ユーザー向けの変更ではありません。影響を受けるのは、Copilotの支援を受けながら Microsoft Foundry / Azure AI Foundry の Hosted Agents を作成、デプロイ、呼び出ししている開発者や運用担当者です。
| 対象者 | 対応の必要性 | 理由 |
|---|---|---|
Hosted Agentsを invocations で公開している開発者 | 高い | リクエスト本文とレスポンス仕様を自分たちで定義・検証する必要がある |
| Copilotにエージェント呼び出し手順を生成させているチーム | 高い | Copilotが推測したpayloadをそのまま使うとスキーマ不一致になりやすい |
responses のみを使うチャット型エージェント運用者 | 低〜中 | 基本方針は変わらないが、セッションと会話履歴の違いは確認すべき |
| Microsoft 365 Copilotの通常利用者 | 低い | 今回の主対象はFoundry Hosted Agentsの呼び出しドキュメント |
Microsoft Learnでも、Hosted Agentsはコンテナ化されたアプリケーションをMicrosoft管理インフラにデプロイする仕組みであり、Responses ProtocolとInvocations Protocolのどちらか、または両方を通じて公開できると説明されています。Responsesは多くのエージェントの出発点として推奨され、Invocationsはカスタムpayloadや非会話型処理、OpenAI互換ではないストリーミングが必要な場合に使う位置づけです。(Microsoft Learn)
Invocations Protocolは「AIチャット用の標準入力」ではない
invocations を使うときに最も起きやすい誤解は、「inputText や conversationId を渡せば、プラットフォームがよしなに解釈してくれる」と考えることです。
今回の Microsoft Copilot documentation update では、この誤解を避けるため、invocations は raw bytes pass-through であり、入力と出力のスキーマはコンテナ開発者が定義する、と明確にされています。PRでは、OpenAPI仕様の取得、ソースコード確認、必要に応じたユーザー確認という3段階のスキーマ発見ワークフローも追加されています。(GitHub)
Responses Protocolとの違い
| 観点 | Responses Protocol | Invocations Protocol |
|---|---|---|
| 主な用途 | チャット、Q&A、会話型エージェント | Webhook、分類、抽出、独自UI、外部システム連携 |
| 入力形式 | OpenAI互換の /responses 契約 | コンテナが定義する任意のpayload |
| 会話履歴 | プラットフォームが管理 | コンテナ側またはアプリ側で管理 |
| ストリーミング | プラットフォーム管理のイベント | コンテナがSSEなどを自前で返す |
| クライアント実装 | OpenAI互換SDKを使いやすい | HTTPクライアント側で契約を合わせる必要がある |
| 向いているケース | 一般的なAIアシスタント | 独自プロトコル、非チャット処理、外部サービスのpayload受信 |
Microsoft LearnのHosted Agents概要でも、Responsesは会話履歴やストリーミングライフサイクルをプラットフォームが管理する一方、Invocationsは任意のJSON、カスタムpayload、raw SSE制御などに向くと整理されています。(Microsoft Learn)
まず確認すべき変更点
invocations のpayloadを推測してはいけない
更新後の考え方では、invocations のリクエスト本文は「この形で送ればよい」と決め打ちできません。たとえば、あるエージェントは次のようなbodyを期待するかもしれません。
{
"message": "Hello"
}別のエージェントでは、次のような構造かもしれません。
{
"task": "classify",
"text": "この問い合わせを分類してください",
"labels": ["billing", "technical", "sales"]
}どちらが正しいかは、プラットフォームではなくコンテナの実装が決めます。したがって、Copilotが生成したサンプルpayloadをそのまま採用するのではなく、まずOpenAPI仕様やソースコードで確認する必要があります。
今回のPRでは、期待される入力形式を知るための優先手段としてOpenAPI spec discoveryが追加され、GET .../invocations/docs/openapi.json エンドポイントも文書化されています。(GitHub)
conversationId と stream をInvocationsに流用しない
Responses Protocolで使う会話継続やストリーミングの考え方を、そのままInvocationsに持ち込むと失敗しやすくなります。
悪い例は次のようなリクエストです。
{
"inputText": "続きの説明をしてください",
"conversationId": "abc123",
"stream": true
}この形が必ず間違いというより、コンテナ側がこのスキーマを明示的に受け付ける実装でない限り、Invocations Protocolとしては期待できないという点が重要です。PRでは、conversationId と stream は invocations には適用されないことが明確化されています。(GitHub)
セッションIDは本文ではなくプロトコルに合った場所へ渡す
Microsoft Learnのセッション管理ドキュメントでは、ResponsesとInvocationsで agent_session_id の渡し方が異なると説明されています。Responsesではリクエストbodyのフィールドとして渡せますが、Invocationsではクエリ文字列 ?agent_session_id=<id> として渡す必要があります。body内の agent_session_id や session_id、x-agent-session-id のようなヘッダーはコンテナへそのまま転送されるだけで、プラットフォームのサンドボックスルーティングには使われません。(Microsoft Learn)
Invocationsで同じサンドボックスを再利用したい場合の考え方は、次のようになります。
az rest --method POST \
--url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/protocols/invocations?api-version=v1&agent_session_id=${SESSION_ID}" \
--resource "https://ai.azure.com" \
--headers "Foundry-Features=HostedAgents=V1Preview" \
--body '{"message":"Continue"}'ここで注意すべきなのは、{"message":"Continue"} の部分はあくまで例だという点です。実際には、対象エージェントのOpenAPI仕様やコンテナ実装に合わせてbodyを作ります。
移行・設定確認のチェックリスト
今回の更新で、すべてのエージェントを移行し直す必要があるとは限りません。ただし、invocations を使っている環境では、呼び出し契約の確認を必ず行うべきです。
| 手順 | 確認内容 | 判断基準 |
|---|---|---|
| 1 | 対象エージェントが使うプロトコルを確認する | responses のみか、invocations を含むか |
| 2 | InvocationsのOpenAPI仕様を取得する | 期待されるbody、content-type、レスポンス形式が分かるか |
| 3 | クライアントコードのpayloadを見直す | Copilot生成の推測payloadになっていないか |
| 4 | セッションIDの渡し方を確認する | Invocationsではクエリ文字列に入っているか |
| 5 | 会話履歴の保存場所を確認する | プラットフォーム任せにしていないか |
| 6 | エラー処理を追加する | schema mismatch、認証、RBAC、タイムアウトを分けて扱えるか |
| 7 | テストを更新する | 正常系だけでなく、不正payloadのテストがあるか |
特に重要なのは、responses と invocations を「どちらもエージェントを呼ぶAPI」として一括りにしないことです。Responsesは会話型AIの標準的な流れに向き、Invocationsは外部システムや独自アプリが持つpayload契約をそのまま受けるための柔軟な入口です。
失敗しやすいポイントと対処法
スキーマ不一致を権限エラーと混同する
400 Bad Request や想定外のレスポンスが出た場合、まず確認すべきはpayloadです。Invocationsでは、プラットフォームが「このフィールド名なら意味が分かる」と補正してくれるとは考えない方が安全です。
| 症状 | よくある原因 | 対処 |
|---|---|---|
| 400系エラーになる | bodyがコンテナの期待スキーマと違う | OpenAPI仕様と実装を確認する |
| セッションが継続しない | agent_session_id をbodyやheaderに入れている | クエリ文字列で渡す |
| 会話の文脈が残らない | conversationId に期待している | Invocations側で状態管理する |
| ストリーミングされない | stream: true をbodyに入れているだけ | コンテナ側でSSEなどを実装する |
| 403や認証失敗 | トークン、ヘッダー、RBACの問題 | --resource、プレビュー用ヘッダー、権限を確認する |
Microsoft Learnでは、Foundry Agent Serviceのdata-planeエンドポイントを az rest で呼ぶ際に --resource が必要であること、セッション操作はプレビュー機能として Foundry-Features: HostedAgents=V1Preview ヘッダーを含めることが示されています。(Microsoft Learn)
セッションと会話履歴を同じものとして扱う
セッションは、同じサンドボックスや永続化された $HOME、アップロード済みファイルを使うための概念です。一方、会話履歴は「前の発話や応答をどのように次の応答へつなぐか」という概念です。
Responsesでは、previous_response_id や conversation を使って会話を継続できます。Invocationsでは、プラットフォームが会話履歴を保存しないため、コンテナ側で状態を管理する必要があります。Microsoft Learnでも、Invocations Protocolではコンテナが必要な状態を管理し、セッションはファイルや $HOME の永続化、セッション単位の状態参照に役立つと説明されています。(Microsoft Learn)
Responsesを使うべきか、Invocationsを使うべきか
迷った場合は、まずResponsesを検討するのが実務上は安全です。Microsoft Learnでも、どちらか迷う場合はResponsesから始め、必要に応じてInvocationsを追加できると案内されています。(Microsoft Learn)
| やりたいこと | 推奨プロトコル | 理由 |
|---|---|---|
| 社内チャットボットを作る | Responses | 会話履歴やストリーミングを扱いやすい |
| RAGを使ったQ&Aを作る | Responses | 会話継続とツール結果の管理に向く |
| GitHub、Stripe、JiraなどのWebhookを受ける | Invocations | 外部サービスのpayload形式を変えにくい |
| テキスト分類やデータ抽出をAPI化する | Invocations | チャットではなく構造化入力に向く |
| 独自UI用のSSEを返す | Invocations | レスポンス形式を自分で制御できる |
| Microsoft 365やTeams連携を想定する | Responses中心 | チャネル連携では会話管理の整合性が重要 |
独自性を出すなら、選定基準を「AIエージェントの種類」ではなく 呼び出し契約を誰が管理するか で考えると判断しやすくなります。プラットフォームに会話管理を任せたいならResponses、自社アプリや外部サービスの契約を優先したいならInvocationsです。
現場で今日やるべきこと
この Microsoft Copilot documentation update を受けて、開発チームが最初に行うべきことは、既存エージェントの棚卸しです。
まず、invocations を使っているHosted Agentを洗い出します。次に、それぞれのOpenAPI仕様またはコンテナ実装を確認し、実際に受け付けるbodyと返すレスポンスをドキュメント化します。最後に、Copilotが生成した呼び出しサンプルやテストコードが、conversationId、stream、session_id を誤った場所に入れていないかを確認します。
チーム内の運用ルールとしては、次の3点を明文化しておくと再発防止に役立ちます。
- Invocationsのbodyは推測せず、OpenAPI仕様またはソースコードで確認する
- セッション継続が必要な場合は、Invocationsでは
agent_session_idをクエリ文字列で渡す - 会話履歴をプラットフォームに任せたいエージェントは、原則としてResponsesを使う
今回の更新は一見すると小さなドキュメント修正ですが、実務上は「Copilotが生成した手順をそのまま信じる」のではなく、「プロトコルごとの責任分界点を確認する」ための重要な合図です。Invocations Protocolを使う環境では、payload、セッション、状態管理、エラー処理を見直し、テストで確認してから本番運用に反映しましょう。
コメント