Connecting an AI Agent to Microsoft 365: Graph API, Permissions, Copilot
Most organisations that run Microsoft 365 keep their working knowledge in a handful of places: Outlook mailboxes, calendars, SharePoint libraries and Teams channels. An AI agent is only useful if it can reach those places safely. In Microsoft 365, every one of them sits behind the same layer, the Microsoft Graph API. This guide explains how that layer works, which permissions an agent needs, how to keep its reach narrow, and where a custom agent ends and Microsoft 365 Copilot begins. Microsoft documentation cited here was checked in October 2026.
What does connecting an AI agent to Microsoft 365 actually mean?
It means giving a language model controlled access to data in your Microsoft 365 tenant through a registered application. The agent can read incoming requests, look up documents, create reply drafts or book meetings, but only within the permissions granted to that application. Nothing more, and ideally a good deal less.
This is a different thing from a chat tool that staff paste text into. A connected agent fetches its own context: the latest email on an order, the inspection report in a document library, the field engineer's free slots next week. Common jobs include:
- Triaging a shared inbox: classify messages arriving at a service or sales address and leave a reply draft in the Drafts folder for a person to check and send.
- Answering from documents: search manuals, supplier contracts or test reports in SharePoint and quote the passage with a link.
- Scheduling: check availability across several people and propose meeting slots.
- Answering in Teams: respond to questions in a channel or chat, so nobody has to switch tools.
For an overview of agents built around specific business processes, see AI agents for business functions. Document-heavy work is covered under knowledge management agents.
How does Microsoft Graph work as the shared layer?
Microsoft Graph is a REST API with a single endpoint, https://graph.microsoft.com. According to Microsoft's overview, it covers Outlook and Exchange, Calendar, OneDrive, SharePoint, Teams, Planner, To Do and more. For an agent this means one sign-in, one permission model and one error behaviour across all of those services.
An agent replying to a customer question can, with a single token, read the message (/users/{id}/messages), search a document library (/sites/{site-id}/drives) and create a draft. The services are linked by relationships: an email leads to its sender, the sender to their groups, a group to the files behind its team.
Every integration is made of the same parts:
- An app registration in Microsoft Entra ID. It gets a client ID and a secret or, preferably, a certificate. This is the identity the agent signs in with.
- Permissions. Delegated (on behalf of a signed-in user) or application (no user). See the next section.
- An access token. The agent requests a token from the Microsoft identity platform and sends it with every call.
- Tools for the model. Through tool use, your agent code exposes small functions to the language model, such as "fetch new messages", "search documents" or "create draft". The model decides when to call them; your code makes the actual Graph requests.
- Events instead of polling. Change notifications let Graph tell your service that something changed, so the agent doesn't have to keep asking.
A minimal read of a mailbox looks like this:
curl -s "https://graph.microsoft.com/v1.0/users/inbox@example.com/messages?\$top=5&\$select=subject,from,receivedDateTime" \
-H "Authorization: Bearer $GRAPH_TOKEN"
Microsoft describes two further components next to the API. Copilot connectors (formerly Graph connectors) bring external data into Microsoft Search, and Microsoft Graph Data Connect delivers bulk Graph data to Azure. For an agent that reads and writes during the working day, the REST API is the normal route. If several agents or models should share the same Graph functions, you can wrap them in your own Model Context Protocol server; the guide to MCP servers for AI agents covers that pattern. The distinction: MCP defines how an agent discovers and calls tools, while Graph is the data source behind them.
Delegated or application permissions: which does your agent need?
Delegated permissions let the agent act for a signed-in user and never see more than that user can. Application permissions work without a user and apply across the whole tenant. Microsoft's guidance is that, from a least-privilege point of view, delegated access is the recommended approach whenever it meets the application's requirements.
Microsoft's permissions overview uses a clear example. With the delegated Files.Read.All permission, an app reads only the files the signed-in user can already open. Granted as an application permission, the same name lets the app read every file in the organisation.
| Question | Delegated | Application (app-only) |
|---|---|---|
| Who is signed in? | a user | nobody, the app itself |
| Effective reach | overlap of app and user rights | everything the permission covers |
| Who consents? | user or admin | admin only |
| Typical agent | assistant in chat, Teams or a browser | background service on a shared inbox or nightly job |
The practical rule follows from that. If the agent works for a person who is talking to it, use delegated permissions. If it runs unattended, for example on a shared support mailbox, you need application permissions and you then have to narrow them down.
Two things are worth settling early:
- Who approves. Microsoft states that only Privileged Role Administrator and Global Administrator can consent to application permissions. Without one of them, no background agent goes live.
- How to read permission names. They follow the pattern resource.operation.constraint, for example Mail.Read, Calendars.ReadWrite or Sites.Selected. A .All suffix means tenant-wide; .Selected means only objects explicitly granted.
There is also a dedicated identity type for agents, Microsoft Entra Agent ID. According to the permissions overview, some high-risk Graph permissions are blocked outright for agent identities. Whether your agent is registered as a classic app or with an agent identity is a decision to make together with whoever runs your tenant.
How do you keep an agent's access narrow?
Use the Selected permissions for files and RBAC for Applications in Exchange Online for mailboxes and calendars. Together they let a background agent see one site, one library or one group of mailboxes rather than the whole tenant. That is the single most effective control you have.
SharePoint and OneDrive: Sites.Selected and friends
Microsoft lists four Selected scopes: Sites.Selected for a site collection, Lists.SelectedOperations.Selected for a list, ListItems.SelectedOperations.Selected for list items or folders, and Files.SelectedOperations.Selected for individual files. All of them work in both delegated and application mode.
What makes them useful is the default. Once consented in Entra ID, the app has no access. Only an explicit call such as POST /sites/{siteId}/permissions with a role (read, write, owner or fullcontrol) opens a specific site. Miss any of the three steps — consent, grant, a token carrying the scope — and the door stays shut. An agent that only needs to answer from a "Product documentation" site should get read on that site and nothing else.
One side effect to plan for: granting app permissions on lists, folders or files breaks permission inheritance on that object. Grants at site-collection level don't, because that is the root of inheritance.
Exchange Online: RBAC for Applications
For mail, calendars and contacts, Microsoft documents RBAC for Applications. You assign the app a role such as "Application Mail.Read" and limit it with a management scope or an administrative unit. Microsoft states that this replaces Application Access Policies.
New-ManagementScope -Name "Support mailboxes" -RecipientRestrictionFilter "CustomAttribute1 -eq 'support'"
New-ManagementRoleAssignment -App <ObjectId> -Role "Application Mail.Read" -CustomResourceScope "Support mailboxes"
Test-ServicePrincipalAuthorization -Identity <ObjectId> -Resource inbox@example.com
The trap is spelled out in Microsoft's own FAQ. If the app also holds tenant-wide Mail.Read in Entra ID, the two grants are combined and the scope does nothing. Remove the Entra ID grant once the Exchange role is in place. Changes are cached for between 30 minutes and 2 hours depending on recent app activity; the test cmdlet bypasses that cache, so use it before you assume something is broken.
Teams: resource-specific consent
For Teams, chats and messages there is resource-specific consent (RSC). An authorised user grants the app access to one team or chat rather than all of them. Microsoft notes that only a subset of Graph features support RSC, Teams and chats among them.
Mail, calendars, SharePoint and Teams: how do they differ?
All four share the same sign-in, but each has its own permissions, scoping method and event model. Planning them separately stops an agent built for a shared inbox from quietly gaining read access to every document library as well.
Outlook mailboxes and drafts. The agent reads, sorts and drafts replies. According to the Exchange documentation, Mail.ReadWrite lets an app create and update mail but doesn't include sending; that requires Mail.Send. If you want a person to press send, simply don't grant Mail.Send.
Calendars. Finding free time, proposing slots and preparing meetings. Reading is often enough (Calendars.Read); creating events needs Calendars.ReadWrite.
SharePoint and OneDrive. Searching documents and answering with a citation. Under the hood this is usually retrieval followed by an answer grounded in the hits, see enterprise RAG architecture. Here the state of the library matters more than the API. Outdated versions, duplicates and missing metadata will degrade any answer.
Teams. The agent shows up where people already type. For access to specific teams or chats, resource-specific consent is the better fit than tenant-wide rights.
Each of these services gets its own in-depth guide; the guides hub lists them as they are published.
How is a custom agent different from Microsoft 365 Copilot?
Microsoft 365 Copilot is a licensed Microsoft product that works with Graph data in the context of the signed-in user. A custom agent is your application: you choose the model, tools, workflow and hosting, and you register it with its own permissions. Both reach the same data, but with different levels of control.
According to Microsoft's Copilot privacy documentation, Copilot only surfaces organisational data to which individual users have at least view permission, and prompts, responses and data accessed through Graph aren't used to train foundation models. In other words, Copilot works in delegated mode. A background process that clears a shared mailbox overnight is outside that model.
| Question | Copilot | Custom agent |
|---|---|---|
| Who does the work? | the user, assisted | a process or an assistant |
| Model and hosting | set by Microsoft | your choice, including on-premises |
| Fixed workflow with approval step | limited | fully configurable |
| Effort | licence and setup | development and operations |
The two can sit side by side. A sensible split is Copilot for individual work in Word and Outlook, and custom agents for defined processes with clear rules. If you need models running in your own infrastructure, the background is covered under sovereign AI. A custom agent can still use Graph when the model itself runs locally.
What do you need in place before you start?
Three things: someone who can register and approve apps in Entra ID, reasonably tidy data in the mailboxes and libraries involved, and a written description of the process the agent will take over. When projects stall, it is rarely the API. It is usually approvals or data quality.
In more detail:
- Roles. For application permissions, one of the admin roles named above. For RBAC for Applications, Microsoft requires membership of the Organization Management role group, or the Exchange Administrator role in Entra ID.
- A single source of truth. Which site, library or mailbox is authoritative? Clean up duplicate stores first.
- A permission model that holds up. A delegated agent inherits existing mistakes. If a library is overshared, the agent will find it too.
- Privacy and works councils. If the agent reads staff mailboxes, involve your data protection officer. In Germany and several other European countries, employee representatives (works councils) also have a say in tools that can monitor staff. This is general orientation, not legal advice; the guide to GDPR and AI agents goes further.
- Where it runs. Decide where the agent, its certificate and its logs live. For unattended services, a certificate is a sturdier credential than a client secret.
A six-step path from idea to working agent
Start with one narrowly defined process and the smallest set of permissions that supports it. Expand only once that process runs reliably. The steps below are the sequence we follow in our own operations to get from an idea to an agent that can be checked and audited.
- Define the process. For example: "classify requests in the support mailbox and leave a reply draft". Write down input, output and the human approval step.
- Derive the permissions. In that example, Mail.ReadWrite on exactly one mailbox and no Mail.Send. For documents, Sites.Selected with
readon one site. - Register and scope the app. Create the app in Entra ID, upload a certificate, assign the Exchange role with a scope, remove tenant-wide grants, verify with
Test-ServicePrincipalAuthorization. - Build the tools. Small, single-purpose functions for the model ("get new messages", "create draft"), each with its own error handling.
- Subscribe to events. Use change notifications for the mailbox instead of a polling loop. Microsoft documents a maximum lifetime of 10,080 minutes (just under seven days) for Outlook message subscriptions, or 1,440 minutes when resource data is included, so your service has to renew them in time.
- Keep a human in the loop at first. The agent drafts, a human sends. Log every tool call so you can trace what happened when something goes wrong.
Limits and risks
The main risks aren't in the API. They are over-broad permissions, instructions hidden in incoming mail, and throttling under load. An agent that can read and send any message is an attractive target, and every restriction you apply reduces what can go wrong.
- Over-broad application permissions. Mail.Read without a scope means read access to every mailbox; Files.Read.All as an application permission means every file. Microsoft also singles out permissions such as Directory.ReadWrite.All to be used with caution.
- Prompt injection. Incoming email and documents are untrusted text. If they contain instructions aimed at the model, the agent must not follow them. Put any tool that writes or sends behind an approval step.
- Throttling. When limits are exceeded, Microsoft Graph returns HTTP 429 with a
Retry-Afterheader. Wait for that interval; immediate retries still count against your usage. Inside JSON batches, throttled requests aren't retried automatically by the SDKs. - Existing permission mistakes become visible. A delegated agent finds whatever the user can find, including files shared by mistake. The agent doesn't create the problem, but it does expose it.
- When this approach is the wrong one. For one-off analysis of large data volumes, Microsoft points to Graph Data Connect rather than the REST API. And if there is no clearly described process, no integration will rescue it.
Where should you start?
Pick a process that is mostly reading and where a mistake is cheap, such as triaging a shared inbox with reply drafts. Agree with your tenant administrators who registers and approves the app, and settle on the smallest permissions that support the process before anyone writes code.
A test tenant or a test site with a small set of real but non-sensitive documents is a good first environment. It lets you confirm that scoping actually works before the agent touches live mailboxes. For process ideas that suit a first project, see the pages on quotation agents and technical service agents. Terms such as tool use and prompt injection are explained in the AI glossary.
Frequently asked questions
Do I need a Microsoft 365 Copilot licence to build my own agent?
No. Microsoft Graph works independently of Copilot. What you need is an app registration in Microsoft Entra ID and the right permissions.
Who can approve application permissions?
According to Microsoft, only the Privileged Role Administrator and Global Administrator roles can consent to application permissions. Involve them at the start, not the end.
Can an agent be limited to one SharePoint site?
Yes. With Sites.Selected the app starts with no access at all, and only an explicit grant on a site, list or file opens it up.
How do I stop a background agent from reading every mailbox?
Assign mail and calendar roles through RBAC for Applications in Exchange Online with a management scope, then remove the tenant-wide permission in Entra ID. Otherwise the two grants add up and the scope has no effect.
What happens if the agent sends too many requests?
Graph returns HTTP 429 with a Retry-After header. Wait for the stated number of seconds before retrying; immediate retries keep counting against the limit.
Sources
- Microsoft Graph overview (Microsoft Learn) learn.microsoft.com
- Overview of Microsoft Graph permissions (Microsoft Learn) learn.microsoft.com
- Overview of Selected Permissions in OneDrive and SharePoint (Microsoft Learn) learn.microsoft.com
- Role Based Access Control for Applications in Exchange Online (Microsoft Learn) learn.microsoft.com
- Set up notifications for changes in resource data (Microsoft Learn) learn.microsoft.com
- Microsoft Graph throttling guidance (Microsoft Learn) learn.microsoft.com
- Data, Privacy, and Security for Microsoft Copilot (Microsoft Learn) learn.microsoft.com