From 8e25c2bf0d3a2a59e3f1b4dc1a66e8d009049b7d Mon Sep 17 00:00:00 2001 From: soyalejolopez <88358406+soyalejolopez@users.noreply.github.com> Date: Tue, 15 Sep 2026 16:58:00 -0500 Subject: [PATCH] Update Agent 365 lifecycle atlas discovery Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- copilot-agent-strategy/README.md | 2 +- .../agent-365-lifecycle-atlas/CHANGELOG.md | 10 ++ .../agent-365-lifecycle-atlas/README.md | 29 ++++-- .../agent-365-lifecycle-atlas/index.html | 93 ++++++++++++++++++- 4 files changed, 120 insertions(+), 14 deletions(-) diff --git a/copilot-agent-strategy/README.md b/copilot-agent-strategy/README.md index 84d1cd5..387ded5 100644 --- a/copilot-agent-strategy/README.md +++ b/copilot-agent-strategy/README.md @@ -6,7 +6,7 @@ A curated collection of strategic tools, templates, and guides to help you plan, | Resource | Type | Description | Best For | |----------|------|-------------|----------| -| **[Agent 365 Lifecycle Atlas](./agent-365-lifecycle-atlas/)** | Interactive Architecture Atlas | Maps Agent 365 lifecycles, identity, token flows, SDK and CLI boundaries, governed MCP tooling, telemetry, administration, and public API endpoints. | Developers, architects, and administrators implementing or governing agents with Agent 365 | +| **[Agent 365 Lifecycle Atlas](./agent-365-lifecycle-atlas/)** | Interactive Architecture Atlas | Maps Agent 365 lifecycles, discovery and inventory, identity, token flows, SDK and CLI boundaries, governed MCP tooling, telemetry, administration, and public API endpoints. | Developers, architects, and administrators implementing or governing agents with Agent 365 | | **[Copilot Agents Guide](./copilot-agents-guide/)** | Interactive Dashboard | Comprehensive comparison of all Microsoft Copilot agent types with decision frameworks, capabilities matrix, and deployment guidance. Includes Researcher & Analyst, Lite, Full Custom, SharePoint, Declarative, and Toolkit options. | Business decision makers, IT leadership, solution architects planning agent strategy | | **[Agent Brainstorming Template](./copilot-agent-brainstorm/)** | PowerPoint | Visual template to map out agent specifications before building. Choose your agent type (SharePoint, Declarative, or Custom), map user interactions, identify knowledge sources, and plan agent flow. | Product managers, developers, business analysts designing specific agents | | **[Agents Cost Calculator](./copilot-agents-cost-tool/)** | Interactive Calculator | Estimate production costs for M365 Copilot agents — Custom (Copilot Studio), Agent Builder, SharePoint, and Azure Foundry agents. Includes quick-start templates, credit/token modeling, capacity tracking, and CSV export. | Finance, IT leadership, solution architects estimating agent costs | diff --git a/copilot-agent-strategy/agent-365-lifecycle-atlas/CHANGELOG.md b/copilot-agent-strategy/agent-365-lifecycle-atlas/CHANGELOG.md index c513701..5d4fb0e 100644 --- a/copilot-agent-strategy/agent-365-lifecycle-atlas/CHANGELOG.md +++ b/copilot-agent-strategy/agent-365-lifecycle-atlas/CHANGELOG.md @@ -2,6 +2,16 @@ All notable changes to the Agent 365 Lifecycle Atlas are documented here. +## 1.1.0 - 2026-09-15 + +- Expanded the whole-system map with connected-platform registry ingestion, + Agent Map inventory, and a separate Shadow AI governance lane. +- Added two discovery and inventory diagrams, bringing the atlas to eleven. +- Clarified that connected-platform synchronization is currently manual and + metadata-only, with scheduled synchronization listed as a future release. +- Added documented external platform categories and examples. +- Preserved the existing 18-endpoint catalog and linked public Learn sources. + ## 1.0.0 - 2026-09-10 - Published the initial public interactive atlas. diff --git a/copilot-agent-strategy/agent-365-lifecycle-atlas/README.md b/copilot-agent-strategy/agent-365-lifecycle-atlas/README.md index c2f81f0..74131b8 100644 --- a/copilot-agent-strategy/agent-365-lifecycle-atlas/README.md +++ b/copilot-agent-strategy/agent-365-lifecycle-atlas/README.md @@ -3,12 +3,12 @@ title: Agent 365 Lifecycle Atlas type: strategy category: Interactive summary: >- - Explore Agent 365 lifecycles, identity, tooling, telemetry, admin actions, and - 18 public API endpoints in one atlas. + Explore Agent 365 lifecycles, discovery, identity, tooling, telemetry, admin + actions, and 18 public API endpoints in one atlas. author: Alejandro Lopez -version: 1.0.0 +version: 1.1.0 published: "2026-09-10" -updated: "2026-09-10" +updated: "2026-09-15" tags: - agent-365 - architecture @@ -23,6 +23,7 @@ whatItIs: >- and third-party platforms. whyUseIt: - Follow five agent classes through build, connection, identity, packaging, runtime, and governance. + - Distinguish registry ingestion, Agent Map inventory, and Shadow AI discovery boundaries. - Trace Agent 365 identity, token, SDK, CLI, MCP, telemetry, and administration relationships. - Search and filter 18 representative public API endpoints with linked Microsoft Learn sources. howToUse: >- @@ -43,8 +44,10 @@ run, and which governance and observability interfaces apply at each stage. ## What the atlas covers -- Nine linked architecture and sequence diagrams +- Eleven linked architecture and sequence diagrams - Five agent classes across six lifecycle stages +- Native onboarding and connected-platform registry ingestion +- Agent Map inventory and the separate Shadow AI discovery experience - Entra agent identity objects and token exchanges - Agent 365 SDK and CLI boundaries - Governed MCP tooling and telemetry flows @@ -55,6 +58,16 @@ The atlas keeps generally available, preview, and beta capabilities visibly separate. Preview and beta details must be checked against current Microsoft documentation for the target tenant, cloud, and scenario before implementation. +## September 15, 2026 update + +This update adds a discovery and inventory section to the atlas. It distinguishes +native Agent 365 onboarding from connected-platform metadata synchronization, +shows Agent Map as a registry-backed visual inventory, and keeps Shadow AI in a +separate unmanaged-agent governance lane. Connected-platform synchronization is +manual in the currently documented preview; scheduled synchronization is a +future release. The diagrams also identify the documented external platform +categories and their current examples. + ## Usage Open [`index.html`](./index.html) in a modern browser. No server, build process, @@ -74,9 +87,9 @@ Use the page to: ## Sources and scope The content is compiled from the public Microsoft Learn sources linked inside -the atlas and was reviewed on September 10, 2026. It is an architecture -reference, not a deploy-ready configuration or an official product -specification. +the atlas. The full atlas was reviewed on September 10, 2026, and the discovery +and inventory update was reviewed on September 15, 2026. It is an architecture +reference, not a deploy-ready configuration or an official product specification. ## Applies To diff --git a/copilot-agent-strategy/agent-365-lifecycle-atlas/index.html b/copilot-agent-strategy/agent-365-lifecycle-atlas/index.html index 61cb3d1..5020bc3 100644 --- a/copilot-agent-strategy/agent-365-lifecycle-atlas/index.html +++ b/copilot-agent-strategy/agent-365-lifecycle-atlas/index.html @@ -219,10 +219,10 @@ }); }); })(); -
Agent 365 · Lifecycle Atlas
Developer & administrator reference

