Connect agents to Microsoft 365 with Work IQ (preview)

Important

Items marked preview in this article are currently in preview. This preview is provided without a service-level agreement, and Microsoft doesn'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.

Note

The built-in Work IQ tool (work_iq_preview) is in preview and calls the Work IQ A2A endpoint.

For new agents and toolboxes, including Outlook mail and organizational lookups, use the generally available (GA) MCP path. Use the standard MCP tool (type: mcp) with the Work IQ MCP endpoint: https://workiq.svc.cloud.microsoft/mcp. For setup, see Connect a Microsoft Foundry project to Work IQ.

Adding the built-in tool to a toolbox doesn't change its preview status or A2A protocol. Before reusing an existing connection for the GA path, verify that it targets the Work IQ MCP endpoint and has the required authentication and permissions.

Work IQ is the intelligence layer that grounds Microsoft 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 can connect your Foundry agent to the Work IQ MCP endpoint by using the standard MCP tool. The examples in this article call Work IQ and retrieve content from a specific SharePoint site.

For information on optimizing tool usage, see best practices.

Warning

When you connect to Work IQ, you might incur costs and data might be sent outside the Azure compliance boundary and processed according to the applicable service terms and data handling policies. It's your responsibility to manage whether your data flows 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 responsibility 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, ensure 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.

  • Visual Studio Code workflow: Install Visual Studio Code and Foundry Toolkit for Visual Studio Code if you use this workflow.

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

Important

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

MCP samples

Before running either MCP sample:

  • Deploy a model that supports the MCP tool.
  • Follow Connect Work IQ to Microsoft Foundry to create a Work IQ MCP connection. Its target must be https://workiq.svc.cloud.microsoft/mcp, not the A2A endpoint.
  • Configure delegated Microsoft Entra authentication with the api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask scope and complete user consent for the connection. Work IQ doesn't support application-only authentication.
  • Install the Azure CLI and sign in with az login --tenant <tenant-id>. The SDK samples use AzureCliCredential to authenticate to Foundry. This sign-in doesn't replace the Work IQ connection's OAuth consent.

For retrieve, also complete the retrieve prerequisites, including Copilot Credits billing and a spending policy that includes Work IQ API. Confirm that the server's tools/list response includes retrieve. The live tool schema is authoritative.

Built-in A2A tool

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.

Tip

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

The standard MCP integration is generally available and supports Python, C#, JavaScript/TypeScript, Java, and REST. The Work IQ retrieve tool remains in preview. The following table describes the separate built-in Work IQ A2A tool.

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

Call the Work IQ MCP endpoint

This example connects a prompt agent directly to https://workiq.svc.cloud.microsoft/mcp and lets it call the ask tool. It doesn't use WorkIQPreviewTool or the A2A endpoint.

Set these environment variables for the SDK examples:

  • FOUNDRY_PROJECT_ENDPOINT: Your Foundry project endpoint.
  • FOUNDRY_MODEL_NAME: Your model deployment name.
  • WORK_IQ_MCP_CONNECTION_ID: The resource ID of the Work IQ MCP project connection.

The SDK function creates an agent version, sends a request, prints the response, and deletes that version. It approves only calls to the selected tool on the workiq server. The SharePoint example reuses the function with an additional check of the tool arguments.

Select Python, C#, JavaScript/TypeScript, Java, or REST API to view the MCP samples. For the visual toolbox workflow, see Add the Work IQ tool to your agent.

Install azure-ai-projects and azure-identity:

pip install azure-ai-projects azure-identity

Reference: Azure AI Projects client library.

Save the following example as work_iq_mcp.py.

import json
import os

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPTool, PromptAgentDefinition
from azure.identity import AzureCliCredential


def run_work_iq(tool_name, prompt, expected_arguments=None):
    with (
        AzureCliCredential() as credential,
        AIProjectClient(
            endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            credential=credential,
        ) as project,
        project.get_openai_client() as client,
    ):
        tool = MCPTool(
            server_label="workiq",
            server_url="https://workiq.svc.cloud.microsoft/mcp",
            project_connection_id=os.environ["WORK_IQ_MCP_CONNECTION_ID"],
            allowed_tools=[tool_name],
            require_approval="always",
        )
        agent = project.agents.create_version(
            agent_name="work-iq-mcp-example",
            definition=PromptAgentDefinition(
                model=os.environ["FOUNDRY_MODEL_NAME"],
                instructions=f"Use the workiq {tool_name} tool to answer.",
                tools=[tool],
            ),
        )
        reference = {
            "agent_reference": {
                "type": "agent_reference",
                "name": agent.name,
                "version": agent.version,
            }
        }
        try:
            response = client.responses.create(
                input=prompt, extra_body=reference
            )
            while True:
                approvals = []
                for item in response.output:
                    if item.type != "mcp_approval_request":
                        continue
                    if (
                        item.server_label != "workiq"
                        or item.name != tool_name
                        or (
                            expected_arguments is not None
                            and json.loads(item.arguments)
                            != expected_arguments
                        )
                    ):
                        raise ValueError("Unexpected tool call; not approved.")
                    approvals.append({
                        "type": "mcp_approval_response",
                        "approval_request_id": item.id,
                        "approve": True,
                    })
                if not approvals:
                    break
                response = client.responses.create(
                    input=approvals,
                    previous_response_id=response.id,
                    extra_body=reference,
                )
            print(response.model_dump_json(indent=2))
        finally:
            project.agents.delete_version(
                agent_name=agent.name, agent_version=agent.version
            )


