Connecter des agents à Microsoft 365 avec Work IQ (préversion)

Important

Les éléments indiqués comme (aperçu) dans cet article sont en aperçu public. Cette version préliminaire est fournie sans contrat de niveau de service, et nous la déconseillons pour les charges de travail en production. Certaines fonctionnalités peuvent ne pas être prises en charge ou avoir des fonctionnalités contraintes. Pour plus d’informations, consultez Conditions d'utilisation supplémentaires pour les versions préliminaires de Microsoft Azure.

Work IQ est la couche d’intelligence qui constitue la base de Microsoft 365 Copilot et de vos utilisateurs avec un contexte partagé et en temps réel dans votre organisation. Il capture les signaux à partir d’e-mails, de réunions, de fichiers, de conversations et de systèmes métier, et applique la compréhension sémantique afin que les agents puissent raisonner sur les données de travail et prendre des mesures. Toutes les requêtes s’exécutent dans le contexte de l’utilisateur connecté et respectent les autorisations Microsoft 365.

Vous connectez votre agent Foundry à Work IQ via le protocole Agent à Agent (A2A). Votre agent délègue des tâches en langage naturel à Work IQ en tant qu'agent homologue( par exemple, « Résumer mes courriers électroniques récents sur Project Contoso » et Work IQ gère la récupération, le raisonnement et la synthèse des réponses par rapport aux données Microsoft 365 de l'utilisateur.

Pour plus d’informations sur l’optimisation de l’utilisation des outils, consultez les meilleures pratiques.

Warning

Lorsque vous vous connectez à Work IQ, vous pouvez entraîner des coûts et des données peuvent être envoyées en dehors de la limite de conformité Azure et traitées en fonction des conditions de service et des stratégies de gestion des données applicables. Il est de votre responsabilité de gérer si vos données circulent en dehors des limites géographiques et de conformité de votre organisation et des implications connexes, et que les autorisations, les limites et les approbations appropriées sont approvisionnées.

Vous êtes responsable de l’examen et du test des applications que vous créez dans le contexte de vos cas d’usage spécifiques et de prendre toutes les décisions et personnalisations appropriées. Cela inclut l’implémentation de vos propres atténuations d’IA responsables, telles que les métaprompts, les filtres de contenu ou d’autres systèmes de sécurité, et la garantie que vos applications répondent aux normes de qualité, de fiabilité, de sécurité et de fiabilité appropriées. Consultez la note de transparence du service Foundry Agent.

Prerequisites

Avant de commencer, assurez-vous d’avoir :

  • Exigence commerciale pour la connexion que vous utilisez :

    Chemin d’accès de connexion Type d’exigence Requirement
    API Work IQ via A2A, REST ou MCP Facturation basée sur l’utilisation Activez la facturation avec Copilot Crédits. Ce chemin d’accès n’utilise pas les licences de connecteur.
    Outils de Microsoft 365 soutenus par le connecteur Licences de connecteur Vérifiez les prérequis du connecteur sélectionné. Un connecteur peut nécessiter une licence Microsoft 365 Copilot pour chaque utilisateur appelant.
  • Un projet Microsoft Foundry actif avec un modèle déployé.

  • Azure rôles RBAC :

    • Rôle Utilisateur Foundry sur le projet Foundry pour l’identité du développeur, l’identité d’exécution de l’agent et toute identité utilisateur impliquée dans les flux OAuth.
    • Le rôle Gestionnaire de projet Foundry dans le projet Foundry pour créer une connexion à Foundry vers le point de terminaison Work IQ.
  • Administrateur général Microsoft Entra qui peut effectuer la configuration du locataire unique en approvisionnant le principal du service Work IQ et en accordant le consentement WorkIQAgent.Askde l’administrateur. Activez ce rôle juste à temps via Microsoft Entra Privileged Identity Management (PIM) et désactivez-le après l’installation. Les utilisateurs quotidiens d’IQ professionnel n’ont pas besoin de ce rôle.

  • Foundry Toolkit : installez Visual Studio Code et Foundry Toolkit pour Visual Studio Code.

  • Développement JavaScript : utilisez Node.js 22 ou version ultérieure et installez @azure/ai-projects la version 2.4.0 ou ultérieure avec @azure/identity.

