はじめに

Microsoft Foundry でエージェントを利用する際、セキュリティの観点からパブリックアクセスを無効にし、Private Endpoint 経由のアクセスに限定したいことがあります。

ところが、パブリックアクセスを無効にすると、そのままでは Teams からエージェントを呼び出せなくなります。Teams のチャネル側から Foundry の Private Endpoint には接続できないためです。安全に閉じたい一方で、利用者には Teams から手軽に使ってもらいたいという悩みが生まれます。

Application Gateway や Azure Firewall を使い、Private Endpoint へ到達する経路をインターネットに公開する方法も考えられます。ただ、エージェントを Teams で使うために中継用の構成を用意し、その公開範囲や運用まで管理するのは手間です。

そんな中、Foundry に Microsoft 365/Teams のチャネル通信向けに、Activity Protocol のパブリックエンドポイントだけを限定公開する機能が追加されました。

Step 2: Enable source IP-filtered Activity Protocol access and Bot Service authorization

Activity Protocol は、Teams などのチャネルとエージェントの間で、メッセージや会話に関するイベントをやり取りするための通信仕様です。利用者が Teams で送ったメッセージは、この仕様に沿った要求としてエージェントに届けられます。

Activity Protocol のパブリックエンドポイントだけを限定公開できれば、中継用のリソースを用意せずに、パブリックアクセスの制限と Teams での利用を両立できそうです。そこで今回は、実際にエージェントを公開し、Teams からの応答に加えて、直接 API の公開アクセスが拒否されることも確かめてみました。

今回の構成

Foundry アカウントのパブリックアクセスを無効にし、管理 API と Responses API は、既存 VNet に配置した Private Endpoint 経由で利用します。エージェントの実行環境には、専用サブネットへの VNet injection を使用しています。

一方、Teams/Microsoft 365 Copilot からの通信は、限定例外を有効にした Activity Protocol のパブリックエンドポイントで受け付けます。これにより、チャネルからの通信を許可しつつ、インターネットから管理 API や Responses API を直接呼び出す通信は拒否する構成です。限定公開であっても、認証・認可は必要です。

構成図

今回作成したエージェント

今回の検証では network-lab-agent という閉域の API と Microsoft 365/Teams のチャネルからエージェントを呼び出せるかを確認するためのシンプルなエージェントを利用します。gpt-4.1-mini のモデルデプロイを使ったプロンプト型(kind: prompt)で、外部ツールや業務データとの接続は設定していません。

指示には、次の応答ルールを設定しました。

  • network-check と聞かれたら、FOUNDRY-M365-NETWORK-OK だけを返すこと。
  • 会話継続の確認では、同じ会話で渡された無害なテスト用マーカーを覚え、尋ねられたらそのマーカーを返すこと。
  • 認証情報、個人情報、内部データを要求したり返したりしないこと。

固定の文字列が返るかを見ることで呼び出しの成否を判断し、続けてマーカーを尋ねることで同じ会話の情報を引き継げるかを確認します。

エージェントの動作確認

まずは Foundry のエージェントと閉域でやりとりしてみます。

## トークンと接続先の準備
$token = Get-AzAccessToken -ResourceUrl 'https://ai.azure.com' -ErrorAction Stop
$projectEndpoint = 'https://<foundry-account>.services.ai.azure.com/api/projects/m365-network-lab'
$agentEndpoint = "$projectEndpoint/agents/network-lab-agent/endpoint/protocols/openai"

API に送信する要求の内容として使用する config\response-request.json を作成します

{
  "input": [
    {
      "role": "user",
      "content": "network-check"
    }
  ]
}

実際に要求を送信します。

$response = Invoke-WebRequest `
    -Uri "$agentEndpoint/responses?api-version=v1" `
    -Method Post `
    -Authentication Bearer `
    -Token $token.Token `
    -ContentType 'application/json' `
    -InFile .\config\response-request.json `
    -SkipHttpErrorCheck `
    -ErrorAction Stop
