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.
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.
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.
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.
Wide diagram — scroll horizontally within the frame to see all six stages. Detailed per-class flows follow below.
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.
- 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).
- Share for personal/shared availability, or submit/request for organizational use.
- Microsoft 365 admin center reviews the request and publishes to the Agent Store or rejects it.
- Install / assign to users or groups (may include admin consent); pin, block/unblock, manage owners.
B · Copilot Studio agents Maker + ALM
- Design in Copilot Studio: instructions, topics, knowledge, actions, connectors and APIs; optionally Work IQ MCP tools preview.
- Power Platform ALM moves the agent across Development, Test, and Production environments.
- Publish / channel package to Teams and Microsoft Copilot, or download the ZIP package.
- Reach Agent 365 through built-in integration; or upload the ZIP via Agents → All agents → Upload custom agent.
- Admin center: inventory, review permissions, publish/install/assign, block/unblock, reassign owner.
C · Microsoft Foundry agents Azure compute
- 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).
- Registry / inventory picks up the agent.
- Configure Agent 365 observability collection; optional Work IQ or custom MCP tools preview.
- Deploy through Foundry / Azure; publish a package/channel separately if required.
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.
- Choose the integration: already integrated by platform/partner (built-in); Vertex AI / Bedrock (registry sync preview); otherwise Agent 365 SDK + CLI.
- 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.
- Add capabilities: Identity, Observability, Work IQ MCP preview, Notifications Frontier preview when an agent user is required.
- Validate: identity/token mode, permissions and consent, root invoke_agent span, MCP discovery/tool invocation, notification routing.
- Deploy the runtime to Azure / AWS / GCP / on-premises — the SDK does not host or deploy it.
- Optionally package and publish to Microsoft 365; operate through Agent Registry, Entra, Defender, Purview.
E · Template agents & user-created instances Preview
- A template/blueprint agent appears in Agent 365.
- A user requests activation, or an admin proactively selects scope.
- Admin approves and activates for specific users, groups, or the tenant.
- An authorized user creates an agent instance, which receives tenant-local identity/resources.
- Runtime operation and monitoring; instance-level block or delete.
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.
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.
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
On-behalf-of · delegated user
Agentic-User Frontier preview
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
| Capability | Representative package families |
|---|---|
| Notifications | microsoft-agents-a365-notifications · @microsoft/agents-a365-notifications · Microsoft.Agents.A365.Notifications |
| Observability | microsoft-agents-a365-observability-* · @microsoft/agents-a365-observability · Microsoft.Agents.A365.Observability* |
| Runtime / auth / discovery | microsoft-agents-a365-runtime · @microsoft/agents-a365-runtime · Microsoft.Agents.A365.Runtime |
| MCP tooling | microsoft-agents-a365-tooling · @microsoft/agents-a365-tooling · Microsoft.Agents.A365.Tooling |
| Framework adapters | Agent Framework, OpenAI, LangChain, Semantic Kernel, Claude, Azure AI Foundry (by language) |
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
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:
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.
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.
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.
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.
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.
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.
Administrator control surfaces
| Plane | Primary interface | Responsibilities |
|---|---|---|
| Agent catalog / governance | Microsoft 365 admin center → Agents | Inventory, requests, publishing, install/uninstall, user/group assignment, blocking, owner management, package details |
| Agent identity | Microsoft Entra admin center + Graph | Blueprints, principals, identities, sponsors, credentials, permissions, consent, Conditional Access, identity lifecycle |
| Tool governance | M365 admin center → Agents and Tools | Allow/block Work IQ and custom MCP servers; review custom server registration |
| Threat protection | Microsoft Defender | Agent activity views, exposure/misconfiguration risk, suspicious activity, advanced hunting in CloudAppEvents |
| Data security / compliance | Microsoft Purview | DLP, audit, retention, eDiscovery, communication compliance, data security posture |
| Runtime infrastructure | Azure / Foundry | Deploy, scale, start/stop Foundry compute; Azure RBAC |
| Copilot Studio ALM | Power Platform admin center | Move agents and actions across Dev, Test, Production; environment governance |
| Automation | Microsoft Graph | Inventory, package details, registration metadata, identity objects, selected governance actions |
Action semantics — what each action does and does not mean
| Action | Means | Not equivalent to |
|---|---|---|
| Register | Create inventory metadata and/or identity objects | Publish, install, consent, or deploy code |
| Publish to store | Add an approved package to the organizational catalog | Assigning it to users |
| Install / deploy | Make an available agent ready for selected users/groups | Starting its external runtime |
| Activate template | Permit scoped users to instantiate a template agent | Creating every instance automatically |
| Approve request | Accept a request and perform the documented activation/publication | Granting every downstream API permission |
| Block package | Prevent organizational use through governed host surfaces | Deleting source code or every identity |
| Disable identity | Identity-plane restriction on the selected agent identity | Removing catalog/package metadata |
| Stop Foundry agent | Deallocate the underlying Azure deployment | Blocking a package |
| Uninstall | Remove assignment/availability for users | Deleting the source agent |
| Delete registration | Remove beta registry metadata record | Cascade deletion of package, runtime, identity, or data |
| Delete Agent Builder agent | Permanently removes the agent, files, and SharePoint Embedded container | General deletion behavior for all platforms |
| Delete Entra identity/blueprint | Soft-delete the identity object for 30 days | Removing host package or external runtime |
| Cleanup Azure | Remove CLI-created App Service resources | Removing registry or Entra objects unless separately requested |
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 function | Method & path | Status | Least-privileged permission | Source |
|---|---|---|---|---|---|
| 1 | Create identity blueprint | POST https://graph.microsoft.com/v1.0/applications/microsoft.graph.agentIdentityBlueprint | v1.0 GA | Delegated or application: AgentIdentityBlueprint.Create | [12] |
| 2 | Create blueprint principal | POST https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal | v1.0 GA | AgentIdentityBlueprintPrincipal.Create. Body uses the blueprint appId, not the application object id. | [ref] |
| 3 | Create agent identity | POST https://graph.microsoft.com/v1.0/servicePrincipals/microsoft.graph.agentIdentity | v1.0 GA | AgentIdentity.Create.All; application alternative AgentIdentity.CreateAsManager | [13] |
| 4 | Enable / disable or update identity | PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}/microsoft.graph.agentIdentity | v1.0 GA | Enable/disable: application AgentIdentity.EnableDisable.All AND AgentIdentity.CreateAsManager; broader AgentIdentity.ReadWrite.All; delegated EnableDisable.All. Custom security attribute changes need additional rights. Scopes are not uniform across all PATCH properties. | [ref] |
| 5 | Delete agent identity | DELETE https://graph.microsoft.com/v1.0/servicePrincipals/{id}/microsoft.graph.agentIdentity | v1.0 GA · soft-delete 30d | Delegated AgentIdentity.DeleteRestore.All; application also requires AgentIdentity.CreateAsManager | [13] |
| 6 | Delete blueprint | DELETE https://graph.microsoft.com/v1.0/applications/{id}/microsoft.graph.agentIdentityBlueprint | v1.0 GA · soft-delete 30d | AgentIdentityBlueprint.DeleteRestore.All | [12] |
| 7 | Register external / custom agent metadata | POST https://graph.microsoft.com/beta/copilot/agentRegistrations | Preview · not for production | AgentRegistration.ReadWrite.All, delegated or application | [15] |
| 8 | Read registration | GET https://graph.microsoft.com/beta/copilot/agentRegistrations/{id} | Preview | AgentRegistration.Read.All or read/write permission | [14] |
| 9 | Update registration | PATCH https://graph.microsoft.com/beta/copilot/agentRegistrations/{id} | Preview | AgentRegistration.ReadWrite.All | [14] |
| 10 | Delete registration | DELETE https://graph.microsoft.com/beta/copilot/agentRegistrations/{id} | Preview · irreversible | AgentRegistration.ReadWrite.All | [14] |
| 11 | Inventory catalog packages | GET https://graph.microsoft.com/v1.0/copilot/admin/catalog/packages | v1.0 GA | CopilotPackages.Read.All, delegated or application. Requires an Agent365 license. | [16] |
| 12 | Block package | POST https://graph.microsoft.com/beta/copilot/admin/catalog/packages/{id}/block | Beta · delegated only | Delegated CopilotPackages.ReadWrite.All; application not available; global commercial only. | [16] |
| 13 | Reassign package owner | POST https://graph.microsoft.com/beta/copilot/admin/catalog/packages/{id}/reassign | Beta · delegated only | Delegated CopilotPackages.ReadWrite.All; application not available; global commercial only. | [16] |
| 14 | Ingest S2S telemetry | POST https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1 | Direct OTLP/HTTP+JSON | App role Agent365.Observability.OtelWrite; audience 9b975845-388f-4429-889e-eab1ef63949c. {agentId} must equal the calling agent identity appId. | [11] |
| 15 | Ingest delegated telemetry | POST https://agent365.svc.cloud.microsoft/observability/tenants/{tenantId}/otlp/agents/{agentId}/traces?api-version=1 | Direct OTLP/HTTP+JSON | Delegated scope Agent365.Observability.OtelWrite | [11] |
| 16 | Check tenant telemetry eligibility | GET https://agent365.svc.cloud.microsoft/observabilityService/tenants/{tenantId}/eligibility?api-version=1 | Optional S2S preflight | Auth per the direct OTel guide; do not infer eligibility from licensing alone. | [11] |
| 17 | Work IQ Mail MCP interface | MCP https://agent365.svc.cloud.microsoft/agents/tenants/{tenantId}/servers/mcp_MailTools | Preview · MCP server URL | Delegated Work IQ Mail permission on client/blueprint; exact catalog values from ToolingManifest.json. Standard MCP methods, not REST paths. | [17] |
| 18 | MCP Management server | MCP https://agent365.svc.cloud.microsoft/mcp/environments/{environmentId}/servers/MCPManagement | Preview · MCP server URL | Tenant/admin configuration required; only tenant administrators can publish custom MCP servers. | [17] |
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.
Sources
All sources are canonical, public Microsoft Learn documentation, reviewed on 2026-09-10.
- Overview of Microsoft Agent 365 — GA 2026-05-01; control-plane purpose and licensing. Public · 2026-09-10
- Choose an Agent 365 integration option — built-in, registry-sync, and SDK mechanisms. Public · 2026-09-10
- Microsoft Agent 365 SDK overview — SDK boundary, capabilities, languages, package catalog. Public · 2026-09-10
- Agent 365 identity — objects, cardinality, credentials, S2S/OBO/Agentic-User, sponsors. Public · 2026-09-10
- Quickstart: Connect an existing agent to Agent 365 — skills onboarding, runtime modes, Work IQ restrictions. Public · 2026-09-10
- Agents for Microsoft 365 Copilot (declarative) — declarative-agent architecture and build interfaces. Public · 2026-09-10
- Governance and lifecycle actions for agents — install, uninstall, block, delete, owners, Foundry start/stop. Public · 2026-09-10
- Agents admin guide for Microsoft 365 — custom ZIP upload, assignment, deployment, publication. Public · 2026-09-10
- Agent 365 CLI reference — exact command families and boundaries. Public · 2026-09-10
- Agent management in Microsoft 365 admin center — template activation and instance management. Public · 2026-09-10
- Direct OpenTelemetry integration — exact ingestion and eligibility endpoints; two-step S2S. Public · 2026-09-10
- Create agentIdentityBlueprint — v1.0 method and permissions. Public · 2026-09-10
- Create agentIdentity — v1.0 method and permissions. Public · 2026-09-10
- Agent Registration API overview — beta CRUD surface. Public · 2026-09-10
- Create agentRegistration — exact beta endpoint, schema, permissions. Public · 2026-09-10
- Agent 365 Package Management API overview — package inventory and governance operations. Public · 2026-09-10
- Work IQ MCP overview — preview status, MCP server URLs, governance, clients. Public · 2026-09-10
- Graph API for Agent Registry and agent details — current Agent 365 admin API direction. Public · 2026-09-10
- Agent 365 observability concepts — identity binding, scopes, limits, downstream surfaces. Public · 2026-09-10
- Install and use the Agent 365 CLI — installation, authentication application, WAM/device-code. Public · 2026-09-10
- Add and manage tools — ToolingManifest, CLI configuration, consent, BYO MCP lifecycle. Public · 2026-09-10