Pour les appels A2A directs, Work IQ prend en charge les versions de protocole 1.0 et 0.3. Envoyer A2A-Version: 1.0 pour utiliser des noms de méthode v1. Omettre les valeurs par défaut de l’en-tête sur v0.3. Incluez les métadonnées d’emplacement pour les requêtes sensibles au temps et utilisez l’authentification utilisateur déléguée.

Suivre la carte des dépendances d’installation

Utilisez cette carte pour séparer le flux d’utilisation de l’agent des dépendances qu’un administrateur termine une fois pour l’organisation.

Objectif Dépend de Continuer à
Ajouter Work IQ à un agent et envoyer une requête Une connexion Work IQ existante, les autorisations d'Microsoft 365 de l'utilisateur connecté et les licences de facturation ou de connecteur répertoriées dans les conditions préalables. Ajouter l’outil Work IQ à votre agent
Créer la première connexion Work IQ pour l’organisation Principal du service Work IQ, application Entra monolocataire, autorisation déléguée WorkIQAgent.Ask et consentement administrateur à l’échelle du locataire. Configurer votre application Entra
Utiliser un outil de Microsoft 365 soutenu par un connecteur Connexion pour ce connecteur et toute licence spécifique au connecteur requise pour l’utilisateur connecté. Ajouter l’outil Work IQ à votre agent

Terminez d’abord le flux d’utilisation de l’agent lorsque votre organisation dispose déjà d’une connexion. Utilisez le programme d’installation unique du locataire uniquement lorsqu’un administrateur doit créer la première connexion.

Tip

Envisagez d’ajouter cet outil à l’aide d’une boîte à outils. À l’aide d’une boîte à outils, vous pouvez réutiliser l’outil entre les agents et les runtimes, ainsi que centraliser la gestion des informations d’identification, le contrôle de version et l’application des stratégies via un point de terminaison MCP géré. Consultez le guide de démarrage rapide de la boîte à outils.

Assistance à l'utilisation

Support de Microsoft Foundry Kit de développement logiciel (SDK) Python Kit de développement logiciel (SDK) C# Kit de développement logiciel (SDK) JavaScript Kit de développement logiciel (SDK) Java API REST Configuration d’agent de base Configuration de l’agent standard
IQ de travail ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Fonctionnement

  1. Votre agent envoie un appel d’outil — Lorsque le modèle d’agent identifie une tâche qui nécessite des données Microsoft 365, il émet un appel d’outil vers l’outil work_iq_preview.
  2. Foundry achemine la requête vers Work IQ via A2A : Foundry utilise le protocole Agent-à-Agent (A2A) pour transférer la requête en langage naturel vers Work IQ en tant qu’agent homologue. L’authentification utilise On-Behalf-Of (OBO) afin que la requête s’exécute dans le contexte de l’utilisateur connecté.
  3. Work IQ récupère les données M365 et raisonne sur celles-ci — Work IQ interroge les e-mails, les réunions, les fichiers, les conversations et d’autres signaux Microsoft 365 de l’utilisateur. Il applique une compréhension sémantique pour synthétiser une réponse fondée sur le contexte de travail réel de l’utilisateur, en respectant de bout en bout les autorisations de Microsoft 365 et les étiquettes de confidentialité.
  4. Le résultat est retourné à votre agent : Work IQ retourne la réponse synthétisée à Foundry via A2A. Votre agent l’intègre dans sa réponse à l’utilisateur.

Se connecter à Work IQ

Ajouter l’outil Work IQ à votre agent