Write-Output "HttpStatus=$([int]$response.StatusCode)"
$result = $response.Content | ConvertFrom-Json
$texts = @(
    $result.output |
        Where-Object type -eq 'message' |
        ForEach-Object content |
        Where-Object type -eq 'output_text' |
        ForEach-Object text
)
[pscustomobject]@{
    Status = $result.status
    OutputText = $texts -join ''
    AgentVersion = $result.agent_reference.version
} | Format-List

無事に応答が返ります。閉域からの通信が成功していることが確認できます。

HttpStatus=200

Status       : completed
OutputText   : FOUNDRY-M365-NETWORK-OK
AgentVersion : 1

マーカーを含む会話の作成

次に、無害な検証用マーカーを最初のメッセージに含めて、Conversations API で会話を作成します。

$body = '{"items":[{"type":"message","role":"user","content":[{"type":"input_text","text":"Remember this harmless test marker: LAB-CONTINUITY-20261114"}]}]}'
$response = Invoke-WebRequest `
    -Uri "$agentEndpoint/conversations?api-version=v1" `
    -Method Post `
    -Authentication Bearer `
    -Token $token.Token `
    -ContentType 'application/json' `
    -Body $body `
    -SkipHttpErrorCheck `
    -ErrorAction Stop
Write-Output "HttpStatus=$([int]$response.StatusCode)"
Write-Output $response.Content
$conversation = $response.Content | ConvertFrom-Json

実出力です。

HttpStatus=200
{
  "id": "conv_02cd6f4d3e7e2f7f008f4EDHu2yDqHBI5fW7eHbQSk8zKk1EpO",
  "object": "conversation",
  "metadata": {},
  "created_at": 1794647536
}

作成した会話の取得

返された conversation ID を使い、別の GET 要求で会話の存在を確認します。

$response = Invoke-WebRequest `
    -Uri "$agentEndpoint/conversations/$($conversation.id)?api-version=v1" `
    -Authentication Bearer `
    -Token $token.Token `
    -SkipHttpErrorCheck `
    -ErrorAction Stop
Write-Output "HttpStatus=$([int]$response.StatusCode)"
Write-Output $response.Content
$conversation = $response.Content | ConvertFrom-Json

実出力です。

HttpStatus=200
{
  "id": "conv_02cd6f4d3e7e2f7f008f4EDHu2yDqHBI5fW7eHbQSk8zKk1EpO",
  "object": "conversation",
  "metadata": {},
  "created_at": 1794647536
}

同じ会話でのマーカー確認

同じ conversation ID を指定して、先ほどのマーカーだけを返すよう Responses に要求します。この要求の input にはマーカーそのものを含めません。

$body = @{
    conversation = $conversation.id
    input = 'Return only the harmless test marker supplied earlier in this conversation.'
} | ConvertTo-Json
$response = Invoke-WebRequest `
    -Uri "$agentEndpoint/responses?api-version=v1" `
    -Method Post `
    -Authentication Bearer `
    -Token $token.Token `
    -ContentType 'application/json' `
    -Body $body `
    -SkipHttpErrorCheck `
    -ErrorAction Stop
Write-Output "HttpStatus=$([int]$response.StatusCode)"
$result = $response.Content | ConvertFrom-Json
$texts = @(
    $result.output |
        Where-Object type -eq 'message' |
        ForEach-Object content |
        Where-Object type -eq 'output_text' |
        ForEach-Object text
)
[pscustomobject]@{
    Status = $result.status
    OutputText = $texts -join ''
    AgentVersion = $result.agent_reference.version
    ConversationId = $result.conversation.id
} | Format-List

実出力です。

HttpStatus=200

Status         : completed
OutputText     : LAB-CONTINUITY-20261114
AgentVersion   : 1
ConversationId : conv_02cd6f4d3e7e2f7f008f4EDHu2yDqHBI5fW7eHbQSk8zKk1EpO

作成した会話と同じ ID で、最初のメッセージに含めた LAB-CONTINUITY-20261114 が返りました。これにより、単発の応答だけでなく、同じ会話内で以前のメッセージを参照できることも確認しました。

Activity の限定公開

閉域で動作していることが確認できたので、チャットのやりとりだけを Microsoft 365 向けに限定公開する設定を行います。

まず、変更対象のエージェントを GET し、現在のプロトコル設定と認証方式を確認します。

$agentUri = "$projectEndpoint/agents/network-lab-agent"
$response = Invoke-WebRequest `
    -Uri "${agentUri}?api-version=v1" `
    -Method Get `
    -Authentication Bearer `
    -Token $token.Token `
    -ErrorAction Stop
