Catalogue › Microsoft 365 Agents › agent-grounding

Agent grounding

Configures and controls what a Microsoft 365 agent grounds on - choosing specific sites, libraries, files or connectors rather than broad locations, deciding on web content, restricting answers to named sources, checking permission trimming and citations - and keeps a controlled knowledge list with owners and change approval. Use when a maker is adding knowledge to an agent, when answers come from the wrong places, or when knowledge changes.

Department: Microsoft 365 Agents
Lifecycle: Deliver, Assure, Improve
Maturity: adopter, builder, scaler, ai-enterprise
Risk tiers: 1, 2, 3
Platforms: m365-agents, copilot-studio, sharepoint
Editions: starter, scale, enterprise
Reviewers: security-privacy, evaluation-quality
Status: draft
Copilot Cowork: Microsoft 365 Agents plugin for Copilot Cowork, or this skill on its own: Download SKILL.md
Licence: CC BY 4.0, by Simon Foote

Purpose

An agent answers from what it is pointed at, so the grounding configuration decides both the quality of its answers and what it can expose. This skill takes sources that have passed readiness and configures them precisely: the specific sites, libraries, folders, files or connectors, whether web content is used, whether answers are restricted to the named sources, and how citations appear. It then keeps that configuration under control as sources change. Grounding usually goes wrong when a maker adds a whole site or a whole drive because it is quicker, so the agent answers from drafts, archives and content the audience should never have been able to find.

When to use

A maker is about to add knowledge to an agent built from an agreed brief.
An agent's answers come from the wrong documents, old versions or unexpected locations.
A knowledge source is moving, being restructured or being retired.
Someone wants to add a new source or turn on web content for a live agent.

When not to use

Judging whether a source is fit to ground on (owner, currency, accuracy, permissions) - use m365-agents:knowledge-source-readiness.
Designing knowledge sources and retrieval for Copilot Studio agents in depth - use copilot-studio:studio-knowledge-architecture.
Designing indexing, chunking and search for a custom AI solution - use ai-foundry:retrieval-design.
Setting organisation-wide standards that content must meet before agents ground on it - use knowledge-management:knowledge-grounding-standards.
Keeping knowledge current once the agent is in operation - use ai-operations:knowledge-refresh.

Questions to ask first

Which sources did the brief name, and what readiness verdict has each received?
What is the narrowest scope within each source that covers the in-scope questions (site, library, folder or file)?
Should the agent use web content or only the named sources, and why?
Can every intended user already open each source, and should anyone who can open it be excluded from the audience?
Who approves a change to the knowledge list, and how is it tested?

Required inputs

The agent brief with in-scope questions and named sources.
A readiness verdict for each source from m365-agents:knowledge-source-readiness.
The intended audience and sharing scope.
The evaluation set from m365-agents:agent-testing, including permission-trimming tests.

A source without a ready or ready-with-conditions verdict is not added. Never widen a source's scope to make an answer work; fix the content or its location instead.

Decision framework

Decision	Default	Change only when
Scope within a source	The narrowest folder, library or file set that covers the in-scope questions	Evidence shows needed content sits outside it and that content is ready
Whole sites or drives	Avoid	The whole site is curated for this purpose and owned
Web content	Off for organisational knowledge agents	The brief needs public information and the business owner accepts the trade-off
Restrict to named sources	On, where the build path supports it	The agent's purpose depends on general knowledge, recorded in the brief
Connectors to other systems	Only with an owner, an access model and a security review	Never as a shortcut to content that should be in governed locations
Citations	Shown for factual answers	The format does not support them, and users are told how to verify

Decision

Default

Change only when

Scope within a source

The narrowest folder, library or file set that covers the in-scope questions

Evidence shows needed content sits outside it and that content is ready

Whole sites or drives

Avoid

The whole site is curated for this purpose and owned

Web content

Off for organisational knowledge agents

The brief needs public information and the business owner accepts the trade-off

Restrict to named sources

On, where the build path supports it

The agent's purpose depends on general knowledge, recorded in the brief

Connectors to other systems

Only with an owner, an access model and a security review

Never as a shortcut to content that should be in governed locations

Citations

Shown for factual answers

The format does not support them, and users are told how to verify

Every source in the configuration appears on a knowledge list with location, scope, owner, readiness verdict, review date and the date it was added.

Practitioner approach

Start with the in-scope questions and work backwards to content. For each representative question, find the document that should answer it. That tells you exactly which folders and files the agent needs, and usually reveals that the answer lives in a small, well-defined part of a large site. Point the agent at that part, not the whole site.

Check permissions from the user's side. Agents answer with the permissions of the person asking, so the question is not "can the agent see this?" but "can each intended user see this, and should they?". If the intended audience cannot open a source, the agent will not answer from it for them; if a source is open to far more people than intended, the agent makes that oversharing easier to exploit. Resolve either problem at the source with its owner, not by adjusting the agent.

Decide about web content deliberately. For agents that answer from organisational policy or procedure, mixing in web content blurs the authority of the answer. Leave it off unless the brief needs it and the owner accepts the trade-off, and check in the source records how the setting behaves in the build path you are using.

Where the build path allows the agent to answer only from named sources, use that setting for knowledge agents, and test that it holds. Confirm the current options and their behaviour in the source records, because they change.

Configure citations so users can open the source behind an answer, and test that the citations point to the current version. Stale copies in other locations are a common cause of confident but outdated answers.

