Numbered nodes ①–④ are the four entry routes. Every node links to its detailed section (§01–§11). Fit-to-width by default — use the zoom controls, or focus the map and press + / − / 0, then screenshot the whole frame.
Every agent that Agent 365 governs follows the same six-stage spine, but ownership and interfaces differ sharply by class. Read each row left to right. Build, connect, identity, packaging, runtime, and governance are independent operations — a registry record does not host code, grant permissions, or create a mailbox, and most actions do not cascade automatically. The documented exception is Entra blueprint deletion, which soft-deletes its child agent identities and their agent user accounts.
Wide diagram — scroll horizontally within the frame to see all six stages. Detailed per-class flows follow below.
Expand each class for its exact build interfaces, integration path, packaging, runtime ownership, and the admin actions that apply. Distinctions that are commonly conflated are called out explicitly.
Declarative agents use Copilot’s built-in model and orchestrator; they add instructions, knowledge, and actions and need no separate model hosting.
Any existing agent runtime — Microsoft 365 Agents SDK, Microsoft Agent Framework, OpenAI Agents SDK, Claude Agent SDK, LangChain, Semantic Kernel, CrewAI, LlamaIndex, or custom code — can adopt Agent 365 without changing its model, orchestration, or hosting.
Three separate paths make agents visible to administrators, and they must not be conflated. Agents onboarded to Agent 365 are recorded in the registry and surfaced visually by Agent Map; external platforms are brought in by admin-triggered Connected platforms / registry sync, which imports registry metadata and can expose provider-supported controls; and unmanaged agents you never onboarded are found through a separate Shadow AI discovery experience — a separate Frontier page from All agents that public admin docs do not describe as part of Connected platforms ingestion. Accuracy reviewed 2026-09-16 Public documentation conflicts are noted inline.
Numbered nodes ①–④ are the four entry routes. Every node links to its detailed section (§01–§11). Fit-to-width by default — use the zoom controls, or focus the map and press + / − / 0, then screenshot the whole frame.
Every agent that Agent 365 governs follows the same six-stage spine, but ownership and interfaces differ sharply by class. Read each row left to right. Build, connect, identity, packaging, runtime, and governance are independent operations — a registry record does not host code, grant permissions, or create a mailbox, and most actions do not cascade automatically. The documented exception is Entra blueprint deletion, which soft-deletes its child agent identities and their agent user accounts.
Wide diagram — scroll horizontally within the frame to see all six stages. Detailed per-class flows follow below.
Expand each class for its exact build interfaces, integration path, packaging, runtime ownership, and the admin actions that apply. Distinctions that are commonly conflated are called out explicitly.
Declarative agents use Copilot’s built-in model and orchestrator; they add instructions, knowledge, and actions and need no separate model hosting.
Any existing agent runtime — Microsoft 365 Agents SDK, Microsoft Agent Framework, OpenAI Agents SDK, Claude Agent SDK, LangChain, Semantic Kernel, CrewAI, LlamaIndex, or custom code — can adopt Agent 365 without changing its model, orchestration, or hosting.
Three separate paths make agents visible to administrators, and they must not be conflated. Agents onboarded to Agent 365 are recorded in the registry and surfaced visually by Agent Map; external platforms are brought in by admin-triggered Connected platforms / registry sync, which imports registry metadata and can expose provider-supported controls; and unmanaged agents you never onboarded are found through a separate Shadow AI discovery experience — a separate Frontier page from All agents that public admin docs do not describe as part of Connected platforms ingestion. Accuracy reviewed 2026-09-16 Public documentation conflicts are noted inline.
The boundary marks that Shadow AI is documented as a separate Frontier page from All agents; public admin docs do not describe it as part of Connected platforms registry ingestion.
Source: Connected platforms, Choose an integration option. See the status note.
Source: Agent Map.
Source: Understand Shadow AI.
Source: Ecosystem partner agents.
Five identity and metadata objects are routinely confused. They have separate identifiers and separate lifecycles. A blueprint is a credential boundary: one blueprint can create many tenant-local agent identities that all share its credentials. Registration and package records are metadata — they are not the identity.
Telemetry identifiers map onto these objects: gen_ai.agent.id must equal the authenticated agent’s appId (not the Entra object id); the blueprint is separately identified in telemetry by its application appId.
Three documented identity patterns. The distinction that matters for authorization and audit is who the token subject is and which appId acts. Return messages are dashed. The Agentic-User exchange follows the documented user_fic on-behalf-of flow [30].
Two Microsoft SDKs are routinely confused. They are different products with different jobs, and can be combined.
Adds identity, observability, governed MCP tooling, and notifications to an existing agent. It does not host or deploy the agent.
| Capability | Representative package families |
|---|---|
| Notifications | microsoft-agents-a365-notifications · @microsoft/agents-a365-notifications · Microsoft.Agents.A365.Notifications |
| Observability | microsoft-agents-a365-observability-* · @microsoft/agents-a365-observability · Microsoft.Agents.A365.Observability* |
| Runtime / auth / discovery | microsoft-agents-a365-runtime · @microsoft/agents-a365-runtime · Microsoft.Agents.A365.Runtime |
| MCP tooling | microsoft-agents-a365-tooling · @microsoft/agents-a365-tooling · Microsoft.Agents.A365.Tooling |
| Framework adapters | Agent Framework, OpenAI, LangChain, Semantic Kernel, Claude, Azure AI Foundry (by language) |
A different product: it supplies framework and hosting abstractions for building conversational agents; you deploy and host the runtime separately.
M365 Agents SDK, Microsoft Agent Framework, OpenAI Agents SDK, Claude Agent SDK, LangChain, Semantic Kernel, CrewAI, LlamaIndex, or custom code — any can adopt Agent 365 without changing model, orchestration, or hosting.
Install and verify:
The boundary marks that Shadow AI is documented as a separate Frontier page from All agents; public admin docs do not describe it as part of Connected platforms registry ingestion.
Connected platforms / registry sync is in Preview. Status follows Choose an Agent 365 integration option, checked 16 September 2026.
Source: Connected platforms, Choose an integration option. See the source note.
Source: Agent Map.
Source: Understand Shadow AI.
Source: Ecosystem partner agents.
Five identity and metadata objects are routinely confused. They have separate identifiers and separate lifecycles. A blueprint is a credential boundary: one blueprint can create many tenant-local agent identities that all share its credentials. Registration and package records are metadata — they are not the identity.
Telemetry identifiers map onto these objects: gen_ai.agent.id must equal the authenticated agent’s appId (not the Entra object id); the blueprint is separately identified in telemetry by its application appId.
Three documented identity patterns. The distinction that matters for authorization and audit is who the token subject is and which appId acts. Return messages are dashed. The Agentic-User exchange follows the documented user_fic on-behalf-of flow [30].
Two Microsoft SDKs are routinely confused. They are different products with different jobs, and can be combined.
Adds identity, observability, governed MCP tooling, and notifications to an existing agent. It does not host or deploy the agent.
| Capability | Representative package families |
|---|---|
| Notifications | microsoft-agents-a365-notifications · @microsoft/agents-a365-notifications · Microsoft.Agents.A365.Notifications |
| Observability | microsoft-agents-a365-observability-* · @microsoft/agents-a365-observability · Microsoft.Agents.A365.Observability* |
| Runtime / auth / discovery | microsoft-agents-a365-runtime · @microsoft/agents-a365-runtime · Microsoft.Agents.A365.Runtime |
| MCP tooling | microsoft-agents-a365-tooling · @microsoft/agents-a365-tooling · Microsoft.Agents.A365.Tooling |
| Framework adapters | Agent Framework, OpenAI, LangChain, Semantic Kernel, Claude, Azure AI Foundry (by language) |
A different product: it supplies framework and hosting abstractions for building conversational agents; you deploy and host the runtime separately.
M365 Agents SDK, Microsoft Agent Framework, OpenAI Agents SDK, Claude Agent SDK, LangChain, Semantic Kernel, CrewAI, LlamaIndex, or custom code — any can adopt Agent 365 without changing model, orchestration, or hosting.
Install and verify:
§05A — Behind a365 setup all traces exactly what setup provisions and how it binds custom code to the Entra Blueprint.
Selected lifecycle command families (not exhaustive) — note that cleanup instance, cleanup blueprint, and cleanup azure target distinct resource groups. These are separate commands for separate objects; they are not, by themselves, proof that no deletion cascades — deleting an Entra blueprint does soft-delete its child agent identities and their agent user accounts (see §08).
Read-only validation & endpoint recovery: CLI query-entra [33], messaging endpoint [35], publish [34]. All commands above are shown for reference only and are not executed by this page.
Tool access separates a management plane (declare + consent) from an MCP data plane (discover + execute). Declaring a server does not grant permission; a Global Administrator must separately grant the blueprint’s MCP permissions, and permissions take precedence over local configuration.
A valid run is an OpenTelemetry span tree with a required root. Without a valid root invoke_agent span the run is invisible to the Defender agent activity view, the admin-center activity/inventory telemetry, and Purview agent experiences — though child spans remain queryable in Defender advanced hunting.
Identity, registration, package, runtime, Azure resources, and agent-owned data each have separate deletion and retention behavior, and no single control blocks or deletes across all of them. One documented cascade is the exception: deleting an Entra blueprint (application or principal) asynchronously soft-deletes its child agent identities and their agent user accounts.
| Plane | Primary interface | Responsibilities |
|---|---|---|
| Agent catalog / governance | Microsoft 365 admin center → Agents | Inventory, requests, publishing, install/uninstall, user/group assignment, blocking, owner management, package details |
| Agent identity | Microsoft Entra admin center + Graph | Blueprints, principals, identities, sponsors, credentials, permissions, consent, Conditional Access, identity lifecycle |
| Tool governance | M365 admin center → Agents and Tools | Allow/block Work IQ and custom MCP servers; review custom server registration |
| Threat protection | Microsoft Defender | Agent activity views, exposure/misconfiguration risk, suspicious activity, advanced hunting in CloudAppEvents |
| Data security / compliance | Microsoft Purview | DLP, audit, retention, eDiscovery, communication compliance, data security posture |
| Runtime infrastructure | Azure / Foundry | Deploy, scale, start/stop Foundry compute; Azure RBAC |
| Copilot Studio ALM | Power Platform admin center | Move agents and actions across Dev, Test, Production; environment governance |
| Automation | Microsoft Graph | Inventory, package details, registration metadata, identity objects, selected governance actions |
| Action | Means | Not equivalent to |
|---|---|---|
| Register | Create inventory metadata and/or identity objects | Publish, install, consent, or deploy code |
| Publish to store | Add an approved package to the organizational catalog | Assigning it to users |
| Install / deploy | Make an available agent ready for selected users/groups | Starting its external runtime |
| Activate template | Permit scoped users to instantiate a template agent | Creating every instance automatically |
| Approve request | Accept a request and perform the documented activation/publication | Granting every downstream API permission |
| Block package | Prevent organizational use through governed host surfaces | Deleting source code or every identity |
| Disable identity | Identity-plane restriction on the selected agent identity | Removing catalog/package metadata |
| Stop Foundry agent | Deallocate the underlying Azure deployment | Blocking a package |
| Uninstall | Remove assignment/availability for users | Deleting the source agent |
| Reassign owner | Transfer ownership of a shared Agent Builder or Copilot Studio agent | Changing owners of every agent type, or moving identity credentials |
| Add / remove owners | Manage owners of an Agent Builder agent; owners have equal rights and the last owner cannot be removed | Owner management for Copilot Studio or other agent types |
| Delete registration | Remove beta registry metadata record | Cascade deletion of package, runtime, identity, or data |
| Delete Agent Builder agent | Permanently removes the agent, files, and SharePoint Embedded container | General deletion behavior for all platforms |
| Delete Entra identity/blueprint | Soft-delete the identity for 30 days; deleting a blueprint also soft-deletes its child agent identities and their agent user accounts | Removing host package or external runtime |
| Cleanup Azure | Remove CLI-created App Service resources | Removing registry or Entra objects unless separately requested |
Diagram-worthy control points rather than an exhaustive API inventory. Search by function, path, or permission; filter by status. Every path marked preview or beta must be re-verified for the tenant, cloud, and scenario before use.
| # | Lifecycle function | Method & path | Status | Least-privileged permission | Source |
|---|---|---|---|---|---|
| 1 | Create identity blueprint | POST https://graph.microsoft.com/v1.0/applications/microsoft.graph.agentIdentityBlueprint | v1.0 GA | Delegated or application: AgentIdentityBlueprint.Create | [12] |
| 2 | Create blueprint principal | POST https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal | v1.0 GA | AgentIdentityBlueprintPrincipal.Create. Body uses the blueprint appId, not the application object id. | [ref] |
| 3 | Create agent identity | POST https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentity | v1.0 GA | AgentIdentity.Create.All; application alternative AgentIdentity.CreateAsManager | [13] |
| 4 | Enable / disable or update identity | PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}/microsoft.graph.agentIdentity | v1.0 GA | Enable/disable: application AgentIdentity.EnableDisable.All AND AgentIdentity.CreateAsManager; broader AgentIdentity.ReadWrite.All; delegated EnableDisable.All. Custom security attribute changes need additional rights. Scopes are not uniform across all PATCH properties. | [ref] |
| 5 | Delete agent identity | DELETE https://graph.microsoft.com/v1.0/servicePrincipals/{id}/microsoft.graph.agentIdentity | v1.0 GA · soft-delete 30d | Delegated AgentIdentity.DeleteRestore.All; application also requires AgentIdentity.CreateAsManager | [13] |
| 6 | Delete blueprint | DELETE https://graph.microsoft.com/v1.0/applications/{id}/microsoft.graph.agentIdentityBlueprint | v1.0 GA · soft-delete 30d | AgentIdentityBlueprint.DeleteRestore.All — delete cascades: child agent identities and their agent user accounts are soft-deleted (30-day restore). [26] | [12] |
| 7 | Register external / custom agent metadata | POST https://graph.microsoft.com/beta/copilot/agentRegistrations | Preview · not for production | AgentRegistration.ReadWrite.All, delegated or application | [15] |
| 8 | Read registration | GET https://graph.microsoft.com/beta/copilot/agentRegistrations/{id} | Preview | AgentRegistration.Read.All or read/write permission | [14] |
| 9 | Update registration | PATCH https://graph.microsoft.com/beta/copilot/agentRegistrations/{id} | Preview | AgentRegistration.ReadWrite.All | [14] |
| 10 | Delete registration | DELETE https://graph.microsoft.com/beta/copilot/agentRegistrations/{id} | Preview · irreversible | AgentRegistration.ReadWrite.All | [14] |
| 11 | Inventory catalog packages | GET https://graph.microsoft.com/v1.0/copilot/admin/catalog/packages | v1.0 GA | CopilotPackages.Read.All, delegated or application. Requires an Agent365 license. | [16] |
| 12 | Block package | POST https://graph.microsoft.com/beta/copilot/admin/catalog/packages/{id}/block | Beta · delegated only | Delegated CopilotPackages.ReadWrite.All; application not available; global commercial only. | [16] |
| 13 | Reassign package owner | POST https://graph.microsoft.com/beta/copilot/admin/catalog/packages/{id}/reassign | Beta · delegated only | Delegated CopilotPackages.ReadWrite.All; application not available; global commercial only. | [16] |
| 14 | Ingest S2S telemetry | POST https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1 | Direct OTLP/HTTP+JSON | App role Agent365.Observability.OtelWrite; audience 9b975845-388f-4429-889e-eab1ef63949c. {agentId} must equal the calling agent identity appId. | [11] |
| 15 | Ingest delegated telemetry | POST https://agent365.svc.cloud.microsoft/observability/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1 | Direct OTLP/HTTP+JSON | Delegated scope Agent365.Observability.OtelWrite | [11] |
| 16 | Check tenant telemetry eligibility | GET https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/eligibility?api-version=1 | Optional S2S preflight | Auth per the direct OTel guide; do not infer eligibility from licensing alone. Intended for onboarded third-party S2S agents; a 503 response is indeterminate, not a definitive ineligible. | [11] |
| 17 | Work IQ Mail MCP interface | MCP https://agent365.svc.cloud.microsoft/agents/tenants/{tenantId}/servers/mcp_MailTools | Preview · MCP server URL | Delegated Work IQ Mail permission on client/blueprint; exact catalog values from ToolingManifest.json. Standard MCP methods, not REST paths. | [17] |
| 18 | MCP Management server | MCP https://agent365.svc.cloud.microsoft/mcp/environments/{environmentId}/servers/MCPManagement | Preview · MCP server URL | Tenant/admin configuration required; a developer with appropriate permissions can publish or submit a custom MCP server, but it stays unavailable until a tenant administrator approves it. | [17] |
This is a public architecture reference, not a deploy-ready configuration. Beta features are not supported for production. Frontier preview capabilities carry additional guardrails. Roles, OAuth permissions, licenses, and cloud availability differ by operation.
Agent 365 is GA, but the Agent Registration API, Work IQ MCP, MCP Management, package block/reassign APIs, agent user accounts, and notification-dependent AI teammate scenarios carry explicit preview limits — and the documented status of connected-platform / registry sync is itself contested across public docs (see the §02A status note).
Verify platform-specific guidance before adding the Agent 365 SDK to Copilot Studio or Foundry agents.
Legacy /beta/agentRegistry/agentInstances (replacement from May 2026), current package-management APIs, and preview /beta/copilot/agentRegistrations are different API models — not aliases.
Package management governs the organizational catalog; agentRegistration stores imported/managed metadata and an agent card. Different things.
Identity, registration, package, runtime, Azure resources, and agent-owned M365 data have separate deletion operations and retention behavior — there is no universal cross-plane cascade. The documented exception: deleting an Entra blueprint (application or principal) soft-deletes its child agent identities and their agent user accounts (30-day restore).
Blocking Agent Builder / Copilot Studio agents affects Microsoft Copilot and other hosts; Foundry infrastructure may keep running unless separately stopped.
In the current quickstart it requires delegated context and admin OAuth consent.
Ordinary identity, telemetry, and many tooling scenarios need no mailbox-bearing user. Frontier preview.
Agent ID Developer/Administrator, Agent Registry Administrator, AI Administrator, Global Administrator, Azure Contributor, and Azure AI Owner apply to different operations.
Beta endpoints require explicit beta SDK/client configuration.
Microsoft OpenTelemetry Distro is the recommended new-integration path; existing Observability SDK integrations remain supported.
Checked Agent Registration and package governance beta endpoints document global commercial support, but not GCC High, DoD, or China.
All sources are canonical, public Microsoft Learn documentation. Accuracy reviewed 2026-09-16; unresolved public documentation conflicts are noted inline. The date on each entry is when the page was checked, not a claim that Microsoft updated it that day.