feat: Add x-ms-agentid header for MCP platform calls

[pontemonti]

Summary

Port of Node.js SDK PR #183 - Add an \x-ms-agentid\ header to all outbound HTTP requests from the tooling package to the MCP platform for agent identification.

Problem

The MCP platform needs to identify which agent is making tooling requests for:

• Logging and diagnostics
• Usage analytics

Solution

Add \x-ms-agentid\ header with value determined by priority:

1. TurnContext agenticAppBlueprintId (highest priority)
2. Token claims (\xms_par_app_azp\ > \�ppid\ > \�zp)
3. Application name from env var or pyproject.toml (lowest priority)

If no identifier is available, the header is omitted.

Changes

Runtime package (\microsoft-agents-a365-runtime)

• Add \get_agent_id_from_token()\ method for extracting agent ID from JWT token
• Add \get_application_name()\ method with thread-safe caching

Tooling package (\microsoft-agents-a365-tooling)

• Add header constants: \AGENT_ID, \CHANNEL_ID, \SUBCHANNEL_ID\
• Add _resolve_agent_id_for_header()\ method to resolve best agent identifier
• Update _prepare_gateway_headers()\ to include \x-ms-agentid\

Documentation

• Add PRD document: \docs/prd-x-ms-agentid-header.md\

Testing

• Added 64 new unit tests covering all edge cases
• All 514 existing tests continue to pass
• 3 code review iterations completed

Breaking Changes

None - fully backward compatible

[Copilot]

Pull request overview

This PR adds an x-ms-agentid header to all outbound HTTP requests from the tooling package to the MCP platform for agent identification. The header value is determined through a priority-based fallback mechanism: TurnContext agenticAppBlueprintId (highest) → token claims (xms_par_app_azp > appid > azp) → application name from environment/pyproject.toml (lowest). If no identifier is available, the header is omitted.

Changes:

• Added new utility methods for extracting agent ID from JWT tokens and reading application name from environment/pyproject.toml with thread-safe caching
• Updated MCP tooling service to include x-ms-agentid header in gateway requests with priority-based fallback logic
• Added comprehensive test coverage (64 new tests) for all edge cases and priority levels

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
libraries/microsoft-agents-a365-runtime/microsoft_agents_a365/runtime/utility.py	Added get_agent_id_from_token() for JWT claim extraction and get_application_name() with thread-safe caching
libraries/microsoft-agents-a365-tooling/microsoft_agents_a365/tooling/utils/constants.py	Added header name constants for AGENT_ID, CHANNEL_ID, and SUBCHANNEL_ID
libraries/microsoft-agents-a365-tooling/microsoft_agents_a365/tooling/services/mcp_tool_server_configuration_service.py	Updated _prepare_gateway_headers() to include x-ms-agentid and added _resolve_agent_id_for_header() method
tests/runtime/test_utility.py	Added 42 unit tests for new utility methods covering all priority levels and edge cases
tests/tooling/test_mcp_server_configuration.py	Added 22 unit tests for header preparation and agent ID resolution
docs/prd-x-ms-agentid-header.md	Added comprehensive PRD documentation explaining design decisions and implementation details

Comments suppressed due to low confidence (1)

libraries/microsoft-agents-a365-runtime/microsoft_agents_a365/runtime/utility.py:1

• The assumption that Path.cwd() returns the application root directory may not hold in all deployment scenarios (e.g., when the application is launched from a different directory, or in containerized environments). The documentation should mention this limitation and emphasize that users should rely on the AGENT365_APPLICATION_NAME environment variable for reliable behavior in production.

# Copyright (c) Microsoft Corporation.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (5)

libraries/microsoft-agents-a365-runtime/microsoft_agents_a365/runtime/utility.py:2

• Missing Microsoft copyright header. All Python files should include the standard copyright header at the top of the file.

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.

libraries/microsoft-agents-a365-tooling/microsoft_agents_a365/tooling/utils/constants.py:2

• Missing Microsoft copyright header. All Python files should include the standard copyright header at the top of the file.

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.

libraries/microsoft-agents-a365-tooling/microsoft_agents_a365/tooling/services/mcp_tool_server_configuration_service.py:2

• Missing Microsoft copyright header. All Python files should include the standard copyright header at the top of the file.

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.

tests/tooling/test_mcp_server_configuration.py:2

• Missing Microsoft copyright header. All Python files should include the standard copyright header at the top of the file.

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.

tests/runtime/test_utility.py:2

• Missing Microsoft copyright header. All Python files should include the standard copyright header at the top of the file.

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT License.