为 Foundry 智能体服务配置专用网络

#为 Foundry 智能体服务配置专用网络

这些步骤背后的网络架构、子网规模和 IP 分配模型，见深入了解 Foundry 智能体服务网络。

本文描述两种做法。使用门户或模板路径，用 Bicep 或 Terraform 供应一个网络安全的 Foundry 环境。使用 Azure Developer CLI 路径，把 azd 托管智能体项目的依赖放到专用终结点（private endpoint）后面。用选择器选择一种方法。

Foundry 智能体服务（Foundry Agent Service）提供带专用网络的标准设置（Standard Setup with private networking）环境。该设置创建隔离的网络环境，在你完全控制网络基础设施的同时，实现对数据的安全访问。

默认情况下，带专用网络的标准设置确保：

• 无公共出站：基础基础设施为智能体和工具提供正确的身份验证与安全，而不需要受信任服务绕过。
• 子网集成：你从虚拟网络提供一个委派子网。平台把智能体计算连接到该子网，使它能与同一虚拟网络内的 Azure 资源进行本地通信。
• 专用资源访问：如果资源被标记为专用且无法从互联网发现，只要具备必要的凭据和授权，平台网络仍然可以访问它们。

如果还没有现有虚拟网络，带专用网络的标准设置流程可以为你供应所需的网络基础设施。

先决条件

• 一个 Azure 订阅——免费创建一个。

• 权限中描述的权限。供应和运行时使用两个不同的身份，各自需要自己的角色。

• Python 3.10 或更高版本

• 注册提供程序。必须注册以下提供程序：

• Microsoft.KeyVault
• Microsoft.CognitiveServices
• Microsoft.Storage
• Microsoft.MachineLearningServices
• Microsoft.Search
• Microsoft.Network
• Microsoft.App
• Microsoft.ContainerService
• 若要使用 Bing Search 工具：Microsoft.Bing

Console

   az provider register --namespace 'Microsoft.KeyVault'
   az provider register --namespace 'Microsoft.CognitiveServices'
   az provider register --namespace 'Microsoft.Storage'
   az provider register --namespace 'Microsoft.MachineLearningServices'
   az provider register --namespace 'Microsoft.Search'
   az provider register --namespace 'Microsoft.Network'
   az provider register --namespace 'Microsoft.App'
   az provider register --namespace 'Microsoft.ContainerService'
   # only to use Grounding with Bing Search tool
   az provider register --namespace 'Microsoft.Bing'

重要

标准设置要求你自带（Bring Your Own，BYO）资源，以便所有智能体数据都留在你的 Azure 租户中。

BYO 资源包括：Azure Storage、Azure AI Search 和 Azure Cosmos DB。

Foundry 智能体服务处理的全部数据都会自动静态存储在这些资源中，帮助你满足合规要求和企业安全标准。

权限

供应身份取决于部署路径。通过 ARM REST 或 Bicep 提交的功能设置使用调用方身份。门户部署以及对旧版功能宿主 REST API 的调用，继续使用项目托管身份进行供应。

供应所需的调用方权限

对于使用 API 版本 2026-07-15-preview 的功能设置的部署，调用方可以是交互用户、CI/CD 服务主体或工作负载身份。除部署帐户和网络资源所需的权限外，功能设置只需要以下角色。Azure AI Search 不需要调用方角色。

能够创建 Foundry 帐户但缺少 Storage Blob Data Contributor 或 Cosmos DB Operator 的调用方，会使功能设置供应失败。

部署后的运行时访问

项目托管身份是正在运行的智能体用来访问 Azure Cosmos DB、Azure AI Search 和 Azure Storage 的身份。在智能体运行之前，在每个资源上为它授予数据平面角色。上一张表中的调用方角色只用于功能设置供应。它们不能替代项目托管身份在运行时所需的角色。对于门户部署和旧版功能宿主 REST API 部署，项目托管身份也会执行供应。各资源的角色列表见标准智能体设置。

环境配置完成后，为每个创建或编辑智能体的团队成员，在项目上分配内置的 Foundry User RBAC 角色。最低权限是 *agents/\/read、agents/\/action 和 agents/\/delete**。

配置网络安全环境

可以在 Azure 门户中创建此设置，或使用 Bicep 或 Terraform 部署它。

注意

