Agent 365 identity creation for custom agents

Use the two approaches for different goals:

• Agent 365 SDK/CLI: preferred when building or provisioning an agent and the goal is to have setup handled for the agent, including identity creation and registration.
• Migrate an existing app registration/service principal to Agent ID: use when an existing custom agent already authenticates with a standard Microsoft Entra app registration or service principal and needs Agent ID governance capabilities.

Recommended decision criteria:

1. New agent project or flexible existing codebase Use the Microsoft 365 Agents SDK. It is the recommended way to build and provision agents, and it handles agent identity creation and registration in the Agent 365 registry automatically. This is described as the simplest and most durable path, and it avoids coordinating multiple API calls manually.
2. Existing custom agent already using app registration or service principal Migrate to Agent ID when the agent currently authenticates like a normal application and needs agent-specific governance such as:
   • Conditional Access policies
   • centralized audit logging
   • lifecycle management
   In that case, migration means creating new Agent ID resources, updating application code, and then decommissioning the old identity. There is no in-place conversion of an existing app registration or service principal into an agent identity.
3. Existing provisioning workflow cannot be changed immediately If agent identity blueprints must be created programmatically with Microsoft Graph because of existing identity-issuance workflows, create the blueprint through Graph and then explicitly call the Agent Registry API afterward to register the corresponding agent card. This is the manual path when the SDK/CLI path cannot be adopted yet.

Practical onboarding guidance:

• Choose SDK/CLI-first if starting fresh or if refactoring is acceptable.
• Choose migration to Agent ID if there is already a deployed custom agent backed by a traditional Entra app registration/service principal.
• Choose direct Graph + Agent Registry API only when existing automation requires programmatic control and the SDK/CLI cannot be used end-to-end.

Additional design guidance from the identity model:

• Use one blueprint per credential boundary.
• Use separate blueprints for agents that cannot safely share credentials and inherited baseline permissions.
• Decide up front whether the agent needs application permissions, delegated permissions, or both.
• Each blueprint and each agent identity requires at least one sponsor.

What migration to Agent ID changes:

• The process is phased: discover, classify, migrate, then validate/decommission.
• Before migrating, inventory the existing service principals and classify them by usage.
• Low-usage identities can be cleanup candidates instead of migration candidates.
• Medium- and high-usage identities are migration candidates, with high-usage identities requiring more caution, parallel run, and rollback planning.

Credential and hosting considerations during migration:

• Azure hosting: user-assigned managed identity is the recommended production credential.
• Non-Azure cloud: federated identity credential with external IDP.
• On-premises/local development: client secret or certificate, with certificates preferred over client secrets for production on-premises deployments.

In short, the recommended approach is:

• SDK/CLI for new or adaptable agent onboarding
• Agent ID migration for existing agents already using app registrations/service principals
• Graph + Agent Registry API for constrained legacy automation scenarios

References:

• Create an agent identity blueprint
• Agent 365 identity
• Migrate custom app registrations to Agent ID