if __name__ == "__main__":
    run_work_iq(
        "ask", "Summarize my recent emails about Project Contoso."
    )

Reference: AIProjectClient, MCPTool, and PromptAgentDefinition.

Create a .NET 8 or later console application and add the packages:

dotnet add package Azure.AI.Projects --version 2.0.1
dotnet add package Azure.AI.Extensions.OpenAI --version 2.0.0
dotnet add package Azure.Identity

Reference: Azure AI Projects client library and Azure AI Projects OpenAI extension library.

Replace Program.cs with the following code. The static connection setter also works with compilers that don't support C# 14 extension properties.

#pragma warning disable OPENAI001
using System;
using System.ClientModel.Primitives;
using System.Linq;
using System.Text.Json.Nodes;
using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;

static void RunWorkIq(
    string toolName, string prompt, JsonNode? expectedArguments = null)
{
    string Required(string name) =>
        Environment.GetEnvironmentVariable(name)
        ?? throw new InvalidOperationException($"Set {name}.");

    AIProjectClient project = new(
        endpoint: new Uri(Required("FOUNDRY_PROJECT_ENDPOINT")),
        tokenProvider: new AzureCliCredential());
    McpTool tool = ResponseTool.CreateMcpTool(
        serverLabel: "workiq",
        serverUri: new Uri("https://workiq.svc.cloud.microsoft/mcp"),
        allowedTools: new McpToolFilter { ToolNames = { toolName } },
        toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
            GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval));
    McpToolExtensions.set_ProjectConnectionId(
        tool, Required("WORK_IQ_MCP_CONNECTION_ID"));
    DeclarativeAgentDefinition definition =
        new(model: Required("FOUNDRY_MODEL_NAME"))
        {
            Instructions = $"Use the workiq {toolName} tool to answer.",
            Tools = { tool }
        };
    ProjectsAgentVersion agent =
        project.AgentAdministrationClient.CreateAgentVersion(
            agentName: "work-iq-mcp-example", options: new(definition));
    try
    {
        AgentReference reference = new(agent.Name, agent.Version);
        var client = project.ProjectOpenAIClient
            .GetProjectResponsesClientForAgent(reference);
        CreateResponseOptions requestOptions = new()
        {
            InputItems = { ResponseItem.CreateUserMessageItem(prompt) }
        };
        ResponseResult response = client.CreateResponse(requestOptions);
        while (true)
        {
            var requests = response.OutputItems
                .OfType<McpToolCallApprovalRequestItem>().ToArray();
            if (requests.Length == 0)
                break;

            CreateResponseOptions continuation = new()
            {
                PreviousResponseId = response.Id
            };
            foreach (var request in requests)
            {
                if (request.ServerLabel != "workiq"
                    || request.ToolName != toolName
                    || (expectedArguments is not null
                        && !JsonNode.DeepEquals(expectedArguments,
                            JsonNode.Parse(request.ToolArguments.ToString()))))
                {
                    throw new InvalidOperationException(
                        "Unexpected tool call; not approved.");
                }
                continuation.InputItems.Add(
                    ResponseItem.CreateMcpApprovalResponseItem(
                        approvalRequestId: request.Id, approved: true));
            }
            response = client.CreateResponse(continuation);
        }
        Console.WriteLine(ModelReaderWriter.Write(response));
    }
    finally
    {
        project.AgentAdministrationClient.DeleteAgentVersion(
            agentName: agent.Name, agentVersion: agent.Version);
    }
}

RunWorkIq("ask", "Summarize my recent emails about Project Contoso.");

Reference: AIProjectClient and MCP tool with a project connection.

Install the JavaScript packages:

npm install @azure/ai-projects @azure/identity

Reference: Azure AI Projects client library.

Save this example as work-iq-mcp.cjs. The same MCP configuration applies to TypeScript.

const { isDeepStrictEqual } = require("node:util");
const { AIProjectClient } = require("@azure/ai-projects");
const { AzureCliCredential } = require("@azure/identity");