门户部署使用向后兼容的功能宿主流程，并使用项目托管身份进行供应。

从高层看，部署包含以下步骤：

1. 为 Foundry 资源选择目标 Azure 区域。
2. 决定是自带虚拟网络（VNet）和子网，还是使用自动供应的网络。
3. 如果自带 VNet，收集 VNet 和子网的资源 ID。
4. 在 Azure 门户中创建该设置，或使用 Bicep 或 Terraform 部署它。
5. 验证部署（见验证部署）。

该设置会供应以下资源（除非你自带）：

• 一个 Foundry 帐户和一个 Foundry 项目。
• 一个 gpt-4o 模型部署。
• 用于存储文件、线程和向量数据的 Azure Storage、Azure Cosmos DB 和 Azure AI Search。
• 这些资源会连接到你的项目。
• 默认使用 Microsoft 管理的加密密钥，用于存储帐户和认知帐户（Foundry）。

使用以下选项卡选择首选部署方法：

• Azure 门户
• 模板

1. 从 Azure 门户搜索 Foundry，并选择创建资源。
2. 配置完基本信息选项卡后，选择存储选项卡，然后在智能体服务下选择选择资源。

• 选择或创建一个存储帐户、Azure AI Search 资源和 Azure Cosmos DB 资源。如果使用虚拟网络注入，必须自带 Storage、Azure AI Search 和 Azure Cosmos DB 资源，才能创建具有端到端虚拟网络隔离的标准智能体。

3. 配置完存储选项卡后，选择网络选项卡，然后为公共访问选择已禁用。
4. 在专用终结点部分，选择 + 添加专用终结点。
5. 在创建专用终结点的表单中，请务必：

• 在基本信息中，选择与虚拟网络相同的区域。
• 在虚拟网络表单中，选择要连接的虚拟网络和子网。

注意

在门户 UI 中，创建专用终结点的目标应标记为“帐户”。出现提示时选择你的 Foundry 资源。

6. 设置入站专用终结点后，会出现一个新的下拉框，用于设置虚拟网络注入。在第一个下拉框中选择虚拟网络，然后选择已委派给 Microsoft.App/environments、子网规模为 /27 或更大的子网。注入需要此委派和子网规模。
7. 继续完成表单以创建项目。到达查看 + 创建选项卡时，检查设置并选择创建以创建项目。
8. 继续执行验证部署中的检查。

注意

部署 Foundry 资源时，不会自动创建指向 Azure AI Search、Azure Storage 和 Azure Cosmos DB 的专用终结点。请在 Azure 门户中这些资源各自的页面上另行创建专用终结点。

使用以下基础设施即代码示例之一：

• Bicep 模板：遵循网络安全的标准智能体设置示例。该示例使用功能宿主流程和项目托管身份进行供应。
• Terraform 配置：遵循 GitHub 上的此示例中的说明。

部署完成后，继续执行验证部署中的检查。

验证部署

部署完成后，验证所有资源是否配置正确：

1. 确认子网委派：在 Azure 门户中，导航到你的 VNet > 子网，并验证智能体子网显示已委派给 Microsoft.App/environments。
2. 检查公共网络访问：打开每个资源（Foundry、Azure AI Search、Azure Storage、Azure Cosmos DB），确认公共网络访问设为已禁用。
3. 验证专用终结点 DNS 解析：从连接到该 VNet 的计算机，对DNS 区域配置摘要中列出的每个终结点运行 nslookup。
4. 测试智能体连接：从 VNet 内部访问 Foundry 项目（见访问受保护的智能体），并确认可以创建和运行智能体。
5. 配置角色分配：运行以下命令以分配所需角色。第一条在用户分配的托管身份上授予托管身份操作员，第二条为跨租户访问在远程 VNet 上授予网络参与者。

az role assignment create \
   --assignee <your-principal-id> \
   --role "Managed Identity Operator" \
   --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<id>"

 az role assignment create \
   --assignee <service-principal-object-id-in-remote-tenant> \
   --role "Network Contributor" \
   --scope "/subscriptions/<remote-subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/virtualNetworks/<vnet-name>"

限制

• VNet 和子网 IP 地址限制：

