FastAPI based samples

[jkshan]

It seems like the samples for FastAPI is not working? Does any managed to make the Agents SDK work with FastAPI with Authorization enabled?

[CarlosOliveira-23]

RESOLUTION: Microsoft Agents SDK (Agents-for-python) + FastAPI + Authorization

Discussion: #400
Date: May 24, 2026

WHAT IS HAPPENING

Discussion #400 has no official response from Microsoft yet (opened May 19, 2026).
The FastAPI samples in the repo live under test_samples/fastapi — meaning they are
development/test samples, not production-ready ones. The aiohttp samples are the
more mature and officially supported path.

The core issue: the JWT authorization middleware pattern differs between aiohttp
and FastAPI hosting modules, and the samples do not make this clear.

ROOT CAUSE

The SDK exposes two separate hosting modules:

from microsoft_agents.hosting.aiohttp import start_agent_process # mature
from microsoft_agents.hosting.fastapi import start_agent_process # newer

For aiohttp, authorization is enabled by passing jwt_authorization_middleware
directly into the Application constructor:

from microsoft_agents.hosting.aiohttp import (
start_agent_process,
jwt_authorization_middleware,
CloudAdapter,
)
APP = Application(middlewares=[jwt_authorization_middleware])

There is no equivalent jwt_authorization_middleware exported for FastAPI yet,
or if it exists, it is not documented in the samples.

SOLUTIONS

OPTION 1 — Use fastapi-microsoft-identity (recommended for production)

pip install fastapi-microsoft-identity

from fastapi import FastAPI, Request
from fastapi_microsoft_identity import requires_auth, initialize
from microsoft_agents.hosting.fastapi import start_agent_process

initialize(tenant_id="YOUR_TENANT_ID", client_id="YOUR_CLIENT_ID")

app = FastAPI()

@app.post("/api/messages")
@requires_auth
async def messages(request: Request):
return await start_agent_process(request, agent_app, adapter)

This library validates JWT tokens against Azure AD and throws HTTP 401/403
automatically on invalid or missing tokens.

OPTION 2 — Manual JWT middleware in FastAPI

from fastapi import FastAPI, Request, HTTPException
from starlette.middleware.base import BaseHTTPMiddleware

class BotAuthMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request: Request, call_next):
if request.method == "POST" and request.url.path == "/api/messages":
auth_header = request.headers.get("Authorization", "")
if not auth_header.startswith("Bearer "):
raise HTTPException(status_code=401, detail="Unauthorized")
return await call_next(request)

app = FastAPI()
app.add_middleware(BotAuthMiddleware)

@app.post("/api/messages")
async def messages(request: Request):
return await start_agent_process(request, agent_app, adapter)

NOTE: In practice, the CloudAdapter inside the SDK already validates the
Bot Framework JWT when processing the activity. For Teams / Copilot Studio
scenarios, token validation happens inside start_agent_process itself, so
you may not need extra middleware at all.

OPTION 3 — Minimal working FastAPI setup (no extra middleware)

from fastapi import FastAPI, Request
from microsoft_agents.hosting.fastapi import start_agent_process
import uvicorn

app = FastAPI()

@app.get("/api/messages")
async def health():
return {"status": "ok"}

@app.post("/api/messages")
async def messages(request: Request):
return await start_agent_process(request, agent_app, adapter)

if name == "main":
uvicorn.run(app, host="localhost", port=3978)

INSTALL DEPENDENCIES (from source, for latest fixes)

pip install -e libraries/microsoft-agents-hosting-fastapi
pip install -e libraries/microsoft-agents-hosting-core
pip install -e libraries/microsoft-agents-authentication-msal
pip install -e libraries/microsoft-agents-activity

RECOMMENDATIONS

1. Open a GitHub ISSUE (not just a discussion) to get an official response:
   https://github.com/microsoft/Agents-for-python/issues

2. Reference working sample:
   https://github.com/Azure-Samples/m365-custom-engine-agents
   This repo uses a Python FastAPI backend with the Agents SDK and has a
   proven proxy agent pattern with authorization.

3. If unblocked is urgent: migrate to aiohttp hosting, which is the mature
   path. The aiohttp samples are production-ready and jwt_authorization_middleware
   is fully supported there.

USEFUL LINKS

• Repo: https://github.com/microsoft/Agents-for-python
• FastAPI test samples: https://github.com/microsoft/Agents-for-python/tree/main/test_samples/fastapi
• Working proxy agent sample: https://github.com/Azure-Samples/m365-custom-engine-agents
• fastapi-microsoft-identity: https://pypi.org/project/fastapi-microsoft-identity/
• Official quickstart (aiohttp): https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/quickstart

[jkshan]

Thanks for the response. I do agree that the fastapi hosting is newer and not very well documented (even the samples they have also don't run). Coming to the solutions suggested,

I tried out the Options 1 and discovered that, it doesn't support agents/bot framework identity verification. (as it doesn't have links to Bots JWT Keys), but this does give me direction to build my own middleware by extending JWT validation the SDK already have.

For Option 2, is it possible for you to point to any documentation? I don't seem to find this in my research.

PS: I did notice there is issue already raised for it and was not responded; hence I thought of using discussion. Link to issue

[CarlosOliveira-23]

Hi! Thanks for testing this out and sharing your findings — really useful feedback, especially about fastapi-microsoft-identity not supporting Bot Framework JWT validation.

Regarding Option 2, you're right that there isn't direct official documentation for this specific pattern applied to the Agents SDK. The approach I suggested is based on Starlette's BaseHTTPMiddleware, which is the standard way to add request-level middleware in FastAPI apps. You can find the general docs here:

• Starlette middleware docs: https://www.starlette.io/middleware/
• FastAPI middleware guide: https://fastapi.tiangolo.com/tutorial/middleware/

That said, your observation is actually the key insight here: the CloudAdapter (used internally by start_agent_process) already performs Bot Framework JWT validation as part of processing the activity. This means that for Teams / Copilot Studio scenarios, adding an extra middleware layer might not even be necessary — the SDK handles it internally.

So if you're looking to build your own middleware that extends the SDK's existing JWT validation logic, the most relevant starting point would be the SDK source itself:

• Authentication handling: https://github.com/microsoft/Agents-for-python/tree/main/libraries/microsoft-agents-authentication-msal
• Hosting core (where the adapter processes incoming requests): https://github.com/microsoft/Agents-for-python/tree/main/libraries/microsoft-agents-hosting-core

The idea would be to hook into or replicate the same token verification the aiohttp jwt_authorization_middleware does, but as a FastAPI/Starlette middleware. Since the aiohttp version is already implemented in the SDK, it could serve as a reference for what a FastAPI equivalent should look like.

Hope this helps point you in the right direction. And agreed — this really deserves an official response from the team, especially given that the FastAPI samples don't even run out of the box.

[jkshan]

I investigated further for option 2, my finding says the JWT validation really doesn't happen if you didn't configure the middleware for the app. Reference to the code in SDK. If I go by the code comment mentioned, it seems like, it up to the developer to config the validation using the SDK middleware's and the validation is not implicit as you have called out.

[CarlosOliveira-23]

Glad you confirmed it! Yes, exactly — the JWT validation is opt-in, not implicit. The developer is responsible for wiring up the middleware explicitly. Good to have that clarified directly from the SDK code. Thanks for investigating further!