Use AgenticIdentity as Python Agent 365 SDK scope

[heyitsaamir]

Summary

Use AgenticIdentity as the Python Agent 365 operation scope for requests, proactive sends, and scoped API clients.

Why

Agent 365 starts from a blueprint, which can create apps, which can optionally have users. So agentic_app_blueprint_id is required, while agentic_app_id and agentic_user_id stay optional until a token flow actually needs them.

Interesting bits

• Token helpers stay specific: get_agentic_user_token and get_agentic_app_token.
• Lifecycle stays Agentic User-specific because the service events are about agentic users.
• Service wire names stay as-is, including lifecycle agenticAppInstanceId and agentIdentityBlueprintId.
• Auth diagnostics now report app_only, agentic_user, or agentic_app.

Reviewer tips

Start with the AgenticIdentity model, API client token dispatch, token manager/provider, and lifecycle value models. The main thing to watch is the intentional split between SDK-facing names and service-owned wire names.

[Copilot]

Pull request overview

This PR reintroduces AgenticIdentity as the canonical operation/request scoping concept for Agent 365 (proactive/API/auth) flows, while keeping AgenticUser as the concrete activity-facing model. The change is applied across the apps layer, API client scoping, auth provider interfaces, and supporting tests/examples.

Changes:

• Introduces AgenticIdentity as a type alias and threads agentic_identity through API scoping/auth surfaces.
• Updates API client scoping helpers/constants (AGENTIC_IDENTITY_CLEAR, from_agentic_identity, etc.) while retaining from_agentic_user wrappers.
• Migrates tests and the examples/agent365 sample to use the new agentic_identity surface.

Show a summary per file

File	Description
packages/apps/tests/test_token_manager.py	Updates token-manager tests to prefer agentic_identity and adds dispatch coverage for identity token helper.
packages/apps/tests/test_app.py	Updates proactive send/reply tests to pass agentic_identity through app and API clone scoping.
packages/apps/tests/test_app_process.py	Updates context-building test to assert scoping via agentic_identity.
packages/apps/tests/test_activity_context.py	Updates routing/context tests to scope API clones with agentic_identity.
packages/apps/src/microsoft_teams/apps/token_manager.py	Adds get_agentic_identity_token and updates token-provider dispatch/error messaging to prefer agentic_identity.
packages/apps/src/microsoft_teams/apps/routing/activity_context.py	Routes outbound sends using agentic_identity derived from inbound recipient agentic user.
packages/apps/src/microsoft_teams/apps/auth_provider.py	Renames auth-provider parameter surface to agentic_identity and routes to token-manager identity token helper.
packages/apps/src/microsoft_teams/apps/app.py	Renames proactive send/reply keyword surface to agentic_identity.
packages/apps/src/microsoft_teams/apps/app_process.py	Scopes API client creation using agentic_identity from inbound activity.
packages/apps/src/microsoft_teams/apps/activity_send.py	Scopes send_or_update_activity via agentic_identity for cloning the API client.
packages/api/tests/unit/test_user_client.py	Updates auth-provider test harnesses to accept agentic_identity.
packages/api/tests/unit/test_team_client.py	Updates team client tests to use agentic_identity scoping and auth-provider calls.
packages/api/tests/unit/test_reaction_client.py	Updates reaction client tests to use identity scoping and auth-provider calls.
packages/api/tests/unit/test_meeting_client.py	Updates meeting client tests to use identity scoping and auth-provider calls.
packages/api/tests/unit/test_conversation_client.py	Updates conversation client tests and flattened method kwargs to agentic_identity.
packages/api/tests/unit/test_bot_client.py	Updates bot token-provider test to reflect positional agentic_identity naming and auth-provider usage.
packages/api/tests/unit/test_base_client.py	Updates base-client auth harness naming/expectations to agentic_identity.
packages/api/tests/unit/test_api_client.py	Updates API client scoping/clone tests for agentic_identity and identity-clear constants.
packages/api/src/microsoft_teams/api/models/agentic_user.py	Introduces AgenticIdentity as a TypeAlias to AgenticUser and exports it.
packages/api/src/microsoft_teams/api/models/init.py	Re-exports AgenticIdentity from models.
packages/api/src/microsoft_teams/api/diagnostics/_constants.py	Renames telemetry auth-flow constant from agentic_user to agentic_identity.
packages/api/src/microsoft_teams/api/clients/conversation/client.py	Threads agentic_identity through conversation operations and scoping factory types.
packages/api/src/microsoft_teams/api/clients/conversation/activity.py	Threads agentic_identity through activity operations and scoping factory types.
packages/api/src/microsoft_teams/api/clients/bot/token_client.py	Extends bot token-provider dispatch to recognize agentic_identity keyword.
packages/api/src/microsoft_teams/api/clients/api_client.py	Renames default-scoping storage and clone surface to agentic_identity and adds identity-first helpers/constants.
packages/api/src/microsoft_teams/api/clients/_auth_provider.py	Updates the AuthProvider Protocol to agentic_identity.
packages/api/src/microsoft_teams/api/clients/init.py	Exports new identity-clear/constants/types from the clients package.
packages/api/src/microsoft_teams/api/auth/credentials.py	Updates TokenProvider typing to use agentic_identity.
examples/agent365/src/proactive.py	Updates sample to scope via agentic_identity and from_agentic_identity.
examples/agent365/README.md	Updates documentation to describe identity-based scoping with a concrete AgenticUser.

Review details

Comments suppressed due to low confidence (1)

packages/apps/src/microsoft_teams/apps/app.py:383

• App.reply overloads only accept agentic_identity. If reply previously accepted agentic_user, callers using that keyword will now fail. Consider adding agentic_user as a deprecated alias in the overload signature for backwards-compatible typing.

        *,
        service_url: Optional[str] = None,
        agentic_identity: Optional[AgenticIdentity] = None,
    ) -> SentActivity: ...

• Files reviewed: 30/30 changed files
• Comments generated: 11
• Review effort level: Lite

[corinagum]

validate agentic_user_id values here?