• 智能体服务委派子网必须使用以下地址空间之一：
• RFC 1918：10.0.0.0/8、172.16.0.0/12 或 192.168.0.0/16。
• RFC 6598（CGNAT）：100.64.0.0/10 内的地址，但不包括 100.100.0.0/17、100.100.192.0/19 和 100.100.224.0/19。
• 智能体服务可用的每个区域都支持专用 A 类地址空间（10.0.0.0/8）。当前列表见支持的区域。
• 不能把公共 IP 范围（例如 44.x.x.x）用于智能体服务委派子网。
• 确保 VNet 或任何对等 VNet 中的地址空间都不与 Azure 环境中的现有网络或这些保留范围重叠：169.254.0.0/16、172.30.0.0/16、172.31.0.0/16、192.0.2.0/24、0.0.0.0/8、127.0.0.0/8、100.100.0.0/17、100.100.192.0/19 和 100.100.224.0/19。
• 智能体子网独占：智能体子网不能由多个 Foundry 资源共享。每个 Foundry 资源必须使用专用的智能体子网。
• 智能体子网规模：由于子网委派给 Microsoft.App/environments，建议的委派智能体子网规模为 /24（256 个地址）。子网规模的更多说明见为 Azure 容器应用配置虚拟网络。
• 智能体子网名称长度：对于由 Azure 容器应用支持的部署，委派智能体子网名称不得超过 63 个 UTF-8 字节。此限制适用于子网名称，不适用于虚拟网络名称或完整的子网资源 ID。
• 智能体子网出站防火墙允许列表：如果把 Azure 防火墙与专用网络安全的标准智能体集成，把 control-{region}.identity.azure.net、{region}.login.microsoft.com 和 login.microsoftonline.com 加入防火墙允许列表。把 {region} 替换为部署智能体的 Azure 区域。同时加入与 Azure 防火墙集成一文中托管身份下列出的完全限定域名（FQDN），或加入 AzureActiveDirectory 服务标记。如果对委派智能体子网或相关子网应用网络安全组（NSG），请为所需依赖配置匹配的出站允许规则，包括用于 Microsoft Entra ID 身份验证的 AzureActiveDirectory 服务标记。如果防火墙或 NSG 规则阻止了所需依赖，智能体供应和运行时操作可能失败。

• 验证防火墙中没有可能添加自签名证书的 TLS 检查。失败时，检查是否有流量到达防火墙，以及哪些流量被阻止。
• 对于源代码智能体部署，还要允许专用虚拟网络的防火墙要求中列出的部署终结点。
• Foundry 资源必须部署在与虚拟网络（VNet）相同的区域。其他 Azure 资源，例如 Azure Cosmos DB、Azure AI Search 和 Azure Storage，可以部署在不同区域。请考虑跨区域部署的成本影响。
• 区域可用性：

• 模型部署支持的区域见：Azure OpenAI 模型区域支持。
• Azure Blob 存储：文件搜索工具不支持使用 Azure Blob 存储文件。
• 代码解释器文件限制：在专用网络（BYO）配置中，代码解释器只在不涉及文件上传或下载的场景中工作。在此设置中，该工具无法从存储帐户检索文件。如果需要把文件用于代码解释器，必须使用 SDK 显式创建一个包含所需文件的容器，然后把 container_id 传给代码解释器。此变通办法仅可通过 SDK 使用；Foundry 门户 UI 不支持它。
• 使用 Bing Search 的接地：仅支持以下区域：West Europe、Canada East、Switzerland North、Spain Central、UAE North、Korea Central、Poland Central、Southeast Asia、West US、West US 2、West US 3、East US、East US 2、Central US、South India、Japan East、UK South、France Central、Norway East、Australia East、Canada Central、Sweden Central、South Africa North、Italy North、Brazil South
• 删除网络注入：如果要删除带安全网络设置的 Foundry 资源和标准智能体，最后再删除 Foundry 资源和虚拟网络。删除虚拟网络之前，先删除并清除 Foundry 资源。
• 托管智能体虚拟网络注入：对于托管智能体，虚拟网络配置（网络注入）必须在首次创建 Foundry 帐户时包含。创建之后再向现有 Foundry 帐户添加网络注入，对托管智能体不受支持。
• 专用网络后面的托管智能体容器注册表：对于托管智能体，对位于专用网络后面（专用终结点且已禁用公共网络访问）的 Azure 容器注册表（ACR）的支持，取决于 Foundry 项目的创建时间。2026 年 6 月 25 日之后创建的项目支持专用 ACR。该日期之前创建的项目要求 ACR 可通过其公共终结点访问，以便平台拉取映像。现有项目不受影响，并继续使用公共网络访问。

