Add a365 network vnet for linking an Azure VNet to Agent 365

CHANGELOG.md

@@ -27,6 +27,7 @@ Agents provisioned before this release need `Agent365.Observability.OtelWrite` g
 **Option B — CLI** (`a365 setup admin`) has been removed in this release. Use Option A above, or copy the PowerShell instructions printed in the `a365 setup all` summary output.
 
 ### Added
+- `a365 network vnet link|unlink|status` links an Azure virtual network enterprise policy to your Agent 365 environment (#494).
 - `a365 develop-mcp grant-agents-access --agent-blueprint-id <GUID> --mcp-server-name <NAME>` reports which agent instances of a blueprint are missing the permission to call a BYO MCP server, and prompts you to select which ones to grant it to (#500).
 - When more than one Entra application shares the MCP server's name, `a365 develop-mcp grant-agents-access` now lists them all and asks which one to use instead of failing (#500).
 - `a365 develop-mcp grant-agents-access --help` now lists Microsoft's first-party agent blueprint names and IDs, and the same list is printed when `--agent-blueprint-id` is missing or not a GUID, so you can find the ID without looking it up elsewhere (#500).

docs/commands/README.md

@@ -27,6 +27,10 @@ There is reference documentation for each command.
 | [develop-mcp list-servers](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop-mcp#develop-mcp-list-servers) | List MCP servers in a specific Dataverse environment. |
 | [develop-mcp publish](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop-mcp#develop-mcp-publish) | Publish an MCP server to a Dataverse environment. |
 | [develop-mcp unpublish](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop-mcp#develop-mcp-unpublish) | Unpublish an MCP server from a Dataverse environment. |
+| [network](network.md) | Configure tenant networking for Agent 365. |
+| [network vnet link](network.md#link) | Link a NetworkInjection enterprise policy to your Agent 365 environment. |
+| [network vnet unlink](network.md#unlink) | Remove the virtual network link from your Agent 365 environment. |
+| [network vnet status](network.md#status) | Show whether a virtual network policy is linked to your Agent 365 environment. |
 | [publish](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/publish) | Update manifest.json ID values and publish the package. Configure federated identity and app role assignments. |
 | [query-entra](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/query-entra) | Query Microsoft Entra ID for agent information including scopes, permissions, and consent status. |
 | [query-entra blueprint-scopes](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/query-entra#query-entra-blueprint-scopes) | List configured scopes and consent status for the agent blueprint. |

docs/commands/network.md

@@ -0,0 +1,128 @@
+# `a365 network vnet`
+
+Links an Azure virtual network to Agent 365 via a Power Platform **NetworkInjection enterprise
+policy**, without needing the id of the Power Platform environment.
+
+## Why this command exists
+
+The documented subnet-injection flow
+([Set up virtual network support](https://learn.microsoft.com/power-platform/admin/vnet-support-setup-configure))
+ends with `Enable-SubnetInjection` from the `Microsoft.PowerPlatform.EnterprisePolicies` module,
+which takes an `-environmentId`. Agent 365 provisions a managed Power Platform environment for the
+tenant and does not publish its id, so that final step cannot be run.
+
+`a365 network vnet` replaces only that last step. The CLI reads the policy's `systemId` from Azure
+Resource Manager with your own sign-in, then asks the Agent 365 platform to perform the link
+against the environment it resolves for your tenant.
+
+Everything before the final step is unchanged — keep using the PowerShell module to create the
+subnets, delegate them to `Microsoft.PowerPlatform/enterprisePolicies`, and create the policy with
+`New-SubnetInjectionEnterprisePolicy`.
+
+## Prerequisites
+
+- **Global Administrator** or **Power Platform Administrator** in the tenant. The platform rejects
+  anyone else.
+- An active `az login` session. It supplies two defaults: the tenant to operate on, and the
+  signed-in account used as a login hint for the Agent 365 call. `--tenant-id` overrides the
+  first. Tokens are not borrowed from Azure CLI -- both the ARM policy read and the Agent 365 call
+  acquire their own tokens through the CLI's sign-in. The ARM read is not given the login hint, so
+  with several cached accounts in the same tenant it may sign in as a different one; sign out of
+  the accounts you do not want the CLI to use.
+- A NetworkInjection enterprise policy already created by `New-SubnetInjectionEnterprisePolicy`,
+  with subnets delegated to `Microsoft.PowerPlatform/enterprisePolicies`.
+- Public cloud only. Sovereign clouds are not supported.
+
+## Subcommands
+
+| Command | Description |
+| --- | --- |
+| `a365 network vnet link` | Link a NetworkInjection enterprise policy to the tenant's Agent 365 environment. |
+| `a365 network vnet unlink` | Remove the virtual network link. |
+| `a365 network vnet status` | Show the current link, or check a running operation. |
+
+### `link`
+
+```bash
+a365 network vnet link --policy-arm-id <arm-id> [--swap] [--tenant-id <guid>] [--wait] [--yes]
+```
+
+| Option | Description |
+| --- | --- |
+| `--policy-arm-id`, `-p` | **Required.** ARM resource id of the policy, as returned by `New-SubnetInjectionEnterprisePolicy`. |
+| `--swap` | Replace an existing link to a *different* policy. Without it, a different existing link is reported as a conflict instead of being silently replaced. |
+| `--tenant-id` | Tenant to authenticate against, for both the Azure policy read and the Agent 365 call. Defaults to the tenant of your current `az login`. |
+| `--wait` | Poll until the operation settles instead of returning an operation id. |
+| `--yes`, `-y` | Skip the confirmation prompt. |
+
+Every `link` prompts for confirmation: Power Platform documents that enabling subnet delegation can
+leave the environment unstable for up to 30 minutes while connections re-initialize, and the change
+applies to every Agent 365 agent in the tenant. Pass `--yes` in automation.
+
+Linking the policy that is already linked is a no-op and succeeds without `--swap`.
+
+### `unlink`
+
+```bash
+a365 network vnet unlink [--tenant-id <guid>] [--wait] [--yes]
+```
+
+Unlink needs no policy id from you, but it does need your Azure session: it reads which policy is
+linked, resolves that policy in Azure to get the identifier the platform requires, then unlinks. If
+the policy has been deleted from Azure, unlink fails and names it — use the PowerShell
+`Disable-SubnetInjection` module instead. It prompts before removing the link; pass `--yes` in
+automation.
+
+### `status`
+
+```bash
+a365 network vnet status [--operation-id <id>] [--tenant-id <guid>]
+```
+
+Without `--operation-id`, reports the environment's current link. With one, reports that specific
+operation.
+
+## Statuses and exit codes
+
+| Status | Meaning |
+| --- | --- |
+| `Linked` | A policy is linked; `Policy` names it. |
+| `NotLinked` | No policy is linked. |
+| `Running` | The operation is still in flight; `Operation` is the handle to poll. |
+| `Failed` | The operation failed; `Reason` explains why. |
+| `Unknown` | The operation id is not recognised — mistyped, expired, or from another tenant. Operation ids are tenant-scoped, so check `--tenant-id`; to read the current link instead, run `status` with no `--operation-id`. |
+
+Exit code is `1` on `Failed`, on `Unknown`, and on any request error; `0` otherwise — including a
+still-running operation, which is a legitimate outcome when `--wait` is not passed.
+
+## Typical flow
+
+```bash
+# 1. Create the policy with the PowerShell module (unchanged).
+New-SubnetInjectionEnterprisePolicy `
+    -SubscriptionId <sub> -ResourceGroupName <rg> -PolicyName <name> `
+    -PolicyLocation <geography> -VirtualNetworkId <vnetId> -SubnetName <subnet>
+
+# 2. Link it — this replaces Enable-SubnetInjection.
+a365 network vnet link --policy-arm-id /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.PowerPlatform/enterprisePolicies/<name> --wait
+
+# 3. Confirm.
+a365 network vnet status
+```
+
+Two things the Learn walkthrough covers that are easy to miss:
+
+- Geographies with two supported regions (`unitedstates`, for example) need a second virtual
+  network: pass `-VirtualNetworkId2` and `-SubnetName2` as well.
+- The CLI reads the policy with *your* identity, so whoever runs `link` needs read access on the
+  policy even if someone else created it.
+
+## Troubleshooting
+
+| Symptom | Cause |
+| --- | --- |
+| `Could not determine your Azure tenant` | No `az login` session. Run `az login`, or pass `--tenant-id`. |
+| `--tenant-id was supplied but is empty` | `--tenant-id` was passed with a blank value. Pass a tenant id, or omit the option entirely. |
+| `403` from the platform | Caller is not a Global or Power Platform Administrator, or the CLI app lacks consent for the `AgentTools.VNet.*` scopes. |
+| Conflict reported on `link` | A *different* policy is already linked. Re-run with `--swap`, or `unlink` first. |
+| Policy read fails | The policy ARM id is wrong, or your `az login` identity cannot read it. |