docs(openshell): add NAT deployment guide

[afourniernv]

Summary

Add a guide for running NeMo Agent Toolkit workloads inside OpenShell, including a minimal example, auth-boundary guidance, outbound tool and MCP access, and local versus Kubernetes deployment lanes.

Related Issue

N/A

Changes

• added a new OpenShell guide under docs/source/run-workflows/existing-agents/openshell.md
• linked the OpenShell guide from the existing agents index
• linked the broader OpenShell deployment pattern from the A365 example README

Testing

• PATH=/Users/afournier/proj/NeMo-Agent-Toolkit/.venv/bin:$PATH NAT_DISABLE_API_BUILD=1 sphinx-build -M html docs/source docs/build -j 4 --show-traceback
• Unit tests added/updated
• E2E tests added/updated (if applicable)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)

Summary by CodeRabbit

• Documentation
  • Added a new guide for running NeMo Agent Toolkit agents with OpenShell, including architecture boundaries, credential/token delivery options, policy-controlled tool/API access, and step-by-step command examples.
  • Updated the “Running Existing Agents” documentation to add OpenShell to the supported frameworks list and documentation navigation.
  • Linked the OpenShell guide from the A365 example README with brief integration context.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 45428330-1652-421c-9c7a-be9f75fd442a

📥 Commits

Reviewing files that changed from the base of the PR and between 2164fa5 and ee4ff20.

📒 Files selected for processing (1)

• docs/source/run-workflows/existing-agents/openshell.md

✅ Files skipped from review due to trivial changes (1)

• docs/source/run-workflows/existing-agents/openshell.md

---

Walkthrough

Adds OpenShell as a supported framework in the existing-agents documentation index, introduces a new 546-line openshell.md guide covering the NAT+OpenShell deployment model, authentication boundaries, credential delivery modes, worked examples, and deployment lanes, and adds a cross-reference link in the a365_example README.

Changes

OpenShell Documentation

Layer / File(s)	Summary
Index and cross-reference wiring docs/source/run-workflows/existing-agents/index.md, examples/a365_example/README.md	Adds OpenShell to the Supported Frameworks list and toctree in the existing-agents index, and adds a cross-reference bullet in the a365 example README.
Architecture overview and auth boundary concepts docs/source/run-workflows/existing-agents/openshell.md	Introduces the OpenShell+NAT deployment model and container packaging guidance; defines auth boundary concepts and how OpenShell provider contracts map to NAT auth providers; covers static vs brokered credential modes plus outbound tool call and MCP requirements.
Worked examples and deployment guidance docs/source/run-workflows/existing-agents/openshell.md	Provides the minimal OpenShell example with NAT workflow, container setup, restrictive policy, and openshell commands; the brokered-auth variant using token URLs; deployment lane descriptions for local/container and Kubernetes/cloud environments; an A365 hosting example on AKS; separation-of-responsibilities guidance; and the recommended onboarding workflow sequence.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title clearly and concisely describes the main change: adding OpenShell deployment documentation to NeMo Agent Toolkit. It uses imperative mood ('add'), follows the conventional commit format with a 'docs' scope, is descriptive, and stays within the recommended 72 character limit at 41 characters.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/source/run-workflows/existing-agents/openshell.md`:
- Around line 514-518: In the responsibility table around line 514-518, replace
the header "NAT owns" with "NeMo Agent Toolkit owns" or "The Toolkit owns" to
comply with the documentation guideline that restricts the acronym NAT to code
contexts only. Update the header text while keeping the bullet point list
structure (workflow YAML, tool definitions, frontend behavior, tracing and
evaluation hooks, agent-specific auth adapters) intact, formatted as bold
markdown for the header followed by the bullet points.
- Around line 18-29: Replace all instances of "NAT" used to refer to the toolkit
product with either "NeMo Agent Toolkit" or "the toolkit" throughout the
document, reserving "NAT" for use only in code comments as per documentation
guidelines. Specific examples include: "run a NAT agent as a managed service"
should become "run a NeMo Agent Toolkit agent" or "run an agent", and "This
guide focuses on the NAT side of the integration. NAT still owns the workflow"
should become "This guide focuses on the NeMo Agent Toolkit side" or "the
toolkit side", with "the toolkit still owns" replacing the second instance.
Apply this replacement systematically across the entire document wherever NAT
appears in prose text.
- Around line 24-29: The documentation file
docs/source/run-workflows/existing-agents/openshell.md violates the naming
guideline by using "NAT" in prose sections to refer to the toolkit product.
Replace all "NAT" references with "NeMo Agent Toolkit" (on first mention) or
"the toolkit" (on subsequent mentions) across all prose content, while
preserving "NAT" only in code examples, package names, and code identifiers.
Apply the following replacements in
docs/source/run-workflows/existing-agents/openshell.md: at lines 24-29, replace
"run a NAT agent", "the NAT side", "NAT still owns"; at lines 37-38, replace
"NAT workload" and "The NAT image"; at line 80, update the heading to remove
"NAT Auth Providers"; at line 95, replace "NAT auth providers"; at line 104,
replace "NAT auth providers"; at line 108, replace "NAT-side auth shape"; at
line 118, replace "NAT consumes"; at line 194, replace "the NAT workload"; at
line 233, replace "the NAT workflow"; at line 314, replace "service-oriented NAT
entrypoint". Ensure consistency by using the full product name on first
reference and the shorter form "the toolkit" for subsequent references within
each section.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 7affce30-43c4-450b-a54d-5245103564f6

📥 Commits

Reviewing files that changed from the base of the PR and between 6bacce9 and 22954f5.

📒 Files selected for processing (3)

• docs/source/run-workflows/existing-agents/index.md
• docs/source/run-workflows/existing-agents/openshell.md
• examples/a365_example/README.md

[afourniernv]

/ok to test

[copy-pr-bot]

/ok to test

@afourniernv, there was an error processing your request: E1

See the following link for more information: https://docs.gha-runners.nvidia.com/cpr/e/1/

[afourniernv]

/ok to test 2164fa5

[afourniernv]

/ok to test ee4ff20