From 790882197f5e95d6ce5dfb54ed55c953856366c0 Mon Sep 17 00:00:00 2001 From: soyalejolopez <88358406+soyalejolopez@users.noreply.github.com> Date: Wed, 16 Sep 2026 11:23:31 -0500 Subject: [PATCH] docs: explain Agent 365 setup and identity binding Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../agent-365-lifecycle-atlas/CHANGELOG.md | 17 +++++++++ .../agent-365-lifecycle-atlas/README.md | 35 +++++++++++++++---- .../agent-365-lifecycle-atlas/index.html | 14 ++++++-- 3 files changed, 56 insertions(+), 10 deletions(-) diff --git a/copilot-agent-strategy/agent-365-lifecycle-atlas/CHANGELOG.md b/copilot-agent-strategy/agent-365-lifecycle-atlas/CHANGELOG.md index 23d0e9c..cb1dcee 100644 --- a/copilot-agent-strategy/agent-365-lifecycle-atlas/CHANGELOG.md +++ b/copilot-agent-strategy/agent-365-lifecycle-atlas/CHANGELOG.md @@ -2,6 +2,23 @@ All notable changes to the Agent 365 Lifecycle Atlas are documented here. +## 1.2.0 - 2026-09-16 + +- Added an SDK-adjacent section and sequence diagram for the seven stages behind + `a365 setup all`. +- Documented blueprint, child identity, credential, permission, grant, and + programmatic registration relationships. +- Clarified application ID, object ID, and Agent 365 identity mappings, + including the current CLI's child service-principal object ID behavior. +- Added representative Microsoft Graph operations, conditional project-path + synchronization behavior, production checks, and recovery guidance. +- Clarified that setup neither deploys hosted agent code nor installs an SDK, + and that host deployment is separate from ZIP publishing and administrator + availability-instance creation. +- Expanded the public bibliography from 31 to 36 sources, including pinned + public CLI implementation references reviewed on September 16, 2026, without + treating that source version as a universal installed-binary guarantee. + ## 1.1.1 - 2026-09-16 - Reconciled conflicting public documentation for connected-platform and diff --git a/copilot-agent-strategy/agent-365-lifecycle-atlas/README.md b/copilot-agent-strategy/agent-365-lifecycle-atlas/README.md index 92cc9ba..86c78d9 100644 --- a/copilot-agent-strategy/agent-365-lifecycle-atlas/README.md +++ b/copilot-agent-strategy/agent-365-lifecycle-atlas/README.md @@ -6,7 +6,7 @@ summary: >- Explore Agent 365 lifecycles, discovery, identity, tooling, telemetry, admin actions, and 18 public API endpoints in one atlas. author: Alejandro Lopez -version: 1.1.1 +version: 1.2.0 published: "2026-09-10" updated: "2026-09-16" tags: @@ -24,7 +24,7 @@ whatItIs: >- 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. + - Trace Agent 365 identity, token, SDK, CLI setup, MCP, telemetry, and administration relationships. - Search and filter 18 representative public API endpoints with linked Microsoft Learn sources. howToUse: >- Open `index.html` in a modern browser. Use the section navigation and linked @@ -44,12 +44,13 @@ run, and which governance and observability interfaces apply at each stage. ## What the atlas covers -- Eleven linked architecture and sequence diagrams +- Twelve 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 +- The seven-stage `a365 setup all` flow and custom-agent identity binding - Governed MCP tooling and telemetry flows - Administration actions and documented deletion behavior - Eighteen representative API endpoints with public Microsoft Learn sources @@ -58,6 +59,23 @@ 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 16, 2026 setup update + +This additive update explains the seven stages behind `a365 setup all`, including +the blueprint application and service principal, credentials, inheritable +permissions and grants, child identity, programmatic registration, and optional +project-path synchronization. It distinguishes application IDs from object IDs, +shows the current CLI's child service-principal object ID mapping, and links the +setup flow to the Agent 365 SDK and representative Microsoft Graph operations. + +The atlas also makes the hosting boundary explicit: setup does not deploy agent +code or install an SDK, and host deployment remains separate from publishing a +ZIP package for administrator upload and availability-instance creation. +Production guidance calls out token validation, exporter settings, source +warnings, secret protection, read-only checks, and recovery steps. The CLI +implementation references are pinned to public source reviewed on September 16, +2026; that source version is not asserted to match every installed CLI binary. + ## September 16, 2026 accuracy update This correction pass reconciles conflicting public descriptions of connected @@ -66,7 +84,8 @@ release stage. It also corrects Entra blueprint deletion behavior, the Agentic User on-behalf-of token chain, custom MCP server publishing and approval, conversation and run terminology, Agent Map limits and licensing, and the documented scope of Shadow AI discovery. The bibliography now contains 31 -public sources, with unresolved documentation conflicts called out inline. +public sources at that correction point, with unresolved documentation +conflicts called out inline. ## September 15, 2026 update @@ -97,9 +116,11 @@ Use the page to: ## Sources and scope The content is compiled from the public Microsoft Learn and Microsoft 365 -Roadmap sources linked inside the atlas. The full atlas was accuracy-reviewed on -September 16, 2026. It is an architecture reference, not a deploy-ready -configuration or an official product specification. +Roadmap sources and pinned public Agent 365 CLI implementation references linked +inside the atlas. The full atlas was accuracy-reviewed on September 16, 2026. It +is an architecture reference, not a deploy-ready configuration or an official +product specification. Validate details against the target tenant, cloud, +scenario, and installed CLI version before implementation. ## 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 6d663e5..158d5b0 100644 --- a/copilot-agent-strategy/agent-365-lifecycle-atlas/index.html +++ b/copilot-agent-strategy/agent-365-lifecycle-atlas/index.html @@ -222,7 +222,7 @@ }); }); })(); -
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-01Accuracy reviewed 2026-09-16Public doc conflicts notedSeveral 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 · 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-01Accuracy reviewed 2026-09-16Public doc conflicts notedSeveral 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 / registry sync, whose documented status is contested; 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 / registry sync (imports registry metadata and can expose provider-supported controls), 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; public admin docs do not describe it as part of Connected platforms registry ingestion. @@ -431,7 +431,7 @@ Separate experience — not Connected platforms ingestion

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.