Microsoft Agent 365 — agent lifecycles, interfaces & APIs

Agent 365 is the governance and control plane for agents — it inventories, secures, governs, and observes agents built on Microsoft and third-party platforms. It is not an agent-building runtime. This atlas maps how each class of agent is built, connected, identified, deployed, governed, and observed, with the exact interfaces, SDKs, CLI commands, token flows, and API endpoints that developers and admins use at each step.

Public · Microsoft LearnAgent 365 GA 2026-05-01Research cutoff 2026-09-10Several capabilities remain preview
00

The whole system — Agent 365 in one picture

One connected view: how agents enter Agent 365, how they are configured and given identity, the unified control plane that inventories and governs them, and the runtime that keeps executing on its own host. The eight detailed diagrams below expand each part — select any node to jump to its section. Agent 365 governs; it does not host or run agents, and no single action cascades across the others.

ComponentAgent 365 surfacePlatform-hosted runtimePreview
Fit to width
- +
Agent 365 · Lifecycle Atlas
Developer & administrator reference

Microsoft Agent 365 — agent lifecycles, interfaces & APIs

Agent 365 is the governance and control plane for agents — it inventories, secures, governs, and observes agents built on Microsoft and third-party platforms. It is not an agent-building runtime. This atlas maps how each class of agent is built, connected, identified, deployed, governed, and observed, with the exact interfaces, SDKs, CLI commands, token flows, and API endpoints that developers and admins use at each step.

Public · Microsoft LearnAgent 365 GA 2026-05-01Research cutoff 2026-09-10Several capabilities remain preview
00

The whole system — Agent 365 in one picture

One connected view: how agents enter Agent 365, how they are configured and given identity, the unified control plane that inventories and governs them, and the runtime that keeps executing on its own host. The detailed diagrams below expand each part — select any node to jump to its section, including a new discovery & inventory view (§02A). Agent 365 governs; it does not host or run agents, and no single action cascades across the others.

ComponentAgent 365 surfacePlatform-hosted runtimePreview
Fit to width
+ Agent 365 whole-system architecture -Left to right: four entry routes (built-in platform agents; manifest ZIP upload; connected-platform sync, in preview; and custom-coded agents) each pass through their own configure-and-identify card — platform-managed integration (no SDK needed for inventory), admin upload and approval (catalog availability, separate from code hosting), connected-platform sync (metadata only), and the Agent 365 SDK and CLI with an Entra Agent ID for custom integration. Distinct connectors route them into the central Agent 365 registry and control plane, a unified inventory of distinct objects: the registry record, the package or catalog entry, and the identity blueprint reference. The control plane exposes right-hand surfaces: Registry UI with Microsoft Graph inventory and selected governance actions, Microsoft Entra, and Microsoft Defender with Purview, plus independent operations that do not cascade across objects. A separate runtime plane along the bottom runs the agent on its own platform, Azure, or partner host, using governed MCP tools and WorkIQ in preview to reach downstream Microsoft 365 services; the control plane governs it and receives telemetry back. +Left to right: four entry routes (built-in platform agents; manifest ZIP upload; connected-platform sync, in preview; and custom-coded agents) each pass through their own configure-and-identify card — platform-managed integration (no SDK needed for inventory), admin upload and approval (catalog availability, separate from code hosting), connected-platform sync (metadata only), and the Agent 365 SDK and CLI with an Entra Agent ID for custom integration. Distinct connectors route them into the central Agent 365 registry and control plane, a unified inventory of distinct objects: the registry record, the package or catalog entry, and the identity blueprint reference. The control plane exposes right-hand surfaces: Registry UI with Microsoft Graph inventory and selected governance actions, Microsoft Entra, and Microsoft Defender with Purview, plus independent operations that do not cascade across objects. A separate runtime plane along the bottom runs the agent on its own platform, Azure, or partner host, using governed MCP tools and WorkIQ in preview to reach downstream Microsoft 365 services; the control plane governs it and receives telemetry back. A bottom administrator-surfaces band adds two separate experiences: an Agent Map visual inventory that reads the registry, and a separate Agents-Shadow-AI lane for detecting unmanaged agents (Defender for Endpoint detection, Intune blocking on managed Windows, optional Global Secure Access enrichment) that is documented as a separate discovery experience, not a registry ingestion path. Sources & entry routes Configure & identify @@ -345,7 +345,90 @@ Downstream Microsoft 365 services Graph, mail, files and more — reached onlyunder governance. Activity emits telemetrythat surfaces back in the control plane andin Defender & Purview. -

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.

01

Lifecycle overview — five agent classes, six stages

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 no action cascades across stages automatically.

Standard stepAgent 365 connection pointPlatform-managed / no own controlPreview
Build / AcquireConnect to Agent365IdentityCapabilities &PackageDeploy / RuntimeGovern & OperateAgent Builder /DeclarativeHosted on CopilotAgent Builder in M365 Copilot;or pro-code declarative package(M365 Agents Toolkit)Built-in integrationUses Copilot identity; no ownblueprintShare or submit package; adminreview / requestCopilot model & orchestrator; noown runtimeAdmin center: publish, install,pin, block, delete (files + SPEcontainer)Copilot StudioMaker + ALMDesign: instructions, topics,knowledge, actionsBuilt-in integrationPlatform-managed identityPower Platform ALM: Dev to Testto Prod; publish channelPublish to Teams & Copilot; orupload custom agent ZIPAdmin center: inventory, block,reassign ownerMicrosoftFoundryAzure computeBuild / configure Foundry agentBuilt-in (hosted) OR Agent 365SDK (code path)Built-in, or agent identity viaSDKObservability; optional MCP;publish package separatelyDeploy on Foundry / Azurecompute (distinct runtime)Block package AND start/stopAzure compute (Azure AI Owner)Custom /SDK-ownedYou hostExisting runtime: M365 AgentsSDK, Agent Framework, OpenAI,LangChain, CrewAI, LlamaIndex,customAgent 365 SDK + a365 CLIEntra blueprint to principal toagent identity; declare perms +admin consentIdentity, Observability, Work IQMCP, Notifications; a365 publish= ZIP onlyDeploy to Azure / AWS / GCP /on-prem; SDK does not hostRegistry, Entra, Defender,PurviewExternalregistry syncMetadata onlyPREVIEWVertex AI / Amazon Bedrockagent, built externallyPREVIEWRegistry synchronizationNo blueprint or SDK required;metadata onlyImports metadata for visibility& governanceRuns on external platform;runtime not instrumentedInventory & governancevisibility only

