Connect agents to Microsoft 365 with Work IQ (preview)

Learn how to connect Foundry Agent Service agents to Work IQ so they can use Microsoft 365 emails, meetings, files, and chats as context.

Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Work IQ is the intelligence layer that grounds Microsoft 365 Copilot and your agents in real-time, shared context across your organization. It captures signals from emails, meetings, files, chats, and business systems, and applies semantic understanding so agents can reason over work data and take action. All requests run in the context of the signed-in user and honor Microsoft 365 permissions.

You connect your Foundry agent to Work IQ through the Agent-to-Agent (A2A) protocol. Your agent delegates natural-language tasks to Work IQ as a peer agent — for example, “Summarize my recent emails about Project Contoso” — and Work IQ handles retrieval, reasoning, and response synthesis against the user’s Microsoft 365 data.

For information on optimizing tool usage, see best practices.

When you connect to Work IQ, you may incur costs and data may be sent outside the Azure compliance boundary and processed according to the applicable service terms and data handling policies. It is your responsibility to manage whether your data will flow outside of your organization’s compliance and geographic boundaries and any related implications, and that appropriate permissions, boundaries, and approvals are provisioned.

You’re responsible for carefully reviewing and testing applications you build in the context of your specific use cases and making all appropriate decisions and customizations. This includes implementing your own responsible AI mitigations, such as metaprompts, content filters, or other safety systems, and ensuring your applications meet appropriate quality, reliability, security, and trustworthiness standards. See the Foundry Agent Service transparency note.

Prerequisites

Before you begin, make sure you have:

• The commercial requirement for the connection you use:

  Connection path	Requirement type	Requirement
  Work IQ API through A2A, REST, or MCP	Usage-based billing	Enable billing with Copilot Credits. This path doesn’t use connector licensing.
  Connector-backed Microsoft 365 tools	Connector licensing	Confirm the selected connector’s prerequisites. A connector can require a Microsoft 365 Copilot license for each calling user.

• An active Microsoft Foundry project with a deployed model.

• Azure RBAC roles:

  • Foundry User role on the Foundry project for the developer identity, the agent’s runtime identity, and any user identity involved in OAuth flows.
  • Foundry Project Manager role on the Foundry project for creating a Foundry connection to the Work IQ endpoint.

• A Microsoft Entra Global Administrator who can complete the one-time tenant setup by provisioning the Work IQ service principal and granting admin consent for WorkIQAgent.Ask. Activate this role just in time through Microsoft Entra Privileged Identity Management (PIM), and deactivate it after setup. Day-to-day Work IQ users don’t need this role.

• Foundry Toolkit: Install Visual Studio Code and Foundry Toolkit for Visual Studio Code.

• JavaScript development: Use Node.js 22 or later and install @azure/ai-projects 2.4.0 or later with @azure/identity.

For direct A2A calls, Work IQ supports protocol versions 1.0 and 0.3. Send A2A-Version: 1.0 to use v1 method names. Omitting the header defaults to v0.3. Include location metadata for time-sensitive requests, and use delegated user authentication.

Follow the setup dependency map

Use this map to separate the agent-use flow from dependencies that an administrator completes once for the organization.

Goal	Depends on	Continue at
Add Work IQ to an agent and send a query	An existing Work IQ connection, the signed-in user’s Microsoft 365 permissions, and the billing or connector licensing listed in the prerequisites.	Add the Work IQ tool to your agent
Create the first Work IQ connection for the organization	The Work IQ service principal, a single-tenant Entra app, delegated WorkIQAgent.Ask permission, and tenant-wide admin consent.	Set up your Entra app
Use a connector-backed Microsoft 365 tool	A connection for that connector and any connector-specific license required for the signed-in user.	Add the Work IQ tool to your agent

Complete the agent-use flow first when your organization already has a connection. Use the one-time tenant setup only when an administrator needs to create the first connection.

Consider adding this tool using a toolbox. By using a toolbox, you are able to reuse the tool across agents and runtimes, as well as centralizing credential management, versioning, and policy enforcement through a managed MCP endpoint. See the toolbox quickstart.

Usage support

Microsoft Foundry support	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Basic agent setup	Standard agent setup
Work IQ	✔️	✔️	✔️	—	✔️	✔️	✔️

How it works

1. Your agent dispatches a tool call — When the agent model identifies a task that requires Microsoft 365 data, it emits a tool call to the work_iq_preview tool.
2. Foundry routes the request to Work IQ via A2A — Foundry uses the Agent-to-Agent (A2A) protocol to forward the natural-language query to Work IQ as a peer agent. Authentication uses On-Behalf-Of (OBO) so the request runs in the context of the signed-in user.
3. Work IQ retrieves and reasons over M365 data — Work IQ queries the user’s emails, meetings, files, chats, and other Microsoft 365 signals. It applies semantic understanding to synthesize a response grounded in the user’s actual work context, honoring Microsoft 365 permissions and sensitivity labels throughout.
4. The result is returned to your agent — Work IQ returns the synthesized response to Foundry via A2A. Your agent incorporates it into its reply to the user.