Status note (reviewed 2026-09-16): the documented status of Connected platforms / registry sync is inconsistent across public sources, so this atlas labels it neutrally rather than asserting GA or preview. Choose an integration option (updated 2026-08-13) explicitly calls Registry sync a preview; the Connected platforms admin guide (updated 2026-08-12) applies no blanket preview label but marks the Claude Managed Agents connector as preview; Microsoft 365 Roadmap item 559615 shows the capability In development (preview targeted 2026-05, GA targeted 2026-07); and the service description (updated 2026-09-15) lists the capability without a global GA announcement. Product-level GA on 2026-05-01 does not by itself make this feature GA. Verify against current docs before relying on a specific status.

Connected platforms / registry sync Status: see note

  • Create a connection: name, platform, region, optional auto-import at setup, then enter & validate credentials.
  • An admin triggers Sync agents; external agents import into the registry. Import brings in registry metadata, and a connected integration can also perform provider-API-supported management actions (for example delete) depending on the credentials granted.
  • 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 (connector in preview) and Oracle Generative AI Agents — the catalog keeps expanding.
  • Import is admin-triggered, with optional auto-import at setup; a recurring sync schedule is not documented as available. Sync itself creates no identity, telemetry or runtime wiring.

Source: Connected platforms, Choose an integration option. See the status note.