Utilisez Foundry Toolkit pour Visual Studio Code pour ajouter Work IQ en tant qu’outil intégré lorsque vous créez une boîte à outils, puis connectez votre agent au point de terminaison de boîte à outils publié. La boîte à outils expose les options Work IQ sélectionnées via son point de terminaison MCP.

  1. Sélectionnez Foundry Toolkit dans la barre d’activité.
  2. Sous Mes ressources, développez le nom de votre projet>Outils.
  3. Sélectionnez l’icône + Ajouter une boîte à outils .
  4. Sous l’onglet Générer une boîte à outils personnalisée , entrez le nom et la description de la boîte à outils.
  5. Sélectionnez Ajouter des outils, puis sélectionnez Work IQ.
  6. Dans Add the Work IQ Tool, sélectionnez les données Microsoft 365 Copilot que vous souhaitez utiliser. Work IQ Chat se connecte via un point de terminaison A2A. D’autres options se connectent via des points de terminaison MCP, notamment Copilot Chat, Teams, Word, calendrier Outlook, courrier Outlook, profil utilisateur Microsoft 365, SharePoint et OneDrive.
  7. Pour chaque option sélectionnée, choisissez une connexion existante ou sélectionnez Créer une connexion.
  8. Cliquez sur Ajouter.
  9. Cliquez sur Publier.

Pour obtenir le flux de travail de création de boîte à outils complet, consultez la boîte à outils Curate basée sur les intentions dans Foundry.

Pour ajouter l’outil Work IQ via une boîte à outils à l’aide du code ou de l’API REST, sélectionnez l’onglet Python, .NET, JavaScript ou API REST dans cette section.

Installez le package :

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

Définissez les variables d’environnement suivantes :

  • FOUNDRY_PROJECT_ENDPOINT — votre point de terminaison de projet, trouvé dans la page Vue d’ensemble de votre projet Foundry.
  • WORK_IQ_PROJECT_CONNECTION_ID : l’ID de ressource complet de la connexion du projet Work IQ.

Sélectionnez Agents d’invite pour utiliser le sdk Azure AI Projects pour créer un agent d’invite côté serveur ou des agents hébergés pour utiliser l’infrastructure de l’agent Microsoft pour générer un agent éphémère et in-process qui se connecte à l’outil via une boîte à outils.

Agents déclencheurs

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

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

    agent = project_client.agents.create_version(
        agent_name="MyAgent",
        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})")

    user_input = "Summarize my recent emails about Project Contoso."
    response = openai_client.responses.create(
        input=user_input,
        extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
    )

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

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

Sortie attendue : l’agent appelle Work IQ avec la requête de l’utilisateur. Work IQ récupère et synthétise le contenu Microsoft 365 pertinent de l'utilisateur, ancré dans ses autorisations et retourne la réponse.

Agents hébergés

Créez une version de boîte à outils avec WorkIQPreviewToolboxTool. Le type spécifique à la boîte à outils est différent de WorkIQPreviewToolcelui qui ajoute Work IQ directement à un agent d’invite.

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}")

L’exemple retourne la nouvelle version de la boîte à outils :

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

Ensuite, connectez la boîte à outils à un agent hébergé. Ce flux de travail utilise l’intégration du runtime hébergé pour conserver le contexte de requête requis pour les appels Work IQ délégués par l’utilisateur. Pour obtenir une implémentation complète Python, consultez l’exemple d’activité Agent Framework Teams.


La méthode recommandée pour ajouter Work IQ consiste à utiliser une boîte à outils, puis à attacher la boîte à outils à votre agent en tant qu’outil MCP. Voir Qu’est-ce qu’une boîte à outils ?

Étape 1 : Créez une boîte à outils qui contient l’outil Work IQ :

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}"
      }
    ]
  }'

La boîte à outils expose un point de terminaison compatible MCP à l’emplacement {project_endpoint}/toolboxes/work-iq-toolbox/versions/<version>/mcp?api-version=v1<version> est la version retournée par l’appel précédent.

Étape 2 : Créez une connexion de projet à distance qui pointe vers le point de terminaison de la boîte à outils, à l’aide d’un jeton Entra utilisateur afin que l’identité de l’appelant soit transmise (audience https://ai.azure.com) :

azd ai connection create work-iq-toolbox-conn \
  --kind remote-tool \
  --target "{project_endpoint}/toolboxes/work-iq-toolbox/versions/<version>/mcp?api-version=v1" \
  --auth-type user-entra-token \
  --audience https://ai.azure.com

Étape 3 : Créez l’agent avec la boîte à outils attachée en tant qu’outil MCP :

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"
    }
  ]
}

Étape 4 : Créez une session de conversation :

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

{}

La réponse inclut un id champ. Utilisez-le à l’étape suivante.