async function runWorkIq(toolName, prompt, expectedArguments = null) {
  const project = new AIProjectClient(
    process.env.FOUNDRY_PROJECT_ENDPOINT, new AzureCliCredential()
  );
  const client = project.getOpenAIClient();
  const agent = await project.agents.createVersion(
    "work-iq-mcp-example", {
      kind: "prompt",
      model: process.env.FOUNDRY_MODEL_NAME,
      instructions: `Use the workiq ${toolName} tool to answer.`,
      tools: [{
        type: "mcp",
        server_label: "workiq",
        server_url: "https://workiq.svc.cloud.microsoft/mcp",
        project_connection_id: process.env.WORK_IQ_MCP_CONNECTION_ID,
        allowed_tools: [toolName],
        require_approval: "always",
      }],
    }
  );
  const options = {
    body: {
      agent_reference: {
        type: "agent_reference",
        name: agent.name,
        version: agent.version,
      },
    },
  };
  try {
    let response = await client.responses.create({ input: prompt }, options);
    while (true) {
      /**
       * @type {import("openai/resources/responses/responses").ResponseInput}
       */
      const approvals = response.output
        .filter(item => item.type === "mcp_approval_request")
        .map(item => {
          if (item.server_label !== "workiq" || item.name !== toolName
              || (expectedArguments !== null && !isDeepStrictEqual(
                JSON.parse(item.arguments), expectedArguments))) {
            throw new Error("Unexpected tool call; not approved.");
          }
          return {
            type: "mcp_approval_response",
            approval_request_id: item.id,
            approve: true,
          };
        });
      if (approvals.length === 0) break;
      response = await client.responses.create({
        previous_response_id: response.id,
        input: approvals,
      }, options);
    }
    console.log(JSON.stringify(response, null, 2));
  } finally {
    await project.agents.deleteVersion(agent.name, agent.version);
  }
}

runWorkIq("ask", "Summarize my recent emails about Project Contoso.")
  .catch(error => {
    console.error(error);
    process.exitCode = 1;
  });

Reference: AIProjectClient and MCPTool.

Use Java 17 or later and add the com.azure:azure-ai-agents:2.9.0 and com.azure:azure-identity:1.19.0 dependencies. For Maven setup, see the Azure AI Agents client library. Save the following class as WorkIqMcpExample.java.

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.ai.agents.models.McpTool;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.core.util.BinaryData;
import com.azure.core.util.serializer.TypeReference;
import com.azure.identity.AzureCliCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import com.openai.models.responses.ResponseOutputItem;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class WorkIqMcpExample {
    public static void run(
        String toolName, String prompt, Map<String, Object> expectedArguments) {
        AgentsClientBuilder builder = new AgentsClientBuilder()
            .endpoint(System.getenv("FOUNDRY_PROJECT_ENDPOINT"))
            .credential(new AzureCliCredentialBuilder().build());
        AgentsClient agents = builder.buildAgentsClient();
        ResponsesClient responses = builder.buildResponsesClient();
        McpTool tool = new McpTool("workiq")
            .setServerUrl("https://workiq.svc.cloud.microsoft/mcp")
            .setProjectConnectionId(
                System.getenv("WORK_IQ_MCP_CONNECTION_ID"))
            .setAllowedTools(List.of(toolName))
            .setRequireApproval("always");
        AgentVersionDetails agent = agents.createAgentVersion(
            "work-iq-mcp-example",
            new PromptAgentDefinition(System.getenv("FOUNDRY_MODEL_NAME"))
                .setInstructions("Use the workiq " + toolName + " tool.")
                .setTools(List.of(tool)));
        AzureCreateResponseOptions options = new AzureCreateResponseOptions()
            .setAgentReference(new AgentReference(agent.getName())
                .setVersion(agent.getVersion()));
        try {
            Response response = responses.createAzureResponse(
                options, ResponseCreateParams.builder().input(prompt));
            while (true) {
                List<ResponseInputItem> approvals = new ArrayList<>();
                for (ResponseOutputItem item : response.output()) {
                    if (!item.isMcpApprovalRequest()) {
                        continue;
                    }
                    var request = item.asMcpApprovalRequest();
                    Map<String, Object> actualArguments =
                        BinaryData.fromString(request.arguments()).toObject(
                            new TypeReference<Map<String, Object>>() { });
                    if (!"workiq".equals(request.serverLabel())
                        || !toolName.equals(request.name())
                        || (expectedArguments != null
                            && !expectedArguments.equals(actualArguments))) {
                        throw new IllegalStateException(
                            "Unexpected tool call; not approved.");
                    }
                    approvals.add(ResponseInputItem.ofMcpApprovalResponse(
                        ResponseInputItem.McpApprovalResponse.builder()
                            .approvalRequestId(request.id())
                            .approve(true)
                            .build()));
                }
                if (approvals.isEmpty()) {
                    break;
                }
                response = responses.createAzureResponse(options,
                    ResponseCreateParams.builder()
                        .previousResponseId(response.id())
                        .inputOfResponse(approvals));
            }
            System.out.println(response);
        } finally {
            agents.deleteAgentVersion(agent.getName(), agent.getVersion());
        }
    }

    public static void main(String[] args) {
        run("ask", "Summarize my recent emails about Project Contoso.", null);
    }
}

Reference: AgentsClient, ResponsesClient, and McpTool.

