test(azure.ai.agents): validate azure.yaml examples in docs

cli/azd/extensions/azure.ai.agents/AGENTS.md

@@ -38,6 +38,38 @@ replace github.com/azure/azure-dev/cli/azd => ../../
 
 That `replace` points this extension at your local `cli/azd` checkout instead of the version in `go.mod`. Do not merge the extension with that `replace` still present.
 
+## Documentation examples
+
+`azure.yaml` examples in this extension's markdown docs are validated by
+`TestDocExamplesAreValid` (`internal/project/doc_examples_test.go`). Every fenced
+YAML block declaring an `azure.ai.agent` service must:
+
+1. Resolve through `AgentDefinitionFromService` without error, and
+2. Satisfy `schemas/azure.ai.agent.json`, including required fields, types,
+   enums, patterns, and declared properties, and
+3. Parse core-owned service fields (`docker`, `k8s`, `infra`, `hooks`, and the
+   scalar fields) with the same YAML shapes azd core expects.
+
+azd ignores unknown service properties at runtime, so an undocumented key
+deploys cleanly while doing nothing — the test blocks that in our docs.
+
+Snippets that are deliberately incomplete (for example, the network examples in
+`docs/private-networking.md`, which omit `kind` because azd falls back to the
+on-disk `agent.yaml`) opt out of the "must fully resolve" check with a marker on
+the line before the fence:
+
+````markdown
+<!-- azd:doc-example partial -->
+```yaml
+services:
+  my-agent:
+    host: azure.ai.agent
+```
+````
+
+Use the marker only when the snippet is intentionally partial. If a complete
+example fails, fix the example rather than adding the marker.
+
 ## Error handling
 
 This extension uses `internal/exterrors` so the azd host can show a useful message, attach an optional suggestion, and emit stable telemetry.

cli/azd/extensions/azure.ai.agents/README.md

@@ -80,6 +80,7 @@ carries `config: env:` gets a warning naming the affected variables on both
 
 Move them up one level to fix it:
 
+<!-- azd:doc-example partial -->
 ```yaml
 services:
   my-agent:

cli/azd/extensions/azure.ai.agents/docs/private-networking.md

@@ -8,6 +8,7 @@ The `azure.ai.projects` extension owns the project service and the `microsoft.fo
 
 When `network:` is present, azd always provisions an **account private endpoint** and disables public data-plane access. Dependent stores (Cosmos DB, AI Search, Storage) stay platform-managed.
 
+<!-- azd:doc-example partial -->
 ```yaml
 infra:
   provider: microsoft.foundry
@@ -98,6 +99,7 @@ azd env set AZURE_DNS_SUBSCRIPTION_ID "<subscription-id>"
 
 Omit `agentSubnet` so the hosted-agent runtime uses a Microsoft-managed network. `peSubnet` is still required: the account data plane stays private behind an account private endpoint in your VNet, reachable from inside the VNet, a peered VNet, or VPN.
 
+<!-- azd:doc-example partial -->
 ```yaml
 infra:
   provider: microsoft.foundry
@@ -142,6 +144,7 @@ azd ai agent invoke --new-session "hello"
 
 Set `agentSubnet` to inject the hosted-agent runtime into your customer subnet. `agentSubnet` and `peSubnet` must reference the same VNet in v1.
 
+<!-- azd:doc-example partial -->
 ```yaml
 services:
   my-agent:

cli/azd/extensions/azure.ai.agents/go.mod

@@ -35,6 +35,7 @@ require (
 	github.com/Netflix/go-expect v0.0.0-20220104043353-73e0943537d2
 	github.com/creack/pty v1.1.24
 	github.com/hinshun/vt10x v0.0.0-20220119200601-820417d04eec
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
 	golang.org/x/term v0.44.0
 )
 
@@ -98,7 +99,6 @@ require (
 	github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
-	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
 	github.com/sethvargo/go-retry v0.3.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
 	github.com/theckman/yacspin v0.13.12 // indirect