架构图

查看已供应的网络资源

使用带专用网络的标准设置时，除非你自带，否则会自动供应以下资源：

网络基础设施

• 一个虚拟网络（192.168.0.0/16）
• 智能体子网（192.168.0.0/24）：承载智能体客户端
• 专用终结点子网（192.168.1.0/24）：承载专用终结点

虚拟网络能力

虚拟网络控制哪些终结点可以对你的资源进行 API 调用。Azure 服务会自动拒绝来自所定义网络之外设备的 API 调用。

网络规则

所有帐户及其对应项目默认受公共网络访问已禁用标志保护，需要显式配置才能通过专用终结点允许访问。这些规则适用于所有协议，包括 REST 和 WebSocket。

DNS 区域配置摘要

要在 DNS 服务器中创建指向 Azure DNS 虚拟服务器的条件转发器，使用上表中列出的区域。Azure DNS 虚拟服务器 IP 地址是 168.63.129.16。

访问受保护的智能体

部署完成后，可以使用以下方法之一，访问虚拟网络后面的 Foundry 项目：

• Azure VPN 网关：通过专用连接把本地网络连接到虚拟网络。连接经由公共互联网建立。可以使用两种 VPN 网关：

• 点到站点：每台客户端计算机使用 VPN 客户端连接到虚拟网络。
• 站点到站点：VPN 设备把虚拟网络连接到本地网络。
• ExpressRoute：通过专用连接把本地网络接入云。连接由连接提供商建立。
• Azure Bastion：在此场景中，你在虚拟网络内创建一台 Azure 虚拟机（有时称为跳板机）。然后使用 Azure Bastion 连接到该 VM。Bastion 允许你从本地 Web 浏览器通过 RDP 或 SSH 会话连接到 VM。然后把跳板机用作开发环境。由于它在虚拟网络内，可以直接访问工作区。

常见问题

整个虚拟网络应使用什么地址范围？

虚拟网络地址范围可以是任何专用 IP 范围，只要为委派智能体子网和专用终结点子网都留下足够的地址空间。

可以使用对等虚拟网络，或把资源放在不同的虚拟网络中吗？

支持对等虚拟网络，但数据传输成本可能增加。

多个 Foundry 资源可以复用同一个虚拟网络和子网吗？

可以复用同一个 VNET，但不能复用同一个子网。多个 Foundry 资源可以复用同一个虚拟网络。但是，每个 Foundry 资源需要自己专用的智能体运行时子网。智能体子网不能在多个 Foundry 资源之间共享。

虚拟网络需要与 Foundry 资源位于同一资源组吗？

不需要。虚拟网络和 Foundry 资源不必位于同一资源组，但必须位于同一区域。

故障排除指南

无论使用 Azure 门户、Bicep 还是 Terraform，都参考本指南解决标准智能体部署期间或之后的错误。

部署错误

"CreateCapabilityHostRequestDto is invalid: Agents CapabilityHost supports a single, non empty value for vectorStoreConnections property."

"Agents CapabilityHost supports a single, non empty value for storageConnections property."

"Agents CapabilityHost supports a single, non empty value for threadStorageConnections property."

解决方案：部署没有提供全部三项自带（BYO）资源。安全的标准设置需要一个 Azure Cosmos DB 帐户、一个 Azure Storage 帐户和一个 Azure AI Search 服务。在创建项目之前，通过功能设置在帐户或项目上设置这三项。如果项目已存在，请删除并使用所需设置重新创建，因为不支持更新功能设置。

"Provided subnet must be of the proper address space. Please provide a subnet which has address space in the range of 172 or 192."

解决方案：委派智能体子网没有使用正确的 IP 范围。验证你使用的是有效的专用 IP 地址空间。有效的 RFC1918 范围包括 10.0.0.0/8、172.16-31.0.0/12 和 192.168.0.0/16。更多细节见上文限制。

"Subscripton is not registered with the required resource providers, please register with the resource providers Microsoft.App and Microsoft.ContainerService."