Wide diagram — scroll horizontally within the frame to see all six stages. Detailed per-class flows follow below.

02

Per-class lifecycle detail

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.

A · Agent Builder & declarative agents Hosted on Copilot

Declarative agents use Copilot’s built-in model and orchestrator; they add instructions, knowledge, and actions and need no separate model hosting.

  1. Maker creates a declarative agent in Agent Builder (Microsoft 365 Copilot), or builds a pro-code declarative package with the Microsoft 365 Agents Toolkit (optionally Work IQ Dev Tools preview).
  2. Share for personal/shared availability, or submit/request for organizational use.
  3. Microsoft 365 admin center reviews the request and publishes to the Agent Store or rejects it.
  4. Install / assign to users or groups (may include admin consent); pin, block/unblock, manage owners.
Distinct actions: Publish to store makes an approved package available; install/deploy assigns it to users; pin only changes discoverability; block prevents use with platform-varying effects; delete is irreversible and removes the agent’s files and its SharePoint Embedded container. Do not generalize that delete cascade to other platforms.
B · Copilot Studio agents Maker + ALM
  1. Design in Copilot Studio: instructions, topics, knowledge, actions, connectors and APIs; optionally Work IQ MCP tools preview.
  2. Power Platform ALM moves the agent across Development, Test, and Production environments.
  3. Publish / channel package to Teams and Microsoft Copilot, or download the ZIP package.
  4. Reach Agent 365 through built-in integration; or upload the ZIP via Agents → All agents → Upload custom agent.
  5. Admin center: inventory, review permissions, publish/install/assign, block/unblock, reassign owner.
Guidance: Copilot Studio has built-in Agent 365 integration — do not add the Agent 365 SDK merely to create a registry entry. Use the SDK only for code-level capabilities the platform path does not supply.
C · Microsoft Foundry agents Azure compute
  1. Build/configure a Foundry agent: a hosted path (built-in integration where supported) or a code-based path (Agent 365 SDK for code-level capabilities).
  2. Registry / inventory picks up the agent.
  3. Configure Agent 365 observability collection; optional Work IQ or custom MCP tools preview.
  4. Deploy through Foundry / Azure; publish a package/channel separately if required.
Do not merge these controls: Block is a Microsoft 365 availability/governance action. Stop deallocates the underlying Azure compute and is unique to Foundry agents (requires Azure AI Owner) — it is not a catalog status change.
D · Custom & third-party code-owned agents SDK + CLI

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.

  1. Choose the integration: already integrated by platform/partner (built-in); Vertex AI / Bedrock (registry sync preview); otherwise Agent 365 SDK + CLI.
  2. Register the identity foundation: create the Entra agent identity blueprint, create a blueprint principal where required, configure credentials/federation, declare permissions, obtain admin consent, create the agent identity.
  3. Add capabilities: Identity, Observability, Work IQ MCP preview, Notifications Frontier preview when an agent user is required.
  4. Validate: identity/token mode, permissions and consent, root invoke_agent span, MCP discovery/tool invocation, notification routing.
  5. Deploy the runtime to Azure / AWS / GCP / on-premises — the SDK does not host or deploy it.
  6. Optionally package and publish to Microsoft 365; operate through Agent Registry, Entra, Defender, Purview.
a365 publish prepares IDs in manifest.json and creates manifest.zip. It does not prove the package was approved, uploaded, installed, or assigned in the tenant — those are separate operations.
E · Template agents & user-created instances Preview
  1. A template/blueprint agent appears in Agent 365.
  2. A user requests activation, or an admin proactively selects scope.
  3. Admin approves and activates for specific users, groups, or the tenant.
  4. An authorized user creates an agent instance, which receives tenant-local identity/resources.
  5. Runtime operation and monitoring; instance-level block or delete.
Instance semantics: Activate lets authorized users instantiate a template; block instance stops access to that instance; delete instance starts documented account/data handling (temporary access to OneDrive and Outlook data before permanent deletion) — distinct from deleting an Agent Builder package.
03

Identity objects & relationships

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.

CREDENTIAL & IDENTITYRUNTIME IDENTITYMETADATA & CATALOGAgent identity blueprintEntra application object id + appId.Reusable definition and credentialboundary.Blueprint principalService principal id + appId.Tenant-local enterprise application.SponsorUser or group. Required accountable ownerfor each blueprint and agent identity.Agent identitySP object id + agent appId.servicePrincipalType = ServiceIdentity.PREVIEWAgent user accountEntra user id / UPN. Mailbox, OneDrive, Teamspresence.PREVIEWAgent registrationagentRegistration.id, sourceAgentId, managedByAppId.May reference agentIdentityId +agentIdentityBlueprintId as distinct objects.Copilot packagePackage id, manifest id, app id, asset id. Catalogrecord for inventory, deployment, blocking,ownership.OwnerUser ids or managing app id. Registry registrationrequires owners or a managing app.1 : 11 : * createsshared credentials0 : 1referencesaccountableowns / manages
Permission inheritance: a blueprint can declare baseline Microsoft Graph / API permissions inherited by its agent identities, but declaring a permission does not grant it — tenant admin consent is still required. Instance-specific permissions can be assigned directly to an agent identity.
Azure RBAC: cannot be placed on the blueprint. Assign Azure roles to each individual agent identity. Blueprint credentials are shared by all identities created from it, so treat each blueprint as a credential boundary.

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.

04

Runtime token flows

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.

S2S · autonomous · app-only

Agent runtimeMicrosoft Entra ID (STS)Agent 365 / downstreamresource1Authenticate with blueprint credential/ federation2Token T1 (blueprint-authenticated)3Exchange T1 for Agent 365 resourcetoken, as agent identity4Resource token: appid / azp = agentidentity appId; app roles in rolesclaim5Call downstream / observabilityService endpoint (app-only)Two-step: the blueprint authenticates, but the resulting resource token subject (appid / azp) is the AGENTIDENTITY appId, not the blueprint appId. Use for scheduled, event-driven, monitoring, or background work with nosigned-in human.

On-behalf-of · delegated user

User / front endAgent runtimeMicrosoft Entra IDDownstream / Work IQ1User signs in; front end sends usertoken Tc2OBO exchange: blueprint T1 + incominguser token Tc3Delegated token: subject = user, actor= agent identity, scp scopes4Call with delegated token, constrained by user + agent permissionsUser remains the token subject; the agent identity is the actor. This is the primary documented mode for Work IQ MCP access. Delegated scopes appear in thescp claim.

Agentic-User Frontier preview

Agent identityAgent user accountMicrosoft 365 workloads1Act through associated agent useraccount2Mailbox, OneDrive, Teams presence, Word& Outlook interactionsFrontier preview. The acting account is the agent’s OWN user account (not the human caller), so user resourcesand licensing apply. The registered Agent 365 identity is unchanged. Not equivalent to S2S.
05

