Get started with Agent 365 development

Agent 365 works with a range of agent implementations. An agent can assist users on demand, run autonomously in the background, or operate with its own user identity in Microsoft 365. Understanding which pattern best describes your agent is important because it determines the agent's identity model, what access it has to Microsoft 365 resources, and which lifecycle steps apply.

Types of agents

Before you begin, ask yourself: What kind of agent am I building?

There are two types of agents depending on the type of access they have:

Agent type Overview
Agents Work on behalf of a user with delegated access, or operate as an application with scoped permissions. Registered as Microsoft Entra applications or agent identity blueprints.
AI teammate Operate with their own user identity in Microsoft 365, including mailbox, Teams presence, and directory entry. This type of agent is only available for tenants participating in the Frontier preview program.

Agents

An agent works on behalf of a user. It responds to requests, runs tasks in the background, connects to APIs, processes data, and drives actions.

Agents come in all shapes. Some are conversational - a user asks something and the agent responds. Some run quietly in the background - triggered by a schedule, an event, or an incoming message - without anyone actively involved. Some do both.

Example scenarios:

  • A user asks an agent to summarize their unread emails and draft replies. The agent does the work, accessing only resources the user can access, and hands the result back.
  • A customer service agent helps a support engineer query internal knowledge bases and compose responses during a live support session.
  • A compliance monitoring agent runs every night, scans SharePoint sites to which the agent is granted access for policy violations, and files audit reports - with no one watching.
  • An order processing agent picks up new sales orders from a queue, updates a CRM, and sends confirmation emails - all without anyone kicking it off.

Identity basis:

Traditionally, you register agents as Microsoft Entra applications. That approach continues to work. Going forward, you can also build agents on a Microsoft Entra Agent ID via an agent identity blueprint - the IT-approved, governance-enforced definition of an agent's capabilities, permitted tool access, and compliance constraints. Building on a blueprint is the recommended path for new agents. It unlocks governed Work IQ tool access, Microsoft Purview data protection, Microsoft Defender threat monitoring, and Entra ID governance - making your agent a fully governed enterprise identity from day one.

AI teammate

Important

To get early access to this type of agent, you need to be part of the Frontier preview program. Frontier connects you directly with Microsoft's latest AI innovations. Frontier previews are subject to the existing preview terms of your customer agreements. As these features are still in development, their availability and capabilities might change over time.

An AI teammate operates in Microsoft 365 using its own agent identity. You can provision it with capabilities such as sending and receiving email through its own mailbox, participating in Teams 1:1 and group conversations, and appearing in directory and organizational metadata with an assigned manager relationship. People can interact with it through familiar Microsoft 365 entry points such as @mentions, email, calendar invites, and Teams chat.

Create these agents from an agent blueprint, which is the IT-approved, governance-enforced definition of the agent's capabilities, permitted tool access, and compliance constraints. Each agent instance inherits the identity model, permissions, and policies from its parent agent identity blueprint.

What the agent does — whether it is conversational, background, or both — depends on how you design it. Some agents are highly interactive, responding to messages and supporting work in real time. Others process tasks in the background, acting on emails or events without direct user engagement. The agent operates with its own user identity, and its actions are governed and auditable through that identity.

If you already have an agent, you don't have to start over. Existing agents can be extended to operate with their own identity by adding the identity and blueprint configuration described later in this guide.

Example scenarios:

  • Add an HR onboarding AI teammate to a new hire's Teams onboarding channel. It sends welcome emails from its own mailbox, schedules orientation meetings on its own calendar, and responds to questions by using the capabilities configured for that agent instance.
  • Assign a manager relationship in directory metadata to a procurement AI teammate. Employees email purchase requests to its mailbox. The agent processes the request, queries ERP and finance systems by using its governed Work IQ tool access, and responds with approval or escalation from its own identity.
  • Add a research AI teammate to a project team's SharePoint site and Teams channel. It can surface relevant documents during meetings, respond in conversation threads, and draft weekly status reports by using the permissions and tools configured for that agent.

Identity basis:

Built on an agent identity blueprint, which creates a Microsoft Entra Agent ID and associated user account: always required.

Adding Agent 365 capabilities incrementally

Agent 365 isn't all or nothing. You don't need to build an AI teammate on day one - or at all, if your scenario doesn't require it. Adopt capabilities incrementally, starting with what your agent needs now and expanding as your requirements evolve.