Étape 5 : Envoyez une demande à l’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}"
  }
}

La réponse comprend des métadonnées sur l’exécution de l’agent ainsi qu’un champ text dans content contenant la réponse synthétisée.

Note

Utilisez la portée https://ai.azure.com/.default du jeton pour obtenir le jeton porteur.

Sélectionnez Agents d’invite pour utiliser le sdk Azure AI Projects pour créer un agent d’invite côté serveur ou des agents hébergés pour utiliser l’infrastructure de l’agent Microsoft pour générer un agent éphémère et in-process qui se connecte à l’outil via une boîte à outils.

Agents déclencheurs

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);

Agents hébergés

Créez une version de boîte à outils avec WorkIQPreviewToolboxTool. Le type spécifique à la boîte à outils est différent de WorkIQPreviewToolcelui qui ajoute Work IQ directement à un agent d’invite.

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}");

L’exemple retourne la nouvelle version de la boîte à outils :

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

Ensuite, connectez la boîte à outils à un agent hébergé. Pour obtenir une implémentation C# complète qui inscrit les outils de boîte à outils Work IQ avec Agent Framework, consultez l’exemple d’activité Teams.


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. Create a remote-tool project connection that points at the toolbox endpoint.
  //    Use a user Entra token so the caller's identity is passed through
  //    (audience https://ai.azure.com). Create the connection once, for example
  //    with the Azure Developer CLI:
  //
  //    azd ai connection create work-iq-toolbox-conn \
  //      --kind remote-tool \
  //      --target "<toolboxMcpUrl>" \
  //      --auth-type user-entra-token \
  //      --audience https://ai.azure.com
  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);
});

Ajouter Work IQ à une boîte à outils avec l’interface CLI Azure développeur

Utilisez l’interface CLI Azure développeur pour créer la connexion de projet Work IQ A2A, puis référencez-la à partir d’une boîte à outils MINIMALE 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"

Note

Cet article utilise le point de terminaison https://workiq.svc.cloud.microsoft/a2a/Work IQ A2A . Le catalogue de boîte à outils précédent utilisé https://agent365.svc.cloud.microsoft/agents/agents/workiq pour son flux de travail azd ; vérifiez le point de terminaison si votre connexion Work IQ utilise une autre cible A2A ou MCP.

# 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

Utiliser Work IQ avec un agent hébergé

Après avoir créé work-iq-toolbox, suivez la boîte à outils avec un agent hébergé pour le connecter à Agent Framework, l’exécuter localement et le déployer sur le service De l’agent Foundry. L’intégration hébergée conserve le contexte par requête que Work IQ doit agir pour le compte de chaque utilisateur connecté.

Pour les implémentations de bout en bout, utilisez l’exemple d’activité Teams géré Python ou .NET exemple d’activité Teams.

Authentification et sécurité

Work IQ utilise l’authentification déléguée Microsoft Entra ID. Toutes les requêtes s’exécutent dans le contexte de l’utilisateur connecté. L’authentification d’application uniquement (app uniquement) n’est pas prise en charge. Microsoft 365 autorisations sont appliquées automatiquement : les agents Work IQ ne peuvent jamais accéder aux données que l'utilisateur connecté n'est pas déjà autorisé à voir.

Seule l’option Utiliser votre propre application Entra (authentification On-Behalf-Of) est prise en charge pour les connexions Work IQ. Cela permet à votre administrateur Entra de contrôler explicitement les applications qui peuvent récupérer des données Microsoft 365 via Work IQ : l’administrateur examine et accorde l’autorisation WorkIQAgent.Ask spécifiquement pour votre application inscrite.

Configurer votre application Entra (une seule fois par organisation)

Un administrateur Entra doit effectuer l’opération de locataire unique suivante avant de pouvoir créer une connexion Work IQ dans Foundry. Pour connaître les étapes qui nécessitent le rôle Administrateur général, utilisez Microsoft Entra PIM pour activer le rôle juste à temps et le désactiver lorsque l’installation est terminée. Les utilisateurs quotidiens d’IQ professionnel n’ont pas besoin de ce rôle.

Configurer le principal de service Work IQ (une seule fois)