SDKs, tooling & the a365 CLI

Two Microsoft SDKs are routinely confused. They are different products with different jobs, and can be combined.

Microsoft Agent 365 SDK

Adds identity, observability, governed MCP tooling, and notifications to an existing agent. It does not host or deploy the agent.

Package ecosystems

  • Python / PyPI
  • JavaScript / TypeScript / NPM
  • .NET / NuGet

Capability modules

CapabilityRepresentative package families
Notificationsmicrosoft-agents-a365-notifications · @microsoft/agents-a365-notifications · Microsoft.Agents.A365.Notifications
Observabilitymicrosoft-agents-a365-observability-* · @microsoft/agents-a365-observability · Microsoft.Agents.A365.Observability*
Runtime / auth / discoverymicrosoft-agents-a365-runtime · @microsoft/agents-a365-runtime · Microsoft.Agents.A365.Runtime
MCP toolingmicrosoft-agents-a365-tooling · @microsoft/agents-a365-tooling · Microsoft.Agents.A365.Tooling
Framework adaptersAgent Framework, OpenAI, LangChain, Semantic Kernel, Claude, Azure AI Foundry (by language)
For new observability-only integrations Microsoft recommends the Microsoft OpenTelemetry Distro; the earlier Observability SDK still works, and direct OTel targets existing OTel pipelines or unsupported languages such as Java.

Microsoft 365 Agents SDK

A different product: it builds and hosts conversational agents.

  • Builds conversational agents
  • Handles activity / message delivery and conversation state
  • Targets Teams, Microsoft 365 Copilot, web, and custom apps
  • Documented samples in .NET, JavaScript / Node.js, and Python
  • Can be combined with the Agent 365 SDK
Context7 resolved this SDK as /microsoft/agents and did not expose a separate Agent 365 SDK documentation library — another reason not to conflate the two.

Framework reach (Agent 365 SDK adopters)

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.

Agent 365 CLI

Install and verify:

dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli + + +Administrator discovery & inventory surfaces +Managed inventory drawn from the registry, plus a separate experience for detecting agents you did not onboard. See §02A. +Go to section 02A — Discovery & inventory + +Agent Map — visual agent inventory +Clusters onboarded agents by platform; filters & at-risk / ownerless / unmanaged cards.Visual inventory surface over the registry. E7 (Agent 365); Global or AI Admin. + +boundary +Go to section 02A — Discovery & inventory + +PREVIEW +Agents ▸ Shadow AI — unmanaged-agent detection +Separate experience: Defender detects · Intune blocks (managed Windows) · GSA enriches usage (optional).Separate discovery experience — not a documented registry ingestion path; no auto-onboarding. +

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.

01

Lifecycle overview — five agent classes, six stages

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 no action cascades across stages automatically.

Standard stepAgent 365 connection pointPlatform-managed / no own controlPreview
Build / AcquireConnect to Agent365IdentityCapabilities &PackageDeploy / RuntimeGovern & OperateAgent Builder /DeclarativeHosted on CopilotAgent Builder in M365 Copilot;or pro-code declarative package(M365 Agents Toolkit)Built-in integrationUses Copilot identity; no ownblueprintShare or submit package; adminreview / requestCopilot model & orchestrator; noown runtimeAdmin center: publish, install,pin, block, delete (files + SPEcontainer)Copilot StudioMaker + ALMDesign: instructions, topics,knowledge, actionsBuilt-in integrationPlatform-managed identityPower Platform ALM: Dev to Testto Prod; publish channelPublish to Teams & Copilot; orupload custom agent ZIPAdmin center: inventory, block,reassign ownerMicrosoftFoundryAzure computeBuild / configure Foundry agentBuilt-in (hosted) OR Agent 365SDK (code path)Built-in, or agent identity viaSDKObservability; optional MCP;publish package separatelyDeploy on Foundry / Azurecompute (distinct runtime)Block package AND start/stopAzure compute (Azure AI Owner)Custom /SDK-ownedYou hostExisting runtime: M365 AgentsSDK, Agent Framework, OpenAI,LangChain, CrewAI, LlamaIndex,customAgent 365 SDK + a365 CLIEntra blueprint to principal toagent identity; declare perms +admin consentIdentity, Observability, Work IQMCP, Notifications; a365 publish= ZIP onlyDeploy to Azure / AWS / GCP /on-prem; SDK does not hostRegistry, Entra, Defender,PurviewExternalregistry syncMetadata onlyPREVIEWVertex AI / Amazon Bedrockagent, built externallyPREVIEWRegistry synchronizationNo blueprint or SDK required;metadata onlyImports metadata for visibility& governanceRuns on external platform;runtime not instrumentedInventory & governancevisibility only

Wide diagram — scroll horizontally within the frame to see all six stages. Detailed per-class flows follow below.

02

Per-class lifecycle detail

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.

A · Agent Builder & declarative agents Hosted on Copilot

Declarative agents use Copilot’s built-in model and orchestrator; they add instructions, knowledge, and actions and need no separate model hosting.

  1. Maker creates a declarative agent in Agent Builder (Microsoft 365 Copilot), or builds a pro-code declarative package with the Microsoft 365 Agents Toolkit (optionally Work IQ Dev Tools preview).
  2. Share for personal/shared availability, or submit/request for organizational use.
  3. Microsoft 365 admin center reviews the request and publishes to the Agent Store or rejects it.
  4. Install / assign to users or groups (may include admin consent); pin, block/unblock, manage owners.
Distinct actions: Publish to store makes an approved package available; install/deploy assigns it to users; pin only changes discoverability; block prevents use with platform-varying effects; delete is irreversible and removes the agent’s files and its SharePoint Embedded container. Do not generalize that delete cascade to other platforms.
B · Copilot Studio agents Maker + ALM
  1. Design in Copilot Studio: instructions, topics, knowledge, actions, connectors and APIs; optionally Work IQ MCP tools preview.
  2. Power Platform ALM moves the agent across Development, Test, and Production environments.
  3. Publish / channel package to Teams and Microsoft Copilot, or download the ZIP package.
  4. Reach Agent 365 through built-in integration; or upload the ZIP via Agents → All agents → Upload custom agent.
  5. Admin center: inventory, review permissions, publish/install/assign, block/unblock, reassign owner.
Guidance: Copilot Studio has built-in Agent 365 integration — do not add the Agent 365 SDK merely to create a registry entry. Use the SDK only for code-level capabilities the platform path does not supply.
C · Microsoft Foundry agents Azure compute
  1. Build/configure a Foundry agent: a hosted path (built-in integration where supported) or a code-based path (Agent 365 SDK for code-level capabilities).
  2. Registry / inventory picks up the agent.
  3. Configure Agent 365 observability collection; optional Work IQ or custom MCP tools preview.
  4. Deploy through Foundry / Azure; publish a package/channel separately if required.