Use your project endpoint as <project-endpoint>. Obtain a Foundry token for the signed-in user:

az account get-access-token --resource https://ai.azure.com \
  --query accessToken --output tsv

Reference: az account get-access-token.

Use that value as <foundry-access-token>, not as a Work IQ token. The project connection handles Work IQ authentication. Create an agent:

POST <project-endpoint>/agents?api-version=v1
Authorization: Bearer <foundry-access-token>
Content-Type: application/json

{
  "name": "work-iq-mcp-example",
  "definition": {
    "kind": "prompt",
    "model": "<model-deployment-name>",
    "instructions": "Use the workiq ask tool to answer.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "workiq",
        "server_url": "https://workiq.svc.cloud.microsoft/mcp",
        "project_connection_id": "<work-iq-mcp-connection-id>",
        "allowed_tools": ["ask"],
        "require_approval": "always"
      }
    ]
  }
}

Reference: Foundry REST API.

Send a request to the agent:

POST <project-endpoint>/openai/v1/responses
Authorization: Bearer <foundry-access-token>
Content-Type: application/json

{
  "agent_reference": {
    "type": "agent_reference",
    "name": "work-iq-mcp-example"
  },
  "input": "Summarize my recent emails about Project Contoso."
}

Reference: Responses API.

Inspect each mcp_approval_request in output. Confirm that server_label is workiq, name is ask, and the arguments match your intended request. Copy the response id and approval request id, then send:

POST <project-endpoint>/openai/v1/responses
Authorization: Bearer <foundry-access-token>
Content-Type: application/json

{
  "agent_reference": {
    "type": "agent_reference",
    "name": "work-iq-mcp-example"
  },
  "previous_response_id": "<response-id>",
  "input": [
    {
      "type": "mcp_approval_response",
      "approval_request_id": "<approval-request-id>",
      "approve": true
    }
  ]
}

Reference: MCP tool approval.

If the agent requests more tool calls, review each request before continuing. When finished, delete only the sample agent you created by sending DELETE <project-endpoint>/agents/work-iq-mcp-example?api-version=v1 with the same authorization header.

The response contains the tool output and the agent's answer when the call succeeds. An oauth_consent_request means the request is waiting for user authorization, not that retrieval succeeded.

Complete the consent_link flow as described in OAuth identity passthrough, then rerun the SDK example or continue the REST response with previous_response_id. Check the response and tool errors before using the answer.

Retrieve from a specific SharePoint site

The Work IQ retrieve tool returns grounding content that your agent can use to write an answer. To scope retrieval to a site, pass OneDriveAndSharePoint and items_by_url in the tool call arguments. These arguments aren't properties of the Foundry MCP tool definition.

Important

The Work IQ retrieve tool is in public preview. Use a canonical SharePoint site URL, not a sharing link. Omitting capabilities, or passing an empty list, allows all sources available to the retrieval strategy.

For example, the following arguments request content only from the specified site:

{
  "query": "Summarize the approved customer identity requirements.",
  "strategy": "grounding",
  "capabilities": [
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/sites/ProjectNorthwind"
        }
      ]
    }
  ]
}

Reference: Work IQ retrieve arguments and source scoping.

Set SHAREPOINT_SITE_URL to a site the signed-in user can access. The SDK examples reuse the function from Call the Work IQ MCP endpoint. Replace its ask invocation with the code in the following section.

Each example allows only retrieve and requires approval. Before approving, the SDK function compares the generated arguments with the complete expected object, including the query, strategy, and site.

A mismatch raises an error without approving the call. allowed_tools limits tool names; it doesn't restrict SharePoint sources by itself.

Select a code language or REST API to view the site-scoped retrieve example.

Keep the run_work_iq function and replace the if __name__ == "__main__": block with:

import json
import os

if __name__ == "__main__":
    sharepoint_arguments = {
        "query": "Summarize the approved customer identity requirements.",
        "strategy": "grounding",
        "capabilities": [{
            "name": "OneDriveAndSharePoint",
            "items_by_url": [{"url": os.environ["SHAREPOINT_SITE_URL"]}],
        }],
    }
    run_work_iq(
        "retrieve",
        "Call retrieve with exactly these arguments, then summarize "
        "the returned content and cite its sources: "
        + json.dumps(sharepoint_arguments),
        expected_arguments=sharepoint_arguments,
    )

Reference: MCPTool and Work IQ retrieve.

Keep the RunWorkIq function and replace the final RunWorkIq("ask", ...) statement with the following code. Keep the using directives at the top of Program.cs.

using System;
using System.Text.Json.Nodes;