Agent Map

  • Open from Agents ▸ All Agents ▸ Map — a visual inventory grouped by builder/platform.
  • Requires an Agent 365 entitlement (standalone or via E7) 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, Data source, Usage. Export the list to Excel.
  • The usage/observability filter scale limit is inconsistently documented — the same page states fewer than 4,000 agents in one place and fewer than 4,000 users in another; verify against current docs. The limit applies to usage filters, not to Map access.
  • Not read-only: select an agent from the map to assign an owner, block/unblock, install and pin it.

Single Agent Map Preview

  • A connected view of one agent with its top 50 users and top 50 tools over the last 7 or 30 days (30 by default).
  • Uses Agent 365 observability data; tools with an exception rate above 1% are highlighted. Knowledge signals are not included yet.
  • Preview; subject to change.

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 supports OpenClaw 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 / registry sync writes agent metadata into the registry (and can expose provider-supported controls), and Agent Map is a visual inventory surface over that same inventory. Shadow AI is a separate discovery and governance experience that detects agents you did not onboard; public admin docs describe it as a separate Frontier page from All agents and do not describe it as part of Connected platforms registry ingestion. 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. The Agentic-User exchange follows the documented user_fic on-behalf-of flow [30].

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 runtime(blueprint credential)Microsoft Entra ID (STS)Microsoft 365 workloads(as agent user)1Authenticate blueprint credential → token T12user_fic OBO: client_assertion=T1,user_federated_identity_credential=T23Resource token, subject = agent user account4Call as the agent’s own user: mailbox, OneDrive, TeamsFrontier preview. grant_type=user_fic with requested_token_use=on_behalf_of and username set to the agent user; the actingsubject is the agent’s OWN user account (not the human caller). T2 audience = agent identity; no incoming human token is used.The registered Agent 365 identity is unchanged. Not equivalent to S2S. Agent user accounts are an optional Frontier preview.
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 supplies framework and hosting abstractions for building conversational agents; you deploy and host the runtime separately.

  • 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

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).

# setup +a365 -h

§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).

# setup a365 setup requirements a365 setup all a365 setup blueprint @@ -460,7 +460,15 @@ 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 loads MCP configuration and registers tools with the agent orchestrator; the chosen framework / runtime executes the tool calls. Server definitions are registered and published through the a365 CLI / admin, not by the SDK.
  • Blocking an MCP server in the admin center blocks it for users and agents tenant-wide.
  • A developer with the appropriate permissions can publish or submit a custom MCP server, but it stays unavailable until a tenant administrator approves it. [31]
  • 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 identifies a conversation / thread, which may span multiple runs; a run is a span tree whose spans share one OTel traceId.
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, 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.

