Skip to content

docs: add deployHostedAgent prerequisites documentation - #127

Draft
Paulo Lacerda (placerda) wants to merge 8 commits into
mainfrom
placerda-docs-hosted-agent-capability
Draft

docs: add deployHostedAgent prerequisites documentation#127
Paulo Lacerda (placerda) wants to merge 8 commits into
mainfrom
placerda-docs-hosted-agent-capability

Conversation

@placerda

@placerda Paulo Lacerda (placerda) commented Jul 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Companion documentation for deployHostedAgent

Adds/updates MkDocs pages in Azure/AI-Landing-Zones to document the opt-in
deployHostedAgent capability introduced by
Azure/bicep-ptn-aiml-landing-zone #121.

What this PR documents

deployHostedAgent defaults to false; the existing resource graph is unchanged
when disabled. When enabled, the landing zone adds only:

  1. Foundry Project Manager RBAC — deploying principal → Foundry project
    (enables downstream agent deployment)
  2. Container Registry Repository Reader RBAC — Foundry project MI → selected ACR
    (deployment-time repository read access during azd deploy)
  3. A typed HOSTED_AGENT_DEPLOYMENT output handoff consumed by azure.ai.agent

It does not create agents, Container Apps, UI panels, or modify Cosmos DB, Search,
Storage, App Configuration, or workload lists.

Pages changed

File Change
docs/bicep/hosted-agent.md New dedicated page
docs/bicep/overview.md Opt-in section + Next steps link
docs/bicep/parameterization.md Toggle row + hosted-agent deployment contract table
docs/bicep/permissions.md Hosted-agent role-assignments section
docs/bicep/deployed-resources.md Scenario add-on table
docs/whatisnew.md New dated entry
mkdocs.yml Nav entry

Validation

mkdocs build --strict   → exit 0 (no errors, no warnings)
PR diff → 311 additions / 1 deletion across 7 files; existing CRLF pages preserved