JsonNode sharepointArguments = new JsonObject
{
    ["query"] = "Summarize the approved customer identity requirements.",
    ["strategy"] = "grounding",
    ["capabilities"] = new JsonArray
    {
        new JsonObject
        {
            ["name"] = "OneDriveAndSharePoint",
            ["items_by_url"] = new JsonArray
            {
                new JsonObject
                {
                    ["url"] = Environment.GetEnvironmentVariable(
                        "SHAREPOINT_SITE_URL")
                        ?? throw new InvalidOperationException(
                            "Set SHAREPOINT_SITE_URL.")
                }
            }
        }
    }
};
RunWorkIq(
    "retrieve",
    "Call retrieve with exactly these arguments, then summarize "
        + "the returned content and cite its sources: "
        + sharepointArguments.ToJsonString(),
    sharepointArguments);

Reference: JsonNode.DeepEquals and Work IQ retrieve.

Keep runWorkIq and the imports. Replace the final runWorkIq("ask", ...) invocation and its error handler with:

if (!process.env.SHAREPOINT_SITE_URL) {
  throw new Error("Set SHAREPOINT_SITE_URL.");
}
const sharepointArguments = {
  query: "Summarize the approved customer identity requirements.",
  strategy: "grounding",
  capabilities: [{
    name: "OneDriveAndSharePoint",
    items_by_url: [{ url: process.env.SHAREPOINT_SITE_URL }],
  }],
};
runWorkIq(
  "retrieve",
  "Call retrieve with exactly these arguments, then summarize "
    + "the returned content and cite its sources: "
    + JSON.stringify(sharepointArguments),
  sharepointArguments
).catch(error => {
  console.error(error);
  process.exitCode = 1;
});

Reference: MCPTool and Work IQ retrieve.

Keep WorkIqMcpExample.java and save the following class as SharePointRetrievalExample.java. Run this class instead of WorkIqMcpExample.

import com.azure.core.util.BinaryData;
import java.util.List;
import java.util.Map;
import java.util.Objects;

public class SharePointRetrievalExample {
    public static void main(String[] args) {
        String siteUrl = Objects.requireNonNull(
            System.getenv("SHAREPOINT_SITE_URL"), "Set SHAREPOINT_SITE_URL.");
        Map<String, Object> sharepointArguments = Map.of(
            "query", "Summarize the approved customer identity requirements.",
            "strategy", "grounding",
            "capabilities", List.of(Map.of(
                "name", "OneDriveAndSharePoint",
                "items_by_url", List.of(Map.of("url", siteUrl)))));
        WorkIqMcpExample.run(
            "retrieve",
            "Call retrieve with exactly these arguments, then summarize "
                + "the returned content and cite its sources: "
                + BinaryData.fromObject(sharepointArguments),
            sharepointArguments);
    }
}

Reference: McpTool, BinaryData, and Work IQ retrieve.

Use the project endpoint, Foundry token, and MCP connection from the first example. Create a separate agent that allows only retrieve:

POST <project-endpoint>/agents?api-version=v1
Authorization: Bearer <foundry-access-token>
Content-Type: application/json

{
  "name": "work-iq-sharepoint-example",
  "definition": {
    "kind": "prompt",
    "model": "<model-deployment-name>",
    "instructions": "Use retrieve with the arguments requested in the input.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "workiq",
        "server_url": "https://workiq.svc.cloud.microsoft/mcp",
        "project_connection_id": "<work-iq-mcp-connection-id>",
        "allowed_tools": ["retrieve"],
        "require_approval": "always"
      }
    ]
  }
}

Reference: Foundry REST API.

Request retrieval from your site. Replace <sharepoint-site-url> with the canonical site URL.

POST <project-endpoint>/openai/v1/responses
Authorization: Bearer <foundry-access-token>
Content-Type: application/json

{
  "agent_reference": {
    "type": "agent_reference",
    "name": "work-iq-sharepoint-example"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize the approved customer identity requirements."
        },
        {
          "type": "input_text",
          "text": "Call retrieve with that exact query and strategy grounding."
        },
        {
          "type": "input_text",
          "text": "Use only the OneDriveAndSharePoint capability."
        },
        {
          "type": "input_text",
          "text": "Set items_by_url to [{\"url\":\"<sharepoint-site-url>\"}]."
        },
        {
          "type": "input_text",
          "text": "Add no other arguments. Summarize and cite the results."
        }
      ]
    }
  ]
}

Reference: Responses API and Work IQ retrieve.

Before approving any mcp_approval_request, check that server_label is workiq and name is retrieve. Parse its arguments JSON string and compare it with the complete expected argument object, using your site URL. Don't approve missing, empty, additional, or different source scopes.

Only if the arguments match, send the approval request from the first example with name set to work-iq-sharepoint-example. Use the latest response ID and the matching approval request ID. Repeat the check for every subsequent approval request.

When finished, send DELETE <project-endpoint>/agents/work-iq-sharepoint-example?api-version=v1 with the same authorization header to delete the sample agent.

The retrieved content is limited to the requested site and the signed-in user's permissions. No matching content is a valid result. The tool returns grounding content, not a synthesized answer; the Foundry agent uses that content to answer your question.

The retrieve result's authoritative payload is structuredContent["application/vnd.ms-workiq.retrieval"]. It includes markdown, retrievalHits, resultCount, and stoppedReason. Use retrievalHits for source metadata. Treat MCP isError: true or stoppedReason: "error" as failure, and don't automatically retry policy denials.

