docs: document analyst agent name requirement

[BrianNewsom]

Summary

Document that NeMo Insights requires Intake spans to have a normalized agent_name matching the configured analyst agent. Telemetry without the attribute can ingest successfully but is excluded from the analyst queries used to retrieve and group spans.

Related Issue

ASE-795

Changes

• Document the analyst telemetry requirement and current lack of a fallback attribute.
• List the supported OTLP aliases: gen_ai.agent.name, llm.agent.name, and agent.name.
• Add an analyst-visible agent_name verification step to the nemo-intake skill and synchronize its vendored SDK copy.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with documentation updates
• Documentation only
• Contributor tooling or automation
• CI, build, or test infrastructure

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification: analyst tests verify enforced agent_name scoping and session grouping; Intake catalog tests verify semantic attribute normalization and query construction.
• Tests not applicable — justification:
• Documentation updated for user-visible behavior
• Documentation not applicable — justification:

Verification

• Pull request title follows the repository's Conventional Commit format
• Every commit includes an appropriate Signed-off-by: trailer
• uv run pre-commit run -a passes, or any blocked checks are identified below
• Targeted tests pass, or tests are marked not applicable above
• No secrets, API keys, or credentials are included

Targeted validation:

• uv run pre-commit run -a — passed.
• uv run --frozen pytest plugins/nemo-insights/tests/test_analyst_agent.py::test_nooa_read_method_preserves_run_scope plugins/nemo-insights/tests/test_periodic_analysis.py::test_count_agent_sessions_uses_server_side_session_groups services/intake/tests/test_spans_span_attribute_catalog.py -q — 39 passed.
• Source and vendored nemo-intake skill files are byte-identical.

Summary by CodeRabbit

• Documentation
  • Clarified telemetry requirements for NeMo Insights, including stable agent naming and supported attribute normalization.
  • Added guidance for filtering and verifying agent-scoped queries against the configured agent name.
  • Documented automatic agent-name mapping for ATIF telemetry and limitations for unnamed spans.
  • Clarified that named evaluation leaderboard workflows use the designated experiment upload process.

[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: e45850d3-abad-4e08-ba46-a6345c75927b

📥 Commits

Reviewing files that changed from the base of the PR and between 2c7e810 and 3efa02c.

⛔ Files ignored due to path filters (1)

• sdk/python/nemo-platform/src/nemo_platform/skills/nemo-intake/SKILL.md is excluded by !sdk/**

📒 Files selected for processing (2)

• packages/nemo_platform_ext/src/nemo_platform_ext/skills/nemo-intake/SKILL.md
• plugins/nemo-insights/README.md

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/nemo_platform_ext/src/nemo_platform_ext/skills/nemo-intake/SKILL.md
• plugins/nemo-insights/README.md

---

📝 Walkthrough

Walkthrough

Documentation defines stable agent naming, configured-agent query matching, ingestion verification, and routing for named leaderboard workflows.

Changes

NeMo Insights telemetry guidance

Layer / File(s)	Summary
Agent-scoped telemetry and verification packages/nemo_platform_ext/src/nemo_platform_ext/skills/nemo-intake/SKILL.md, plugins/nemo-insights/README.md	Documents supported OTLP agent-name attributes, ATIF mapping, configured-agent query matching, ingestion checks, and routing to nemo-experiments-upload.

Possibly related PRs

• NVIDIA-NeMo/nemo-platform#694: Shares telemetry agent-name requirements and nemo-experiments-upload workflows.
• NVIDIA-NeMo/nemo-platform#1096: Introduced related NeMo Intake telemetry guidance.
• NVIDIA-NeMo/nemo-platform#1097: Covers related NeMo Insights agent_name tracing configuration.

Suggested labels: docs

Suggested reviewers: callingmedic911

🚥 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 title clearly and concisely describes the documentation change for the analyst agent name requirement.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch brnewsom/ase-795-agent-analysis-fails-if-the-agentname-attr-is-not-set

---

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

[github-actions]

Suite	Lines Covered	Line Rate	Branch Rate
Unit Tests	31438/40061	78.5%	63.0%
Integration Tests	18305/38013	48.1%	20.8%