MS Forms Agent

This page provides configuration instructions for the MS Forms Agent, which enables integration with Microsoft Forms for creating forms and quizzes, managing questions, and collecting responses

Overview

• Create Microsoft Forms and quizzes from a plain-language prompt, drafted in chat and created only after the user approves

• Add, change, and remove questions on an existing form directly within Blockbrain

• List the connected user's forms and read submitted responses for summarizing and analysis

• Ground form content in your organization's knowledge bases so questions come from your own material

• Export any form, including an unsaved draft, as a downloadable Word document

Prerequisites

• Complete the general setup steps from the main AI Agents page

• Ensure users have active Microsoft 365 accounts with Microsoft Forms enabled

• Verify appropriate Microsoft 365 licensing for Microsoft Forms

• Permissions to create and administer an Azure app registration in Microsoft Entra ID

The MS Forms Agent is the one Microsoft agent that does not run on Microsoft Graph. Microsoft Graph has no endpoint for creating or editing a form, so this agent talks to the Microsoft Forms API directly. That changes which permissions you add and which scopes you configure, so follow this page rather than adapting another Microsoft agent's setup.

Azure App Registration Configuration

Required API Permissions

The agent needs delegated permissions from two APIs. Add all six to your app registration.

Permission	API	Type	Description
Forms.Read	Microsoft Forms	Delegated	View user's forms
Forms.ReadWrite	Microsoft Forms	Delegated	View and modify user's forms
Responses.Read.All	Microsoft Forms	Delegated	View responses of user's forms
Responses.ReadWrite	Microsoft Forms	Delegated	Submit responses for user
offline_access	Microsoft Graph	Delegated	Maintain access to data you have given it access to
User.Read	Microsoft Graph	Delegated	Sign in and read user profile

Microsoft Forms is not listed under Microsoft Graph. If you search the Graph permission list for Forms.Read you will not find it.

Add it through APIs my organization uses and search for Microsoft Forms. The four Forms permissions are then available under Delegated permissions.

None of these six permissions requires admin consent, so a user can consent for themselves on first connect. Granting admin consent for the organization is still recommended, because it removes the individual consent prompt for every user.

Redirect URL

• Add https://nango.theblockbrain.ai/oauth/callback as an allowed redirect URL on your app registration

Permission Configuration Steps

1. In your Azure app registration, go to API permissions

2. Click "Add a permission" > APIs my organization uses > search for Microsoft Forms

3. Choose Delegated permissions and select Forms.Read, Forms.ReadWrite, Responses.Read.All, and Responses.ReadWrite

4. Click "Add a permission" again > Microsoft Graph > Delegated permissions and select offline_access and User.Read

5. Click "Add permissions"

6. Click "Grant admin consent" (recommended for organization-wide deployment)

Agent Configuration in Blockbrain

Configuration Steps

1. Access Agent Settings:

   • Navigate to your Blockbrain admin panel

   • Go to Agents and open the Connectors tab

   • Find Microsoft Forms and open its Tool Configuration

2. Enter Azure Credentials:

   • Client ID: Enter the Application ID from your Azure app registration

   • Client Secret: Paste the client secret you generated (use the eye icon to toggle visibility)

3. Configure OAuth Scopes:

   • Add each of the four scopes individually using the "Add" button:

     • https://forms.office.com/.default

     • offline_access

     • openid

     • profile

   • Each scope appears as a removable tag

   • Use the "X" button to remove any incorrect scopes

4. Additional Configuration:

   • Add one key-value pair, with the key tenant and your Azure tenant ID as the value

   • This is required, not optional. Without it the Connect button fails for every user

5. Save Configuration:

   • Click "Save" to apply all settings

   • Wait for the confirmation message

Do not drop openid and profile from the scope list. They look cosmetic and they are not.

Microsoft issues an encrypted, unreadable access token for the Forms resource, so the agent cannot read your tenant and user identifiers from it. It reads them from the ID token instead, and only the openid and profile scopes cause one to be issued. If either is missing, every action fails immediately with a message asking you to add them, before any call to Microsoft Forms is even attempted.

If you change the scopes after users have already connected, those users must disconnect and reconnect. An existing connection keeps the ID token it was originally issued, so a scope change alone does not fix it.

A note on the .default scope

