Align public api

[nikhilNava]

Task
Align public API across the 3 languages of observability SDK

Solution

{
    "name": "Chat gpt-4o-mini",
    "context": {
        "trace_id": "0xc90f5f1d6f46e8665169026c56d0e494",
        "span_id": "0xc6f8c689ee7f31d2",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": "0x2c2187ce3dc20fa6",
    "start_time": "2026-03-25T20:01:45.581311Z",
    "end_time": "2026-03-25T20:01:50.863487Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.conversation.id": "123cf5d2-5c91-47e3-9801-ea736cf0ce88",
        "microsoft.conversation.item.link": "http://localhost:56150/_connector",
        "microsoft.agent.user.email": "b7a3a940-b39a-4a82-9629-0048f947f80a",
        "microsoft.channel.name": "msteams",
        "telemetry.sdk.name": "A365ObservabilitySDK",
        "telemetry.sdk.language": "python",
        "telemetry.sdk.version": "0.0.0",
        "gen_ai.agent.id": "84d06baf-416c-4a43-a22d-f2ee93ea9e7e",
        "gen_ai.agent.name": "Azure OpenAI Agent",
        "gen_ai.agent.description": "An AI agent powered by Azure OpenAI",
        "microsoft.a365.agent.blueprint.id": "4a380e3b-7092-4d73-bb9d-b6a54702684af",
        "microsoft.tenant.id": "badf1f56-284d-4dc5-ac59-0dd53900e743",
        "gen_ai.input.messages": "Calculate 29 modules 3\n\nTool result: Calculation result for 2 + 2: 42",
        "gen_ai.operation.name": "Chat",
        "gen_ai.request.model": "gpt-4o-mini",
        "gen_ai.provider.name": "Azure OpenAI",
        "gen_ai.output.messages": "\"To calculate 29 modulo 3, you divide 29 by 3 and find the remainder.\\n\\n29 divided by 3 is 9 with a remainder of 2. \\n\\nSo, 29 modulo 3 is **2**.\"",
        "gen_ai.usage.input_tokens": 48,
        "gen_ai.usage.output_tokens": 49,
        "gen_ai.response.finish_reasons": "[\"stop\"]"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.38.0",
            "service.namespace": "AzureOpenAiKairoTesting",
            "service.name": "AzureOpenAiKairoTracing"
        },
        "schema_url": ""
    }
}
{
    "name": "output_messages 84d06baf-416c-4a43-a22d-f2ee93ea9e7e",
    "context": {
        "trace_id": "0xc90f5f1d6f46e8665169026c56d0e494",
        "span_id": "0x57c049a325f2f7ea",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": "0x2c2187ce3dc20fa6",
    "start_time": "2026-03-25T20:01:50.866188Z",
    "end_time": "2026-03-25T20:01:50.868889Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "microsoft.conversation.item.link": "http://localhost:56150/_connector",
        "gen_ai.operation.name": "output_messages",
        "telemetry.sdk.name": "A365ObservabilitySDK",
        "telemetry.sdk.language": "python",
        "telemetry.sdk.version": "0.0.0",
        "gen_ai.agent.id": "84d06baf-416c-4a43-a22d-f2ee93ea9e7e",
        "gen_ai.agent.name": "nikhilcPermTest",
        "gen_ai.agent.description": "agenticUser",
        "microsoft.agent.user.email": "b7a3a940-b39a-4a82-9629-0048f947f80a",
        "microsoft.tenant.id": "badf1f56-284d-4dc5-ac59-0dd53900e743",
        "gen_ai.conversation.id": "123cf5d2-5c91-47e3-9801-ea736cf0ce88",
        "gen_ai.output.messages": "[\"To calculate 29 modulo 3, you divide 29 by 3 and find the remainder.\\n\\n29 divided by 3 is 9 with a remainder of 2. \\n\\nSo, 29 modulo 3 is **2**.\"]",
        "user.id": "a92962f3-9ed4-4bcd-9ae0-ad0002b6ca76",
        "user.name": "Alex Wilber",
        "microsoft.channel.name": "msteams"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.38.0",
            "service.namespace": "AzureOpenAiKairoTesting",
            "service.name": "AzureOpenAiKairoTracing"
        },
        "schema_url": ""
    }
}
{
    "name": "invoke_agent Azure OpenAI Agent",
    "context": {
        "trace_id": "0xc90f5f1d6f46e8665169026c56d0e494",
        "span_id": "0x2c2187ce3dc20fa6",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": null,
    "start_time": "2026-03-25T20:01:43.897292Z",
    "end_time": "2026-03-25T20:01:50.874290Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.conversation.id": "123cf5d2-5c91-47e3-9801-ea736cf0ce88",
        "microsoft.conversation.item.link": "http://localhost:56150/_connector",
        "microsoft.agent.user.email": "b7a3a940-b39a-4a82-9629-0048f947f80a",
        "microsoft.channel.name": "msteams",
        "user.id": "a92962f3-9ed4-4bcd-9ae0-ad0002b6ca76",
        "user.name": "Alex Wilber",
        "gen_ai.operation.name": "invoke_agent",
        "telemetry.sdk.name": "A365ObservabilitySDK",
        "telemetry.sdk.language": "python",
        "telemetry.sdk.version": "0.0.0",
        "gen_ai.agent.id": "84d06baf-416c-4a43-a22d-f2ee93ea9e7e",
        "gen_ai.agent.name": "Azure OpenAI Agent",
        "gen_ai.agent.description": "An AI agent powered by Azure OpenAI",
        "microsoft.a365.agent.blueprint.id": "4a380e3b-7092-4d73-bb9d-b6a54702684af",
        "microsoft.tenant.id": "badf1f56-284d-4dc5-ac59-0dd53900e743",
        "microsoft.session.id": "123cf5d2-5c91-47e3-9801-ea736cf0ce88",
        "gen_ai.input.messages": "[\"Calculate 29 modules 3\"]"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.38.0",
            "service.namespace": "AzureOpenAiKairoTesting",
            "service.name": "AzureOpenAiKairoTracing"
        },
        "schema_url": ""
    }
}