Connect to Work IQ

Add the Work IQ tool to your agent

Add Work IQ to a toolbox with the Azure Developer CLI

Use the Azure Developer CLI to create the Work IQ A2A project connection, then reference it from a minimal toolbox YAML.

# Step 1. Create the Work IQ connection
azd ai connection create my-workiq-conn \
  --kind remote-a2a \
  --target https://workiq.svc.cloud.microsoft/a2a/ \
  --auth-type oauth2 \
  --authorization-url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize \
  --token-url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask offline_access"

This article uses the Work IQ A2A endpoint https://workiq.svc.cloud.microsoft/a2a/. The previous toolbox catalog used https://agent365.svc.cloud.microsoft/agents/agents/workiq for its azd workflow; verify the endpoint if your Work IQ connection uses a different A2A or MCP target.

# Step 2. Define the toolbox (my-toolbox.yaml)
description: Work IQ toolbox
tools:
  - type: work_iq_preview
    project_connection_id: my-workiq-conn

# Step 3. Create the toolbox
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

Use Work IQ with a hosted agent

After you create work-iq-toolbox, follow Use a toolbox with a hosted agent to connect it to Agent Framework, run it locally, and deploy it to Foundry Agent Service. The hosted integration preserves the per-request context that Work IQ needs to act on behalf of each signed-in user.

For end-to-end implementations, use the maintained Python Teams activity sample or .NET Teams activity sample.

Authentication and security

Work IQ uses Microsoft Entra ID delegated authentication. All requests run in the context of the signed-in user. Application-only (app-only) authentication isn’t supported. Microsoft 365 permissions are enforced automatically — Work IQ agents can never access data that the signed-in user isn’t already permitted to see.

Only Bring your own Entra app (On-Behalf-Of authentication) is supported for Work IQ connections. This gives your Entra admin explicit control over which applications can retrieve Microsoft 365 data through Work IQ: the admin reviews and grants the WorkIQAgent.Ask permission specifically for your registered app.

Set up your Entra app (one-time, per organization)

An Entra admin must complete the following one-time tenant operation before you can create a Work IQ connection in Foundry. For steps that require the Global Administrator role, use Microsoft Entra PIM to activate the role just in time, and deactivate it when setup is complete. Day-to-day Work IQ users don’t need this role.

Provision the Work IQ service principal (one-time)

Before you create the app registration, a Global Administrator must provision the Work IQ service principal as part of this one-time tenant operation. If you skip this step, the Work IQ option won’t appear when you search API permissions.

Follow Step 1: Create the Work IQ service principal in the Work IQ API quickstart. A 201 Created response from Graph Explorer confirms success. A conflict error means the principal already exists — continue to the next step.

Create the app registration

1. Go to the Microsoft Entra admin center. In the left navigation, select Entra ID > App registrations.

2. Select New registration. Give the app a descriptive name and set Supported account types to Accounts in this organizational directory only. Select Register.

3. Copy the Application (client) ID. You need this value when creating the Foundry connection.

4. Select API permissions > Add a permission > APIs my organization uses. Search for Work IQ (application ID fdcc1f02-fc51-4226-8753-f668596af7f7), select Delegated permissions, select WorkIQAgent.Ask, then select Add permissions.

5. Select Grant admin consent for [your tenant]. Review the confirmation dialog and select Yes.

Granting tenant-wide admin consent is a one-time tenant operation that requires the Global Administrator role in Microsoft Entra ID. Activate the role just in time through Microsoft Entra PIM, and deactivate it after granting consent. Day-to-day Work IQ users don’t need this role. If you don’t have this role, ask your organization’s Global Administrator to complete this step.

1. Select Certificates & secrets > New client secret. Add a description and expiration. Select Add, and then immediately copy the secret Value - it’s only shown once. Store the secret in Azure Key Vault or another approved secret store. Never commit the secret to source control or print or log it. Rotate the secret before it expires.
2. Copy your Directory (tenant) ID from the Microsoft Entra ID overview page.

Fill in the Foundry connection values

In Microsoft Foundry, open your project and go to Settings > Connections > New connection > Work IQ. Fill in the following fields:

Field	Value
Client ID	Application (client) ID from step 3
Client secret	Client secret value from step 6
Authorization URL	https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
Token URL	https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Refresh URL	https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Scopes	api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask,offline_access

Replace {tenant-id} with your Directory (tenant) ID from step 7. Select Save to create the connection.

Connection fields can’t be edited after creation. If you enter incorrect values, delete the connection and create a new one.

Add the redirect URI to your app registration

After Foundry creates the connection, it displays an OAuth redirect URL. Add this URL to your app registration:

1. In the Microsoft Entra admin center, go to Entra ID > App registrations and select your app.
2. Select Authentication > Add a platform > Web.
3. Under Redirect URIs, paste the OAuth redirect URL from Foundry.
4. Select Configure.

