Built on the Agent 365 + Microsoft Agent Framework sample.

• Observability — Tracing and monitoring via Agent 365 Observability SDK
• MCP Tools — Model Context Protocol server integration (Outlook, SharePoint, etc.)
• Notifications — Email and Word-comment notification handlers
• Authentication — Dual-mode:
  • Anonymous / dev — No auth; only Azure OpenAI credentials required
  • Production — Full agentic auth via AUTH_HANDLER_NAME=AGENTIC

Anonymous mode — LLM chat in Agents Playground (no Agent 365 needed)

main.py                 # Entry point
modules/
  agent.py              # Agent365Agent -- LLM + MCP + notifications
  host.py               # AgentHost -- aiohttp server, auth, typing indicator
  auth.py               # LocalAuthenticationOptions (dev/bearer token)
  token_cache.py        # Observability token cache
scripts/                # One-time tenant admin scripts

Docs: Set up and run the Python Agent Framework sample agent

# 1. Install (uv recommended; pip works too)
uv sync          # or: pip install -e .

# 2. Configure
cp .env.template .env   # fill in Azure OpenAI + auth values

# 3. Grant Azure OpenAI RBAC (required for Managed Identity / DefaultAzureCredential)
az role assignment create \
  --assignee "<your-user-or-managed-identity-object-id>" \
  --role "Cognitive Services OpenAI User" \
  --scope "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>"

# 4. Run
python main.py

# 5. Health check
curl http://localhost:3978/api/health

Eligibility: Copilot license + Modern Billing + Frontier opt-in.

• Admin Center → Copilot → Settings → User Access → Copilot Frontier → turn on
• Accept Agent 365 T&C: Admin Center → Agents → Agent Overview → Try

dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli

Requires: Application Administrator, Cloud Application Administrator, or Global Administrator + Application.ReadWrite.All Graph scope.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\New-Agent365ToolsServicePrincipalProdPublic.ps1

The script creates the tenant-wide enterprise application / service principal for the Agent 365 tooling resource app. In many tenants this appears as Work IQ Tools. Check Microsoft Entra ID → Enterprise applications and search for Work IQ Tools. Agent 365 Tools is the shared MCP resource app, and an A365 admin uses it to grant MCP permissions and consent to the a365demo Blueprint. It only needs to be created once per tenant.

Docs: Agent blueprint and instance setup

Requires: Global Admin + Azure Subscription Contributor/Owner; Microsoft.Web resource provider registered.

a365 config init
a365 config display              # verify

a365 setup all                   # infra + blueprint + permissions
# Or step-by-step:
#   a365 setup infrastructure
#   a365 setup blueprint
#   a365 setup permissions mcp
#   a365 setup permissions bot

a365 config display -g           # verify final config

• Agent 365 Tools → Created via .\scripts\New-Agent365ToolsServicePrincipalProdPublic.ps1
• a365demo Blueprint → Created by a365 CLI
• a365demo Identity → Created by Agent 365 platform via a365 setup flow
• Microsoft 365 publish backend app → Created by Microsoft 365 publish flow

In short:

• Work IQ Tools is the shared MCP resource app, and an A365 admin uses it to grant MCP permissions and consent to the blueprint.
• a365demo Blueprint is your tenant's bot-style blueprint app created by a365 setup blueprint, and it is the app that holds delegated API permissions such as Work IQ Tools delegated scopes.
• a365demo Identity is the runtime agent user / ServiceIdentity created from that blueprint and used by the running agent.

a365demo in this README is a sample, user-defined naming prefix from this repo's configuration. It is not a reserved Agent 365 platform name. You can replace it with a project-specific name in your own a365.config.json, and the generated blueprint, identity, UPN, and web app names will follow that choice.

So the usual order is: create or verify Work IQ Tools -> run a365 setup blueprint to create a365demo Blueprint -> create the agent identity (a365demo Identity) -> use Agent 365 Tools to grant MCP permissions and consent to the blueprint -> publish.

Example: the blueprint app carries delegated API permissions to Work IQ Tools.

Related names that are easy to confuse:

• a365demo Playground is not an Entra object. It refers to the local Agents Playground testing tool/context used for local testing.
• a365demo-**-webapp is not an Entra identity object. It is the Azure App Service web app that hosts your agent runtime after a365 deploy.

M365 communicates with your agent via a public HTTPS endpoint.

a365 deploy

Docs: Add MCP servers to your agent

a365 develop list-available
a365 develop add-mcp-servers <serverName>
a365 develop list-configured
a365 setup permissions mcp

To use MCP servers with this agent in Microsoft 365:

1. Add the MCP server to your local ToolingManifest.json by using a365 develop add-mcp-servers.

2. Make sure ToolingManifest.json contains the MCP servers you want this runtime to expose. This repo already includes mcp_MailTools as an example.

3. Enable MCP in the runtime configuration:

   # .env
   ENABLE_MCP=true

4. Apply the MCP scopes to the existing agent blueprint by running a365 setup permissions mcp. This reads ToolingManifest.json and grants the required MCP permissions to the blueprint. This step typically requires a Global Administrator.

5. For local development, you can run with bearer-token-based MCP access. For Microsoft 365 / deployed usage, use agentic auth (USE_AGENTIC_AUTH=true and AUTH_HANDLER_NAME=AGENTIC) so the hosted agent can call MCP tools with the configured agent identity.