解决方案：缺少正确的资源注册。确保所需资源已在租户中注册。

"Failed to create Aml RP virtual workspace due to System.Exception: Failed async operation." 或 "The resource operation completed with terminal provisioning state 'Failed'. Capability host operation failed."

解决方案：此错误消息可能表示许多问题。对于 ARM REST 或 Bicep 功能设置部署，确认调用方拥有供应所需的调用方权限中列出的每个角色。对于门户或旧版功能宿主 REST API 部署，确认项目托管身份拥有所需的供应和运行时角色。如果部署身份已拥有全部所需角色，请创建支持工单以调查你的设置。

"Subnet requires any of the following delegation(s) [Microsoft.App/environments] to reference service association link /subscriptions/11111-aaaaa-2222-bbbb-333333333/resourceGroups/agentRANGEChange/providers/Microsoft.Network/virtualNetworks/my-agent-vnet/subnets/agent-subnet/serviceAssociationLinks/legionservicelink."

解决方案：当你试图在 Azure 中删除安全标准模板设置、但没有正确删除全部资源时，会出现此错误。一种解决办法是导航到 Azure 门户中的 Foundry 资源页，并选择管理已删除的资源。从那里清除与此虚拟网络关联的智能体所使用的资源。另一种办法是运行安全标准模板中的 deleteCaphost.sh 脚本。

在 Foundry 项目中加载智能体页面时出现 "Timeout of 60000ms exceeded" 错误

解决方案：Foundry 项目在与 Azure Cosmos DB 通信以创建智能体时出现问题。验证到 Azure Cosmos DB 的连接（专用终结点和 DNS）。

专用终结点 DNS 解析失败

解决方案：如果无法通过专用终结点访问资源，验证每个专用 DNS 区域都已链接到你的虚拟网络。确认条件转发器指向 Azure DNS 虚拟服务器 IP 地址 168.63.129.16。从连接到该 VNet 的计算机运行 nslookup <resource-fqdn>，并验证每个名称都解析到专用 IP 地址。

后续步骤

你现在已成功配置一个网络安全的帐户和项目。使用快速入门创建第一个智能体。

有关网络隔离配置和选项的更多内容，见配置网络隔离。

许多企业环境要求 Foundry、容器注册表以及 Application Insights 和 Storage 等依赖服务只能从专用网络访问。本节说明如何供应和部署其依赖位于虚拟网络（VNet）中专用终结点后面的 azd 托管智能体。

通过自定义脚手架生成的 infra/ Bicep 模板，并从 VNet 内部（或能够访问 VNet 的位置）运行 azd，可以实现 VNet 集成。

如果使用 GitHub Copilot 这类编码智能体，Microsoft Foundry Skill 可以帮助选择正确的专用网络路径，并应用所需的 azd、Bicep 或 Terraform 步骤。

先决条件

• 一个已初始化的托管智能体项目。要创建一个，见使用 Azure Developer CLI 初始化托管智能体项目。
• 已安装 Azure Developer CLI Foundry 扩展。
• 一个虚拟网络（新建或现有），以及创建专用终结点和专用 DNS 区域的权限。
• 熟悉脚手架生成的 Bicep。见使用 Azure Developer CLI 的托管智能体基础设施。

VNet 保护对 azd 部署意味着什么

托管智能体项目会供应若干 Azure 资源。可以在每一项上禁用公共网络访问，并在 VNet 中放置一个专用终结点。

如果需要智能体终结点本身是专用的，那是此扩展目前范围之外的平台侧功能。

扩展会做什么、不会做什么

决定拓扑

大多数受 VNet 保护的部署都属于以下形态之一。编辑 Bicep 之前先选一种：

• 全新环境，一切都在新 VNet 内。 运行 azd ai agent init，然后向脚手架生成的 infra/ 添加专用终结点模块。一次 Bicep 运行同时供应 VNet 和资源。
• 现有环境，接入现有 VNet。 与全新做法相同，但通过参数引用现有 VNet，而不是创建一个。当另一个团队负责网络时，这很有用。
• 复用全部现有资源。 平台团队已在专用终结点上预先供应 Foundry 帐户、ACR 和 Application Insights。你只带入智能体定义，并把环境变量指向现有资源。main.bicep 只创建所缺的部分。