Do not merge these controls: Block is a Microsoft 365 availability/governance action. Stop deallocates the underlying Azure compute and is unique to Foundry agents (requires Azure AI Owner) — it is not a catalog status change.
D · Custom & third-party code-owned agents SDK + CLI

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.

  1. Choose the integration: already integrated by platform/partner (built-in); Vertex AI / Bedrock (registry sync preview); otherwise Agent 365 SDK + CLI.
  2. Register the identity foundation: create the Entra agent identity blueprint, create a blueprint principal where required, configure credentials/federation, declare permissions, obtain admin consent, create the agent identity.
  3. Add capabilities: Identity, Observability, Work IQ MCP preview, Notifications Frontier preview when an agent user is required.
  4. Validate: identity/token mode, permissions and consent, root invoke_agent span, MCP discovery/tool invocation, notification routing.
  5. Deploy the runtime to Azure / AWS / GCP / on-premises — the SDK does not host or deploy it.
  6. Optionally package and publish to Microsoft 365; operate through Agent Registry, Entra, Defender, Purview.
a365 publish prepares IDs in manifest.json and creates manifest.zip. It does not prove the package was approved, uploaded, installed, or assigned in the tenant — those are separate operations.
E · Template agents & user-created instances Preview
  1. A template/blueprint agent appears in Agent 365.
  2. A user requests activation, or an admin proactively selects scope.
  3. Admin approves and activates for specific users, groups, or the tenant.
  4. An authorized user creates an agent instance, which receives tenant-local identity/resources.
  5. Runtime operation and monitoring; instance-level block or delete.
Instance semantics: Activate lets authorized users instantiate a template; block instance stops access to that instance; delete instance starts documented account/data handling (temporary access to OneDrive and Outlook data before permanent deletion) — distinct from deleting an Agent Builder package.
02A

Discovery & inventory — how agents become visible

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 sync as metadata only; and unmanaged agents you never onboarded are found through a separate Shadow AI discovery experience — a separate Frontier page from All agents, not a registry ingestion path. Section added 2026-09-15 The rest of this atlas was reviewed 2026-09-10.

Agent 365 surfaceComponentComplementary / externalPreview
+Registry ingestion routes and inventory surfaces +Two documented routes place agent metadata into the Agent 365 registry: native onboarding of built-in and SDK-registered agents, and admin-triggered Connected platforms sync that imports metadata only from external platforms such as Amazon Bedrock and Google Vertex AI, with last-run status and errors monitored. The registry is a unified metadata inventory. Agent Map is a visual inventory surface over that inventory that clusters agents by platform and offers status, publisher, platform, channel and usage filters plus total, at-risk, ownerless and unmanaged cards; usage filters are limited to tenants under four thousand agents and it requires an E7 Agent 365 license and Global Administrator or AI Administrator role. The All agents list is the complementary text view. + +ENTRY ROUTES +UNIFIED REGISTRY +INVENTORY SURFACES + +Native onboarding +Built-in platform & SDK-registeredagents already recorded in the registry. + +Connected platforms sync +Connect & authenticate an externalplatform, then an admin runsSync agents. Metadata imports;monitor last run, status & errors. +Metadata only. Scheduled sync: future release. + +Agent 365 registry +Unified inventory of agentmetadata: ownership, source,status. Management actions limitedto what each platform API supports. + +Agent Map +Visual inventory; clusters by platform.Filters: Status · Publisher · Platform ·Channel · Usage. Cards: Total · At-risk ·Ownerless · Unmanaged. Export to Excel. +Usage filters: tenants < 4,000 agents.E7 (Agent 365); Global or AI Admin. + +All agents (registry list) +Text list view. Agent Map complementsit for large estates. + +recorded + +metadata + +reads + +

Registry ingestion is metadata only — sync creates no identity, telemetry or runtime instrumentation. Agent Map reads the same inventory.

+Shadow AI — separate unmanaged-agent governance +Shadow AI is a dedicated Frontier public-preview page under Agents in the Microsoft 365 admin center, separate from the All agents registry. Microsoft Defender for Endpoint detects unmanaged AI agent usage on managed devices; Global Secure Access optionally enriches usage metadata such as traffic, users and recent activity; and administrators can apply a Microsoft Intune blocking policy that stops supported agents on Intune-managed Windows devices. A marked boundary shows that Shadow AI is documented as a separate Frontier page from All agents, not a registry ingestion path; detected agents are not auto-onboarded into the Agent 365 registry or Agent Map. + +SIGNALS +SHADOW AI (FRONTIER) +ENFORCEMENT + +Managed devices +Intune-enrolled Windowsendpoints in scope. + +Defender for Endpoint +Detects local / unmanaged AIagent usage on devices.Required for detection. + +Global Secure Access +Optional. Enriches usagemetadata: traffic, users, recentactivity. Fields blank without it. + +PREVIEW +Agents ▸ Shadow AI +Dedicated page, separate fromAll agents. Review detectedagents, devices, users & traffic.E5 license; Frontier opt-in. + +Intune blocking +Blocks supported agentson managed Windowsdevices. Blocking variesby agent (e.g. OpenClaw). + + +detections + +enrich (opt.) + +block + +separate experience — boundary + +Agent 365 registry / Agent Map + +✗ +Not a documented ingestion path +

The crossed link marks the boundary: Shadow AI is documented as a separate Frontier page from All agents, not a registry ingestion path — detected agents are not auto-onboarded into the Agent 365 registry or Agent Map.

Connected platforms sync Metadata only

  • Create a connection: name, platform, region, optional auto-import, then enter & validate credentials.
  • An admin triggers Sync agents; external agents import into the registry.
  • Monitor connection sync status, last run date, last sync status, total synced agents and errors.
  • Documented platforms include Amazon Bedrock, Google Vertex AI, Salesforce Agentforce, Databricks Genie, Anthropic Claude Managed Agents and Oracle Generative AI Agents — the catalog keeps expanding.
  • Scheduled sync is a future release; sync creates no identity, telemetry or runtime wiring.

Source: Connected platforms.

Agent Map

  • Open from Agents ▸ All Agents ▸ Map — a visual inventory grouped by builder/platform.
  • Requires an E7 (Agent 365) license and a Global Administrator or AI Administrator role.
  • Cards: Total agents, Agents at risk, Agents without owners, Unmanaged agents.
  • Filters: Status, Publisher type, Platform, Channel, Usage. Export the list to Excel.
  • Usage/observability filters are limited to tenants with fewer than 4,000 agents. The Map complements the registry list.
  • Not read-only: select an agent from the map to assign an owner, block/unblock, install and pin it.

Source: Agent Map.

