App ServiceのMarkdown for Agentsとは？Previewの設定手順と注意点

App ServiceのWebページをAIエージェントに読ませたいものの、Markdown専用のAPIや変換処理を追加するのは避けたい。そうした用途で評価できるのが、Azure App Serviceの「Markdown for Agents」です。機能を有効化したアプリにクライアントがMarkdownを要求すると、App ServiceがHTML応答をMarkdownへ自動変換します。アプリケーションコードの変更は不要です。

ただし、2026年9月3日時点ではPublic Previewとして案内されており、正式提供済みの機能と同じ前提で導入する段階ではありません。まずは検証環境で、設定方法、実際の変換結果、認証やキャッシュへの影響を確認することが重要です。この記事では、有効化から動作確認、無効化までの手順と、導入判断に必要な確認ポイントを整理します。

App ServiceのMarkdown for Agentsとは

Markdown for Agentsは、Webページの提供形式をAIエージェントなどのクライアント向けに整える機能です。アプリは従来どおりHTMLを生成し、その応答をApp Service側でMarkdownに変換できます。Webアプリを作り直すのではなく、既存コンテンツの受け渡し方を追加する仕組みと考えると分かりやすいでしょう。

Markdownを要求するのはクライアント側

有効化後、ページを取得するクライアントは、リクエストに次のHTTPヘッダーを付けます。(TECHCOMMUNITY.MICROSOFT.COM)

Accept: text/markdown

Acceptは、クライアントが受け取りたい形式を伝えるヘッダーです。返されたデータの形式を示すレスポンスのContent-Typeとは役割が異なります。(RFCエディタ)

ここで区別したいのは、「Webアプリのコード変更が不要」と「利用するエージェント側の対応が不要」は同じではないという点です。この機能を使う取得処理では、Markdownを要求し、返された形式を確認する必要があります。エージェントからのアクセスだからといって、Markdown応答を無条件に前提にしないでください。(TECHCOMMUNITY.MICROSOFT.COM)

HTMLの装飾を減らし、本文を扱いやすくする

公式説明では、見出し、段落、リンク、リスト、画像、強調、コードなどの一般的な要素を保持し、スクリプトやスタイルの内容を除去します。ブラウザーで表示するための情報を減らし、テキスト中心の応答にすることが目的です。(TECHCOMMUNITY.MICROSOFT.COM)

評価対象としては、FAQ、製品の利用ガイド、社内手順書など、文章を中心に情報を伝えるページから始めるとよいでしょう。たとえばFAQページなら、質問と回答の対応関係が残っているか、参照先のリンクをたどれるかを確認できます。

一方、Markdown化しただけで内容が正しく理解されたと判断するのは早計です。「形式が変わったか」と「必要な情報を正確に利用できるか」は、別々に評価します。

Public Previewの対象環境と利用条件

2026年9月3日時点で参照できる公式のプレビュー案内では、次の条件が示されています。特に、Windows App Serviceが対象で、プランはBasic以上が必要という点を先に確認してください。(TECHCOMMUNITY.MICROSOFT.COM)

項目	公式プレビュー案内の内容
対象OS	Windows App Service
App Serviceプラン	Basic以上
対象リージョン	Azureのすべてのパブリックリージョン
有効化方法	REST API、ARM／Bicep、Azure CLIのaz rest
専用の操作画面・コマンド	Azureポータルの操作画面と専用Azure CLIコマンドは今後の対応予定
Linux対応	今後の対応予定。現行のWindows向け条件とは区別して判断

LinuxのアプリやFree／Sharedプランのアプリでは、上記の対象条件を満たしません。設定だけを先に投入するのではなく、検証対象のOSとプランを確認するところから始めましょう。(TECHCOMMUNITY.MICROSOFT.COM)

また、Public Previewという名称だけで「検証環境も無料」と判断しないでください。Basicなどの専用コンピューティングプランでは、App ServiceプランのVMインスタンスに対する料金が発生します。(Microsoft Learn)

Azure CLIで有効化し、Markdown応答を確認する

以下は、既存の検証用App Serviceアプリに対して設定する手順です。コマンドはAzure Cloud ShellのBash環境を想定しています。ローカルのBash環境で実行する場合は、Azure CLIを用意し、先にaz loginでサインインしてください。az restは、サインイン済みの資格情報を使って管理APIを呼び出します。(Microsoft Learn)

対象アプリと現在の設定を確認する

最初に、サブスクリプションID、リソースグループ名、アプリ名を指定します。操作するアカウントには、対象アプリの設定を読み取り、更新できる権限が必要です。

公式の機能紹介に合わせ、管理APIのバージョンには2026-03-15を指定します。このバージョンのWeb Apps更新APIは、Microsoft.Web/sitesへのPATCH操作を受け付けます。(TECHCOMMUNITY.MICROSOFT.COM)

SUBSCRIPTION_ID="<サブスクリプションID>"
RESOURCE_GROUP="<リソースグループ名>"
APP_NAME="<検証用アプリ名>"

az account set --subscription "$SUBSCRIPTION_ID"