Avant de créer l’inscription de l’application, un administrateur général doit approvisionner le principal du service Work IQ dans le cadre de cette opération de locataire unique. Si vous ignorez cette étape, l’option Work IQ n’apparaît pas lorsque vous recherchez des autorisations d’API.

Suivez l’étape 1 : Créer le principal de service Work IQ dans le guide de démarrage rapide de l’API Work IQ. Une réponse 201 créée à partir de l’Explorateur Graph confirme la réussite. Une erreur de conflit indique que le principal existe déjà ; passez à l’étape suivante.

Créer l'enregistrement de l'application

  1. Accédez au centre d’administration Microsoft Entra. Dans le volet de navigation gauche, sélectionnez Entra ID>inscriptions d'applications.

  2. Sélectionnez Nouvelle inscription. Attribuez à l’application un nom descriptif et définissez Types de comptes pris en charge sur Comptes dans cet annuaire organisationnel uniquement. Sélectionnez Inscrire.

  3. Copiez l’ID de l’application (client). Vous avez besoin de cette valeur lors de la création de la connexion Foundry.

  4. Sélectionnez Autorisations de l’API>Ajouter une autorisation>API que mon organisation utilise. Recherchez Work IQ (ID d’application fdcc1f02-fc51-4226-8753-f668596af7f7), sélectionnez Autorisations déléguées, sélectionnez WorkIQAgent.Ask, puis Ajoutez des autorisations.

  5. Sélectionnez Accorder le consentement de l’administrateur pour [votre locataire]. Passez en revue la boîte de dialogue de confirmation et sélectionnez Oui.

    Important

L’octroi du consentement administrateur à l’échelle du locataire est une opération de locataire unique qui nécessite le rôle Administrateur général dans Microsoft Entra ID. Activez le rôle juste à temps via Microsoft Entra PIM et désactivez-le après l’octroi du consentement. Les utilisateurs quotidiens d’IQ professionnel n’ont pas besoin de ce rôle. Si vous n’avez pas ce rôle, demandez à l’administrateur général de votre organisation d’effectuer cette étape.

  1. Sélectionnez Certificats et secrets>Nouveau secret client. Ajoutez une description et une expiration. Sélectionnez Ajouter, puis copiez immédiatement la valeur secrète . Elle ne s’affiche qu’une seule fois. Stockez le secret dans Azure Key Vault ou un autre magasin de secrets approuvé. Ne validez jamais le secret dans le contrôle de code source ou imprimez-le ou connectez-le. Faites pivoter le secret avant d’expirer.
  2. Copiez votre ID de répertoire (locataire) à partir de la page Vue d’ensemble de Microsoft Entra ID.

Renseignez les valeurs de connexion Foundry

Dans Microsoft Foundry, ouvrez votre projet et accédez à Settings>Connections>New connection>Work IQ. Remplissez les champs suivants :

Champ Valeur
ID du client ID d’application (client) de l’étape 3
Secret client Valeur du secret client de l’étape 6
URL d’autorisation https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
URL du jeton https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
URL d’actualisation https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Étendues api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask,offline_access

Remplacez {tenant-id} par votre ID d’annuaire (locataire) à l’étape 7. Sélectionnez Enregistrer pour créer la connexion.

Capture d’écran du portail Foundry montrant les paramètres d’authentification pour une connexion Work IQ.

Important

Les champs de connexion ne peuvent pas être modifiés après la création. Si vous entrez des valeurs incorrectes, supprimez la connexion et créez-en une nouvelle.

Ajouter l’URI de redirection à l’enregistrement de votre application

Une fois que Foundry a créé la connexion, elle affiche une URL de redirection OAuth. Ajoutez cette URL à l’inscription de votre application :

  1. Dans le centre d’administration Microsoft Entra, accédez à Entra ID>inscriptions d'applications et sélectionnez votre application.
  2. Sélectionnez Authentification>Ajouter une plateforme>Web.
  3. Sous URI de redirection, collez l’URL de redirection OAuth à partir de Foundry.
  4. Sélectionnez Configurer.

Créer la connexion avec l’API REST

En guise d’alternative au portail Foundry, utilisez l’API Azure Resource Manager pour créer la connexion Work IQ par programmation.