$before = $response.Content | ConvertFrom-Json
$before.agent_endpoint | ConvertTo-Json -Depth 20

今回の変更前は、protocol_configuration に responses: {}、authorization_schemes に Entra がありました。Entra の isolation_key_source は {"kind":"Entra"} です。これらを削除せず、BotServiceTenant と enable_m365_public_endpoint を追加します。

Microsoft 365/Teams 経由でエージェントを利用する際の認証・認可方式には、次の二つがあります。

BotServiceRbac は、対象の Foundry プロジェクトと同じテナント内で、エージェントの利用に必要な Azure RBAC 権限を持つサインイン済みユーザーを許可する方式です。BotServiceTenant は、対象の Foundry プロジェクトと同じテナント内のサインイン済みユーザーを許可する方式です。利用者が Foundry プロジェクトの Azure RBAC 権限を持つ必要はありません。今回は、組織内の利用者が Foundry プロジェクトの権限を持たなくても利用できるように、BotServiceTenant を使用します。

もう一つの enable_m365_public_endpoint は「チャネル通信をネットワーク上で到達可能にする設定」です。限定例外を有効にしても匿名で利用できるわけではなく、チャネルからの要求には認証・認可が必要です。

なお、Foundry 側では送信元 IP アドレスによる制限も適用されます。限定例外を有効化したとしても、Foundry は Azure Bot Service と Microsoft 365 の送信元 IP 範囲外からの要求を拒否します。

Foundry は、送信元 IP アドレスをそのAzure Bot ServiceとMicrosoft 365ソース範囲と照合します。

4.1 受信トラフィック フローを理解する

Activity と認証方式の変更用 JSON

今回の構成に対する変更用の $body は次のとおりです。

$body = @{
    agent_endpoint = @{
        protocol_configuration = @{
            responses = @{}
            activity = @{
                enable_m365_public_endpoint = $true
            }
        }
        authorization_schemes = @(
            @{
                type = 'Entra'
                isolation_key_source = @{
                    kind = 'Entra'
                }
            }
            @{
                type = 'BotServiceTenant'
            }
        )
    }
} | ConvertTo-Json -Depth 20

それぞれの設定の意図は次のとおりです。

  • responses = @{} は、既存の Responses の設定を残すために含めています。
  • activity.enable_m365_public_endpoint = $true は、Microsoft 365/Teams 向けの Activity の限定公開を有効にする設定です。Foundry アカウント全体のパブリックアクセスを有効にする操作ではありません。
  • authorization_schemes には、既存の Entra の設定を残したうえで BotServiceTenant を追加しています。この配列は PATCH で置き換わるため、追加分だけを送ると既存の認証方式を失います。

エンドポイント設定の更新

エージェントの管理 URL に、application/merge-patch+json で PATCH します。

$response = Invoke-WebRequest `
    -Uri "${agentUri}?api-version=v1" `
    -Method Patch `
    -Authentication Bearer `
    -Token $token.Token `
    -ContentType 'application/merge-patch+json' `
    -Body $body `
    -ErrorAction Stop
Write-Output "HttpStatus=$([int]$response.StatusCode)"

更新後の設定とバージョン固定の確認

PATCH の成功だけで終わらせず、GET し直して保存された設定を確認します。

$response = Invoke-WebRequest `
    -Uri "${agentUri}?api-version=v1" `
    -Method Get `
    -Authentication Bearer `
    -Token $token.Token `
    -ErrorAction Stop