Why build on an agent identity blueprint?

When you create an agent identity blueprint, the Agent 365 CLI provisions a Microsoft Entra Agent ID for your agent - a first-class identity in your tenant, subject to the same enterprise governance policies as human users. That single identity is the foundation for the security benefits that flow automatically to every blueprint-based agent:

Benefit What it means for your agent
Microsoft Entra ID governance The agent's identity and access lifecycle is managed through the same Conditional Access, identity protection, and access reviews that apply to human users.
Microsoft Purview Every data interaction the agent performs is subject to your tenant's sensitivity labels, DLP policies, and retention policies - automatically, with no extra code.
Microsoft Defender Agent behavior is continuously monitored for anomalies and threats. Suspicious activity triggers the same alerts and response workflows as for any user in the tenant.

These benefits apply to all blueprint-based agents, including both agents with user-delegated access and agents that operate with their own identity, as soon as the blueprint is created. You don't need to configure them separately.

The four capabilty tiers below represent levels you can adopt incrementally. The following table shows what's available for Agent 365 based on your starting point:

Capability Microsoft 365 custom engine agent All other agents 1
Register ✓ 2 ✓
Observability ✓ ✓
Work IQ ✓ ✓
AI teammate ✓ 3 ✓ 3

1 Agents that are currently registered as Microsoft Entra applications must first create an agent identity blueprint to get started with any capability in this column.

2 Microsoft 365 custom engine agents are already registered using their existing Microsoft Entra application registration — no additional setup required.

3 AI teammate for Microsoft 365 custom engine agents requires an agent identity blueprint. Available to Frontier program participants only.

Register

Registering your agent makes it visible and manageable in the Microsoft 365 admin center. Admins can discover it and see it in their organization's agent inventory.

What you get:

  • Your agent appears in the Microsoft 365 admin center; admins can find it and see it in their organization's agent inventory.
  • Blueprint-based agents also receive the full Entra ID governance, Purview, and Defender benefits described in Why build on an agent identity blueprint?

What you build:

Register your agent using your existing Microsoft Entra application registration or a blueprint.

Note

If your agents are built on Google Vertex AI or Amazon Bedrock, registration requires no development work — agents are pulled automatically via the Google and Amazon APIs. No SDK integration, no blueprint, and no code changes are required. Once registered, you can use the Agent 365 SDK to add observability, Work IQ tool access, and other capabilities incrementally. See Registering Google Vertex AI and Amazon Bedrock agents to get started.

How you build it:

Use the AI-guided setup and answer the agent type questions accordingly. The AI-guided setup performs the needed steps for this tier. Microsoft 365 custom engine agents are already discoverable today using their existing Microsoft Entra application registration.

Observability

Once your agent is registered, the next investment is observability — giving IT, security teams, and your own engineering team visibility into what your agent is actually doing. Every inference call, tool invocation, and interaction is captured, traced, and made auditable.

Observability is the foundation for trust. Without it, admins have no way to verify behavior, audit compliance, or diagnose problems at scale. With it, your agent becomes an enterprise asset rather than a black box.