Étape 1 : Acquérir un jeton

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

Étape 2 : Créer la connexion

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"
      }
    }
  }'

Une réponse réussie retourne HTTP 200 ou 201. Le corps de la réponse inclut un properties.oauthRedirectUrl champ : utilisez cette valeur comme URI de redirection dans votre inscription d’application Entra (voir Ajouter l’URI de redirection à votre inscription d’application).

Gouvernance et conformité des données

Work IQ permission-trims extraction sur Microsoft 365. Un flux de travail Foundry peut également envoyer des invites et récupérer des résultats au traitement en aval Copilot et Foundry, afin de passer en revue les limites et la configuration régionale de chaque service dans le chemin de requête.

Résidence des données

Microsoft 365 récupération suit les autorisations et la configuration de résidence de votre locataire. Le traitement de bout en bout dépend également de votre configuration de facturation Copilot et de votre région de projet Foundry. Pour plus d’informations, consultez Microsoft 365 Copilot stratégies de confidentialité et de gestion des données.

Confidentialité et gestion des données

Passez en revue les stratégies de confidentialité et de gestion des données Microsoft 365 Copilot et les exigences de gestion des données Foundry qui s’appliquent à votre déploiement. Confirmez le chemin complet de la demande avec vos équipes de confidentialité et de conformité.

Contrôle d’accès et autorisations

Concevez la connexion afin que la récupération utilise les autorisations Microsoft 365 de l'utilisateur connecté. Testez le découpage des autorisations avec des utilisateurs représentatifs et du contenu restreint avant le déploiement :

  • Le contrôle d’accès en fonction du rôle, les étiquettes de confidentialité et les obstacles à l’information définis dans Microsoft 365 sont respectés.

Révision de conformité

Utilisez les ressources de conformité Microsoft de votre organisation pour vérifier quelles certifications et contrôles s'appliquent au déploiement work IQ et Foundry complet.

Gestion d’administration

En tant qu’administrateur Entra, vous contrôlez les applications de votre locataire qui peuvent accéder aux données Work IQ pour le compte des utilisateurs. Les sections suivantes décrivent les contrôles clés disponibles.

Le consentement de l’administrateur pour WorkIQAgent.Ask est requis avant que tout utilisateur de votre organisation puisse s’authentifier via l’application. Vous pouvez gérer le consentement à tout moment :

  • Accorder le consentement : dans le Centre d’administration Microsoft Entra, accédez à Entra ID>Inscriptions d’applications>, puis sélectionnez l’application >Autorisations d’API. Sélectionnez Accorder le consentement de l’administrateur pour [votre locataire].
  • Révoquer le consentement : dans la même page d’autorisations d’API, sélectionnez l’autorisation, puis révoquez le WorkIQAgent.Askconsentement de l’administrateur. Les jetons existants restent valides jusqu’à leur expiration ; aucun nouveau jeton ne peut être émis après la révocation.

Troubleshooting

Symptôme Cause la plus probable Résolution
403 Forbidden La facturation n’est pas activée pour l’API Work IQ, ou une licence spécifique au connecteur est manquante. Activez Copilot facturation des crédits pour les appels d’API Work IQ. Pour les outils soutenus par le connecteur, vérifiez que l’utilisateur appelant répond aux exigences de licence de ce connecteur.
401 Unauthorized Non-correspondance de l’audience du jeton Vérifiez que le jeton est émis pour api://workiq.svc.cloud.microsoft, et non pour une autre ressource.
403 Forbidden avec Required scopes = [...] Consentement de l’administrateur pour WorkIQAgent.Ask n’a pas été accordé Un administrateur doit accorder son consentement pour l’inscription de l’application.
L’agent n’obtient aucune réponse ou résultat vide Microsoft 365 contenu n'est pas disponible pour l'utilisateur connecté ou n'a pas été indexé. Vérifiez les autorisations sources de l’utilisateur, puis réessayez une fois l’indexation terminée.
Principal does not have access to API/Operation Le rôle Utilisateur Foundry est manquant pour l’identité de l’assistant au niveau du projet. Attribuez Foundry User au niveau du compte et au niveau du projet.