拓扑 2 和 3 在受监管企业中最常见。拓扑 1 适合自包含的试点。

自定义脚手架生成的 Bicep

azd ai agent init 生成的 infra/ 目录是标准 azd Bicep。你拥有它，更改会在多次部署中保留。默认模板创建公共资源，因此你要替换或扩充它们以添加专用终结点。

添加 VNet 和子网参数

向 infra/main.bicep 添加参数，并在 infra/main.parameters.json 中绑定它们：

Bicep

// infra/main.bicep (excerpt)

@description('Resource ID of the existing virtual network. If empty, a new VNet is created.')
param vnetResourceId string = ''

@description('Name of the subnet hosting private endpoints.')
param privateEndpointSubnetName string = 'snet-pe'

@description('Disable public network access on data-plane resources.')
param disablePublicNetworkAccess bool = true

JSON

// infra/main.parameters.json (excerpt)
{
  "vnetResourceId":              { "value": "${AZURE_VNET_RESOURCE_ID=}" },
  "privateEndpointSubnetName":   { "value": "${AZURE_PE_SUBNET_NAME=snet-pe}" },
  "disablePublicNetworkAccess":  { "value": "${DISABLE_PUBLIC_NETWORK=true}" }
}

在 azd provision 之前设置环境变量：

Bash

azd env set AZURE_VNET_RESOURCE_ID \
  /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Network/virtualNetworks/<vnet>
azd env set AZURE_PE_SUBNET_NAME snet-pe
azd env set DISABLE_PUBLIC_NETWORK true

锁定每个资源

对于模板创建的每个资源，设置 publicNetworkAccess: 'Disabled' 并添加一个专用终结点模块。以下模式仅作说明。请根据你的环境调整资源类型和 DNS 区域。

Bicep

// infra/core/ai/account.bicep (excerpt)
resource aiAccount 'Microsoft.CognitiveServices/accounts@2024-10-01' = {
  // ...existing properties...
  properties: {
    // ...existing properties...
    publicNetworkAccess: disablePublicNetworkAccess ? 'Disabled' : 'Enabled'
    networkAcls: {
      defaultAction: disablePublicNetworkAccess ? 'Deny' : 'Allow'
    }
  }
}

添加一个把帐户接入 VNet 的专用终结点模块：

Bicep

module aiAccountPrivateEndpoint '../network/private-endpoint.bicep' = if (disablePublicNetworkAccess) {
  name: 'pe-ai-account'
  params: {
    name: 'pe-${aiAccount.name}'
    location: location
    subnetId: '${vnetResourceId}/subnets/${privateEndpointSubnetName}'
    privateLinkServiceId: aiAccount.id
    groupId: 'account'
    privateDnsZoneId: privateDnsZones.cognitiveServices
  }
}

对要设为专用的资源重复此模式：

• AI 服务帐户：组 ID account。DNS 区域包括 privatelink.cognitiveservices.azure.com、privatelink.openai.azure.com 和 privatelink.services.ai.azure.com，具体取决于数据平面。
• 容器注册表：组 ID registry。DNS 区域 privatelink.azurecr.io。每个区域增加一个数据终结点。
• Application Insights：通过 Azure Monitor 专用链接范围。DNS 区域包括 privatelink.monitor.azure.com、privatelink.ods.opinsights.azure.com、privatelink.oms.opinsights.azure.com 和 privatelink.agentsvc.azure-automation.net。
• 存储帐户：按需要使用组 ID blob、file、queue 和 table。每个服务有对应的 DNS 区域，例如 privatelink.blob.core.windows.net。

智能体扩展所基于的脚手架来源 azd-ai-starter-basic 仓库，是了解默认创建内容的有用参考。扩充这些模块，而不是替换它们。

供应资源

Bash

azd provision

供应之后，列表中的每个依赖都只能通过其专用终结点访问。公共 DNS 解析仍然返回公共主机名，但专用 DNS 区域会在 VNet 内部覆盖它。

从 VNet 内部运行 azd up

禁用公共网络访问后，不能从可访问公共互联网的工作站运行 azd up 或 azd deploy。ARM 控制平面可以访问，但对 Foundry 的数据平面调用和 ACR 推送会因 403 或连接被拒绝而失败。使用以下模式之一。

自托管 GitHub Actions 运行器