[github-actions]

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA d884db3.

Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

Scanned Files

None

[Copilot]

Pull request overview

Aligns the Python observability SDK public API with the other language SDKs by consolidating request/span configuration, renaming invocation configuration types, and removing execution-type / tenant-details concepts from the public surface.

Changes:

• Introduces Request + SpanDetails as the primary way to pass conversation/session metadata and span configuration (parent context, timing, kind).
• Replaces InvokeAgentDetails with InvokeAgentScopeDetails and updates all scope start(...) signatures accordingly.
• Adds UserDetails + updates CallerDetails composition model; removes ExecutionType / GEN_AI_EXECUTION_TYPE_KEY usage across hosting + extensions + tests + docs.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/usage_example.py	Updates example usage to new Request/InvokeAgentScopeDetails API and removes execution type + tenant usage.
tests/observability/hosting/scope_helpers/test_scope_helper_utils.py	Removes execution-type pair helper/test to match removed attribute.
tests/observability/hosting/scope_helpers/test_populate_invoke_agent_scope.py	Updates scope construction + removes execution-type assertions.
tests/observability/hosting/middleware/test_output_logging_middleware.py	Updates middleware expectations (tenant optional; parent passed via SpanDetails).
tests/observability/extensions/openai/integration/test_openai_trace_processor.py	Aligns baggage builder API (user_*, agentic_user_*) and removes execution type expectation.
tests/observability/core/test_trace_context_propagation.py	Migrates scope creation to Request + SpanDetails; removes tenant details usage.
tests/observability/core/test_record_attributes.py	Removes tenant details from OpenTelemetryScope construction.
tests/observability/core/test_output_scope_bounded.py	Updates AgentDetails fields to agentic_user_* and removes tenant mock.
tests/observability/core/test_output_scope.py	Updates OutputScope.start(...) usage to new signature and parent via SpanDetails.
tests/observability/core/test_invoke_agent_scope.py	Updates to InvokeAgentScopeDetails, Request, SpanDetails, UserDetails composition.
tests/observability/core/test_inference_scope.py	Updates InferenceScope.start(...) signature and removes execution type / tenant usage.
tests/observability/core/test_execute_tool_scope.py	Updates ExecuteToolScope.start(...) signature and parent/span kind via SpanDetails.
tests/observability/core/test_custom_start_end_time.py	Moves custom timing into SpanDetails and updates ExecuteToolScope.start(...) signature.
tests/observability/core/test_baggage_builder.py	Renames baggage builder methods to user_* and agentic_user_*.
libraries/microsoft-agents-a365-observability-hosting/.../scope_helpers/utils.py	Removes execution type derivation helper and related constant imports.
libraries/microsoft-agents-a365-observability-hosting/.../populate_invoke_agent_scope.py	Stops recording execution type attribute during scope population.
libraries/microsoft-agents-a365-observability-hosting/.../populate_baggage.py	Stops populating execution type into baggage.
libraries/microsoft-agents-a365-observability-hosting/.../middleware/output_logging_middleware.py	Switches to Request + SpanDetails + UserDetails, removes tenant/execution-type tagging.
libraries/microsoft-agents-a365-observability-extensions-semantickernel/.../span_processor.py	Removes execution-type tagging for invoke-agent spans.
libraries/microsoft-agents-a365-observability-extensions-openai/.../trace_processor.py	Removes execution-type attribute tagging for agent spans.
libraries/microsoft-agents-a365-observability-extensions-langchain/.../utils.py	Removes set_execution_type() helper and execution-type constants usage.
libraries/microsoft-agents-a365-observability-extensions-langchain/.../tracer.py	Stops injecting execution-type attribute into spans.
libraries/microsoft-agents-a365-observability-core/.../trace_processor/util.py	Removes gen_ai.execution.type from exported attribute list.
libraries/microsoft-agents-a365-observability-core/.../spans_scopes/output_scope.py	Updates OutputScope API to accept Request/SpanDetails/UserDetails and records conversation + user attributes.
libraries/microsoft-agents-a365-observability-core/.../span_details.py	Adds SpanDetails dataclass for parent context, timing, and span kind.
libraries/microsoft-agents-a365-observability-core/.../request.py	Makes request content optional and adds conversation_id.
libraries/microsoft-agents-a365-observability-core/.../opentelemetry_scope.py	Removes tenant details support; aligns agentic user fields; factors cancel error type constant.
libraries/microsoft-agents-a365-observability-core/.../models/user_details.py	Introduces UserDetails model for human caller metadata.
libraries/microsoft-agents-a365-observability-core/.../models/caller_details.py	Redefines CallerDetails as composite of UserDetails and optional caller agent details.
libraries/microsoft-agents-a365-observability-core/.../middleware/baggage_builder.py	Renames fluent methods to agentic_user_* and user_*.
libraries/microsoft-agents-a365-observability-core/.../invoke_agent_scope.py	Aligns invocation scope signature + attribute recording with new models and SpanDetails.
libraries/microsoft-agents-a365-observability-core/.../invoke_agent_details.py	Renames to InvokeAgentScopeDetails and narrows to scope-level config.
libraries/microsoft-agents-a365-observability-core/.../inference_scope.py	Aligns inference scope signature + user/conversation attribute recording with new models.
libraries/microsoft-agents-a365-observability-core/.../execute_tool_scope.py	Aligns tool scope signature + user/conversation attribute recording with new models.
libraries/microsoft-agents-a365-observability-core/.../constants.py	Removes execution-type constant and adds cancellation error type constant.
libraries/microsoft-agents-a365-observability-core/.../agent_details.py	Renames agent identity fields to agentic_user_* and removes conversation_id.
libraries/microsoft-agents-a365-observability-core/.../init.py	Updates public exports to new classes and removes deprecated ones.
libraries/microsoft-agents-a365-observability-core/docs/design.md	Updates design doc for new API surface and data models.
docs/design.md	Updates repo-level design doc to new class names and usage patterns.