On the other Microsoft agents, using .default is an alternative to listing individual scopes. For MS Forms it is the normal configuration, shown above, because the four Microsoft Forms permissions are granted on the app registration and requested together as https://forms.office.com/.default. Configure the permissions in Azure, as described above, and the scope list in Blockbrain stays as it is.

Tool Permissions

The Microsoft Forms connector exposes six tools. Because some of them create and change forms in your users' accounts, review their permission levels after enabling the connector.

Read-only tools, safe to leave on Always Allow:

Tool	What it does
List Microsoft Forms	Lists the forms owned by the connected user
Get Microsoft Form	Reads one form with its questions, plus its respondent and edit links
Get Microsoft Form Responses	Reads submitted responses for analysis or summarization
Export Microsoft Form as Document	Renders a form or an unsaved draft as a Word document

Write tools, which default to Needs Approval:

Tool	What it does
Create Microsoft Form	Creates a new form or quiz in the connected user's account
Update Microsoft Form	Changes a form's title or description, and adds, edits, or deletes its questions

We recommend leaving both write tools on Needs Approval. The agent is already instructed to draft a form in chat and create it only after the user approves, so the approval prompt is a second, enforced checkpoint rather than a redundant one. See Manage Tools & Connectors for how to set these levels.

Export Microsoft Form as Document works without a Microsoft Forms connection at all. That is deliberate: a user whose connection is broken, or who has not connected yet, can still get their drafted form out as a Word file.

Testing the MS Forms Agent

Verification Steps

1. Authentication Test:

   • Open a chat with the MS Forms Agent and complete the Connect flow

   • Verify the Microsoft sign-in completes and the connect card does not reappear

2. Read Access:

   • Ask the agent to list your forms

   • Verify the titles match what you see at https://forms.office.com

3. Form Creation:

   • Ask for a short two-question form, approve the draft, and let the agent create it

   • Verify you receive both a respondent link and an edit link

   • Open the respondent link and confirm the form renders for a respondent

4. Response Reading:

   • Submit one response through the respondent link

   • Ask the agent to summarize the responses and verify your answer appears

5. Quiz Creation:

   • Ask for a short quiz with points and correct answers, then approve it

   • Open the edit link and confirm the points and answer key are set

6. Document Export:

   • Ask the agent to export the form as a Word document

   • Verify the download link works and the document lists every question

Common MS Forms Integration Use Cases

Surveys and Feedback

• Event and Training Feedback: Generate a feedback survey from a short description, then summarize the responses as they arrive

• Employee Pulse Checks: Build a recurring short survey with consistent wording across departments

• Response Analysis: Ask for themes, counts, or outliers across submitted responses instead of exporting to a spreadsheet

Assessments and Quizzes

• Knowledge Checks from Internal Material: Ground a quiz in your own policy or onboarding documents so the questions match what your organization actually publishes

• Graded Assessments: Create a quiz with per-question points and a marked answer key, graded automatically by Microsoft Forms

• Iterative Refinement: Adjust wording, options, points, and correct answers in chat before anything is created

Forms Operations

• Bulk Question Edits: Add or revise a batch of questions on an existing form in one request

• Structure Archiving: Export a form to Word for review, sign-off, or record keeping

• Form Inventory: List existing forms and their response counts to find what is still collecting answers

Supported Question Types and Limits

Supported question types

Type	Options
Choice	Single or multiple selection, custom options, optional free-text "Other" option
Text	Short answers, or long multi-line answers
Rating	Star or number scale, 2 to 10 levels, 5 by default
Date	Date picker

Not supported: ranking, Likert, Net Promoter Score, and file-upload questions. When a user asks for one of these, the agent says so and proposes the closest supported type instead. Group-owned forms are also out of scope, because every form is created in the connected user's own account.

Quiz behaviour

• Quiz mode is fixed when the form is created. An existing plain form cannot be converted, so a new quiz has to be created instead

• Points are whole numbers from 0 to 100. Fractional points are rejected, because Microsoft Forms does not support them

• Only choice questions can carry correct answers, and a single-select question can have at most one

• Every option of a graded question must be unique, because correct answers are matched by their option text

• A choice question is graded only once it has correct answers. Points on their own do not grade it

• Automatic scoring of free-text answers, and per-answer feedback, are not supported yet