6. Deploy and publish the agent. After the agent is available in Microsoft 365, users can invoke tool-backed actions in Teams or Microsoft 365 chat. On the first turn, this app loads the configured MCP servers and attaches them to the agent before handling the request.

Docs: Test your agent locally

You can use the Microsoft Teams client or WebChat to test the features that are not supported in the Microsoft 365 Agents playground.

※ Caution: Agents Playground is for local development only. Run the agent locally or remotely in Azure with non-auth configurations (USE_AGENTIC_AUTH=false, AUTH_HANDLER_NAME=) in anonymous mode.

winget install agentsplayground   # or: npm install -g @microsoft/m365agentsplayground
agentsplayground
# pwsh ./scripts/Start-AgentsPlayground.ps1

Docs:

• Deploy agent to Azure App Service
• Publish agent to Microsoft admin center

a365 deploy
a365 publish

Flow:

• Run a365 deploy to deploy the app to Azure App Service. Verify in Azure Portal → App Services → your web app that the site is deployed and running.
• Run a365 publish to update manifest\manifest.json and create manifest\manifest.zip.
• During or after a365 publish, follow the printed instructions and upload manifest\manifest.zip in the Microsoft 365 admin center under Agents → All agents → Upload custom agent.

• Agent 365 SDK — Python
• Agent 365 Samples
• Agent 365 CLI
• Agent 365 development lifecycle
• Test agents by using the Microsoft Agent 365 SDK
• PyPI — microsoft-agents-a365

graph TD
    subgraph IDP [Entra ID and tenant resource apps]
        E[Microsoft Entra ID]
        E1[`a365demo Blueprint` <br/> app / service principal]
        E2[`Agent 365 Tools` <br/> shown as `Work IQ Tools` in Entra <br/> MCP resource app]
    end

    subgraph UC [User and Channel]
        A[Teams / Copilot / Webchat]
    end

    subgraph CP ["Control Plane (Agent 365)"]
        B[Agent 365 control plane]
        B1[Blueprint and instance registry]
        B2[Policy and entitlement checks]
        I[`a365demo Identity` <br/> agent instance identity]
    end

    subgraph RT [Your Agent Runtime]
        C1[Bot-style activity endpoint / SDK]
        C[Azure App Service agent logic]
    end

    subgraph ACT ["Action Layer (MCP Servers)"]
        D[MCP authorization boundary]
        D1[Mail / Outlook MCP]
        D2[SharePoint / Files MCP]
    end

    %% Request routing and control-plane flow
    A -->|1. User message| B
    B -->|2. Resolve published app to blueprint| B1
    B1 -->|3. Select agent instance identity| I
    I -->|4. Agent context for routing and governance| B2
    B2 -->|5. Deliver activity with agent identity context| C1
    C1 -->|6. Invoke agent logic| C
    
   %% Identity roles:
   %%   a365demo Blueprint = the bot app that requests the token and holds delegated API permissions
   %%   Work IQ Tools      = the MCP resource app the delegated permission targets
   %%   a365demo Identity  = the runtime agent user / service identity that is acting

    %% Downstream auth and tool execution
    E1 -->|Blueprint app and enterprise app are registered in Entra| E
    C -.->|7. Acquire downstream token as `a365demo Blueprint`| E
    E -.->|8. Return access token scoped to the MCP resource app, for example `Agent 365 Tools` eq `Work IQ Tools`| C
    E2 -->|Defines MCP resource scopes and app permissions| D
    C -->|9. Call MCP with blueprint token + `a365demo Identity` context| D
    D -->|10. Authorized tool action| D1
    D -->|10. Authorized tool action| D2

    %% Styling
    style B fill:#f9f,stroke:#333,stroke-width:2px
    style I fill:#f9f,stroke:#333,stroke-width:2px
    style C fill:#bbf,stroke:#333,stroke-width:2px
    style C1 fill:#bbf,stroke:#333,stroke-width:2px
    style D fill:#dfd,stroke:#333,stroke-width:2px
    style E fill:#fff2cc,stroke:#d6b656,stroke-width:2px
    style E1 fill:#fff2cc,stroke:#d6b656,stroke-width:2px
    style E2 fill:#fff2cc,stroke:#d6b656,stroke-width:2px

Agent 365 is built on the Bot Framework lineage and deploys as an Azure App Service exposing a bot-style HTTPS endpoint.

In this flow, the three important identity objects appear at different stages:

• a365demo Blueprint is created during setup, published in the app package, and later used by the runtime to acquire downstream app tokens from Entra. This is the bot-style app registration that carries delegated API permissions, including Work IQ Tools delegated scopes.
• a365demo Identity is the agent user / ServiceIdentity selected by the Agent 365 control plane, and that identity context is carried into routing, governance, and MCP execution.
• Agent 365 Tools (often shown as Work IQ Tools in Enterprise Applications) is the shared tenant MCP resource app. It is not the external caller itself; it is the resource/scope target used when the runtime requests tokens and when MCP-backed tool permissions are evaluated.

Three auth layers:

Multi-channel: Teams, Copilot Studio, Webchat, and third-party channels.