Agents ▸ Shadow AI Frontier preview

  • A dedicated admin page, separate from All agents, to discover, monitor and govern unmanaged agents.
  • Prerequisites: Frontier opt-in, Microsoft Defender for Endpoint (detection), Microsoft 365 E5, Intune enrollment for managed Windows, and optionally Global Secure Access for usage metadata.
  • Roles (at least one): Security Administrator, AI Administrator, Global Reader, Security Reader, Security Operator, Reports Reader, User Experience Success Manager, or Intune Administrator.
  • Detection covers agents such as OpenClaw, ChatGPT Desktop and Ollama; blocking currently applies only to supported agents on Intune-managed Windows devices.
  • Traffic, Users and recent-activity fields populate only when Global Secure Access is enabled.

Source: Understand Shadow AI.

Partner acquisition paths

  • Ready-to-deploy agents: fully built partner agents an admin can discover, deploy and manage from the admin center with no custom development.
  • Agent factories: platforms to build your own agents on Agent 365; each new agent gets a governed Entra Agent ID, appears in the admin center and inherits identity, compliance and observability controls.
  • Not everything is generally available — some integrations are marked coming soon (for example Nvidia), and AI-teammate integrations are Frontier-only.
  • The published integration catalog is the source of truth for what each partner supports (Registered, Observable, Work IQ).

Source: Ecosystem partner agents.

Boundary: Connected platforms sync writes agent metadata into the registry, and Agent Map is a visual inventory surface over that same inventory. Shadow AI is a separate discovery experience that detects agents you did not onboard; it is documented as a separate Frontier page from All agents, not a registry ingestion path, and does not auto-onboard them into the registry or Agent Map. Keep the three paths distinct when reasoning about coverage.
03

Identity objects & relationships

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.

CREDENTIAL & IDENTITYRUNTIME IDENTITYMETADATA & CATALOGAgent identity blueprintEntra application object id + appId.Reusable definition and credentialboundary.Blueprint principalService principal id + appId.Tenant-local enterprise application.SponsorUser or group. Required accountable ownerfor each blueprint and agent identity.Agent identitySP object id + agent appId.servicePrincipalType = ServiceIdentity.PREVIEWAgent user accountEntra user id / UPN. Mailbox, OneDrive, Teamspresence.PREVIEWAgent registrationagentRegistration.id, sourceAgentId, managedByAppId.May reference agentIdentityId +agentIdentityBlueprintId as distinct objects.Copilot packagePackage id, manifest id, app id, asset id. Catalogrecord for inventory, deployment, blocking,ownership.OwnerUser ids or managing app id. Registry registrationrequires owners or a managing app.1 : 11 : * createsshared credentials0 : 1referencesaccountableowns / manages
Permission inheritance: a blueprint can declare baseline Microsoft Graph / API permissions inherited by its agent identities, but declaring a permission does not grant it — tenant admin consent is still required. Instance-specific permissions can be assigned directly to an agent identity.
Azure RBAC: cannot be placed on the blueprint. Assign Azure roles to each individual agent identity. Blueprint credentials are shared by all identities created from it, so treat each blueprint as a credential boundary.

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.

04

Runtime token flows

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.

S2S · autonomous · app-only

Agent runtimeMicrosoft Entra ID (STS)Agent 365 / downstreamresource1Authenticate with blueprint credential/ federation2Token T1 (blueprint-authenticated)3Exchange T1 for Agent 365 resourcetoken, as agent identity4Resource token: appid / azp = agentidentity appId; app roles in rolesclaim5Call downstream / observabilityService endpoint (app-only)Two-step: the blueprint authenticates, but the resulting resource token subject (appid / azp) is the AGENTIDENTITY appId, not the blueprint appId. Use for scheduled, event-driven, monitoring, or background work with nosigned-in human.

On-behalf-of · delegated user

User / front endAgent runtimeMicrosoft Entra IDDownstream / Work IQ1User signs in; front end sends usertoken Tc2OBO exchange: blueprint T1 + incominguser token Tc3Delegated token: subject = user, actor= agent identity, scp scopes4Call with delegated token, constrained by user + agent permissionsUser remains the token subject; the agent identity is the actor. This is the primary documented mode for Work IQ MCP access. Delegated scopes appear in thescp claim.

Agentic-User Frontier preview

Agent identityAgent user accountMicrosoft 365 workloads1Act through associated agent useraccount2Mailbox, OneDrive, Teams presence, Word& Outlook interactionsFrontier preview. The acting account is the agent’s OWN user account (not the human caller), so user resourcesand licensing apply. The registered Agent 365 identity is unchanged. Not equivalent to S2S.
05

SDKs, tooling & the a365 CLI

Two Microsoft SDKs are routinely confused. They are different products with different jobs, and can be combined.

Microsoft Agent 365 SDK

Adds identity, observability, governed MCP tooling, and notifications to an existing agent. It does not host or deploy the agent.

Package ecosystems

  • Python / PyPI
  • JavaScript / TypeScript / NPM
  • .NET / NuGet

Capability modules

CapabilityRepresentative package families
Notificationsmicrosoft-agents-a365-notifications · @microsoft/agents-a365-notifications · Microsoft.Agents.A365.Notifications
Observabilitymicrosoft-agents-a365-observability-* · @microsoft/agents-a365-observability · Microsoft.Agents.A365.Observability*
Runtime / auth / discoverymicrosoft-agents-a365-runtime · @microsoft/agents-a365-runtime · Microsoft.Agents.A365.Runtime
MCP toolingmicrosoft-agents-a365-tooling · @microsoft/agents-a365-tooling · Microsoft.Agents.A365.Tooling
Framework adaptersAgent Framework, OpenAI, LangChain, Semantic Kernel, Claude, Azure AI Foundry (by language)
For new observability-only integrations Microsoft recommends the Microsoft OpenTelemetry Distro; the earlier Observability SDK still works, and direct OTel targets existing OTel pipelines or unsupported languages such as Java.

Microsoft 365 Agents SDK

A different product: it builds and hosts conversational agents.

  • Builds conversational agents
  • Handles activity / message delivery and conversation state
  • Targets Teams, Microsoft 365 Copilot, web, and custom apps
  • Documented samples in .NET, JavaScript / Node.js, and Python
  • Can be combined with the Agent 365 SDK
Context7 resolved this SDK as /microsoft/agents and did not expose a separate Agent 365 SDK documentation library — another reason not to conflate the two.

Framework reach (Agent 365 SDK adopters)

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.

Agent 365 CLI

Install and verify:

dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli a365 -h

Verified lifecycle command families — note that cleanup instance, cleanup blueprint, and cleanup azure target distinct resource groups. Separate commands are direct evidence that deleting one lifecycle object does not cascade into the others.

# setup a365 setup requirements a365 setup all @@ -375,7 +458,7 @@ a365 cleanup instance a365 cleanup blueprint a365 cleanup azure -a365 cleanup
AI-guided skills in the current quickstart wrap these commands: a365-setup, make-a365-agent, make-ai-teammate, instrument-observability, add-workiq-tools, test-local. They are workflow automation, not additional control-plane resources.
CLI auth: uses the Microsoft-managed enterprise application when available. Native Windows uses WAM; WSL / macOS / Linux use device code.
06