How it works

The remaining sections describe the built-in Work IQ preview tool and its A2A connection, not the standard MCP integration.

  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

Use Foundry Toolkit for Visual Studio Code to add Work IQ as a built-in tool when you create a toolbox, then connect your agent to the published toolbox endpoint. The toolbox exposes the selected Work IQ options through its MCP endpoint.

  1. Select Foundry Toolkit in the Activity Bar.
  2. Under My Resources, expand Your project name > Tools.
  3. Select the + Add Toolbox icon.
  4. On the Build a Custom Toolbox tab, enter the toolbox name and description.
  5. Select Add tools, and then select Work IQ.
  6. In Add the Work IQ Tool, select the Microsoft Copilot data you want to use. Work IQ Chat connects through an A2A endpoint. Other options connect through MCP endpoints, including Copilot Chat, Teams, Word, Outlook Calendar, Outlook Mail, Microsoft 365 user profile, SharePoint, and OneDrive.
  7. For each selected option, choose an existing connection or select Create new connection.
  8. Select Add.
  9. Select Publish.

For the full toolbox creation workflow, see Curate intent-based toolbox in Foundry.

To add the Work IQ tool through a toolbox by using code or the REST API, select the Python, .NET, JavaScript, or REST API tab in this section.

Install the package:

pip install "azure-ai-projects>=2.3.0"

Set the following environment variables:

  • FOUNDRY_PROJECT_ENDPOINT — your project endpoint, found in the Overview page of your Foundry project.
  • WORK_IQ_PROJECT_CONNECTION_ID — the fully qualified resource ID of the Work IQ project connection.

Select Prompt Agents to use the Azure AI Projects SDK to create a server-side prompt agent, or Hosted Agents to use the Microsoft Agent Framework to build an ephemeral, in-process agent that connects to the tool through a toolbox.

Prompt agents

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WorkIQPreviewTool

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
AGENT_NAME = "MyAgent"

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project,
):
    tool_payload = WorkIQPreviewTool(
        project_connection_id=os.environ["WORK_IQ_PROJECT_CONNECTION_ID"],
    )

    agent = project.agents.create_version(
        agent_name=AGENT_NAME,
        definition=PromptAgentDefinition(
            model="gpt-5-mini",
            instructions="Use the available WorkIQ tools to answer questions and perform tasks.",
            tools=[tool_payload],
        ),
    )
    print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

    with project.get_openai_client(agent_name=agent.name) as openai:
        user_input = "Summarize my recent emails about Project Contoso."
        response = openai.responses.create(
            input=user_input,
        )

        print(f"Agent response: {response.output_text}")

    # Clean up the agent version so unused versions don't accumulate in the project.
    project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
    print("Agent deleted")

Expected output: The agent calls Work IQ with the user's query. Work IQ retrieves and synthesizes the user's relevant Microsoft 365 content, based on their permissions, and returns the answer.

Hosted agents

Create a toolbox version with WorkIQPreviewToolboxTool. The toolbox-specific type is different from WorkIQPreviewTool, which adds Work IQ directly to a prompt agent.

import os

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import WorkIQPreviewToolboxTool
from azure.identity import DefaultAzureCredential

project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
work_iq_connection_id = os.environ["WORK_IQ_PROJECT_CONNECTION_ID"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(
        endpoint=project_endpoint,
        credential=credential,
    ) as project,
):
    toolbox = project.toolboxes.create_version(
        name="work-iq-toolbox",
        description="Toolbox with the Work IQ tool",
        tools=[
            WorkIQPreviewToolboxTool(
                project_connection_id=work_iq_connection_id,
            )
        ],
    )
    print(f"Created toolbox: {toolbox.name}, version: {toolbox.version}")

The sample returns the new toolbox version:

Created toolbox: work-iq-toolbox, version: <version>

Next, connect the toolbox to a hosted agent. That workflow uses the hosted runtime integration to preserve the request context required for user-delegated Work IQ calls. For a complete Python implementation, see the Agent Framework Teams activity sample.


The recommended way to add Work IQ is through a toolbox, then attach the toolbox to your agent as an MCP tool. See What is a toolbox?

Step 1: Create a toolbox that contains the Work IQ tool:

curl --request POST \
  --url "{project_endpoint}/toolboxes/work-iq-toolbox/versions?api-version=v1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  --data '{
    "description": "Toolbox with the Work IQ tool",
    "tools": [
      {
        "type": "work_iq_preview",
        "project_connection_id": "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}/connections/{connection-name}"
      }
    ]
  }'

The toolbox exposes an MCP-compatible endpoint at {project_endpoint}/toolboxes/work-iq-toolbox/versions/<version>/mcp?api-version=v1, where <version> is the version returned by the previous call.

Step 2: Configure an authenticated remote-tool project connection named work-iq-toolbox-conn that targets the toolbox endpoint. For connection setup, see Connect to an MCP server.

