Guide M365 Navigator

A Microsoft 365 development and administration agent that helps you build solutions on the M365 platform, covering Microsoft Graph API, Teams apps, SharePoint customization, Power Platform integration, and Azure AD identity management.

When to Use This Agent

Choose Guide M365 Navigator when:

• Building apps and integrations using Microsoft Graph API
• Developing Microsoft Teams applications (tabs, bots, messaging extensions)
• Customizing SharePoint Online with SPFx web parts
• Integrating Microsoft 365 services with custom applications
• Managing Azure AD (Entra ID) app registrations and permissions

Consider alternatives when:

• Building Azure infrastructure (use an Azure architect agent)
• Working with Power Platform exclusively (use a Power Platform agent)
• Managing on-premises Exchange or Active Directory (use an IT admin agent)

Quick Start

Copy
# .claude/agents/guide-m365-navigator.yml
name: Guide M365 Navigator
description: Microsoft 365 development and integration
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - WebSearch

Example invocation:

claude "Build a Microsoft Teams app that shows project status from our API, allows task creation via adaptive cards, and sends weekly digest notifications"

Core Concepts

M365 Development Platform

Platform	Use Case	Technology
Microsoft Graph	Unified API for M365 data	REST API + SDKs
Teams Apps	Chat bots, tabs, extensions	Bot Framework + Teams SDK
SharePoint SPFx	Custom web parts, extensions	React + SPFx framework
Outlook Add-ins	Email extensions	Office.js + web tech
Power Platform	Low-code automation	Power Automate, Power Apps

Microsoft Graph API Usage

Copy
// Microsoft Graph SDK — Common operations
import { Client } from '@microsoft/microsoft-graph-client';
import { TokenCredentialAuthenticationProvider } from
  '@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials';
import { ClientSecretCredential } from '@azure/identity';

// Application authentication
const credential = new ClientSecretCredential(
  process.env.TENANT_ID,
  process.env.CLIENT_ID,
  process.env.CLIENT_SECRET,
);

const authProvider = new TokenCredentialAuthenticationProvider(credential, {
  scopes: ['https://graph.microsoft.com/.default'],
});

const graphClient = Client.initWithMiddleware({ authProvider });

// Get user's calendar events
const events = await graphClient
  .api('/users/{user-id}/calendarView')
  .query({
    startDateTime: '2026-03-15T00:00:00Z',
    endDateTime: '2026-03-22T00:00:00Z',
  })
  .select('subject,start,end,location')
  .orderby('start/dateTime')
  .top(10)
  .get();

// Send Teams channel message with adaptive card
await graphClient
  .api(`/teams/${teamId}/channels/${channelId}/messages`)
  .post({
    body: {
      contentType: 'html',
      content: '<attachment id="card"></attachment>',
    },
    attachments: [{
      id: 'card',
      contentType: 'application/vnd.microsoft.card.adaptive',
      content: JSON.stringify(adaptiveCard),
    }],
  });

Teams App Architecture

Copy
## Teams App Components

### Tab (Embedded Web Page)
- React SPA hosted on your infrastructure
- Teams JavaScript SDK for context
- SSO via Teams token exchange

### Bot (Conversational Interface)
- Bot Framework SDK (Node.js or C#)
- Hosted as Azure Function or App Service
- Handles messages, commands, adaptive cards

### Messaging Extension (Search + Actions)
- Search external data from compose box
- Create cards from search results
- Action commands for quick workflows

Configuration

Parameter	Description	Default
graph_version	Microsoft Graph API version	v1.0
auth_flow	Authentication flow (client-credentials, on-behalf-of, device-code)	client-credentials
teams_sdk	Teams SDK version	latest
spfx_version	SharePoint Framework version	1.18
tenant_type	Tenant type (single, multi, personal)	single
permissions	Graph API permission level (delegated, application)	application

Best Practices

1. Request the minimum Graph API permissions needed. Graph permissions are granular — Mail.Read reads mail, Mail.ReadWrite reads and writes. Request only what your app needs. Over-permissioned apps are security risks and face stricter admin consent requirements. Use delegated permissions when acting on behalf of a user, application permissions for daemon services. Regularly audit and remove unused permissions.

2. Handle Graph API throttling with exponential backoff. Microsoft Graph returns 429 (Too Many Requests) when rate limits are exceeded. The response includes a Retry-After header. Implement automatic retry with exponential backoff and respect the retry header value. Batch multiple Graph API calls into a single $batch request to reduce call count and avoid throttling.

3. Use Microsoft Graph change notifications instead of polling. Rather than repeatedly querying for new emails, calendar events, or Teams messages, subscribe to change notifications via webhooks. Graph sends a POST to your endpoint when subscribed resources change. This is more efficient, lower latency, and avoids throttling. Renew subscriptions before they expire (maximum 3 days for most resources).

4. Implement SSO in Teams apps using the token exchange flow. Teams provides a token for the signed-in user that can be exchanged for a Microsoft Graph token without prompting the user. This creates a seamless authentication experience. Use the @microsoft/teamsfx SDK to simplify the SSO implementation. Fall back to interactive authentication only if the silent token exchange fails.

5. Test Teams apps in multiple contexts: personal chat, group chat, and channels. Teams apps behave differently in each context. The bot receives different event types, the tab has different viewport sizes, and permissions vary. Test in all three contexts during development. Use the Teams Toolkit for VS Code to simplify local debugging with tunneling and hot reload.

Common Issues

Graph API returns 403 Forbidden despite having the correct permissions. Permission grants are not immediate — admin consent may be required for application permissions, and delegated permissions need user consent. Check that the app registration in Azure AD has the correct permissions AND that admin consent has been granted (green checkmark in portal). For multi-tenant apps, each tenant admin must grant consent separately.

Teams bot does not receive messages in channels. Bots in channels only receive messages when mentioned (@bot) unless the bot has RSC (Resource-Specific Consent) permissions with ChannelMessage.Read.Group. Check the app manifest's bots section for the correct scopes configuration. Verify the bot is installed in the channel, not just the team. Use the Teams admin center to check installation status.

SharePoint SPFx web part works in workbench but fails in production. The SPFx workbench provides a permissive environment that does not enforce the same security constraints as production. Common failures: API permissions not granted in SharePoint admin center, CORS errors from external APIs, missing tenant-wide deployment approval, and Content Security Policy violations. Test in a real SharePoint page early in development.