Governed MCP tooling & tool-call lifecycle

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.

MANAGEMENT PLANEMCP DATA PLANE1Developer: a365 develop list-available thenadd-mcp-servers2ToolingManifest.json declares server uniquename, OAuth scope, audience3Admin runs a365 setup all / setuppermissions mcp; Global Admin grants tenantconsent4SDK loads the configured governed MCPservers5Orchestrator discovers tools via MCP(standard tool discovery)6Framework runtime executes the tool call viaMCP (standard invocation)7Agent 365 gateway enforces server / toolpolicy8Work IQ / M365 workload performs theoperation9OpenTelemetry spans record gateway, server,and tool execution
Protocol shape: interactions are standard MCP (tool discovery and invocation). Microsoft documentation exposes a server URL, not separate REST-style /tools/list or /tools/call product endpoints. Do not invent such HTTP paths.
Work IQ: preview and delegated-user oriented — documented for OBO or Agentic-User. The onboarding quickstart does not connect Work IQ for S2S agents.

Governance facts

  • The SDK registers governed MCP servers, but the chosen framework / runtime executes the tool calls.
  • Blocking an MCP server in the admin center blocks it for users and agents tenant-wide.
  • Currently only tenant administrators can publish custom MCP servers.
  • Exact catalog scopes / audiences must be read from the generated ToolingManifest.json — do not hardcode them.
07

Observability & telemetry

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.

invoke_agentrequired root span for UI visibilitychat / model inferenceexecute_tooloutput_messagesgateway or MCP server execution

Ingestion requirements

  • Identity bindinggen_ai.agent.id must equal the authenticated app’s appId (not the Entra object id).
  • Versionapi-version=1 is mandatory for direct ingestion.
  • Request limitDirect ingestion is capped at 1 MB per request.
  • AcceptanceA 200 OK is not proof of acceptance — inspect the response results.
  • License gateWithout an assigned Microsoft 365 E7 or Agent 365 license, telemetry can be accepted at HTTP level but rejected as tenant_not_licensed.
  • Correlationgen_ai.conversation.id keys a logical run; OTel traceId correlates the span tree.
Two ingestion paths differ by auth mode — app-only uses /observabilityService/; delegated uses /observability/. Both appear in the endpoint catalog below.
08

Administration & action semantics

Identity, registration, package, runtime, Azure resources, and agent-owned data each have separate deletion and retention behavior. No deletion or block cascade should be inferred across them.

Entra identity / blueprint• Disable identity• Delete: soft-delete, 30-day restoreno cascadeRegistration metadata• Delete registration• (beta, irreversible)no cascadeCopilot package (catalog)• Block package• Reassign owner• Uninstallno cascadeRuntime / Azure compute• Stop Foundry agent• Cleanup Azure App Serviceno cascadeAgent-owned M365 data• Delete instance: OneDrive /• Outlook handling then• permanent deletion

Administrator control surfaces

PlanePrimary interfaceResponsibilities
Agent catalog / governanceMicrosoft 365 admin center → AgentsInventory, requests, publishing, install/uninstall, user/group assignment, blocking, owner management, package details
Agent identityMicrosoft Entra admin center + GraphBlueprints, principals, identities, sponsors, credentials, permissions, consent, Conditional Access, identity lifecycle
Tool governanceM365 admin center → Agents and ToolsAllow/block Work IQ and custom MCP servers; review custom server registration
Threat protectionMicrosoft DefenderAgent activity views, exposure/misconfiguration risk, suspicious activity, advanced hunting in CloudAppEvents
Data security / complianceMicrosoft PurviewDLP, audit, retention, eDiscovery, communication compliance, data security posture
Runtime infrastructureAzure / FoundryDeploy, scale, start/stop Foundry compute; Azure RBAC
Copilot Studio ALMPower Platform admin centerMove agents and actions across Dev, Test, Production; environment governance
AutomationMicrosoft GraphInventory, package details, registration metadata, identity objects, selected governance actions

Action semantics — what each action does and does not mean

ActionMeansNot equivalent to
RegisterCreate inventory metadata and/or identity objectsPublish, install, consent, or deploy code
Publish to storeAdd an approved package to the organizational catalogAssigning it to users
Install / deployMake an available agent ready for selected users/groupsStarting its external runtime
Activate templatePermit scoped users to instantiate a template agentCreating every instance automatically
Approve requestAccept a request and perform the documented activation/publicationGranting every downstream API permission
Block packagePrevent organizational use through governed host surfacesDeleting source code or every identity
Disable identityIdentity-plane restriction on the selected agent identityRemoving catalog/package metadata
Stop Foundry agentDeallocate the underlying Azure deploymentBlocking a package
UninstallRemove assignment/availability for usersDeleting the source agent
Delete registrationRemove beta registry metadata recordCascade deletion of package, runtime, identity, or data
Delete Agent Builder agentPermanently removes the agent, files, and SharePoint Embedded containerGeneral deletion behavior for all platforms
Delete Entra identity/blueprintSoft-delete the identity object for 30 daysRemoving host package or external runtime
Cleanup AzureRemove CLI-created App Service resourcesRemoving registry or Entra objects unless separately requested
09

