Power BI and Microsoft 365 / practical developer guides
Microsoft Work IQ API: Semantic Grounding for AI Agents
Begin with a document or message you already have permission to read and a question whose answer you can verify. Do not start by asking an agent to send mail or search the whole organization. Work IQ's protocol, policy and billing boundaries matter as much as the prompt.
1. Chat, context, tools and workspaces: capabilities, not invented URLs
Work IQ builds permission-aware context from Microsoft 365 and connected business systems, including supported Dynamics 365/Power Platform data. Its four capability areas describe how agents work:
| Area | Purpose | Boundary to verify |
|---|---|---|
| Chat | Synthesized grounded responses | Generated answers can be incomplete or wrong. |
| Context | Agent-ready grounding | Current retrieve tool has a public-preview notice. |
| Tools | Discover and operate on supported resources | Writes need permission, tenant policy and explicit application approval. |
| Workspaces | Persistent intermediate work/output | Uses SharePoint Embedded working storage; not an automatic transcript archive for every call. |
These are not a license to invent /v1/context or assume identical availability across MCP, REST and A2A. Use the detailed protocol reference. The earlier api.work-iq.microsoft.com/v1/context example was not an established current contract and should not be used.
Work IQ can reduce the need to build a separate retrieval/indexing pipeline for supported scenarios. It does not remove your responsibility for frontend authorization, downstream model/provider handling, retained outputs, action confirmation and failure recovery.
2. Choose a protocol by the operation you need
| Protocol | Use it for | Do not assume |
|---|---|---|
| Remote MCP | An agent discovering schemas, reading resources, asking questions or invoking permitted actions | That all tools are read-only or that an older conceptual workiq.search tool exists. |
| REST | Textual, multiturn Copilot conversation with work/web grounding | Sending mail, creating files, scheduling or long-running tasks. |
| A2A | Agent delegation with the documented JSON-RPC envelope/version | That an arbitrary REST body is an A2A request. |
| Local CLI/MCP | Supported local command-line integration | That its package/configuration is identical to the remote plugin. |
Current remote MCP is https://workiq.svc.cloud.microsoft/mcp. It exposes generic tools such as fetch, create/update/delete entity, do_action, ask, retrieve, get_schema and search_paths. Discover the current schemas and supported paths at runtime rather than hardcoding a total tool count.
REST is currently text-only, does not support action/content-generation skills, code interpreter or graphic art, and can time out on long tasks. It uses work and web grounding by default; disabling web grounding is per turn, not a conversation-wide permanent setting.
A2A uses https://workiq.svc.cloud.microsoft/a2a/. Current docs distinguish v1.0 via A2A-Version: 1.0 from the no-header v0.3 default. Use returned contextId for supported follow-ups and the documented Location metadata for time-sensitive questions. Authentication stays in the Authorization header, not a token embedded in a JSON-RPC security object.
3. Enablement, billing and delegated authorization
Separate the organization setup from a developer’s client installation. The current tenant guide requires a supported usage-based billing plan linked to an Azure subscription/resource group, assignment of the user to the plan and an administrator for one-time setup.
The tenant must have the Work IQ service principal. Remote MCP documentation says first use normally provisions it automatically, but policy configuration before first use can require the explicit administrator setup. Do not repeatedly create duplicate app registrations or bypass consent to solve that issue.
For the documented custom conversational/A2A application path, the delegated scope is api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask. Its permissions reference says admin consent is required and describes read/write access to supported resources in the user’s scope. It is not a read-only permission merely because its name says Ask.
Use the actual protocol/client’s consent and policy documentation. The remote MCP overview describes broad capability permissions plus path/method policies; do not assume one permission table configures every generic-tool operation.
Public-client samples and server-side apps need different registrations. A server-side confidential client can use the on-behalf-of flow, but that still represents a signed-in user. A client secret does not turn it into supported app-only Work IQ access. Never put secrets/tokens in browser code or shared MCP examples.
4. A current remote MCP setup using Copilot CLI
After the organization approves the client, data access and billing, follow the remote Work IQ MCP quickstart. Inside GitHub Copilot CLI:
/plugin marketplace add microsoft/work-iq
/plugin install workiq@work-iqComplete the documented installation prompts and restart Copilot CLI. Verify the loaded connection and skills:
/mcp
/skillsConfirm the Work IQ entry uses https://workiq.svc.cloud.microsoft/mcp and sign in interactively as the intended Microsoft 365 user. Do not add a manually pasted token or register an overlapping local server unless you intentionally choose that separate path.
The local CLI guide also documents @microsoft/workiq and local stdio mode. Those are valid alternatives, but their client configuration needs the host’s schema; a bare server-name object is not automatically a complete VS Code configuration.
This is a documentation walkthrough, not a connection to your organization’s Microsoft 365 data. Installation is not itself proof that billing assignment, consent, path policies or data-source permissions are correct.
5. Test known evidence, denied access and no side effects
Use a small approved test document with a non-sensitive fictional project name, decision, owner and date. Ensure test user A can access it and test user B cannot. Avoid copying real private mail into a test fixture.
- Ask A’s agent to find the test document and report its decision, source link and decision date. Explicitly prohibit create/update/delete/send actions.
- Compare the answer and citation with the actual document. Retrieval is not guaranteed to be immediate; indexing, selected paths and query behavior affect discovery.
- Ask about an intentionally absent detail. An honest missing-evidence answer is better than a plausible invented owner/date.
- Repeat in B’s authorized test session. Verify the private source/content is not returned. Do not treat a denial on one path as proof of the entire tenant’s access model.
- Inspect the tool calls and policy outcome. Verify no side-effect tool ran and record only the minimal non-sensitive test evidence.
Pass criteria: correct sourced facts for A; no unsupported details; no inaccessible content for B; and no write operations. The tests have not been executed in your tenant by this article.
For an action-taking application, add a separate approval test with a harmless sandbox target. Show the proposed recipient/resource/payload, reject once and verify no action, then approve an independent test and inspect the result. The fact that Work IQ permits an action is not the same as the user authorizing that specific action in your app.
6. Permission trimming does not remove the downstream boundary
Entra delegated identity, Microsoft 365 permissions and tenant policies govern what Work IQ can access. Remote MCP also evaluates resource paths/methods and policy. Do not equate protocol interoperability with permission to send organizational content to any LLM/provider.
Once a custom agent receives a response, its logs, prompts, storage and further tool calls create additional handling decisions. Work IQ’s tenant-governed working storage does not prove that all downstream application processing remains inside the Microsoft 365 trust boundary.
Retrieved messages/documents can contain instructions that are not trustworthy. Treat them as evidence, not authority to change system instructions or invoke writes. Restrict tools, minimize context and make evidence uncertainty visible.
For parent/child multitenant organizations, the documented token issuer must match the signed-in user’s home tenant. Enabling Work IQ in both tenants alone is insufficient; the registration/audience and authority must match the supported flow. Diagnose this before changing data permissions.
Keep approved operational logs without credentials or unnecessary document/mail bodies. Verify actual audit coverage and retention for the chosen integration; platform observability does not imply a complete transcript of every external agent step.
7. Cost controls and choosing Work IQ versus other tools
Work IQ API uses Copilot Credits for custom/third-party apps and agents, including for Microsoft 365 Copilot licensed users. Do not promise that Foundry, GitHub Copilot or any other Microsoft-built host is universally free simply because the user has a Copilot add-on license. The usage route and current licensing terms matter.
The current general billing overview supports administrative spending policies, allowed users/groups, selected services, policy/user limits, notifications and consumption reporting. Review the actual plan assignment and policy before load testing. The article does not invent a fixed per-tool rate, a universal workspace-storage rate or a monthly savings figure.
- Begin with a few known-answer questions and inspect actual credit use for the route.
- Bound retrieval/reasoning loops and action counts in the application.
- Handle exhausted credit/access policies explicitly rather than returning an empty success-shaped answer.
- Keep protocol/component preview notices separate from the core GA announcement.
Use Microsoft Graph for supported deterministic resource enumeration where that is the requirement. Use Fabric IQ for structured business context, Data Agent for its governed analytics path, and Web IQ for public-web evidence. They are complementary options, not mandatory layers of one all-or-nothing stack or a shared SLA.
Common questions
Does Work IQ support app-only authentication?
No. Current Work IQ API documentation requires delegated Entra identity; OBO is supported for a server acting for a user. A confidential client's secret does not remove the user context requirement.
Is WorkIQAgent.Ask a read-only permission without admin consent?
No. The current permission reference requires admin consent and describes supported read/write access scoped to the signed-in user. Review the chosen protocol's capability permissions and tenant path/action policies.
Can the Work IQ REST conversational API send email?
Not currently. Its documented limitations exclude action/content-generation skills such as sending mail, creating files and scheduling meetings. Remote MCP exposes a different generic-tool surface with supported actions subject to permissions and policy.
Is custom Work IQ usage free for Microsoft 365 Copilot licensed users?
Not generally. The current overview says custom and third-party agent use remains subject to usage-based billing, including licensed users. Check the actual route, plan and terms rather than assuming the host application's brand makes it free.
Does permission trimming mean my custom agent cannot leak data later?
No. It governs Work IQ's access under the user and policy. The receiving application's prompts, external model/provider, logs, storage and subsequent actions still need approved controls and data handling.
Official references and review scope
Checked against the following official vendor documentation on 2026-10-30. This is an independent learning guide, not a Microsoft certification, benchmark or customer deployment report. These workflows have not been executed in your tenant. Expected values are teaching acceptance checks; validate feature availability, identity, network, schema, data handling and recovery requirements before production use.
- Work IQ capabilities, governance and access/pricing
- API protocols, delegated identity and OBO
- Tenant setup and billing assignment
- Remote MCP Copilot CLI quickstart
- Remote MCP tool surface, policies and retrieve preview
- Copilot Credits cost management
- Delegated permission and required admin consent
- REST capabilities and current limitations
- A2A version, registration and sample
- Local Work IQ CLI and MCP