Entra identity / blueprint• Disable / delete identity• Delete: soft-delete, 30-day restore• Blueprint delete cascades to itschild identities + agent user acctsno 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
Reassign ownerTransfer ownership of a shared Agent Builder or Copilot Studio agentChanging owners of every agent type, or moving identity credentials
Add / remove ownersManage owners of an Agent Builder agent; owners have equal rights and the last owner cannot be removedOwner management for Copilot Studio or other agent types
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 for 30 days; deleting a blueprint also soft-deletes its child agent identities and their agent user accountsRemoving 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 — delete cascades: child agent identities and their agent user accounts are soft-deleted (30-day restore). [26][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. Intended for onboarded third-party S2S agents; a 503 response is indeterminate, not a definitive ineligible.[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; a developer with appropriate permissions can publish or submit a custom MCP server, but it stays unavailable until a tenant administrator approves it.[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 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).

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. Independent controls; one documented cascade

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).

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. 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.

  1. Overview of Microsoft Agent 365 — GA 2026-05-01; control-plane purpose and licensing. Public · 2026-09-16
  2. Choose an Agent 365 integration option — built-in, registry-sync, and SDK mechanisms. Public · 2026-09-16
  3. Microsoft Agent 365 SDK overview — SDK boundary, capabilities, languages, package catalog. Public · 2026-09-16
  4. Agent 365 identity — objects, cardinality, credentials, S2S/OBO/Agentic-User, sponsors. Public · 2026-09-16
  5. Quickstart: Connect an existing agent to Agent 365 — skills onboarding, runtime modes, Work IQ restrictions. Public · 2026-09-16
  6. Agents for Microsoft 365 Copilot (declarative) — declarative-agent architecture and build interfaces. Public · 2026-09-16
  7. Governance and lifecycle actions for agents — install, uninstall, block, delete, owners, Foundry start/stop. Public · 2026-09-16
  8. Agents admin guide for Microsoft 365 — custom ZIP upload, assignment, deployment, publication. Public · 2026-09-16
  9. Agent 365 CLI reference — exact command families and boundaries. Public · 2026-09-16
  10. Agent management in Microsoft 365 admin center — template activation and instance management. Public · 2026-09-16
  11. Direct OpenTelemetry integration — exact ingestion and eligibility endpoints; two-step S2S. Public · 2026-09-16
  12. Create agentIdentityBlueprint — v1.0 method and permissions. Public · 2026-09-16
  13. Create agentIdentity — v1.0 method and permissions. Public · 2026-09-16
  14. Agent Registration API overview — beta CRUD surface. Public · 2026-09-16
  15. Create agentRegistration — exact beta endpoint, schema, permissions. Public · 2026-09-16
  16. Agent 365 Package Management API overview — package inventory and governance operations. Public · 2026-09-16
  17. Work IQ MCP overview — preview status, MCP server URLs, governance, clients. Public · 2026-09-16
  18. Graph API for Agent Registry and agent details — current Agent 365 admin API direction. Public · 2026-09-16
  19. Agent 365 observability concepts — identity binding, scopes, limits, downstream surfaces. Public · 2026-09-16
  20. Install and use the Agent 365 CLI — installation, authentication application, WAM/device-code. Public · 2026-09-16
  21. Add and manage tools — ToolingManifest, CLI configuration, consent, BYO MCP lifecycle. Public · 2026-09-16
  22. Understand Shadow AI in the Microsoft 365 admin center — Frontier public-preview unmanaged-agent discovery, detection/blocking, prerequisites and roles. Public · 2026-09-15
  23. Use Agent Map in the Microsoft 365 admin center — visual agent inventory, clusters, filters, summary cards, licensing and roles. Public · 2026-09-15
  24. Connected platforms in the Microsoft 365 agent registry — connect/authenticate, admin-triggered Sync agents, sync monitoring, metadata-only import. Public · 2026-09-15
  25. Ecosystem partner agents available in Agent 365 — ready-to-deploy agents vs agent factories; coming-soon and Frontier-only qualifiers. Public · 2026-09-15
  26. Understand agent identity deletion (Microsoft Entra Agent ID) — deleting a blueprint application or principal asynchronously soft-deletes its child agent identities and their agent user accounts; 30-day restore; restoring the parent after cleanup does not restore descendants. See also how to delete an agent identity. Public · 2026-09-16
  27. Choose an integration option — describes Registry sync as a preview integration path; page updated 2026-08-13. Public · 2026-09-16
  28. Microsoft 365 Roadmap item 559615 — connected-platform / registry sync capability; status In development, preview targeted 2026-05, GA targeted 2026-07 (record modified 2026-04-23). Public · 2026-09-16
  29. Microsoft Agent 365 service description — capability listing; page updated 2026-09-15. A GCC At-GA column entry is not a global release announcement. Public · 2026-09-16
  30. Agent user OAuth flow (Microsoft Entra Agent ID) — user_fic on-behalf-of chain: blueprint token T1, agent identity credential T2, resource token whose subject is the agent’s own user account. Public · 2026-09-16
  31. a365 develop-mcp CLI reference — a developer with appropriate permissions can publish or submit a custom MCP server, which stays unavailable until a tenant administrator approves it; page updated 2026-09-04. Public · 2026-09-16

Sources: Compiled entirely from canonical, public Microsoft Learn documentation. Accuracy reviewed 2026-09-16; unresolved public documentation conflicts are noted inline.

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.