Skip to main content

Agentic Identity

SDK 2.1

Agentic identity is a Teams SDK for .NET 2.1 feature. See the 2.1 announcement for the full overview.

With Agent 365, your bot can run as an AI teammate — a first-class identity in Microsoft 365 with its own mailbox, Teams presence, directory entry, and manager relationship. People @mention it, email it, and invite it to meetings, just like a human colleague.

Why it matters​

This changes how your bot interacts with APIs:

  • A traditional bot calls APIs with its own app permissions.
  • An AI teammate can call APIs with its own identity — scoped to what they can access, with actions attributed to them in audit logs.

The SDK handles the token acquisition for you. When an activity arrives in an agentic context, context.Api calls automatically use the right permissions — you don't need to change how you call the API.

Detecting an agentic context​

If you need to know whether the current turn is running in an agentic context — for logging, telemetry, or conditional logic — read the identity off the activity's Recipient:

using Microsoft.Teams.Apps;

teams.OnMessage(async (context, cancellationToken) =>
{
    var agenticIdentity = context.Activity.Recipient?.GetAgenticIdentity();

    if (agenticIdentity is not null)
    {
        context.Log.LogInformation(
            $"Acting on behalf of user {agenticIdentity.AgenticUserId} " +
            $"via app {agenticIdentity.AgenticAppId}");
    }

    // context.Api calls automatically use the right permissions
    // whether or not an agentic identity is present.
    await context.SendAsync($"You said: {context.Activity.Text}", cancellationToken);
});

GetAgenticIdentity() returns null when the turn is not agentic (a traditional bot invocation), so a simple null check is all you need to branch.

AgenticIdentity properties​

PropertyDescription
AgenticUserIdThe ID of the user the AI teammate is acting on behalf of.
AgenticAppIdThe application ID of the AI teammate.
AgenticAppBlueprintIdThe application blueprint ID for the AI teammate.
TenantIdThe tenant ID associated with the agentic identity.

Calling APIs as the AI teammate​

Because the SDK resolves the correct token per turn, you call the Teams API clients exactly as you normally would. In SDK 2.1, context.Api is already scoped from the inbound activity (including agentic identity when present), so you don't pass agentic identity separately — for example, adding a reaction:

teams.OnMessage("(?i)^react$", async (context, cancellationToken) =>
{
    var response = await context.SendAsync("Reacting to this message.", cancellationToken);

    await context.Api.Conversations.AddReactionAsync(
        context.Activity.Conversation!.Id!,
        response!.Id!,
        ReactionType.Like,
        cancellationToken: cancellationToken);
});

Setup​

To enable agentic scenarios you configure your app registration for Agent 365. No additional code or SDK configuration is required beyond the standard AzureAd authentication setup.

Next steps​