RESOURCE_URL="https://management.azure.com/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}/providers/Microsoft.Web/sites/${APP_NAME}?api-version=2026-03-15"

# 操作対象と現在のMarkdown設定を確認
az rest \
  --method get \
  --url "$RESOURCE_URL" \
  --query "{name:name,kind:kind,markdown:properties.aiIntegration.markdown}" \
  --output json

表示されたアプリ名が検証対象と一致することを確認します。認証エラーやリソース未検出のエラーが出た場合は、そのまま次の更新操作へ進まず、サブスクリプション、名前、権限を見直してください。

Markdown変換を有効にする

変更するのは、App Serviceリソースのproperties.aiIntegration.markdown.enabledです。アプリの環境変数に独自の設定名を追加するのではなく、このリソースプロパティを更新します。(TECHCOMMUNITY.MICROSOFT.COM)

az rest \
  --method patch \
  --url "$RESOURCE_URL" \
  --headers "Content-Type=application/json" \
  --body '{"properties":{"aiIntegration":{"markdown":{"enabled":true}}}}' \
  --output none

# 設定の反映を確認
az rest \
  --method get \
  --url "$RESOURCE_URL" \
  --query "properties.aiIntegration.markdown" \
  --output json

有効化を確認する目安は、次のようにenabledがtrueになっていることです。

{
  "enabled": true
}

ただし、設定値が有効であることと、個々のページが期待どおり変換されることは別です。続けて実際のHTMLページを取得します。

同じURLをHTMLとMarkdownで取得する

まず、App Serviceの既定ホスト名を取得し、比較対象のURLを設定します。ルートページに本文がない場合は、PAGE_URLの末尾を実際のFAQやガイドページのパスへ変更してください。

次のcurl例は、Webアプリ用の認証情報を付けていません。認証付きアプリでは、既存の認証方式に対応した資格情報と、アクセスを許可されたネットワークから確認します。Azure CLIで管理APIにサインインできても、その認証がcurlによるWebページ閲覧へ自動的に引き継がれるわけではありません。(Microsoft Learn)

APP_HOST=$(az rest \
  --method get \
  --url "$RESOURCE_URL" \
  --query "properties.defaultHostName" \
  --output tsv)

PAGE_URL="https://${APP_HOST}/"

# HTMLを要求
curl -sS --max-time 30 -i \
  -H "Accept: text/html" \
  "$PAGE_URL"

# 同じURLにMarkdownを要求
curl -sS --max-time 30 -i \
  -H "Accept: text/markdown" \
  "$PAGE_URL"

公式説明では、変換に成功した応答に次のヘッダーが含まれます。(TECHCOMMUNITY.MICROSOFT.COM)

Content-Type: text/markdown; charset=utf-8
x-markdown-source: easy-markdown

確認するのは、HTTPステータス、応答ヘッダー、実際の本文の3点です。

本文がMarkdownらしく見えるだけでは、目的のページを取得できたとは限りません。ログイン画面やエラーページではなく、要求したページの本文が返っていることまで確認しましょう。

検証後に無効化する

無効化する場合は、同じプロパティをfalseへ変更します。(TECHCOMMUNITY.MICROSOFT.COM)

az rest \
  --method patch \
  --url "$RESOURCE_URL" \
  --headers "Content-Type=application/json" \
  --body '{"properties":{"aiIntegration":{"markdown":{"enabled":false}}}}' \
  --output none

az rest \
  --method get \
  --url "$RESOURCE_URL" \
  --query "properties.aiIntegration.markdown" \
  --output json

設定の確認に加え、通常のHTMLページを取得し、既存の閲覧動作に問題がないことを確かめます。有効化だけでなく、この切り戻し手順まで検証に含めておくと、継続評価中に問題が見つかっても対応しやすくなります。

Markdown for Agentsの検証で見落としやすい注意点

Markdownを要求してもHTMLが返る場合がある

公式説明では、安全に変換できないページについて、元のHTMLが返る場合があるとされています。そのため、Accept: text/markdownを送ったという理由だけで、応答をMarkdownとして処理してはいけません。(TECHCOMMUNITY.MICROSOFT.COM)

エージェント側の取得処理では、HTTPステータスを確認したうえで、Content-Typeから形式を判定します。x-markdown-sourceは、App Serviceによる変換を確認する手掛かりとして使用します。

HTMLが返ったときは既存のHTML抽出処理へ戻すなど、代替処理を残しておく設計が適切です。また、Content-Typeにはcharset=utf-8などのパラメーターが付くため、ヘッダー全体が文字列text/markdownと完全一致することだけを条件にしないでください。(TECHCOMMUNITY.MICROSOFT.COM)

JavaScript中心の画面や複雑な表は、内容まで確認する

この機能の公開説明は、アプリのHTML応答を変換するものです。ブラウザーでJavaScriptを実行した後の画面を、そのまま再現することまで保証した説明ではありません。

