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 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.
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 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.
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.
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.
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 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.
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 status: see note); 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.
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 / 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 ingestion is metadata only — sync creates no identity, telemetry or runtime instrumentation. Agent Map reads the same inventory.
Registry sync ingests metadata (and provider-supported controls) — it creates no identity, telemetry or runtime instrumentation. Agent Map reads the same inventory.
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.
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.
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 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.
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. 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
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 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
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:
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).
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
- Understand Shadow AI in the Microsoft 365 admin center — Frontier public-preview unmanaged-agent discovery, detection/blocking, prerequisites and roles. Public · 2026-09-15
- Use Agent Map in the Microsoft 365 admin center — visual agent inventory, clusters, filters, summary cards, licensing and roles. Public · 2026-09-15
- Connected platforms in the Microsoft 365 agent registry — connect/authenticate, admin-triggered Sync agents, sync monitoring, metadata-only import. Public · 2026-09-15
- Ecosystem partner agents available in Agent 365 — ready-to-deploy agents vs agent factories; coming-soon and Frontier-only qualifiers. Public · 2026-09-15