Ceilings

Limit	Value
Questions per create or update	100
Forms returned per listing page	100
Responses returned per page	200
Word download link validity	1 hour

Troubleshooting

Authentication Issues

Problem: The connect card keeps reappearing after a successful Microsoft sign-in

• Solution: Verify the redirect URL is exactly https://nango.theblockbrain.ai/oauth/callback

• Check: Confirm the tenant key is set in Additional Configuration with your Azure tenant ID

• Verify: Client secret has not expired and is entered correctly

Every Action Fails Immediately

Problem: Listing, creating, and reading all fail at once, with a message asking for the openid and profile scopes

• Solution: Add both openid and profile to the scope list and save

• Check: Affected users must disconnect and reconnect, because an existing connection keeps its original ID token

• Verify: Your app registration issues the tenant and user object identifier claims

Actions Stopped Working After Working Fine

Problem: The agent reports an unreadable or non-JSON response from Microsoft Forms

• Solution: Have the user disconnect and reconnect the Microsoft Forms integration

• Check: This is the usual signature of an expired or revoked authorization, because the Microsoft Forms API answers an expired token with a sign-in page rather than an error

• Verify: Confirm the user's Microsoft 365 account is still licensed for Microsoft Forms

Quiz Configuration Errors

Problem: Points or correct answers are rejected

• Solution: Use whole-number points from 0 to 100, and pass correct answers on choice questions only

• Check: The form must have been created as a quiz. Quiz mode cannot be switched on afterwards

• Verify: Every option of a graded question is unique, and a single-select question marks at most one correct answer

Partially Created Forms

Problem: The form was created but some questions are missing

• Solution: Add the missing questions to the existing form. Do not create the form again, because that leaves a duplicate behind

• Check: Open the edit link to see which questions did arrive

• Verify: The question types involved are supported, and any graded question names its correct answers

Users Cannot Find Their Forms

Problem: A form was created but the user cannot see it

• Solution: Direct the user to https://forms.office.com while signed in with the same work account they connected

• Check: Forms are owned by the individual user, not by a group or by a service account

• Verify: The user is signed in to the correct Microsoft tenant

Security and Compliance

Data Protection

• Delegated Access: The agent acts strictly as the signed-in user and can do only what that user can do. There is no organization-wide background access

• Form Ownership: Every form is created in the connected user's own Microsoft Forms account, under their name

• Credential Handling: Tokens are held in Blockbrain's secured OAuth vault. Blockbrain staff never see user passwords, and disconnecting revokes access immediately

Compliance Considerations

• GDPR Compliance: Form and response data processing follows GDPR and other relevant data protection requirements

• Response Data: Responses stay in Microsoft Forms. The agent reads them on request and does not keep its own copy

• Audit Logging: All MS Forms Agent activity is logged for compliance and reporting purposes

• Temporary Exports: Generated Word documents are stored temporarily and served through links that expire after one hour, scoped to your organization

Access Control

• User Permissions: The agent inherits the authenticated user's Microsoft Forms permissions

• Approval Gates: Creating and updating forms require user approval by default, on top of the agent's own draft-then-confirm workflow

• Knowledge Base Grounding: When a form is grounded in internal content, the agent reads only the documents that chat workspace already has access to

How form creation works. Microsoft does not offer an official API for creating forms, so the agent uses the same internal Microsoft interface that Microsoft's own Forms web app and Copilot use, acting as the signed-in user.

If Microsoft changes that interface, form creation may be temporarily unavailable. Drafting a form in chat and downloading it as a Word document always work, and reading existing responses is unaffected.

Next Steps

After successful MS Forms Agent configuration:

• Tool Permissions: Review the permission level on Create Microsoft Form and Update Microsoft Form, as described above

• User Training: Show users the draft-then-approve workflow, since nothing is created until they confirm

• Knowledge Bases: Connect the knowledge bases you want forms and quizzes to be grounded in

Support and Resources

For assistance with MS Forms Agent configuration:

• Blockbrain Support: Contact your Customer Success Manager for feature-specific help

• Microsoft Documentation: Reference the Microsoft Entra ID documentation for delegated permission and consent details

• Azure AD Troubleshooting: Use Microsoft Entra ID sign-in logs for authentication diagnostics