Add InvokeAgent GenAI semantic parameters

[Nikhil Navakiran (nikhilNava)]

Summary

• add Python-native request and response parameter models for InvokeAgent spans
• emit GenAI semantic-convention request, response, usage, and cache token attributes
• document the new APIs and preserve existing call forms

Python parity for microsoft/opentelemetry-distro-dotnet#120.

Validation

• A365 tests: 475 passed, 15 skipped
• Black: passed
• Pylint: 10.00/10
• changed-source mypy: passed

Full mypy still reports the existing missing stubs for msal in an untouched module.

[github-actions]

Performance comparison

Threshold: regressions >15.0% on gating scenarios fail the build. Higher ops/s is better; positive Δ means the PR is slower.

Scenario	Gating	Baseline (ops/s)	Candidate (ops/s)	Δ %	Status
azure_monitor_log	yes	31,498.0	31,753.1	-0.80%	✅
azure_monitor_span	yes	211,104.1	212,449.5	-0.63%	✅
otel_log	no	36,150.7	36,508.3	-0.98%	✅
otel_span	no	63,359.3	62,680.2	+1.08%	✅

[Copilot]

🟡 Changes recommended

Documentation examples and model descriptions need correction before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds Python-native GenAI request/response parameter models for InvokeAgent spans and emits related semantic-convention attributes.

Changes:

• Added request/response parameter models and public exports.
• Recorded request, response, usage, and cache-token attributes.
• Added tests, documentation, and changelog updates.

File summaries

File	Summary	Findings
tests/a365/test_invoke_agent_scope.py	Tests parameter recording behavior.	—
src/microsoft/opentelemetry/a365/README.md	Documents core modules and models.	Nit (3 votes): describe the models as GenAI parameter models rather than message payload models.
src/microsoft/opentelemetry/a365/core/invoke_agent_scope.py	Emits GenAI semantic attributes.	—
src/microsoft/opentelemetry/a365/core/invoke_agent_details.py	Adds request/response parameter fields.	—
src/microsoft/opentelemetry/a365/core/gen_ai_response_parameters.py	Defines response parameters.	—
src/microsoft/opentelemetry/a365/core/gen_ai_request_parameters.py	Defines request parameters.	—
src/microsoft/opentelemetry/a365/core/constants.py	Adds semantic-convention keys.	—
src/microsoft/opentelemetry/a365/core/__init__.py	Exports the new models.	—
src/microsoft/opentelemetry/a365/constants.py	Mirrors semantic-convention keys.	—
README.md	Documents the new API.	Nit (1 vote): the example omits imports or definitions for InvokeAgentScope, request, and agent_details. Nit (2 votes): the example omits the InvokeAgentScope import.
CHANGELOG.md	Records the new feature.	—
A365_DOCUMENTATION.md	Expands InvokeAgent documentation.	—

Review details

Suppressed comments (1)

README.md:130

• This example cannot be copied as shown: it uses InvokeAgentScope, request, and agent_details without importing or defining them, so it raises NameError before demonstrating the new API. Include those imports and initialize the request and agent objects as in the full guide.

from microsoft.opentelemetry.a365.core import GenAiRequestParameters, GenAiResponseParameters, InvokeAgentScopeDetails

• Files reviewed: 12/12 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.