Step 3: Create the agent with the toolbox attached as an MCP tool:

POST {project_endpoint}/agents/{agent_name}/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "model": "gpt-4o-mini",
  "instructions": "You are a helpful assistant with access to the user's Microsoft 365 work context through Work IQ.",
  "tools": [
    {
      "type": "mcp",
      "server_label": "toolbox",
      "server_url": "{project_endpoint}/toolboxes/work-iq-toolbox/versions/<version>/mcp?api-version=v1",
      "require_approval": "never",
      "project_connection_id": "work-iq-toolbox-conn"
    }
  ]
}

Step 4: Create a conversation session:

POST {project_endpoint}/openai/v1/conversations
Authorization: Bearer {token}
Content-Type: application/json

{}

The response includes an id field. Use it in the next step.

Step 5: Send a request to the agent:

POST {project_endpoint}/openai/v1/responses
Authorization: Bearer {token}
Content-Type: application/json

{
  "conversation": "{conversation_id}",
  "input": "Summarize my recent emails about Project Contoso.",
  "agent_reference": {
    "type": "agent_reference",
    "name": "{agent_name}"
  }
}

The response includes metadata about the agent execution and a text field in content with the synthesized answer.

Note

Use token scope https://ai.azure.com/.default when getting the bearer token.

Select Prompt Agents to use the Azure AI Projects SDK to create a server-side prompt agent, or Hosted Agents to use the Microsoft Agent Framework to build an ephemeral, in-process agent that connects to the tool through a toolbox.

Prompt agents

using Azure.AI.Projects;
using Azure.Identity;

var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
var workIQConnectionName = Environment.GetEnvironmentVariable("WORKIQ_CONNECTION_NAME");

AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());

AIProjectConnection workIQConnection = projectClient.Connections.GetConnection(workIQConnectionName);
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful assistant that can access Microsoft 365 data through Work IQ. "
                 + "Use the Work IQ tool to search and retrieve information from emails, calendar events, "
                 + "Teams messages, and other Microsoft 365 content.",
    Tools = { new WorkIQPreviewTool(workIQConnection.Id) }
};

ProjectsAgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myWorkIQAgent",
    options: new(agentDefinition));
Console.WriteLine($"Agent created (name: {agentVersion.Name}, version: {agentVersion.Version})");

ProjectResponsesClient responseClient =
    projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);
CreateResponseOptions responseOptions = new()
{
    ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
    InputItems = { ResponseItem.CreateUserMessageItem("What meetings do I have scheduled today?") },
};
ResponseResult response = responseClient.CreateResponse(responseOptions);
Console.WriteLine(response.GetOutputText());

// Clean up
projectClient.AgentAdministrationClient.DeleteAgentVersion(
    agentName: agentVersion.Name, agentVersion: agentVersion.Version);

Hosted agents

Create a toolbox version with WorkIQPreviewToolboxTool. The toolbox-specific type is different from WorkIQPreviewTool, which adds Work IQ directly to a prompt agent.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

string projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string workIQConnectionName = Environment.GetEnvironmentVariable("WORKIQ_CONNECTION_NAME")
    ?? throw new InvalidOperationException("WORKIQ_CONNECTION_NAME is not set.");

DefaultAzureCredential credential = new();
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
AIProjectConnection workIQConnection = projectClient.Connections.GetConnection(workIQConnectionName);
ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateVersion(
        name: "work-iq-toolbox",
        tools: [new WorkIQPreviewToolboxTool(workIQConnection.Id)],
        description: "Toolbox with the Work IQ tool");

Console.WriteLine(
    $"Created toolbox: {toolboxVersion.Name}, version: {toolboxVersion.Version}");

The sample returns the new toolbox version:

Created toolbox: work-iq-toolbox, version: <version>

Next, connect the toolbox to a hosted agent. For a complete C# implementation that registers Work IQ toolbox tools with Agent Framework, see the Teams activity sample.


Configure an authenticated project connection named work-iq-toolbox-conn for the toolbox's MCP endpoint. For connection setup, see Connect to an MCP server.

const { DefaultAzureCredential } = require("@azure/identity");
const { AIProjectClient } = require("@azure/ai-projects");

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"];
const workIqProjectConnectionId = process.env["WORKIQ_CONNECTION_ID"];