Create the connection with the REST API

As an alternative to the Foundry portal, use the Azure Resource Manager API to create the Work IQ connection programmatically.

Step 1: Acquire a token

ARM_TOKEN=$(az account get-access-token \
  --resource https://management.azure.com \
  --query accessToken -o tsv)

Step 2: Create the connection

SUBSCRIPTION_ID=<your-subscription-id>
RESOURCE_GROUP=<your-resource-group>
ACCOUNT_NAME=<your-foundry-account-name>
PROJECT_NAME=<your-project-name>
CONNECTION_NAME=<name-for-this-connection>
TENANT_ID=<your-tenant-id>
CLIENT_ID=<your-client-id>
CLIENT_SECRET=<your-client-secret>

curl --request PUT \
  --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$ACCOUNT_NAME/projects/$PROJECT_NAME/connections/$CONNECTION_NAME?api-version=2025-04-01-preview" \
  --header "Authorization: Bearer $ARM_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "tags": null,
    "location": null,
    "name": "'"$CONNECTION_NAME"'",
    "type": "Microsoft.MachineLearningServices/workspaces/connections",
    "properties": {
      "authType": "OAuth2",
      "group": "ServicesAndApps",
      "category": "RemoteA2A",
      "expiryTime": null,
      "target": "https://workiq.svc.cloud.microsoft/a2a/",
      "isSharedToAll": true,
      "sharedUserList": [],
      "TokenUrl": "https://login.microsoftonline.com/'"$TENANT_ID"'/oauth2/v2.0/token",
      "AuthorizationUrl": "https://login.microsoftonline.com/'"$TENANT_ID"'/oauth2/v2.0/authorize",
      "RefreshUrl": "https://login.microsoftonline.com/'"$TENANT_ID"'/oauth2/v2.0/token",
      "Scopes": [
        "api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask",
        "offline_access"
      ],
      "Credentials": {
        "ClientId": "'"$CLIENT_ID"'",
        "ClientSecret": "'"$CLIENT_SECRET"'"
      },
      "metadata": {
        "ApiType": "Azure"
      }
    }
  }'

A successful response returns HTTP 200 or 201. The response body includes a properties.oauthRedirectUrl field — use that value as the redirect URI in your Entra app registration (see Add the redirect URI to your app registration).

Data governance and compliance

Work IQ permission-trims retrieval against Microsoft 365. A Foundry workflow can also send prompts and retrieved results to downstream Copilot and Foundry processing, so review the boundaries and regional configuration of every service in the request path.

Data residency

Microsoft 365 retrieval follows your tenant’s permissions and residency configuration. End-to-end processing also depends on your Copilot billing configuration and Foundry project region. For details, see Microsoft 365 Copilot privacy and data handling policies.

Privacy and data handling

Review the Microsoft 365 Copilot privacy and data handling policies and the Foundry data handling requirements that apply to your deployment. Confirm the complete request path with your privacy and compliance teams.

Access control and permissions

Design the connection so retrieval uses the signed-in user’s Microsoft 365 permissions. Test permission trimming with representative users and restricted content before deployment:

• Role-based access control, sensitivity labels, and information barriers defined in Microsoft 365 are respected.

Compliance review

Use your organization’s Microsoft compliance resources to confirm which certifications and controls apply to the complete Work IQ and Foundry deployment.

Admin management

As an Entra admin, you control which applications in your tenant can access Work IQ data on behalf of users. The following sections describe the key controls available to you.

Grant or revoke admin consent

Admin consent for WorkIQAgent.Ask is required before any user in your organization can authenticate through the app. You can manage consent at any time:

• Grant consent: In the Microsoft Entra admin center, go to Entra ID > App registrations > select the app > API permissions. Select Grant admin consent for [your tenant].
• Revoke consent: On the same API permissions page, select the WorkIQAgent.Ask permission and select Revoke admin consent. Existing tokens remain valid until they expire; no new tokens can be issued after revocation.

Troubleshooting

Symptom	Likely cause	Resolution
403 Forbidden	Billing isn’t enabled for the Work IQ API, or a connector-specific license is missing.	Enable Copilot Credits billing for Work IQ API calls. For connector-backed tools, confirm the calling user meets that connector’s license requirements.
401 Unauthorized	Token audience mismatch	Ensure the token is issued for api://workiq.svc.cloud.microsoft, not for a different resource.
403 Forbidden with Required scopes = [...]	Admin consent for WorkIQAgent.Ask not granted	An admin must grant consent for the app registration.
Agent gets no response or empty result	Microsoft 365 content isn’t available to the signed-in user or hasn’t been indexed.	Confirm the user’s source permissions, then retry after indexing completes.
Principal does not have access to API/Operation	Agent identity missing Foundry User role at project scope	Assign Foundry User at both account scope and project scope.

Related content

• Work IQ API overview (preview)
• Work IQ API quickstart (preview)
• Connect to an A2A agent endpoint from Foundry Agent Service