> For the complete documentation index, see [llms.txt](https://docs.blockbrain.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockbrain.ai/for-admins/agents/ms-forms-agent.md). # 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
Cover image
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
Screenshot 2025-12-04 at 13.51.34.png
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
Screenshot 2025-12-04 at 13.51.48.png
{% hint style="info" %} 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. {% endhint %} ### 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 | {% hint style="warning" %} **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**. {% endhint %} 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 {% hint style="danger" %} **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. {% endhint %} #### 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-admins/manage-tools-and-connectors.md) 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 {% hint style="info" %} **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. {% endhint %} ### 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 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.blockbrain.ai/for-admins/agents/ms-forms-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.