async function main() {
  const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  console.log("Creating a toolbox with the Work IQ tool...");

  // 1. Add the Work IQ tool to a toolbox. Using a toolbox is the recommended
  //    way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
  const toolbox = await project.toolboxes.createVersion(
    "work-iq-toolbox",
    [
      {
        type: "work_iq_preview",
        project_connection_id: workIqProjectConnectionId,
      },
    ],
    { description: "Toolbox with the Work IQ tool" },
  );

  // 2. The toolbox exposes an MCP-compatible endpoint.
  const toolboxMcpUrl =
    `${projectEndpoint}/toolboxes/${toolbox.name}` +
    `/versions/${toolbox.version}/mcp?api-version=v1`;

  // 3. Use the project connection configured for toolboxMcpUrl.
  const toolboxConnectionName = "work-iq-toolbox-conn";

  // 4. Attach the toolbox to a prompt agent as an MCP tool.
  const agent = await project.agents.createVersion("MyWorkIQAgent", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "Use the available Work IQ tools to answer questions and perform tasks.",
    tools: [
      {
        type: "mcp",
        server_label: "toolbox",
        server_url: toolboxMcpUrl,
        require_approval: "never",
        project_connection_id: toolboxConnectionName,
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  const userInput = "What meetings do I have scheduled today?";
  const response = await openai.responses.create(
    { input: userInput },
    { body: { agent_reference: { name: agent.name, version: agent.version, type: "agent_reference" } } },
  );
  console.log(`Agent response: ${response.output_text}`);

  // Clean up the agent version so unused versions don't accumulate in the project.
  await project.agents.deleteVersion(agent.name, agent.version);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Add Work IQ to a toolbox with the Azure Developer CLI

Use the Azure Developer CLI to create a Work IQ MCP project connection with custom OAuth2, and then reference it from a minimal toolbox YAML. Work IQ MCP also supports AgentOnBehalfOfUser, but this procedure configures only the custom OAuth2 path.

# 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"

Note

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.

Work IQ MCP supports two ways to preserve user context: the agent can act on behalf of the signed-in user, or the user can sign in through a custom OAuth app. Acting on behalf of the signed-in user requires the agent to use the AgentOnBehalfOfUser authentication type. For more information, see Configure Microsoft Entra user delegation.

The following procedure applies only when you configure Work IQ MCP with a custom Entra app registration (using the OAuth2 connection authentication type). This authentication method 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 Microsoft Entra app (one-time, per organization)

A Microsoft 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.

    Important

    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.

  6. 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.

  7. 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.

Screenshot of the Foundry portal showing authentication settings for a Work IQ connection.

Important

You can't edit connection fields after creation. If you enter incorrect values, delete the connection and create a new one.

Create the connection with the Azure Developer CLI

Set the Foundry project endpoint and your app registration values. Keep the client secret in your shell or secret store, and don't put it in source control.

PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
TENANT_ID="<tenant-id>"
CLIENT_ID="<client-id>"
CLIENT_SECRET="<client-secret>"

azd ai connection create workiq-conn \
  --project-endpoint "$PROJECT_ENDPOINT" \
  --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" \
  --refresh-url "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
  --client-id "$CLIENT_ID" \
  --client-secret "$CLIENT_SECRET" \
  --scopes "api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask,offline_access"

After the connection is created, add its OAuth redirect URL to your app registration.

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 and Foundry are Microsoft services with distinct service and data-processing boundaries. When a Foundry agent calls Work IQ, request data goes beyond the Foundry service boundary and might be processed outside the Azure compliance boundary. Work IQ authenticates requests on behalf of the signed-in user and enforces that user's existing Microsoft 365 permissions and applicable policies. The Microsoft Entra tenant establishes the authorization context; it doesn't, by itself, guarantee where data is processed or stored.

For this Agent-to-Agent (A2A) integration, Work IQ returns a synthesized response that can contain information grounded in the user's Microsoft 365 content. Foundry can further process or store that response according to the agent and project configuration. The complete workflow can involve Work IQ, Copilot, and Foundry processing. Review the applicable service terms, data-handling policies, regional configuration, and certification coverage for every service in the request path. End-to-end processing also depends on the Copilot billing configuration and Foundry project region. Don't infer end-to-end residency or compliance coverage solely from the user's tenant or the location of the original Microsoft 365 content.

Direct traffic between Azure and Microsoft services is expected to use the Microsoft global network, as described in Global routing and interconnection. Work IQ uses the public HTTPS endpoint https://workiq.svc.cloud.microsoft. Authentication and supported file operations can also require outbound HTTPS access to additional endpoints. A public endpoint can still be reached over the Microsoft global network and doesn't necessarily mean that traffic traverses the public internet. Review and allow the destinations required by your Work IQ scenario.

When the Foundry project is configured for bring-your-own virtual network (BYO VNet) outbound integration, Work IQ tool calls route through the project's single-tenant data proxy. This platform-managed networking component is dedicated to the project and handles outbound tool connectivity, allowing customer-defined network controls to govern that traffic. For more information about the data proxy and request path, see Deep dive into Foundry Agent Service networking. For the available inbound and outbound configurations, see Networking options for Foundry Agent Service.

A private endpoint for Foundry provides private inbound access to Foundry. It doesn't configure outbound VNet integration or make the outbound connection to Work IQ private. Work IQ remains a public HTTPS destination in this configuration. Routing through the data proxy doesn't establish private ingress to Work IQ or change the service terms and data-handling requirements applicable to Work IQ processing.

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 Copilot privacy and data handling policies.

Privacy and data handling

Review the Microsoft 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.

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.