Scope boundaries documented

  • startupCommand is optional per azure.ai.agent schema
  • CPU range 0.25–4.0 cores (examples: 0.5, 1); memory 0.5Gi–8Gi (examples: 0.5Gi, 1Gi)
  • Private-ACR compatibility gate: projects created after June 25, 2026 support private-endpoint-only
    ACR; earlier projects require public endpoint reachability
    (source)
  • Unsupported hostedAgent.roles lists are rejected; external-resource RBAC uses explicit role definition IDs after azd deploy creates the agent identity`n- No GPT-RAG-specific naming; accelerator-neutral throughout

Draft — pending approval of the upstream bicep PR #121 before merge.

Paulo Lacerda (placerda) and others added 4 commits July 29, 2026 09:41
@placerda
docs: add deployHostedAgent prerequisites documentation
3f0f5a9 
Document the accelerator-neutral deployHostedAgent opt-in from
Azure/bicep-ptn-aiml-landing-zone PR #121.

Changes:
- docs/bicep/hosted-agent.md (new): dedicated page covering what the
  flag does/doesn't do, typed parameter contract (hostedAgent + ACR
  params), RBAC summary, output reference (HOSTED_AGENT_DEPLOYMENT
  shape), ACR selection logic, VNet-connected build requirements,
  downstream azd deploy boundary, private-registry compatibility gate
  with official MS Learn links
- mkdocs.yml: add nav entry for hosted-agent page
- docs/whatisnew.md: new entry for the deployHostedAgent capability
- docs/bicep/overview.md: opt-in section + updated Next steps
- docs/bicep/deployed-resources.md: scenario add-on table for
  deployHostedAgent (RBAC-only, no new ARM resources)
- docs/bicep/parameterization.md: deployHostedAgent toggle row and
  Hosted-agent deployment contract section (hostedAgent, BYO ACR params)
- docs/bicep/permissions.md: Hosted-Agent Role Assignments section
  (AzureAIProjectManager + Container Registry Repository Reader)

Boundary: deployHostedAgent defaults false; when disabled, resource
graph is unchanged. When enabled, adds only two RBAC assignments and
a typed HOSTED_AGENT_DEPLOYMENT handoff. No Container Apps, agent
versions, admin panels, or existing workload resources are created,
modified, or suppressed.

Related: Azure/bicep-ptn-aiml-landing-zone#121

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7fa7bf5e-4853-447d-8e6e-2fefd7714f60
@placerda
docs: state exact June 25 2026 private-ACR gate date
997670e 
Expand the Private-registry compatibility gate section in
docs/bicep/hosted-agent.md with the precise Foundry-project
creation-date threshold documented in Microsoft Learn:

- Projects created AFTER June 25, 2026: fully private ACR
  (public access disabled + private endpoint only) is supported.
- Projects created BEFORE June 25, 2026: registry must remain
  reachable over its public endpoint.

Added a two-row table and a warning admonition. Linked both
official Microsoft Learn pages (private ACR deployment guide and
hosted-agent permissions reference).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7fa7bf5e-4853-447d-8e6e-2fefd7714f60
@placerda
fix: correct deployHostedAgent docs per review feedback
a77bee7 
- startupCommand is optional per azure.ai.agent schema
- CPU range 0.25-4.0 / memory 0.5Gi-8Gi; remove 500m/512Mi examples
- Disabled state: RBAC unchanged, outputs resolve to false/empty values
- RBAC: Azure AI Project Manager enables downstream agent deployment;
  Container Registry Repository Reader provides deployment-time read;
  AcrPull per-agent identity row added (runtime, assigned by azure.ai.agent)
- Private-ACR gate date sourced from permissions/virtual-network page
- Strip all trailing whitespace (LF normalize)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7fa7bf5e-4853-447d-8e6e-2fefd7714f60
@placerda
fix: accuracy corrections from review (ARM resources, registry table,…
63dba02 
… hostedAgent defaults)

- Replace 'No new ARM resources' with 'no new service or workload
  resources or top-level symbolic resources' — RBAC role assignments
  ARE ARM resources; phrasing now accurately scopes the claim
- Registry-selection table: landing-zone ACR row no longer says 'None';
  documents that operator must provide VNet-reachable build/push
  and satisfy the June 25 2026 project-date gate
- hostedAgent default summary: was 'All fields empty'; now
  'name/image/version/startupCommand empty; runtime and protocols use defaults'

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7fa7bf5e-4853-447d-8e6e-2fefd7714f60
@placerda Paulo Lacerda (placerda) mentioned this pull request Jul 29, 2026
Merged
Paulo Lacerda (placerda) and others added 3 commits July 29, 2026 10:01
@placerda
revert: remove documentation line-ending churn
bbd3740 
Restore the minimal companion diff before reapplying the intended accuracy corrections without rewriting complete files.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 3404566d-8c5e-45a1-a3db-b0da525c96fb
@placerda
fix: restore CRLF line endings in deployed-resources and parameteriza…
be9ad41 
…tion

Both files were originally committed with CRLF stored in origin/main.
The Python LF-normalisation pass in a prior commit converted them to LF,
producing 568 and 812 spurious changed-line counts in the PR diff.

This commit restores the files from origin/main CRLF bytes and re-applies
only the targeted insertions (with CRLF), reducing the diff back to the
expected ~12 and ~30 added lines respectively.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7fa7bf5e-4853-447d-8e6e-2fefd7714f60
@placerda
docs: clarify hosted-agent defaults and registry gates
122440b 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 3404566d-8c5e-45a1-a3db-b0da525c96fb
@placerda Paulo Lacerda (placerda) mentioned this pull request Jul 29, 2026
Closed
@placerda
docs: use current Foundry role naming
ed387d1 
Document explicit rejection of arbitrary hosted-agent role-name lists.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 3404566d-8c5e-45a1-a3db-b0da525c96fb
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@placerda