Representative endpoint catalog

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 functionMethod & pathStatusLeast-privileged permissionSource
1Create identity blueprintPOST https://graph.microsoft.com/v1.0/applications/microsoft.graph.agentIdentityBlueprintv1.0 GADelegated or application: AgentIdentityBlueprint.Create[12]
2Create blueprint principalPOST https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipalv1.0 GAAgentIdentityBlueprintPrincipal.Create. Body uses the blueprint appId, not the application object id.[ref]
3Create agent identityPOST https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentityv1.0 GAAgentIdentity.Create.All; application alternative AgentIdentity.CreateAsManager[13]
4Enable / disable or update identityPATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}/microsoft.graph.agentIdentityv1.0 GAEnable/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]
5Delete agent identityDELETE https://graph.microsoft.com/v1.0/servicePrincipals/{id}/microsoft.graph.agentIdentityv1.0 GA · soft-delete 30dDelegated AgentIdentity.DeleteRestore.All; application also requires AgentIdentity.CreateAsManager[13]
6Delete blueprintDELETE https://graph.microsoft.com/v1.0/applications/{id}/microsoft.graph.agentIdentityBlueprintv1.0 GA · soft-delete 30dAgentIdentityBlueprint.DeleteRestore.All[12]
7Register external / custom agent metadataPOST https://graph.microsoft.com/beta/copilot/agentRegistrationsPreview · not for productionAgentRegistration.ReadWrite.All, delegated or application[15]
8Read registrationGET https://graph.microsoft.com/beta/copilot/agentRegistrations/{id}PreviewAgentRegistration.Read.All or read/write permission[14]
9Update registrationPATCH https://graph.microsoft.com/beta/copilot/agentRegistrations/{id}PreviewAgentRegistration.ReadWrite.All[14]
10Delete registrationDELETE https://graph.microsoft.com/beta/copilot/agentRegistrations/{id}Preview · irreversibleAgentRegistration.ReadWrite.All[14]
11Inventory catalog packagesGET https://graph.microsoft.com/v1.0/copilot/admin/catalog/packagesv1.0 GACopilotPackages.Read.All, delegated or application. Requires an Agent365 license.[16]
12Block packagePOST https://graph.microsoft.com/beta/copilot/admin/catalog/packages/{id}/blockBeta · delegated onlyDelegated CopilotPackages.ReadWrite.All; application not available; global commercial only.[16]
13Reassign package ownerPOST https://graph.microsoft.com/beta/copilot/admin/catalog/packages/{id}/reassignBeta · delegated onlyDelegated CopilotPackages.ReadWrite.All; application not available; global commercial only.[16]
14Ingest S2S telemetryPOST https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1Direct OTLP/HTTP+JSONApp role Agent365.Observability.OtelWrite; audience 9b975845-388f-4429-889e-eab1ef63949c. {agentId} must equal the calling agent identity appId.[11]
15Ingest delegated telemetryPOST https://agent365.svc.cloud.microsoft/observability/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1Direct OTLP/HTTP+JSONDelegated scope Agent365.Observability.OtelWrite[11]
16Check tenant telemetry eligibilityGET https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/eligibility?api-version=1Optional S2S preflightAuth per the direct OTel guide; do not infer eligibility from licensing alone.[11]
17Work IQ Mail MCP interfaceMCP https://agent365.svc.cloud.microsoft/agents/tenants/{tenantId}/servers/mcp_MailToolsPreview · MCP server URLDelegated Work IQ Mail permission on client/blueprint; exact catalog values from ToolingManifest.json. Standard MCP methods, not REST paths.[17]
18MCP Management serverMCP https://agent365.svc.cloud.microsoft/mcp/environments/{environmentId}/servers/MCPManagementPreview · MCP server URLTenant/admin configuration required; only tenant administrators can publish custom MCP servers.[17]
Legacy Agent Registry warning: the older beta surface /beta/agentRegistry/agentInstances is documented with an upcoming replacement beginning May 2026 by Agent 365-powered APIs. Do not make that legacy object model the centerpiece of a new design without verifying migration status. Package Management APIs are the current direction for inventory and governance.
10

Caveats, unknowns & conflicts

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.

1. GA does not mean every feature is GA

Agent 365 is GA, but registry sync, 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.

2. Built-in integration coverage evolves

Verify platform-specific guidance before adding the Agent 365 SDK to Copilot Studio or Foundry agents.

3. Two registry generations coexist

Legacy /beta/agentRegistry/agentInstances (replacement from May 2026), current package-management APIs, and preview /beta/copilot/agentRegistrations are different API models — not aliases.

4. Package vs registration APIs

Package management governs the organizational catalog; agentRegistration stores imported/managed metadata and an agent card. Different things.

5. No deletion cascade

Identity, registration, package, runtime, Azure resources, and agent-owned M365 data have separate deletion operations and retention behavior.

6. Block behavior differs by platform

Blocking Agent Builder / Copilot Studio agents affects Microsoft Copilot and other hosts; Foundry infrastructure may keep running unless separately stopped.

7. Work IQ is not an S2S path

In the current quickstart it requires delegated context and admin OAuth consent.

8. Agent user accounts are optional

Ordinary identity, telemetry, and many tooling scenarios need no mailbox-bearing user. Frontier preview.

9. Role requirements beyond OAuth scopes

Agent ID Developer/Administrator, Agent Registry Administrator, AI Administrator, Global Administrator, Azure Contributor, and Azure AI Owner apply to different operations.

10. Graph SDKs default to v1.0

Beta endpoints require explicit beta SDK/client configuration.

11. Observability guidance has evolved

Microsoft OpenTelemetry Distro is the recommended new-integration path; existing Observability SDK integrations remain supported.

12. Narrower national-cloud availability

Checked Agent Registration and package governance beta endpoints document global commercial support, but not GCC High, DoD, or China.

11

Sources

All sources are canonical, public Microsoft Learn documentation, reviewed on 2026-09-10.

  1. Overview of Microsoft Agent 365 — GA 2026-05-01; control-plane purpose and licensing. Public · 2026-09-10
  2. Choose an Agent 365 integration option — built-in, registry-sync, and SDK mechanisms. Public · 2026-09-10
  3. Microsoft Agent 365 SDK overview — SDK boundary, capabilities, languages, package catalog. Public · 2026-09-10
  4. Agent 365 identity — objects, cardinality, credentials, S2S/OBO/Agentic-User, sponsors. Public · 2026-09-10
  5. Quickstart: Connect an existing agent to Agent 365 — skills onboarding, runtime modes, Work IQ restrictions. Public · 2026-09-10
  6. Agents for Microsoft 365 Copilot (declarative) — declarative-agent architecture and build interfaces. Public · 2026-09-10
  7. Governance and lifecycle actions for agents — install, uninstall, block, delete, owners, Foundry start/stop. Public · 2026-09-10
  8. Agents admin guide for Microsoft 365 — custom ZIP upload, assignment, deployment, publication. Public · 2026-09-10
  9. Agent 365 CLI reference — exact command families and boundaries. Public · 2026-09-10
  10. Agent management in Microsoft 365 admin center — template activation and instance management. Public · 2026-09-10
  11. Direct OpenTelemetry integration — exact ingestion and eligibility endpoints; two-step S2S. Public · 2026-09-10
  12. Create agentIdentityBlueprint — v1.0 method and permissions. Public · 2026-09-10
  13. Create agentIdentity — v1.0 method and permissions. Public · 2026-09-10
  14. Agent Registration API overview — beta CRUD surface. Public · 2026-09-10
  15. Create agentRegistration — exact beta endpoint, schema, permissions. Public · 2026-09-10
  16. Agent 365 Package Management API overview — package inventory and governance operations. Public · 2026-09-10
  17. Work IQ MCP overview — preview status, MCP server URLs, governance, clients. Public · 2026-09-10
  18. Graph API for Agent Registry and agent details — current Agent 365 admin API direction. Public · 2026-09-10
  19. Agent 365 observability concepts — identity binding, scopes, limits, downstream surfaces. Public · 2026-09-10
  20. Install and use the Agent 365 CLI — installation, authentication application, WAM/device-code. Public · 2026-09-10
  21. Add and manage tools — ToolingManifest, CLI configuration, consent, BYO MCP lifecycle. Public · 2026-09-10

Sources: Compiled entirely from canonical, public Microsoft Learn documentation reviewed on 2026-09-10.

Status reminder: This is a public architecture reference, not a deploy-ready configuration. Every endpoint or capability marked preview or beta must be re-verified for the target tenant, cloud, and scenario before implementation.

Diagram system: Diagram Design foundation adapted. Source of all facts: Microsoft Learn. Visual language: Microsoft Fluent.