Comments suppressed due to low confidence (1)

libraries/microsoft-agents-a365-observability-core/docs/design.md:1

• The fluent API names shown here don’t match the updated BaggageBuilder implementation (agentic_user_id(...) and agentic_user_email(...), not agent_auid(...) / agent_email(...)). Please update the table so the documented method names reflect the actual public API.

# Observability Core - Design Document

[fpfp100]

The Python PR #209 does not fully align with the nodejs implementation. The key gaps are below. Please take a look

TenantDetails still exists as a separate required parameter — Node.js absorbed it into AgentDetails.tenantId
Request is not unified — Python still has executionType (removed in Node.js) and lacks conversationId
InvokeAgentDetails not restructured — Should be renamed to InvokeAgentScopeDetails with only endpoint, while AgentDetails becomes a separate parameter
CallerDetails / UserDetails not restructured — Python doesn't have the wrapper CallerDetails (containing userDetails + callerAgentDetails) pattern
SpanDetails grouping doesn't exist — Span options remain as flat parameters
recordCancellation() and ERROR_TYPE_CANCELLED are missing
All scope start() signatures don't match — request should be required and first, tenant_details should be removed

[nikhilNava]

The Python PR #209 does not fully align with the nodejs implementation. The key gaps are below. Please take a look

TenantDetails still exists as a separate required parameter — Node.js absorbed it into AgentDetails.tenantId Request is not unified — Python still has executionType (removed in Node.js) and lacks conversationId InvokeAgentDetails not restructured — Should be renamed to InvokeAgentScopeDetails with only endpoint, while AgentDetails becomes a separate parameter CallerDetails / UserDetails not restructured — Python doesn't have the wrapper CallerDetails (containing userDetails + callerAgentDetails) pattern SpanDetails grouping doesn't exist — Span options remain as flat parameters recordCancellation() and ERROR_TYPE_CANCELLED are missing All scope start() signatures don't match — request should be required and first, tenant_details should be removed

Can you please review the comments, I believe the diff was taken against the main branch and not the PR branch.
Let me know if you have any other comments

[fpfp100]

Since this is breaking change, can you update changelog?

[nikhilNava]

Since this is breaking change, can you update changelog?

done

[Copilot]

Pull request overview

Copilot reviewed 44 out of 44 changed files in this pull request and generated 8 comments.

Comments suppressed due to low confidence (1)

libraries/microsoft-agents-a365-observability-hosting/microsoft_agents_a365/observability/hosting/scope_helpers/utils.py:27

• AGENT_ROLE and _is_agentic() appear to be unused after removing get_execution_type_pair(). Consider removing them to avoid dead code and reduce confusion.

AGENT_ROLE = "agenticUser"


def _is_agentic(entity: Any) -> bool:
    if not entity: