Microsoft Agent 365 — agent lifecycles, interfaces & APIs

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.

Numbered nodes ①–④ are the four entry routes. Every node links to its detailed section (§01–§11). Fit-to-width by default — use the zoom controls, or focus the map and press + / − / 0, then screenshot the whole frame.

Every agent that Agent 365 governs follows the same six-stage spine, but ownership and interfaces differ sharply by class. Read each row left to right. Build, connect, identity, packaging, runtime, and governance are independent operations — a registry record does not host code, grant permissions, or create a mailbox, and most actions do not cascade automatically. The documented exception is Entra blueprint deletion, which soft-deletes its child agent identities and their agent user accounts.

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

Expand each class for its exact build interfaces, integration path, packaging, runtime ownership, and the admin actions that apply. Distinctions that are commonly conflated are called out explicitly.

Three separate paths make agents visible to administrators, and they must not be conflated. Agents onboarded to Agent 365 are recorded in the registry and surfaced visually by Agent Map; external platforms are brought in by admin-triggered Connected platforms / registry sync, which imports registry metadata and can expose provider-supported controls; and unmanaged agents you never onboarded are found through a separate Shadow AI discovery experience — a separate Frontier page from All agents that public admin docs do not describe as part of Connected platforms ingestion. Accuracy reviewed 2026-09-16 Public documentation conflicts are noted inline.

Registry sync ingests metadata (and provider-supported controls) — it creates no identity, telemetry or runtime instrumentation. Agent Map reads the same inventory.

The boundary marks that Shadow AI is documented as a separate Frontier page from All agents; public admin docs do not describe it as part of Connected platforms registry ingestion.

Connected platforms / registry sync is in Preview. Status follows Choose an Agent 365 integration option, checked 16 September 2026.

Five identity and metadata objects are routinely confused. They have separate identifiers and separate lifecycles. A blueprint is a credential boundary: one blueprint can create many tenant-local agent identities that all share its credentials. Registration and package records are metadata — they are not the identity.

Telemetry identifiers map onto these objects: gen_ai.agent.id must equal the authenticated agent’s appId (not the Entra object id); the blueprint is separately identified in telemetry by its application appId.

Three documented identity patterns. The distinction that matters for authorization and audit is who the token subject is and which appId acts. Return messages are dashed. The Agentic-User exchange follows the documented user_fic on-behalf-of flow [30].

S2S · autonomous · app-only

On-behalf-of · delegated user

Agentic-User Frontier preview

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

Agent 365 CLI

Install and verify:

§05A — Behind a365 setup all traces exactly what setup provisions and how it binds custom code to the Entra Blueprint.

Selected lifecycle command families (not exhaustive) — note that cleanup instance, cleanup blueprint, and cleanup azure target distinct resource groups. These are separate commands for separate objects; they are not, by themselves, proof that no deletion cascades — deleting an Entra blueprint does soft-delete its child agent identities and their agent user accounts (see §08).

a365 setup all does not upload, relocate, or run the agent’s code. It builds a chain of references: hosted code → runtime SDK configuration → the Entra Agent Identity Blueprint credential and application ID → a child agent identity → an Agent 365 registration → an optional Microsoft 365 messaging callback and, separately, a catalog package. The URL is never registered globally: it is a routing destination tied to the named blueprint, tenant, and identity, and the hosted app must still implement the expected messaging route and validate the tokens it receives (token flows, SDK & CLI).

Runtime configuration synchronization depends on detecting a supported project, not simply on a project-path flag. The pinned ProjectSettingsSyncHelper uses DeploymentProjectPath, or falls back to the configuration-file directory when that path is missing or does not exist. It detects .NET, Node.js, or Python and updates appsettings.json or .env; without a usable directory or supported project, synchronization is skipped. Config-free setup a365 setup all --agent-name "<name>" can therefore update runtime configuration. The standard-agent orchestrator deliberately skips synchronization for --agent-registration-only. [36]

Standard-agent setup sequence — default / non-AI-teammate path

Solid arrows are calls the CLI drives; dashed arrows are returns. Two OPT frames mark work that only happens under a condition. The dashed banner is a different lifecycle that setup does not perform. This traces the default standard-agent path; --aiteammate provisions only the blueprint and permissions during setup, and --agent-registration-only runs the registration step alone.

Source: Agent 365 CLI setup reference [32], CLI reference [9], and the pinned public DevTools source [36]. Placeholder identifiers only — no tenant data.