そのため、JavaScriptでAPIから本文を取得するページでは、まずAccept: text/htmlで取得した応答に、必要な本文が含まれているかを調べます。含まれていない情報をMarkdown変換だけで取り出せるとは考えず、本文をHTMLに含める構成や、データAPIを直接利用する方法と比較してください。

表やコードを多く含むページでは、見た目よりも情報の対応関係を確認します。たとえば料金表なら「プラン名・金額・適用条件」が正しく結び付いているか、手順書ならコマンドの改行や記号が欠けていないかが重要です。

「Markdownが返ったから成功」ではなく、その出力だけで元のページと同じ判断ができるかを合格基準にしましょう。

Azure Front Door経由ではAcceptヘッダーとキャッシュを確認する

App Serviceへ直接アクセスすると変換されるのに、Azure Front Door経由ではHTMLのままになる場合は、配信経路の設定を切り分けます。

Azure Front Doorの公式ドキュメントでは、キャッシュが有効な場合、Acceptを含む一部のリクエストヘッダーがオリジンへ転送されないと説明されています。Markdownを要求していても、App Serviceまでその要求が届かない可能性があります。(Microsoft Learn)

検証では、アクセス制限を維持したまま、許可された経路でApp Service側の応答を確認し、その後でFront Door経由の結果と比較してください。必要に応じて、キャッシュを無効にした検証用ルートで、ヘッダー転送と応答形式を確認します。

また、一般的なHTTPの仕組みでは、リクエストヘッダーによる応答の違いをキャッシュへ伝えるためにVaryが使われます。ただし、Vary: Acceptを付ければ、どのCDNでも期待どおり動くと決め付けないでください。ヘッダーの転送と、HTML／Markdownを混同しないキャッシュ動作の両方を確認する必要があります。(RFCエディタ)

追加の認証設定が不要でも、認証そのものは必要

Markdown変換のための追加認証設定は不要ですが、アプリの既存の認証、認可、ネットワークアクセス制御は引き続き適用されます。「追加設定が不要」は「誰でも非公開ページを取得できる」という意味ではありません。 (TECHCOMMUNITY.MICROSOFT.COM)

たとえばApp Serviceの認証設定によっては、未認証のアクセスにログイン先への302リダイレクトや401応答が返ります。これらをMarkdown変換の失敗と混同せず、先に認証状態を確認してください。(Microsoft Learn)

認証付きページを評価するときは、異なる権限のテストユーザーを使い、HTMLとMarkdownで参照できる情報の範囲が意図どおりであることを確認します。検証のために本番アプリの認証やアクセス制限を外すのではなく、既存の保護を維持した状態で試すことが重要です。

導入効果はレスポンスサイズだけで判断しない

Microsoftは、63万7,000ページ超を対象とした内部テストで、変換後のMarkdown応答のサイズが中央値で97％小さくなり、変換時間の中央値は2ミリ秒だったと説明しています。ただし、結果はページとその内容によって異なります。これはトークン数や利用料金が97％減るという意味でも、ページ取得全体が2ミリ秒で終わるという意味でもありません。(TECHCOMMUNITY.MICROSOFT.COM)

実務では、次の観点で自分のアプリを評価すると、導入可否を判断しやすくなります。

評価項目	確認する内容	判断のポイント
変換の成立	Markdownで返るページと、HTMLで返るページを記録する	対象ページで安定して利用できるか
情報の保持	見出し、リンク、表の対応関係、コード、例外条件を照合する	重要な意味が欠落していないか
モデルへの入力	実際に利用するモデル向けの入力トークン数を比較する	応答サイズだけでなく、モデルへ渡す量が減ったか
回答品質	同じ質問を用意し、回答と根拠を比較する	小さくなった代わりに誤読が増えていないか
応答時間	ページ取得から利用可能なデータになるまでを測る	通信、変換、抽出を含む全体で改善したか

特に重要なのは、比較対象のそろえ方です。すでにエージェント側でHTMLから本文だけを抽出しているなら、生のHTMLとMarkdownを比較するだけでは不十分です。「現在の本文抽出結果」と「Markdown for Agentsの出力」を比較し、変更後に何が改善するのかを確かめてください。

最初は、FAQ、長文ページ、表を含むページ、JavaScript中心のページ、認証付きページなどから代表的なものを選びます。たとえば10ページ程度で変換結果と回答品質を比較し、重要情報の欠落がないことを確認してから対象を広げる進め方が現実的です。

まずは検証用アプリで有効化から切り戻しまで試す

Markdown for Agentsの導入では、最初に対象アプリのOSとプランを確認し、検証用アプリで有効化します。その後、同じURLにHTMLとMarkdownをそれぞれ要求し、ヘッダーだけでなく本文を比較してください。

エージェント側にはHTML応答への代替処理を残し、認証付きページやFront Door経由のアクセスも別途確認します。最後に無効化まで試しておけば、継続評価中の切り戻し手順も明確になります。

判断の軸は、単に「Markdownで返せたか」ではありません。既存の保護と情報の正確性を維持しながら、取得・抽出・モデル入力の処理を改善できるかを、Previewの評価結果として整理しましょう。