Write-Output "HttpStatus=$([int]$response.StatusCode)"
$after = $response.Content | ConvertFrom-Json
$after.agent_endpoint | ConvertTo-Json -Depth 20

実出力です。

HttpStatus=200
{
  "version_selector": {
    "version_selection_rules": [
      {
        "type": "FixedRatio",
        "agent_version": "1",
        "traffic_percentage": 100
      }
    ]
  },
  "protocols": [
    "activity",
    "responses"
  ],
  "protocol_configuration": {
    "activity": {
      "enable_m365_public_endpoint": true
    },
    "responses": {}
  },
  "authorization_schemes": [
    {
      "type": "Entra",
      "isolation_key_source": {
        "kind": "Entra"
      }
    },
    {
      "type": "BotServiceTenant"
    }
  ],
  "publish_approval_status": "not_published"
}

Activity の限定例外が有効になり、Responses と Entra の設定も残っています。この時点ではまだ公開要求前なので、公開承認状態は not_published です。

パッケージの取得と Tenant 公開

次は、Teams と Microsoft 365 Copilot で利用するアプリパッケージを取得し、テナントへの公開要求を行います。まず、アプリの表示名や開発者情報などを指定した JSON をパッケージ download API に送り、生成された ZIP の内容を確認します。この取得だけでは、テナントへの公開や Bot の登録は行われません。

要求に使用する .\config\publish-request.json には、公開するアプリの情報と公開時の動作を指定します。検証で使用した内容は次のとおりです。英語の説明文も設定ファイルの原文を掲載しています。

{
  "agentDisplayName": "Foundry Private Network Lab",
  "performBotRegistration": true,
  "publishScope": "Tenant",
  "publishAsAutopilot": false,
  "appVersion": "1.0.0",
  "shortDescription": "Private network publishing verification",
  "fullDescription": "A dedicated lab agent to verify Microsoft 365 and Teams publishing with public network access disabled.",
  "developerName": "aimless.jp",
  "developerWebsiteUrl": "https://blog.aimless.jp",
  "privacyUrl": "https://blog.aimless.jp/privacy",
  "termsOfUseUrl": "https://blog.aimless.jp/term"
}

各項目の用途は次のとおりです。

項目 用途と今回の指定
agentDisplayName 公開するアプリの表示名です。Foundry 上のエージェント名 network-lab-agent とは別に指定します。
performBotRegistration 公開要求時に Bot の登録を行う指定です。今回は true にしています。ZIP の取得だけでは登録されません。
publishScope 公開スコープです。今回は Tenant を指定し、テナントへの公開を要求します。
publishAsAutopilot 今回は false を指定しています。Autopilot としての公開は検証対象に含めていません。
appVersion 生成するアプリパッケージのバージョンです。
shortDescription / fullDescription アプリの短い説明と詳細な説明です。今回はネットワーク境界の検証用アプリであることを記載しています。
developerName 利用者に表示する開発者・提供者の名前です。
developerWebsiteUrl 開発者・提供者の Web サイトです。
privacyUrl プライバシーポリシーの URL です。
termsOfUseUrl 利用規約の URL です。

この JSON はパッケージ取得と公開要求の両方で使用します。publishScope を Tenant にするだけで承認や利用者への配布が完了するわけではなく、公開要求後には管理者による承認状態も確認します。

パッケージの取得には、次の POST 要求を使用しました。前節と同じ $agentUri と $token を使い、公開用の設定ファイルを送信します。取得した ZIP は outputs\appPackage.zip に保存します。

$response = Invoke-WebRequest `
    -Uri "${agentUri}/microsoft365/zip?api-version=v1" `
    -Method Post `
    -Authentication Bearer `
    -Token $token.Token `
    -ContentType 'application/json' `
    -InFile .\config\publish-request.json `
    -OutFile .\outputs\appPackage.zip `
    -PassThru `
    -SkipHttpErrorCheck `
    -ErrorAction Stop
Write-Output "HttpStatus=$([int]$response.StatusCode)"
Write-Output "ContentType=$($response.Headers['Content-Type'])"