Run the grounding tests from m365-agents:agent-testing: questions answered from the right source, questions that should find nothing, and permission tests with users inside and outside the audience. Record results against the configuration version.

Put the knowledge list under change control. Adding, widening or removing a source is a change that needs the business owner's approval, a readiness verdict and a regression run. Link each source's review date to its owner's review cycle, so a policy update prompts a check of the agent.

Outputs

A grounding configuration record and knowledge list: each source with location, scope, owner, readiness verdict, web content and restriction settings, review date and date added.
Grounding and permission test results tied to the configuration version.
A change rule for the knowledge list recorded on the agent-card.

Microsoft platform considerations

Agent Builder, declarative agents and Copilot Studio each offer different knowledge source types, scoping options, web content settings, connector options and limits, described in ms-agent-builder, ms-declarative-agents and ms-agents-extensibility. Permission-trimmed grounding is described in ms-copilot-privacy. These change often; check the current records before configuring, and never assert a limit or setting from memory.

Adoption considerations

Users trust agents whose answers cite sources they recognise. Tell users in the launch message where the agent's answers come from and how to report one that looks wrong.

Knowledge considerations

Grounding quality is capped by the content. Prefer a small, curated, owned source over a large, mixed one, and route structural content problems to the knowledge-management department, especially knowledge-management:ai-ready-content for how documents are written and structured.

Security and privacy considerations

Broad sources and connectors widen what an agent can surface. From tier 2, every source and connector is part of the security-privacy:data-exposure-review, and any connector also goes through security-privacy:connector-review. Instructions are never used in place of restricting content.

Responsible AI considerations

Answers must be traceable to sources. Where knowledge covers matters that affect people's rights, pay or safety, ensure the agent cites the authoritative document and redirects to a person for individual cases.

Evaluation requirements

Grounding tests must show answers come from the intended sources, that out-of-scope questions do not draw on unrelated content, and that users outside the audience cannot obtain restricted answers. Re-run after any change to the knowledge list.

Value measures

Track the share of evaluation answers grounded in the intended source and, in operation, feedback flagging wrong or outdated answers, at audience level. The business owner owns these measures with the knowledge owners.

Scale notes

Starter

Two or three narrowly scoped sources with named owners, web content off, and a simple knowledge list kept with the agent's brief.

Scale

A standard knowledge list per agent, grounding tests as part of every release, and knowledge changes approved through the CoE cadence.

Enterprise

Curated knowledge locations designed for agents across business units, connectors governed centrally, and knowledge lists linked to the knowledge owners' review cycles.

Hand-offs

To m365-agents:agent-testing for grounding and permission tests after each change.
To security-privacy:data-exposure-review and security-privacy:connector-review from tier 2.
To ai-operations:knowledge-refresh for keeping knowledge current in operation.
Back to m365-agents:knowledge-source-readiness when a source's condition changes.

Reviewer gates

From risk tier 2, security-privacy reviews every source and connector for exposure, and from tier 3 evaluation-quality confirms grounding test evidence; each finding is blocking or advisory, and blocking findings stop release or the change.

Failure modes

A whole site is added for convenience, and the agent answers from drafts and archives.
Web content is left on, and the agent mixes public material with policy as if both were authoritative.
A source is widened after review, so the agent reaches content reviewers never saw.
Citations point to stale copies, and users act on outdated information.

Sources

references/sources.md in this skill lists the source records behind this skill, what each is authoritative for, how volatile it is and what you may do with it. Product availability, licensing, limits and preview status change often, so check the current source before stating them, and cite what you used.

Never

Add a source without a readiness verdict and an owner.
Point an agent at a whole site or drive when a narrower scope covers the need.
Use instructions in place of restricting content that users should not see.
Change the knowledge list without approval and a regression run.

Source records for this skill

Agent Builder overview

Source id: ms-agent-builder
Publisher: Microsoft (product-documentation)
Link: https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/agent-builder
Authoritative for: Building declarative agents in Agent Builder, knowledge sources, sharing and known limitations.
Volatility: high; review every 30d; last reviewed 2026-10-29
What you may do: Read and cite. Summarise in your own words; do not reproduce the text.

Declarative agents for Microsoft 365 Copilot

Source id: ms-declarative-agents
Publisher: Microsoft (product-documentation)
Link: https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/overview-declarative-agent
Authoritative for: When a declarative agent is warranted, build-or-reuse decisions and the dependencies to record for an agent.
Volatility: high; review every 30d; last reviewed 2026-10-29
What you may do: Read and cite. Summarise in your own words; do not reproduce the text.

Ways to extend Microsoft 365 Copilot

Source id: ms-agents-extensibility
Publisher: Microsoft (product-documentation)
Link: https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/overview
Authoritative for: The extensibility options for Copilot, including agents, connectors, skills and tools, and how to choose between them.
Volatility: high; review every 30d; last reviewed 2026-10-29
What you may do: Read and cite. Summarise in your own words; do not reproduce the text.

Data, privacy and security for Microsoft Copilot

Source id: ms-copilot-privacy
Publisher: Microsoft (trust-and-compliance)
Link: https://learn.microsoft.com/en-us/microsoft-365/copilot/microsoft-365-copilot-privacy
Authoritative for: How Copilot uses organisational data, permission-trimmed grounding, stored interaction data, data residency and extensibility controls.
Volatility: high; review every 30d; last reviewed 2026-10-29
What you may do: Read and cite. Summarise in your own words; do not reproduce the text.

Credit

This skill was created by Simon Foote as part of CopilotForge, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Credit the author when you share or adapt it.