Step detail

Object & ID binding — how the code binds to the Blueprint

The customer question — “how does it bind a custom agent to the Entra Blueprint?” — is answered by these identifiers. Setup writes them into runtime configuration whenever a supported project is detected (the conditional write described above); a365 publish later stamps one into the package manifest.

The endpoint is a routing destination for the named blueprint, tenant, and identity; the hosted app must expose and adopt the expected SDK-validated messaging route, not arbitrary generated logic. See §03 Identity and §04 Token flows. Source [4].

Runtime configuration written by setup

Keys the CLI updates (placeholder identifiers only) — Credential protection source:

Permissions — three separate layers

An authorized developer can build much of the structure, but only a tenant admin turns intent into tenant-wide consent. Work IQ / MCP scopes declared in the manifest are not granted — run a365 setup permissions mcp after approval (§06 MCP tooling); the runtime code still loads the tools separately.

Representative Microsoft Graph calls

Representative of the setup path in the pinned source — not the complete call set (lookups, OAuth-grant inspection, app-role assignment, and endpoint registration also occur). Several live operations use Graph beta; do not rewrite them as v1.0 equivalents. This does not change the §09 endpoint catalog.

Source: pinned public DevTools setup path [36]; Graph method references [12] [13] [14] [15]; CLI setup reference [32].

What setup all does not do

Re-running, validating & recovering

Setup uses targeted reuse and reconciliation, not universal atomic idempotency. It reuses the blueprint by display name, revalidates and replaces invalid/expired secrets, verifies the stored agentRegistrationId before reuse, and saves state before later steps so partial progress survives. Preserve a365.generated.config.json — do not delete objects to “retry.” Review the final Action Required block for pending consent, and recover narrowly with --agent-registration-only (registration) or setup blueprint --endpoint-only (callback).

What changes in my code?

Agent 365 does not take ownership of your executable or automatically intercept everything it does. Registration establishes a management record linked to its identity. Your application then uses that identity for supported resource access and emits activity telemetry. Additional capabilities require their own runtime integration and tenant configuration.

Provisioning and runtime distinctions reviewed 2026-09-22 against the pinned DevTools source [36] and the observability identity contract [19]. Other source-review dates are unchanged. The responsibilities below are illustrative code areas, not verified files in a supplied application.

Read-only validation & endpoint recovery: CLI query-entra [33], messaging endpoint [35], publish [34]. All commands above are shown for reference only and are not executed by this page.

Tool access separates a management plane (declare + consent) from an MCP data plane (discover + execute). Declaring a server does not grant permission; a Global Administrator must separately grant the blueprint’s MCP permissions, and permissions take precedence over local configuration.

A valid run is an OpenTelemetry span tree with a required root. Without a valid root invoke_agent span the run is invisible to the Defender agent activity view, the admin-center activity/inventory telemetry, and Purview agent experiences — though child spans remain queryable in Defender advanced hunting.

Identity, registration, package, runtime, Azure resources, and agent-owned data each have separate deletion and retention behavior, and no single control blocks or deletes across all of them. One documented cascade is the exception: deleting an Entra blueprint (application or principal) asynchronously soft-deletes its child agent identities and their agent user accounts.

Administrator control surfaces

Action semantics — what each action does and does not mean

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.

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.

All sources are canonical, public Microsoft Learn documentation. Accuracy reviewed 2026-09-16, with the a365 setup all and runtime-integration corrections reviewed 2026-09-22; 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. Public · 2026-09-16
29. Microsoft Agent 365 service description — capability listing; page updated 2026-09-15. 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
32. Agent 365 CLI setup reference — exact setup all / setup blueprint flags and boundaries; page updated 2026-09-01. Public · 2026-09-16
33. CLI query-entra reference — read-only blueprint-scopes, inheritance, and instance-scopes checks. Public · 2026-09-16
34. CLI publish reference — builds manifest.json + manifest.zip — a separate lifecycle from setup. Public · 2026-09-16
35. Agent messaging endpoint — opt-in HTTPS callback registration, deferral, and endpoint-only recovery. Public · 2026-09-16
36. Public Agent 365 DevTools source at pinned commit 08e48a9 (2026-09-11) — the setup implementation traced for this section; NuGet 1.1.221 exposes no reliable source-commit mapping, so behavior is current public source, not guaranteed for every installed binary. Public · 2026-09-16