在同一 VNet 的一个子网中供应运行器 VM，或 AKS 托管的运行器。用 runs-on: [self-hosted, agent-vnet] 把工作流指向该运行器。此后每个 azd ai 步骤都会正确解析专用 DNS 名称，并通过专用终结点推送。

YAML

jobs:
  deploy:
    runs-on: [self-hosted, agent-vnet]
    steps:
      - uses: actions/checkout@v4
      - uses: Azure/setup-azd@v2
      - run: azd ext install microsoft.foundry
      - run: azd auth login --client-id ${{ secrets.AZURE_CLIENT_ID }} \
          --federated-credential-provider github \
          --tenant-id ${{ secrets.AZURE_TENANT_ID }}
      - run: azd up --no-prompt

Azure DevOps 自托管代理

对 Azure DevOps 使用相同模式。把代理安装在 VNet 子网中，并用 pool: name: agent-vnet 指令指向它。azd CLI 和 Foundry 扩展无需更改即可运行。

用于一次性运行的 Bastion 或跳板机

对于临时运行，例如手动事件响应或周期外部署，通过 Azure Bastion 连接到 VNet 内的跳板机，在那里安装 azd 和扩展，并从该主机运行 azd。让跳板机保持最小化。长期方案是 CI。

针对专用 Foundry 终结点进行本地开发

本地开发（azd ai agent run 和 azd ai agent invoke）通过环回与本地智能体进程通信，并在 invoke 期间为工具、模型和会话访问 Foundry 数据平面。当 Foundry 终结点仅限 VNet 时，开发计算机需要网络可达性。选项包括：

• 点到站点或始终在线的 VPN，使你进入该 VNet 的 DNS 范围。
• 通过 Azure Bastion 连接到 VNet 内的开发 VM。在该 VM 上运行 azd ai agent run，并通过 Bastion 隧道转发端口 8088，以及用于检查器的 8087。
• 企业网络中的工作站，通过 ExpressRoute 或中心 VNet 路径到达承载专用终结点的分支。

FOUNDRY_PROJECT_ENDPOINT 的解析方式不变。该值仍然来自活动的 azd 环境或全局配置。重要的是 DNS 把终结点解析到专用 IP，而不是公共 IP。

与专用 ACR 结合

如果 Foundry 终结点和 ACR 都位于同一 VNet 中的专用终结点上，请执行以下操作：

1. 从 VNet 内部运行 azd up。
2. 设置 AZURE_CONTAINER_REGISTRY_ENDPOINT 和 AZURE_CONTAINER_REGISTRY_RESOURCE_ID，指向现有专用 ACR，这样 Bicep 就会跳过创建新的公共 ACR。
3. 确保智能体身份在注册表上拥有 AcrPull 角色。azd deploy 在创建智能体身份后会自动处理这一点。

注册表的具体细节见使用专用 Azure 容器注册表部署托管智能体。

诊断网络问题

• azd ai agent doctor 对 Foundry 数据平面运行网络可达性检查。从 VNet 内部，检查会通过。从外部，它们会明确失败。调试非网络问题时，使用 --local-only 跳过远程检查。
• azd ai agent invoke --output raw "ping" 会转储完整的 HTTP 响应。这里的连接被拒绝或没有此主机错误是 DNS 或路由问题，不是身份验证问题。
• 对于 ACR 推送失败，如果原因是缺少角色而不是网络问题，CLI 会发出一条可直接粘贴的 az role assignment create 命令。

已知限制

• 没有一等的 CLI 标志。所有 VNet 接线都是手动的 Bicep 自定义，再加上对运行器放置、DNS 和 RBAC 的操作纪律。
• 在此预览中，智能体终结点保持公开。公共终结点上的租户隔离是通过按用户隔离会话完成的，而不是网络隐私。
• 适用区域约束。托管智能体在固定的一组区域中可用。VNet、ACR 和 Foundry 帐户都应位于这些区域之一，或与之对等。Foundry 资源与其虚拟网络的同区域要求，见专用网络的区域支持。运行 azd ai agent doctor 进行验证。
• DNS 是最常见的失败模式。在认定问题是 RBAC 之前，先端到端确认专用 DNS 解析，例如从运行器或开发 VM 运行 nslookup <endpoint>。

PRIMARY_SOURCE: https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/virtual-networks