-PassThru を付けることで、ファイルを保存しつつ HTTP status と Content-Type も確認できます。検証時の実出力です。

HttpStatus=200
ContentType=application/zip

続いて、パッケージ取得時と同じ JSON を Tenant publish API に送り、テナントへの公開を要求します。検証では performBotRegistration=true を指定し、公開要求とあわせて Bot の登録を行いました。別の Azure Bot リソースは作成していません。

$response = Invoke-WebRequest `
    -Uri 'https://<foundry-account>.services.ai.azure.com/api/projects/m365-network-lab/agents/network-lab-agent/microsoft365/publish?api-version=v1' `
    -Method Post `
    -Authentication Bearer `
    -Token $token.Token `
    -ContentType 'application/json' `
    -InFile .\config\publish-request.json `
    -SkipHttpErrorCheck `
    -ErrorAction Stop
Write-Output "HttpStatus=$([int]$response.StatusCode)"

これにより、M365 管理センターにエージェントが登録されます。ただし、承認待ちとなっているので、管理者で承認します。

Microsoft 365 管理センターでの承認手順(1)
Microsoft 365 管理センターでの承認手順(2)
Microsoft 365 管理センターでの承認手順(3)
Microsoft 365 管理センターでの承認手順(4)

公開要求後のパブリックアクセス設定と直接 API

限定例外を有効にした後も、Foundry アカウントのパブリックアクセスは無効のままです。

