What Is the SharePoint List Agent?
The SharePoint List Agent is a Microsoft 365 Copilot capability released in late 2025 that enables users to query SharePoint List data using plain English — no filter expressions, no Power BI reports, no calling IT. A project manager can ask "Show me all tasks overdue by more than a week assigned to the design team" and receive a filtered, summarised answer drawn directly from the list's current data. The response is grounded in the actual list items the user has permission to see, and it respects SharePoint's existing row-level security.
Under the hood, the List Agent is a specialised Copilot plugin that uses the Microsoft Graph API to retrieve list schema and items, passes them to the Azure OpenAI model as grounding context, and synthesises a response in natural language. It differs from a general Copilot query in that the grounding is scoped to a specific list — the model does not speculate beyond what the list data contains. This scope boundary is what makes it safe to deploy in enterprise scenarios where data accuracy matters more than creative synthesis.
The List Agent surface appears as a chat panel within the SharePoint List experience. When a user opens a list, a Copilot icon appears in the command bar. Clicking it opens an inline chat pane where queries and responses appear alongside the list data — users can see the answer and the underlying data simultaneously, which is critical for verification and trust. The chat history is session-local and is not stored as a permanent record, which aligns with most enterprise data retention policies without additional configuration.
The List Agent is list-scoped, not site-scoped. Users querying a Project Tasks list cannot accidentally retrieve data from a separate Contracts list on the same site — each Agent conversation is isolated to the list context where it was opened.
Enabling the List Agent in Your Tenant
The List Agent is enabled at the tenant level through the Microsoft 365 admin center, not the SharePoint admin center. Navigate to Settings > Microsoft 365 Copilot > Copilot in SharePoint and toggle on the "List Agent" setting. This setting cascades to all SharePoint sites and lists in the tenant within 24 hours. There is no per-site toggle in the initial release — it is all-on or all-off at the tenant level.
Site owners cannot independently enable or disable the List Agent for their specific site. If your organisation needs to restrict the List Agent to specific sensitive lists or exclude particular sites, the current workaround is to apply a SharePoint site template that configures column-level permissions to limit what the Agent can surface, or to use Entra Conditional Access policies to restrict Copilot access for specific user groups on those sites.
Once enabled, the Copilot icon will appear in the SharePoint List command bar for all users who have a qualifying Microsoft 365 Copilot licence. Users without the licence will not see the icon — the feature degrades gracefully, with no error messages or broken UI for unlicensed users.
Licensing Requirements
The List Agent is a Microsoft 365 Copilot feature, which means it requires a Microsoft 365 Copilot licence in addition to a qualifying Microsoft 365 base licence. As of January 2026, the Microsoft 365 Copilot add-on is priced at USD 30 per user per month and requires one of the following base licences: Microsoft 365 E3, E5, Business Standard, Business Premium, F3, or Office 365 E3/E5. Teams Essentials and F1 licences do not qualify.
For organisations with mixed licence populations — for example, a company where only knowledge workers have Copilot licences while frontline workers operate on F3 — the List Agent will be visible only to the Copilot-licensed users. Frontline workers using the same SharePoint lists will see the standard list experience without the Copilot chat pane. This asymmetry is usually acceptable, since list data queries are primarily a knowledge-worker workflow.
Microsoft has been updating Copilot licensing terms frequently. Always verify current requirements at aka.ms/Copilot365 before committing to a licensing architecture, particularly for phased rollouts that extend over multiple quarters.
Supported List Types and Column Constraints
The List Agent supports all standard SharePoint list types: custom lists, task lists, issue tracking lists, contact lists, and calendar lists. Document libraries are explicitly excluded in the initial release — the Agent is designed for structured row-and-column data, not file metadata queries, which are handled by a separate Copilot capability. Event lists (calendar) have partial support — the Agent can answer scheduling queries but cannot synthesise across recurring events.
Column type support is comprehensive for text, number, date, choice, person, lookup, and managed metadata columns. Calculated columns are surfaced by their computed value, not their formula — users see "Priority Score: 87" rather than the underlying calculation. Multi-value columns (multi-select choice, multi-person) are supported but the Agent's summarisation of multi-value data is less precise than for single-value columns, particularly when filtering across multiple multi-value columns in the same query.
Column Naming Best Practices for Agent Accuracy
Column internal names matter more than display names for Agent accuracy. If your list has a column with the internal name field_1 but the display name "Project Owner," the Agent understands the display name in user queries. However, columns with generic internal names like Title that have been repurposed as something semantically different (e.g., "Contract Number") can confuse the grounding context. Review list columns before enabling the Agent and rename display names to reflect their actual business meaning.
Query Examples and What the Agent Handles Well
The List Agent handles four categories of queries particularly well: filtering, aggregation, ranking, and cross-column correlation. Understanding which queries map to each category helps you train users to get high-quality answers quickly and set accurate expectations for edge cases.
Filtering queries are the most reliable. "Show me all items where Status is Blocked and Priority is High" consistently produces accurate results because the Agent translates the query directly to a CAML-equivalent filter. These queries work even on lists with 10,000+ items because the Agent filters at the API level rather than loading all items into the model context.
Aggregation queries — "How many issues were resolved last month?" or "What is the average completion rate across all projects?" — work well for standard aggregations (count, sum, average) on numeric and date columns. Complex aggregations across grouped data (e.g., "What is the average days-to-resolve per team member?") are supported but the Agent will occasionally simplify the grouping when the result set is large.
Ranking queries like "Which five projects have the most overdue tasks?" are reliably answered. The Agent sorts, filters, and limits the result set, then presents the top N results with a brief summary of each item. Ties are handled by secondary sort on the row ID, which is consistent but may not match the user's intended business logic — train users to specify a secondary sort criterion explicitly when needed.
Cross-column correlation — "Are there any vendors where the contract expiry is within 90 days and the renewal status is not Started?" — is where the Agent shows its most impressive capability. These queries would normally require a filtered view or a Power BI dataset, but the Agent handles them fluently. Accuracy degrades when correlations involve calculated columns or lookup columns that reference external lists.
// Filtering "Show all change requests submitted after 1 January 2026 with impact rating Critical" // Aggregation "How many onboarding tasks are still incomplete, grouped by department?" // Ranking "List the top 10 open support tickets sorted by days since creation, oldest first" // Cross-column correlation "Which vendors have an active contract but no renewal owner assigned?" // Temporal reasoning "What items were modified in the last 7 days that are still assigned to Alice?"
Grounding Limitations and Known Gaps
The List Agent is grounded strictly in list data accessible to the current user. It will not synthesise information from external sources, SharePoint pages, document libraries, or other lists — even if those lists are on the same site. This strict grounding is a deliberate design choice for data accuracy, but it creates friction for users who expect the Agent to reason across related data stored in multiple lists.
The most significant current limitation is the list item cap for grounding context. The Agent retrieves up to 2,000 items as grounding context per query session. For lists with more than 2,000 items, the Agent applies a relevance-based pre-filter to select the most likely relevant items before passing to the model. This means that on very large lists, the Agent may miss items that are relevant but ranked below the 2,000-item threshold. Microsoft has indicated this cap will increase as model context windows grow, but for now, lists exceeding 2,000 active items should be considered partially supported.
Lookup columns that reference items in other lists are surfaced by their display value only — the Agent cannot follow the lookup relationship and query properties of the referenced items. A lookup to a Projects list shows the project title but cannot answer "Show tasks where the linked project has a budget over $50,000" because the budget column lives in the Projects list, not the Tasks list.
The List Agent respects SharePoint permissions — it will only return items the current user can see. However, it does not distinguish between items hidden by list view filters and items that the user genuinely has no access to. Train users to understand that "no results" may mean filtered out rather than non-existent.
Combining List Agent with Power Automate
The List Agent's query capability and Power Automate's action capability are complementary. A workflow that works well in practice: the List Agent helps a user identify which items need attention ("Show me invoices overdue by more than 30 days"), and then the user can trigger a Power Automate flow from the list view to act on the identified items — sending reminders, updating statuses, or escalating to a manager.
The integration point is the SharePoint list itself. Power Automate flows triggered on list item updates or on a schedule can update columns that the List Agent then queries. For example, a daily flow that calculates a "DaysOverdue" number column from a due date gives the List Agent a concrete numeric column to filter and aggregate, producing more reliable results than asking the Agent to calculate the date difference itself from raw date column values.
// Trigger: Recurrence (daily at 06:00 UTC) // Action 1: Get Items (filter: DueDate lt utcNow(), Status ne 'Completed') // Action 2: Apply to each item formatDateTime(utcNow(), 'yyyy-MM-ddTHH:mm:ssZ') // Calculate difference in days div( sub( ticks(utcNow()), ticks(item()?['DueDate']) ), 864000000000 // ticks per day ) // Action 3: Update Item — set DaysOverdue to calculated value
Advanced integration patterns use a Power Automate cloud flow triggered by a custom button (a Power Apps canvas app embedded in the SharePoint page) that takes the List Agent's response as input and creates a follow-up task in Planner or a Teams notification. While this pattern is not natively supported by Microsoft's current tooling, it can be achieved by extracting the list item IDs from the Agent's response manually and passing them to the flow via the SharePoint list multi-select UI.
What Developers Can Build on Top of List Agent
The List Agent is a Microsoft-managed capability, not an extensibility point in the traditional SPFx sense. Developers cannot currently inject custom prompt engineering, swap the grounding model, or add custom plugins to the List Agent itself. However, there are several adjacent extensibility opportunities that amplify the List Agent's value for enterprise scenarios.
The most impactful developer opportunity is list schema design for Agent fidelity. Well-designed lists with descriptive column display names, consistent choice values, and no repurposed columns produce dramatically better Agent responses than organically grown lists. Create a list design guide for your organisation that specifies naming conventions, required managed metadata columns for classification, and a policy against calculated columns that reference external data sources — all of these directly improve List Agent accuracy.
The second opportunity is Microsoft Copilot Studio (formerly Power Virtual Agents) integration. You can build a Copilot Studio bot that uses the SharePoint connector to query list data and present results in a Teams adaptive card — effectively building a custom interface around the same underlying capability that the List Agent uses. This gives you full control over the conversational UI, follow-up actions, and escalation logic, at the cost of maintaining a custom bot rather than using Microsoft's native surface.
// GET https://graph.microsoft.com/v1.0/sites/{site-id}/lists/{list-id}/items // ?$expand=fields&$filter=fields/Status eq 'In Progress' // &$select=id,fields&$top=100 const response = await client .api(`/sites/${siteId}/lists/${listId}/items`) .expand('fields') .filter("fields/Status eq 'In Progress'") .select('id,fields') .top(100) .get(); // Pass response.value as grounding context to Azure OpenAI const groundingContext = response.value.map(item => ({ id: item.id, ...item.fields }));
The third opportunity is Declarative Copilot agents built with Microsoft 365 Agents SDK. With the Agents SDK released alongside Microsoft 365 Copilot, developers can build a declarative agent that wraps a specific SharePoint list as its knowledge source, adds custom instructions for domain-specific interpretation (e.g., "when a user asks about a 'deal' they mean an item in the Opportunities list"), and deploys it as a named agent in Microsoft Teams. This is the highest-investment, highest-value option for organisations with complex list-based workflows.
Key Takeaways
The SharePoint List Agent is tenant-wide and requires a Microsoft 365 Copilot add-on licence — there is no per-site toggle in the initial release, so plan your licensing rollout carefully before enabling.
Filtering, aggregation, and cross-column correlation queries are the Agent's strongest capabilities — coach users to phrase queries with specific column names and values for maximum accuracy.
The 2,000-item grounding cap means very large lists have partial support — mitigate this by archiving completed items to a separate list and keeping active lists lean.
Power Automate calculated columns (DaysOverdue, PriorityScore) fed by scheduled flows give the Agent concrete numeric fields that produce more reliable query results than asking the Agent to derive calculations at query time.
For enterprise extensibility, the Microsoft 365 Agents SDK (declarative agents with SharePoint list knowledge sources) is the highest-value investment for teams with complex list-based workflows.