What you get:

  • Full [OpenTelemetry (OTel) (OTel)](https://opentelemetry.io/docs/specs/otel/protocol/) based tracing of every agent interaction: inputs, outputs, tool calls, and model invocations.
  • Activity visible in the Microsoft 365 admin center and connected monitoring surfaces.
  • Audit trails that feed into Microsoft Entra, Microsoft Purview, and Microsoft Defender, supporting compliance, data protection, and threat response requirements.

What you build:

Instrumentation using the Agent 365 SDK observability APIs: either auto-instrumentation (if you're using OpenAI, LangChain, or Agent Framework) or manual instrumentation for any other stack.

How you build it:

Use the AI-guided setup and answer the observability questions accordingly. The AI-guided setup performs the needed steps for this capabilty.

Work IQ

After registering and making your agent observable, give it access to Microsoft 365 data and actions through Work IQ. Work IQ is a governed set of tools that lets your agent work with Mail, Calendar, OneDrive, SharePoint, Teams, and more.

Work IQ tools require admin consent, are audited, and revocable. Your agent calls them by using the permissions defined in its blueprint - no extra OAuth flows or custom connectors needed.

What you get:

  • Access to the full Work IQ tool catalog - Mail, Calendar, OneDrive, SharePoint, Teams, and more.
  • Permissions that admins control and scope to exactly what your agent needs.
  • Every tool call traced and auditable through the observability pipeline.

What you build:

Agent code that calls Work IQ tools by using the Agent 365 SDK tooling APIs.

How you build it:

Use the Agent 365 SDK tooling APIs to add Work IQ tool calls to your agent code manually. The AI-guided setup does not currently support this capability.

AI teammate

AI teammates are available to Frontier program participants.

The final phase enables your agent to operate in Microsoft 365 with its own identity. Depending on configuration, it can have a mailbox, Teams presence, directory entry, and manager relationship. People can interact with it through familiar Microsoft 365 experiences such as email, chat, meetings, and app surfaces.

Note

Identity and permissions model shift

Moving to an AI teammate represents a fundamental change in how your agent accesses resources. Your existing agent might use delegated user access, where the agent acts for a signed-in user and can access only the resources that user can access, or application permissions scoped to a service principal. An agent with a user identity doesn't inherit a calling user's access at run time. Instead, it operates under its own user identity, with its own access grants, governance policies, and audit trail.

This means:

  • In delegated user access, the agent acts on behalf of the signed-in user and is limited to that user's access. With an agent's own identity, you grant access to Microsoft 365 resources such as mailbox, calendar, Teams, and SharePoint directly to the agent identity.
  • You govern and audit permissions granted to the agent identity as that agent's own access. They're not the same as user-delegated permissions passed through from the calling user.
  • If your current implementation relies on delegated user access or application permissions, review and re-scope those permissions for the agent identity before enabling this capability.

What you get:

  • Everything from Discoverability, Observability, and Work IQ.
  • An agent user identity with its own mailbox - people can email it directly and it can send email from its own address.
  • A presence across Microsoft 365 apps - people can chat with it, @mention it, add it to channels, and invite it to meetings in Teams; and interact with it directly in Word, Excel, PowerPoint, and other M365 surfaces.
  • An org chart entry under a designated manager - the agent appears in the organization's directory.
  • Admin-controlled lifecycle - the agent is created, managed, and retired through the Microsoft 365 admin center, with full governance over every instance.

What you build:

All capabilities, plus instance creation and (optionally) Marketplace publishing.

How you build it:

Use the AI-guided setup and answer the AI teammate questions accordingly. The AI-guided setup performs the needed steps for this tier.

AI-guided setup

Use an AI coding agent to automate the setup and configuration of your agent for Agent 365. The AI-guided setup walks you through the prerequisite checks, configuration steps, and code integration needed to enable capabilities like registration, observability, Work IQ tool access, and AI teammate functionality.

AI-guided setup prerequisites

Before you begin, ensure you have the following items:

Requirement Details
AI coding agent Visual Studio Code with GitHub Copilot and GitHub Copilot Chat extensions, or another AI coding agent with terminal access
Agent code A working agent project in Python, Node.js, or .NET. If you don't have one, start with a quickstart sample.
Entra role Global Administrator — completes all steps including OAuth2 permission grants. Agent ID Developer — completes all steps except OAuth2 permission grants; the setup generates a handoff for a Global Administrator.

AI-guided setup steps

These steps apply whether you're enabling a single agent or an agent factory. The AI agent checks for required tools and handles installation, authentication, and validation automatically.

Open your agent project and copy this prompt into your AI agent of choice. If you're using GitHub Copilot, switch to Agent mode first - Ask and Edit modes don't have terminal access.

Follow the steps at aka.ms/agent365enable to enable my agent for Agent 365.

The AI agent begins by asking you three questions to determine which capabilities apply to your agent:

Question 1: Is your agent already available in Teams or Copilot?

  • Yes
  • No

Question 2: How will your agent authenticate when calling downstream APIs?

  • On-behalf-of (OBO) — the agent acts as the signed-in user (delegated permissions)
  • Service-to-service (S2S) — the agent acts as its own identity (application permissions)
  • Both (OBO and S2S)

Question 3: What Agent 365 capabilities do you want to enable?

The setup automatically includes all prerequisite capabilities for your selection.

The AI agent then works through the applicable tiers automatically, pausing only to ask for your input:

Capability What the AI agent does 1
Register Checks for .NET and the Agent 365 CLI (installs or updates if missing), installs Azure CLI if missing, runs az login if not authenticated, validates your custom client app registration, collects agent name and manager email, configures your agent in Teams Developer Portal, and registers your agent blueprint
Observability Adds Agent 365 SDK observability instrumentation to your agent code
AI teammate Runs a365 publish and walks you through post-deployment steps including agent instance creation

1 The steps performed depend on the agent type and phases you selected at the start of the setup.

Important

For Observability, the AI agent writes code directly into your project. AI coding agents can make mistakes. Always review the changes before deploying to production.

Information required to complete

The AI agent pauses to collect configuration during setup:

Prompt What to provide
Agent name, manager email Basic agent metadata
Derived value confirmation Review autogenerated names for the agent identity, blueprint, and user principal
Manifest review Confirm your manifest.json is updated with your agent's name, description, and developer information

Post deployment steps

When the automated tiers finish, the AI agent pauses for two steps that require browser interaction:

  1. Create an agent instance

    (AI teammate only) — In Microsoft Teams, go to Apps, search for your agent, and select Add. If admin approval is required, your Microsoft 365 admin receives the request. Once approved, your agent appears in your organization chart. For additional instances, see Create agent instances. It can take a few minutes for a newly published agent to appear in Teams search.

  2. Test your agent

    Send a message to your agent in Teams to verify it's working.

Done — your agent is deployed, published, and live. See Create agent instances if you need additional instances.

If anything didn't work, the AI agent provides targeted troubleshooting. You can also refer to the Agent 365 Troubleshooting Guide.

Manual path reference

Use this reference only if you're troubleshooting a step, building CI/CD automation, or working without an AI coding agent.

Step What it does Guide
Setup config Creates a365.config.json with your tenant, subscription, and project details. If you have an existing deployment, set the messaging endpoint here. Setup Agent 365 config
Setup blueprint Registers your agent identity in Entra and provisions Azure resources (resource group, App Service Plan, Web App) Setup agent blueprint
Deploy Deploys your agent code to Azure App Service. Optional if already hosted elsewhere. Azure · AWS · GCP
Publish Creates manifest.zip and uploads to Microsoft 365 admin center Publish agent

For CLI installation, commands, and troubleshooting, see Agent 365 CLI.

Publish your agent to Microsoft Marketplace

After you fully develop and test your agent within your own tenant or tenants, make it available in the Microsoft Marketplace.

To do this, you need a Microsoft AI Cloud Partner Program account in Partner Center. If you don't have one, create an account to get your PartnerID. Next, enroll in the Microsoft 365 and Copilot program, which gives you access to the resources and support needed to publish agent offers. Once enrolled, review the submission checklist and validation guidelines, and then submit your agent through the Partner Center step-by-step submission guide.

Learn how to submit your agent to Microsoft Marketplace using Partner Center.

When you're done, your agent is published to Microsoft Marketplace and available for customers to discover and deploy.

Troubleshooting the AI-guided setup

If you encounter problems during the AI-guided setup, see the following common problems and their solutions.

Problem Description
AI agent doesn't run terminal commands AI agent describes commands but doesn't execute them
AI agent skips steps Setup appears to skip required steps
CLI commands fail with permission errors Authorization errors when running a365 CLI commands
Configuration values are wrong Need to change configuration after creating a365.config.json

AI agent doesn't run terminal commands

If the AI agent describes commands but doesn't execute them, make sure you're using Agent mode in GitHub Copilot Chat. Ask and Edit modes don't have terminal access.

AI agent skips steps

The instruction file enforces strict step ordering. If the AI agent appears to skip a step, ask it to start over:

Please start from Step 1 in the setup instructions and work through each step in order.

CLI commands fail with permission errors

If a365 CLI commands fail with authorization errors, the most common cause is a missing or incomplete custom client app registration. The AI agent validates this during setup, but if validation was skipped, see Custom client app registration.

For general troubleshooting, see the Agent 365 Troubleshooting Guide.

Configuration values are wrong

If you need to change configuration values after creating a365.config.json, either:

  • Edit the file directly and rerun a365 config init -c ./a365.config.json
  • Ask the AI agent to update specific values
  • Last updated on