$account = Get-AzCognitiveServicesAccount `
    -ResourceGroupName rg-foundry-m365-lab `
    -Name '<foundry-account>' `
    -ErrorAction Stop
[pscustomobject]@{
    ProvisioningState = $account.ProvisioningState
    PublicNetworkAccess = $account.PublicNetworkAccess
    DisableLocalAuth = $account.DisableLocalAuth
} | Format-List

実出力の抜粋です。

ProvisioningState   : Succeeded
PublicNetworkAccess : Disabled
DisableLocalAuth    : True

公開側での Teams 経由の動作確認

次は、公開したエージェントを Teams に追加し、チャットで応答を確認します。ここでは、閉域の端末から直接 API を呼び出すのではなく、利用者が Teams からエージェントにメッセージを送ります。

Teams へのアプリ追加

管理者による承認後、Teams で Foundry Private Network Lab のアプリ詳細画面を開き、「追加」を選択します。画面には、公開用 JSON に指定した表示名、開発者名の aimless.jp、アプリの説明が表示されています。

Teams で Foundry Private Network Lab を追加する画面

チャットでの応答と会話継続

追加したアプリのチャットを開き、network-check を送信して、エージェントに設定した応答ルールどおり FOUNDRY-M365-NETWORK-OK が返ることを確認します。続いて、同じチャットで検証用マーカー CHANNEL-LAB-20261114 を覚えるように依頼します。その後、マーカーの値を再度入力せずに「先ほどの検証用マーカーのみ返してください」と送信したところ、CHANNEL-LAB-20261114 が返りました。

Teams のチャットで固定応答と会話継続を確認した画面

このように、Foundry アカウントのパブリックアクセスを無効にしたままでも、Microsoft 365/Teams 向けの限定例外を有効にすることで、Teams から応答を受け取れました。また、同じチャットで先に渡したマーカーを返せることから、単発の呼び出しだけでなく会話が継続していることも確認できました。

公開側での直接 API の挙動確認

次は、Teams から利用できるようになったことで、Foundry の直接 API までインターネットから呼び出せる状態になっていないかを確認します。Teams 経由の通信と直接 API への通信を分けて確認するため、インターネット側からエージェントの設定取得と Responses API の呼び出しを試します。

公開側の実行環境と名前解決

検証には Azure Cloud Shell の PowerShell を使用しました。検証対象のサブスクリプションとテナントになっていることを確認したうえで、アクセストークンを取得し、Foundry の名前解決結果を確認します。

$token = Get-AzAccessToken -ResourceUrl 'https://ai.azure.com' -ErrorAction Stop
$hostname = '<foundry-account>.services.ai.azure.com'
$addresses = [System.Net.Dns]::GetHostAddresses($hostname)
$addresses.IPAddressToString

実出力です。

20.191.161.227

この環境では、Private Endpoint のプライベート IP ではなく、公開 IP に名前解決されました。以降の要求は、この公開側の環境から実行しています。

エージェントの設定取得

まず、閉域から取得できていたエージェントの管理 URL に GET 要求を送ります。匿名アクセスではなく、取得したトークンを Bearer 認証で渡します。

$project = "https://$hostname/api/projects/m365-network-lab"
$agent = "$project/agents/network-lab-agent"
$r = Invoke-WebRequest `
    -Uri "${agent}?api-version=v1" `
    -Method Get `
    -Authentication Bearer `
    -Token $token.Token `
    -SkipHttpErrorCheck `
    -ErrorAction Stop
[int]$r.StatusCode
$r.Content
403
{"error":{"code":"403","message": "Public access is disabled. Please configure private endpoint."}}

HTTP403 と、パブリックアクセスが無効であることを示す本文が返りました。

Responses API の呼び出し

続いて、同じエージェントの Responses API に network-check を送ります。閉域の API と Teams では固定文字列が返りましたが、公開側からの直接呼び出しでも同じように応答するかを確認します。

$r = Invoke-WebRequest `
    -Uri "$agent/endpoint/protocols/openai/responses?api-version=v1" `
    -Method Post `
    -Authentication Bearer `
    -Token $token.Token `
    -ContentType 'application/json' `
    -Body '{"input":"network-check"}' `
    -SkipHttpErrorCheck `
    -ErrorAction Stop
[int]$r.StatusCode
$r.Content
403
{"error":{"code":"403","message": "Public access is disabled. Please configure private endpoint."}}

設定取得と Responses API は、どちらも HTTP403 でした。本文にも、パブリックアクセスが無効であることと Private Endpoint を利用するよう求めるメッセージが含まれています。今回の条件では、Teams からは応答を受け取れる一方で、公開側からの直接 API 呼び出しは引き続き拒否されました。

限定例外を無効にした場合の挙動

追加した限定例外をもとの状態に戻すと、Teams からの要求に対して応答が返ってこなくなくなります。以下キャプチャの下から2つ目のメッセージが無効化状態での送信メッセージです。

限定例外を無効にした状態での Teams の無応答

まとめ

今回は、Foundry のパブリックアクセスを無効にしたまま、Microsoft 365/Teams 向けの Activity の限定例外を使ってエージェントを公開しました。検証では、次の動作を確認できました。

  • Private Endpoint 経由では、直接 API からの応答と会話の継続ができること。
  • 限定例外を有効にすると、Teams でも、固定文字列の応答と、同じ会話で渡したマーカーの確認ができること。
  • 限定例外が有効でも、公開側から直接 API を呼び出すと、パブリックアクセスが無効であることを示す HTTP403 が返ること。

特にうれしいのは、Teams で使うためだけに Foundry 全体のパブリックアクセスを有効にしたり、Application Gateway や Azure Firewall などの中継用リソースを追加したりせずに済む点です。今回の構成では、直接 API は Private Endpoint 経由で利用し、Teams からのチャネル通信には限定例外を使う、という使い分けができました。

利用者は普段の Teams からエージェントに話しかけられ、構築する側は公開する通信の範囲を絞れます。「Foundry は閉域で使いたいけれど、利用者の入口は Teams にしたい」という場合に、構成と運用をシンプルにできるよさげな選択肢です

参考リンク

  • 当サイトは個人のブログです。このブログに示されている見解や意見は個人的なものであり、所属組織の見解や意見を表明するものではありません。
  • 公開情報を踏まえて正確な情報を掲載するよう努めますが、その内容の完全性や正確性、有用性、安全性、最新性について一切保証しません。
  • 添付文章やリンク先などを含む本サイトの内容は作成時点でのものであり、予告なく変更される場合があります。