docs: update migration guide for 1.3

[willkill07]

Description

Closes

By Submitting this PR I confirm:

• I am familiar with the Contributing Guidelines.
• We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  • Any contribution which contains commits that are not Signed-Off will not be accepted.
• When the PR is ready for review, new or existing tests cover these changes.
• When the PR is ready for review, the documentation is up to date with these changes.

Summary by CodeRabbit

• Breaking Changes

  • CLI: MCP server commands restructured; nat mcp is now a command group with nat mcp serve as the main start command
  • API: Builder methods are now asynchronous; update code to await results
  • MCP transport protocol updated

• Deprecations

  • Removed telemetry exporter entity field and use_uvloop option

• Documentation

  • Added comprehensive v1.3.0 migration guide with examples

[coderabbitai]

Walkthrough

Documentation update to migration guide introducing v1.3.0 changes covering CLI command restructuring, API data model refactoring, asynchronous builder methods, MCP transport protocol changes, and deprecations.

Changes

Cohort / File(s)	Change Summary
Migration Guide Documentation docs/source/resources/migration-guide.md	Added v1.3.0 migration documentation covering CLI changes (MCP server command restructuring), API changes (Choice model refactoring, async builder methods, transport protocol updates from SSE to streamable-http), dependency updates, and deprecation notices.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Suggested labels

doc

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "docs: update migration guide for 1.3" is concise (36 characters, well within the 72-character limit), uses proper imperative mood with the "update" verb, and includes the conventional "docs:" prefix to indicate a documentation change. The title clearly and directly relates to the main change in the changeset, which is updating the migration guide documentation file to document version 1.3.0 changes including CLI restructuring, API updates, dependency changes, and deprecations.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/source/resources/migration-guide.md (1)

20-20: Use full official name on first mention per naming convention.

Line 20 should use "NVIDIA NeMo Agent toolkit" on first mention, then "NeMo Agent toolkit" for subsequent references. As per coding guidelines.

-NeMo Agent toolkit is designed to be backwards compatible with the previous version of the toolkit except for changes documented on this page.
+NVIDIA NeMo Agent toolkit is designed to be backwards compatible with the previous version of the toolkit except for changes documented on this page.

🧹 Nitpick comments (1)

docs/source/resources/migration-guide.md (1)

114-123: Improve phrasing on line 119 for clarity.

The phrase "uvicornlimited to<0.36" could be more direct. Consider rephrasing as "uvicorn must be <0.36" or "uvicorn less than 0.36`" for better readability.

-* `uvicorn` limited to `<0.36` for `nest_asyncio` compatibility
+* `uvicorn` must be `<0.36` for `nest_asyncio` compatibility

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f7e1120 and 90b664d.

📒 Files selected for processing (1)

• docs/source/resources/migration-guide.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

docs/source/**/*.md

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

docs/source/**/*.md: Use the official naming throughout documentation: first use “NVIDIA NeMo Agent toolkit”, subsequent “NeMo Agent toolkit”; never use deprecated names (Agent Intelligence toolkit, aiqtoolkit, AgentIQ, AIQ/aiq)
Documentation sources are Markdown files under docs/source; images belong in docs/source/_static
Keep docs in sync with code; documentation pipeline must pass Sphinx and link checks; avoid TODOs/FIXMEs/placeholders; avoid offensive/outdated terms; ensure spelling correctness
Do not use words listed in ci/vale/styles/config/vocabularies/nat/reject.txt; accepted terms in accept.txt are allowed

Files:

• docs/source/resources/migration-guide.md

**/*

⚙️ CodeRabbit configuration file

**/*: # Code Review Instructions

• Ensure the code follows best practices and coding standards. - For Python code, follow
  PEP 20 and
  PEP 8 for style guidelines.
• Check for security vulnerabilities and potential issues. - Python methods should use type hints for all parameters and return values.
  Example:

  def my_function(param1: int, param2: str) -> bool:
      pass

• For Python exception handling, ensure proper stack trace preservation:
  • When re-raising exceptions: use bare raise statements to maintain the original stack trace,
    and use logger.error() (not logger.exception()) to avoid duplicate stack trace output.
  • When catching and logging exceptions without re-raising: always use logger.exception()
    to capture the full stack trace information.

Documentation Review Instructions - Verify that documentation and comments are clear and comprehensive. - Verify that the documentation doesn't contain any TODOs, FIXMEs or placeholder text like "lorem ipsum". - Verify that the documentation doesn't contain any offensive or outdated terms. - Verify that documentation and comments are free of spelling mistakes, ensure the documentation doesn't contain any

words listed in the ci/vale/styles/config/vocabularies/nat/reject.txt file, words that might appear to be
spelling mistakes but are listed in the ci/vale/styles/config/vocabularies/nat/accept.txt file are OK.

Misc. - All code (except .mdc files that contain Cursor rules) should be licensed under the Apache License 2.0,

and should contain an Apache License 2.0 header comment at the top of each file.

• Confirm that copyright years are up-to date whenever a file is changed.

Files:

• docs/source/resources/migration-guide.md

docs/source/**/*

⚙️ CodeRabbit configuration file

This directory contains the source code for the documentation. All documentation should be written in Markdown format. Any image files should be placed in the docs/source/_static directory.

Files:

• docs/source/resources/migration-guide.md

🪛 LanguageTool

docs/source/resources/migration-guide.md

[style] ~119-~119: The double modal “needed limited” is nonstandard (only accepted in certain dialects). Consider “to be limited”.
Context: ...er configurations if needed * uvicorn limited to <0.36 for nest_asyncio compatibi...

(NEEDS_FIXED)

🔇 Additional comments (4)

docs/source/resources/migration-guide.md (4)

32-58: CLI changes are clearly documented with helpful migration examples.

The before/after code blocks effectively communicate the restructured commands. Format and content are well-presented.

---

60-106: API changes are well-documented with proper technical cross-references and helpful examples.

Sphinx references are correctly formatted, migration examples are clear, and warning admonitions are properly styled. Documentation effectively conveys the breaking changes.

---

125-132: Deprecations are clearly communicated with proper formatting.

Warning admonitions, cross-references, and actionable guidance are well-presented.

---

1-16: License header is correct and up-to-date.

Apache 2.0 header with 2025 copyright is properly present.

[willkill07]

/merge