Merge pull request #339 from microsoft/users/cleemullins/ConfigurationAndErrors

Add documentation for Agentic Identity concepts and common errors

Author: cleemullins

M365AgentsAgenticIdentity.md

@@ -0,0 +1,111 @@
+# Agentic Identity with the M365 Agents SDK
+
+# Agentic Users and Terms
+To create an AI Teammate who works alongside humans, Microsoft introduced few key concepts like Agent Blueprint (AB), Agent Identity (AI), Agentic User (AU). Agentic Users are autonomous agents that want to behave like user accounts.
+
+**Agentic User** is an identity for an autonomous agent that acts like a user to access resources. Each agentic user is tied to a particular agent instance "parent", and from there to a specific Agent ID Blueprint. Agentic users support the features of normal user accounts -- they can have mailboxes and participate in chats, etc., with some small restrictions for security.
+
+**Agent ID Blueprint** is an application that holds the business logic and orchestration for an agent and has the ability to create and manage agent identities. These agent identities are tied to their parent Agent ID Blueprint and can only be managed by that specific Blueprint. 
+
+[TODO - Confirm] This value will match the Agent ID configured in the Azure Bot Service.
+
+**Agent Identity** is an app-like identity, derived from service principal that represents an autonomous agent. An Agent ID Blueprint can get tokens for its child Agent Identities through FIC impersonation. Agent Identities are single tenant, created in the tenant where the Agent ID Blueprint is installed, but a given Agent ID Blueprint can create and manage multiple Agent Identities within a single tenant.
+
+**Agentic Instance ID**
+
+**Agentic Instance Token**
+
+# Sample Agentic Agents 
+
+# Agentic Configuration Settings
+## Python
+## C#
+## Javascript
+
+# Common Configuration Errors
+
+## context.identity is required for agentic activities
+
+## Missing MSAL Configuration
+
+## Missing Agent Instance ID
+
+## Agentic user not configured
+
+## IAgenticTokenProvider Not Found
+
+# Common MSAL Errors
+
+## Failed to obtain token
+
+## Undefined Agent Application Instance ID
+
+## Failed to acquire agentic instance token
+
+## Failed to acquire token
+
+## Agent application instance Id and agentic user Id must be provided
+
+## Failed to acquire token for client - no payload
+
+## Unable to retrieve agentic user token
+
+# Appendix 1 - Linking to this document. 
+This document is deep linked from the M365 Agents SDK. When errors / exceptions are generated, those exceptions contains aka.ms links that deep link into the sections here. 
+
+This means the names used in the section headers are fragile. The algorithm for deeplinking into a GitHub document is:
+1. Identify the Header ID: GitHub automatically generates an ID for each header in a Markdown file. This ID is derived from the header text by lowercasing it, replacing spaces with hyphens, and removing special characters.
+    * For a header like `# My Section`, the ID would be my-section
+    * For a header like `## Another Great Section!`, the ID would be another-great-section.
+1. Construct the Link: Use standard Markdown link syntax with the header ID as the destination, prefixed by a hash (#).
+
+## Appendix 2 - Links (Autogenerated via GitHub Copilot)
+
+The following GitHub Copilot prompt is used to generate the deep links that are listed below. Claude 4.5 was used inside VS Code for the generation. 
+```
+https://github.com/microsoft/Agents/blob/users/cleemullins/ConfigurationAndErrors/M365AgentsAgenticIdentity.md
+
+Analyze the top level and second level headers of this document. Generate URL's I can use to deeplink into each section.
+
+The rules for generating those deeplinks are found in "Appendix 1". Exclude all appendix from the list of generated deeplinks.
+
+The format for the URLs should be:
+
+https://github.com/microsoft/Agents/blob/{BranchName}/M365AgentsAgenticIdentity.md#TagName
+
+The branchname in the template above is "users/cleemullins/ConfigurationAndErrors"
+
+In the example above "TagName" is generated as part of this prompt. Emit this as markdown suitable for pasting into the document in Appendix 2. 
+```
+
+### Top-Level Headers
+
+- [Agentic Identity with the M365 Agents SDK](https://aka.ms/M365AgentsErrorCodes/#agentic-identity-with-the-m365-agents-sdk)
+- [Agentic Users and Terms](https://aka.ms/M365AgentsErrorCodes/#agentic-users-and-terms)
+- [Sample Agentic Agents](https://aka.ms/M365AgentsErrorCodes/#sample-agentic-agents)
+- [Agentic Configuration Settings](https://aka.ms/M365AgentsErrorCodes/#agentic-configuration-settings)
+- [Common Configuration Errors](https://aka.ms/M365AgentsErrorCodes/#common-configuration-errors)
+- [Common MSAL Errors](https://aka.ms/M365AgentsErrorCodes/#common-msal-errors)
+
+### Second-Level Headers
+
+#### Agentic Configuration Settings
+- [Python](https://aka.ms/M365AgentsErrorCodes/#python)
+- [C#](https://aka.ms/M365AgentsErrorCodes/#c)
+- [Javascript](https://aka.ms/M365AgentsErrorCodes/#javascript)
+
+#### Common Configuration Errors
+- [context.identity is required for agentic activities](https://aka.ms/M365AgentsErrorCodes/#contextidentity-is-required-for-agentic-activities)
+- [Missing MSAL Configuration](https://aka.ms/M365AgentsErrorCodes/#missing-msal-configuration)
+- [Missing Agent Instance ID](https://aka.ms/M365AgentsErrorCodes/#missing-agent-instance-id)
+- [Agentic user not configured](https://aka.ms/M365AgentsErrorCodes/#agentic-user-not-configured)
+- [IAgenticTokenProvider Not Found](https://aka.ms/M365AgentsErrorCodes/#iagentictokenprovider-not-found)
+
+#### Common MSAL Errors
+- [Failed to obtain token](https://aka.ms/M365AgentsErrorCodes/#failed-to-obtain-token)
+- [Undefined Agent Application Instance ID](https://aka.ms/M365AgentsErrorCodes/#undefined-agent-application-instance-id)
+- [Failed to acquire agentic instance token](https://aka.ms/M365AgentsErrorCodes/#failed-to-acquire-agentic-instance-token)
+- [Failed to acquire token](https://aka.ms/M365AgentsErrorCodes/#failed-to-acquire-token)
+- [Agent application instance Id and agentic user Id must be provided](https://aka.ms/M365AgentsErrorCodes/#agent-application-instance-id-and-agentic-user-id-must-be-provided)
+- [Failed to acquire token for client - no payload](https://aka.ms/M365AgentsErrorCodes/#failed-to-acquire-token-for-client---no-payload)
+- [Unable to retrieve agentic user token](https://aka.ms/M365AgentsErrorCodes/#unable-to-retrieve-agentic-user-token)