Agents verbinden met Microsoft 365 met Work IQ (preview)

Important

Items die in dit artikel zijn gemarkeerd (preview) zijn momenteel beschikbaar als openbare preview. Deze preview wordt aangeboden zonder een service level agreement en we raden deze niet aan voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure Previews voor meer informatie.

Work IQ is de intelligentielaag die Microsoft 365 Copilot en uw agents verankert in een realtime gedeelde context binnen uw organisatie. Het legt signalen vast van e-mailberichten, vergaderingen, bestanden, chats en bedrijfssystemen, en past semantisch begrip toe, zodat agenten reden kunnen hebben over werkgegevens en actie kunnen ondernemen. Alle aanvragen worden uitgevoerd in de context van de aangemelde gebruiker en respecteren Microsoft 365 machtigingen.

U verbindt uw Foundry-agent met Work IQ via het A2A-protocol (Agent-to-Agent). Uw agent delegeert taken in natuurlijke taal aan Werk IQ als een peeragent, bijvoorbeeld 'Mijn recente e-mailberichten over Project Contoso samenvatten' en Work IQ verwerkt het ophalen, redeneren en reactiesynthese van de gebruiker op basis van de Microsoft 365 gegevens van de gebruiker.

Zie de aanbevolen procedures voor informatie over het optimaliseren van het gebruik van hulpprogramma's.

Waarschuwing

Wanneer u verbinding maakt met Work IQ, kunnen er kosten in rekening worden gebracht en kunnen er gegevens worden verzonden buiten de Azure nalevingsgrens en worden verwerkt volgens de toepasselijke servicevoorwaarden en het beleid voor gegevensverwerking. Het is uw verantwoordelijkheid om te beheren of uw gegevens buiten de nalevings- en geografische grenzen van uw organisatie en eventuele gerelateerde implicaties stromen, en dat de juiste machtigingen, grenzen en goedkeuringen worden ingericht.

U bent verantwoordelijk voor het zorgvuldig beoordelen en testen van toepassingen die u bouwt in de context van uw specifieke use cases en het nemen van alle juiste beslissingen en aanpassingen. Dit omvat het implementeren van uw eigen verantwoorde AI-oplossingen, zoals metaprompts, inhoudsfilters of andere veiligheidssystemen, en ervoor zorgen dat uw toepassingen voldoen aan de juiste kwaliteit, betrouwbaarheid, beveiliging en betrouwbaarheidsstandaarden. Zie de transparantienotitie van de Foundry Agent Service.

Prerequisites

Voordat u begint, moet u ervoor zorgen dat u het volgende hebt:

  • De commerciële vereiste voor de verbinding die u gebruikt:

    Verbindingspad Type vereiste Requirement
    IQ API gebruiken via A2A, REST of MCP Gebruiksgebaseerde facturering Facturering met Copilot tegoed inschakelen. Dit pad maakt geen gebruik van connectorlicenties.
    Door connector ondersteunde Microsoft 365-hulpprogramma's Connectorlicenties Bevestig de vereisten van de geselecteerde connector. Een connector kan een Microsoft 365 Copilot licentie vereisen voor elke aanroepende gebruiker.
  • Een actief Microsoft Foundry-project met een geïmplementeerd model.

  • Azure RBAC-rollen:

    • Foundry User-rol in het Foundry-project voor de identiteit van de ontwikkelaar, de runtime-identiteit van de agent en elke gebruikersidentiteit die betrokken is bij OAuth-stromen.
    • de rol van Foundry Project Manager binnen het Foundry-project voor het opzetten van een Foundry-verbinding met het Work IQ-eindpunt.
  • Een Microsoft Entra globale beheerder die de eenmalige tenantconfiguratie kan voltooien door de Work IQ-service-principal in te richten en beheerderstoestemming te verlenen voor WorkIQAgent.Ask. Activeer deze rol net op tijd via Microsoft Entra Privileged Identity Management (PIM) en deactiveer deze na de installatie. Dagelijkse werk IQ-gebruikers hebben deze rol niet nodig.

  • Foundry Toolkit: Installeer Visual Studio Code en Foundry Toolkit voor Visual Studio Code.

  • JavaScript-ontwikkeling: gebruik Node.js 22 of hoger en installeer @azure/ai-projects 2.4.0 of hoger met @azure/identity.

Voor directe A2A-aanroepen ondersteunt Work IQ protocolversies 1.0 en 0.3. Verzenden A2A-Version: 1.0 om v1-methodenamen te gebruiken. Als u de header weglaat, wordt standaard v0.3 gebruikt. Voeg locatiemetagegevens toe voor tijdgevoelige aanvragen en gebruik gedelegeerde gebruikersverificatie.

Volg de toewijzing van de installatieafhankelijkheid

Gebruik deze toewijzing om de stroom voor agentgebruik te scheiden van afhankelijkheden die een beheerder eenmaal voor de organisatie heeft voltooid.

Doel Afhankelijk Doorgaan op
Werk-IQ toevoegen aan een agent en een query verzenden Een bestaande Work IQ-verbinding, de Microsoft 365 machtigingen van de aangemelde gebruiker en de facturerings- of connectorlicenties die worden vermeld in de vereisten. Het werk-IQ-hulpprogramma toevoegen aan uw agent
De eerste Werk IQ-verbinding voor de organisatie maken De Work IQ-service-principal, een Entra-app met één tenant, gedelegeerde WorkIQAgent.Ask machtigingen en beheerderstoestemming voor de hele tenant. Uw Entra-app instellen
Een hulpprogramma voor Microsoft 365 met connectorsteun gebruiken Een verbinding voor die connector en een connectorspecifieke licentie die vereist is voor de aangemelde gebruiker. Het werk-IQ-hulpprogramma toevoegen aan uw agent

Voltooi eerst de stroom voor agentgebruik wanneer uw organisatie al een verbinding heeft. Gebruik de eenmalige tenantconfiguratie alleen wanneer een beheerder de eerste verbinding moet maken.

Tip

Overweeg dit hulpprogramma toe te voegen met behulp van een werkset. Met behulp van een werkset kunt u het hulpprogramma opnieuw gebruiken tussen agents en runtimes, evenals het centraliseren van referentiebeheer, versiebeheer en het afdwingen van beleid via een beheerd MCP-eindpunt. Zie de quickstart voor de werkset.

Gebruiksondersteuning

Ondersteuning voor Microsoft Foundry Python SDK C#SDK JavaScript SDK Java SDK REST API Basisagent instellen Standaard agenteninstelling
Iq voor werk ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Hoe werkt het?

  1. Een agent verzendt een hulpprogramma-aanroep — Wanneer het agentmodel een taak identificeert waarvoor Microsoft 365 gegevens zijn vereist, wordt er een tool-aanroep verzonden naar het hulpprogramma work_iq_preview.
  2. Foundry stuurt de aanvraag naar Work IQ via A2A — Foundry gebruikt het A2A-protocol (Agent-to-Agent) om de query in natuurlijke taal door te sturen naar Work IQ als peeragent. Verificatie maakt gebruik van On-Behalf-Of (OBO), zodat de aanvraag wordt uitgevoerd in de context van de aangemelde gebruiker.
  3. Work IQ haalt M365-gegevens op en redeneert erover — Work IQ doorzoekt de e-mailberichten, vergaderingen, bestanden, chats en andere signalen uit Microsoft 365 van de gebruiker. Het past semantisch begrip toe om een antwoord te synthetiseren dat is geaard in de werkelijke werkcontext van de gebruiker, waarbij Microsoft 365 machtigingen en vertrouwelijkheidslabels overal worden toegepast.
  4. Het resultaat wordt geretourneerd aan uw agent : Work IQ retourneert het gesynthetiseerde antwoord op Foundry via A2A. Uw agent neemt deze op in het antwoord op de gebruiker.

Verbinding maken met Werk IQ

Het werk-IQ-hulpprogramma toevoegen aan uw agent

Gebruik Foundry Toolkit voor Visual Studio Code om Work IQ toe te voegen als een ingebouwd hulpprogramma wanneer u een werkset maakt en verbind uw agent vervolgens met het gepubliceerde werkseteindpunt. De toolbox stelt de geselecteerde Work IQ-opties beschikbaar via zijn MCP-eindpunt.

  1. Selecteer Foundry Toolkit in de activiteitenbalk.
  2. Vouw onder Mijn resourcesUw projectnaam>Hulpmiddelen uit.
  3. Selecteer het pictogram + Toolbox toevoegen.
  4. Voer op het tabblad Aangepaste gereedschapskist maken de naam en beschrijving van de gereedschapskist in.
  5. Selecteer Hulpprogramma's toevoegen en selecteer vervolgens Werk-IQ.
  6. Selecteer in Add the Work IQ Tool de Microsoft 365 Copilot gegevens die u wilt gebruiken. Werk IQ Chat maakt verbinding via een A2A-eindpunt. Andere opties maken verbinding via MCP-eindpunten, waaronder Copilot Chat, Teams, Word, Outlook Agenda, Outlook Mail, Microsoft 365 gebruikersprofiel, SharePoint en OneDrive.
  7. Kies voor elke geselecteerde optie een bestaande verbinding of selecteer Nieuwe verbinding maken.
  8. Selecteer Toevoegen.
  9. Selecteer Publiceren.

Zie Intentiegebaseerde toolbox samenstellen in Foundry voor de volledige workflow voor het maken van een toolbox.

Als u het hulpprogramma Work IQ wilt toevoegen via een werkset met behulp van code of de REST API, selecteert u het tabblad Python, .NET, JavaScript of REST API in deze sectie.

Installeer het pakket:

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

Stel de volgende omgevingsvariabelen in:

  • FOUNDRY_PROJECT_ENDPOINT — uw projecteindpunt, te vinden op de overzichtspagina van uw Foundry-project.
  • WORK_IQ_PROJECT_CONNECTION_ID — de volledig gekwalificeerde resource-id van de Work IQ-projectverbinding.

Selecteer Promptagents om de Azure AI Projects SDK te gebruiken om een promptagent aan de serverzijde te maken of gehoste agents om het Microsoft Agent Framework te gebruiken om een tijdelijke, in-process agent te bouwen die via een werkset verbinding maakt met het hulpprogramma.

Agents aansturen

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

Verwachte uitvoer: De agent roept Work IQ aan met de query van de gebruiker. Werk IQ haalt de relevante Microsoft 365 inhoud van de gebruiker op ensynthetiseert deze op basis van hun machtigingen en retourneert het antwoord.

Gehoste agents

Maak een werksetversie met WorkIQPreviewToolboxTool. Het werksetspecifieke type verschilt van WorkIQPreviewTool, waardoor Work IQ rechtstreeks aan een promptagent wordt toegevoegd.

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

Het voorbeeld retourneert de nieuwe werksetversie:

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

Vervolgens koppelt u de werkset aan een gehoste agent. Deze werkstroom maakt gebruik van de gehoste runtime-integratie om de aanvraagcontext te behouden die vereist is voor door de gebruiker gedelegeerde Work IQ-aanroepen. Zie het voorbeeld van de activiteit Agent Framework Teams voor een volledige Python implementatie.


De aanbevolen manier om Work IQ toe te voegen, is via een werkset en koppel de werkset vervolgens als mcp-hulpprogramma aan uw agent. Zie Wat is een werkset?

Stap 1: Maak een werkset die het hulpprogramma Work IQ bevat:

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

De werkset toont een mcP-compatibel eindpunt op {project_endpoint}/toolboxes/work-iq-toolbox/versions/<version>/mcp?api-version=v1, waarbij <version> de versie is die wordt geretourneerd door de vorige aanroep.

Stap 2: Maak een externe projectverbinding die verwijst naar het eindpunt van de werkset, met behulp van een Gebruikers-Entra-token, zodat de identiteit van de beller wordt doorgegeven (doelgroep 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

Stap 3: Maak de agent met de werkset die is gekoppeld als een MCP-hulpprogramma:

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

Stap 4: Een gesprekssessie maken:

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

{}

Het antwoord bevat een id veld. Gebruik deze in de volgende stap.

Stap 5: Een aanvraag verzenden naar de 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}"
  }
}

Het antwoord bevat metagegevens over de uitvoering van de agent en een text veld content met het gesynthetiseerde antwoord.

Note

Gebruik tokenbereik https://ai.azure.com/.default bij het ophalen van het bearer-token.

Selecteer Promptagents om de Azure AI Projects SDK te gebruiken om een promptagent aan de serverzijde te maken of gehoste agents om het Microsoft Agent Framework te gebruiken om een tijdelijke, in-process agent te bouwen die via een werkset verbinding maakt met het hulpprogramma.

Agents aansturen

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

Gehoste agents

Maak een werksetversie met WorkIQPreviewToolboxTool. Het werksetspecifieke type verschilt van WorkIQPreviewTool, waardoor Work IQ rechtstreeks aan een promptagent wordt toegevoegd.

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

Het voorbeeld retourneert de nieuwe werksetversie:

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

Vervolgens koppelt u de werkset aan een gehoste agent. Zie het voorbeeld van de Teams-activiteit voor een volledige C#-implementatie die work IQ-werksethulpprogramma's registreert met Agent Framework.


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

Werk-IQ toevoegen aan een werkset met de Azure Developer CLI

Gebruik de Azure Developer CLI om de Work IQ A2A-projectverbinding te maken en hiernaar te verwijzen vanuit een minimale YAML-werkset.

# 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

In dit artikel wordt het Work IQ A2A-eindpunt https://workiq.svc.cloud.microsoft/a2a/gebruikt. De vorige werksetcatalogus die wordt gebruikt https://agent365.svc.cloud.microsoft/agents/agents/workiq voor de azd-werkstroom; controleer het eindpunt als uw Work IQ-verbinding een ander A2A- of MCP-doel gebruikt.

# 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

Work IQ gebruiken met een gehoste agent

Nadat u een werkset hebt gemaakt work-iq-toolbox, volgt u Gebruik een werkset met een gehoste agent om deze te verbinden met Agent Framework, voert u deze lokaal uit en implementeert u deze in Foundry Agent Service. De gehoste integratie behoudt de context per aanvraag die Work IQ moet uitvoeren namens elke aangemelde gebruiker.

Gebruik voor end-to-end-implementaties het onderhouden voorbeeld van Python Teams-activiteit of .NET Voorbeeld van Teams-activiteiten.

Verificatie en beveiliging

Werk IQ maakt gebruik van Microsoft Entra ID gedelegeerde verificatie. Alle aanvragen worden uitgevoerd in de context van de aangemelde gebruiker. Verificatie met alleen toepassingen (alleen voor apps) wordt niet ondersteund. Microsoft 365-machtigingen worden automatisch gehandhaafd — Work IQ-agenten hebben nooit toegang tot gegevens die de aangemelde gebruiker niet al mag zien.

Alleen Bring Your Own Entra-app (On-Behalf-Of-verificatie) wordt ondersteund voor Work IQ-verbindingen. Dit geeft uw Entra-beheerder expliciet controle over welke toepassingen Microsoft 365 gegevens kunnen ophalen via Work IQ: de beheerder beoordeelt en verleent de WorkIQAgent.Ask machtiging specifiek voor uw geregistreerde app.

Uw Entra-app instellen (eenmalig, per organisatie)

Een Entra-beheerder moet de volgende eenmalige tenantbewerking uitvoeren voordat u een Work IQ-verbinding in Foundry kunt maken. Voor stappen waarvoor de rol Globale beheerder is vereist, gebruikt u Microsoft Entra PIM om de rol just-in-time te activeren en de rol te deactiveren wanneer de installatie is voltooid. Dagelijkse werk IQ-gebruikers hebben deze rol niet nodig.

De Work IQ-service-principal configureren (eenmalig)

Voordat u de app-registratie maakt, moet een globale beheerder de Work IQ-service-principal inrichten als onderdeel van deze eenmalige tenantbewerking. Als u deze stap overslaat, wordt de optie Werk-IQ niet weergegeven wanneer u API-machtigingen zoekt.

Volg Step 1: de Work IQ-service-principal aanmaken in de quickstart voor de Work IQ API. Een 201 Created-antwoord van Graph Explorer bevestigt dat de bewerking is geslaagd. Een conflictfout betekent dat de principal al bestaat. Ga verder met de volgende stap.

De app-registratie maken

  1. Ga naar het Microsoft Entra-beheercentrum. Selecteer in het linkernavigatievenster Entra ID>App-registraties.

  2. Selecteer Nieuwe registratie. Geef de app een beschrijvende naam en stel Ondersteunde accounttypen in op Alleen accounts in deze organisatiedirectory. Selecteer Registreren.

  3. Kopieer de Application (client) ID. U hebt deze waarde nodig bij het maken van de Foundry-verbinding.

  4. Selecteer API-machtigingen>Voeg een machtigings-API>toe die door mijn organisatie wordt gebruikt. Zoek naar Work IQ (fdcc1f02-fc51-4226-8753-f668596af7f7), selecteer Gedelegeerde machtigingen, selecteer WorkIQAgent.Ask en selecteer Vervolgens Machtigingen toevoegen.

  5. Selecteer Beheerderstoestemming verlenen voor [uw tenant]. Controleer het bevestigingsvenster en selecteer Ja.

    Important

Het verlenen van beheerderstoestemming voor de hele tenant is een eenmalige tenantbewerking waarvoor de rol Globale beheerder in Microsoft Entra ID is vereist. Activeer de rol net op tijd via Microsoft Entra PIM en deactiveer deze na het verlenen van toestemming. Dagelijkse werk IQ-gebruikers hebben deze rol niet nodig. Als u deze rol niet hebt, vraagt u de globale beheerder van uw organisatie om deze stap te voltooien.

  1. Selecteer Certificaten en geheimen>Nieuw cliëntgeheim. Voeg een beschrijving en vervaldatum toe. Selecteer Toevoegen en kopieer vervolgens onmiddellijk de geheime waarde . Deze wordt slechts eenmaal weergegeven. Sla het geheim op in Azure Key Vault of een ander goedgekeurd geheimarchief. Voer het geheim nooit door naar broncodebeheer of druk het af of registreer het. Draai het geheim voordat het verloopt.
  2. Kopieer uw Directory-id (tenant)-id vanaf de overzichtspagina Microsoft Entra ID.

Vul de verbindingswaarden van Foundry in

In Microsoft Foundry, open uw project en ga naar Settings>Connections>New connection>Work IQ. Vul de volgende velden in:

Veld Waarde
Client-ID Applicatie-id (client) van stap 3
Geheim van de klant Clientgeheimwaarde uit stap 6
Autorisatie-URL https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
Token-URL https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
URL vernieuwen https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Scopes api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask,offline_access

Vervang door {tenant-id} uw directory-id (tenant) uit stap 7. Selecteer Opslaan om de verbinding te maken.

Schermopname van de Foundry-portal met verificatie-instellingen voor een Work IQ-verbinding.

Important

Verbindingsvelden kunnen niet worden bewerkt na het maken. Als u onjuiste waarden invoert, verwijdert u de verbinding en maakt u een nieuwe.

De omleidings-URI toevoegen aan uw app-registratie

Nadat Foundry de verbinding heeft gemaakt, wordt er een OAuth-omleidings-URL weergegeven. Voeg deze URL toe aan uw app-registratie:

  1. Ga in de Microsoft Entra-beheercentrum naar Entra ID>App-registraties en selecteer uw app.
  2. Selecteer Verificatie>Een platform toevoegen>Web.
  3. Plak onder Omleidings-URI's de omleidings-URL van OAuth uit Foundry.
  4. Selecteer Configureren.

De verbinding maken met de REST API

Als alternatief voor de Foundry-portal gebruikt u de Azure Resource Manager-API om de Work IQ-verbinding programmatisch te maken.

Stap 1: Een token verkrijgen

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

Stap 2: De verbinding maken

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

Een geslaagd antwoord retourneert HTTP 200 of 201. De hoofdtekst van het antwoord bevat een properties.oauthRedirectUrl veld. Gebruik deze waarde als de omleidings-URI in uw Entra-app-registratie (zie De omleidings-URI toevoegen aan uw app-registratie).

Gegevensbeheer en naleving

Het ophalen van IQ-machtigingen op basis van Microsoft 365. Een Foundry-werkstroom kan ook prompts en opgehaalde resultaten verzenden naar downstream-Copilot- en Foundry-verwerking, dus controleer de grenzen en regionale configuratie van elke service in het aanvraagpad.

Opslaglocatie van gegevens

Microsoft 365 ophalen volgt de machtigingen en configuratie van uw tenantlocatie. End-to-end verwerking is ook afhankelijk van uw Copilot factureringsconfiguratie en foundry-projectregio. Zie Microsoft 365 Copilot beleid voor privacy- en gegevensverwerking voor meer informatie.

Privacy en gegevensverwerking

Bekijk de Microsoft 365 Copilot beleidsregels voor privacy- en gegevensverwerking en de vereisten voor de verwerking van foundry-gegevens die van toepassing zijn op uw implementatie. Bevestig het volledige aanvraagpad met uw privacy- en complianceteams.

Toegangsbeheer en machtigingen

Ontwerp de verbinding zodat het ophalen gebruikmaakt van de Microsoft 365 machtigingen van de aangemelde gebruiker. Test het bijsnijden van machtigingen met representatieve gebruikers en beperkte inhoud vóór de implementatie:

  • Op rollen gebaseerd toegangsbeheer, vertrouwelijkheidslabels en informatiebarrières die zijn gedefinieerd in Microsoft 365 worden gerespecteerd.

Nalevingsbeoordeling

Gebruik de Microsoft compliancebronnen van uw organisatie om te bevestigen welke certificeringen en controles van toepassing zijn op de volledige Work IQ en Foundry-implementatie.

Administratiebeheer

Als Entra-beheerder bepaalt u welke toepassingen in uw tenant toegang hebben tot Work IQ-gegevens namens gebruikers. In de volgende secties worden de belangrijkste besturingselementen beschreven die voor u beschikbaar zijn.

Beheerderstoestemming WorkIQAgent.Ask is vereist voordat een gebruiker in uw organisatie zich kan verifiëren via de app. U kunt toestemming op elk gewenst moment beheren:

  • Toestemming verlenen: Ga in het Microsoft Entra-beheercentrum naar Entra ID>App-registraties>, selecteer de app > en ga naar API-machtigingen. Selecteer Beheerderstoestemming verlenen voor [uw tenant].
  • Toestemming intrekken: selecteer op dezelfde pagina met API-machtigingen de WorkIQAgent.Ask machtiging en selecteer Beheerderstoestemming intrekken. Bestaande tokens blijven geldig totdat ze verlopen; er kunnen geen nieuwe tokens worden uitgegeven na intrekking.

Troubleshooting

Symptoom Waarschijnlijke oorzaak Resolutie / Besluit
403 Forbidden Facturering is niet ingeschakeld voor de Iq-API van Work of er ontbreekt een connectorspecifieke licentie. Schakel Copilot facturering van tegoed in voor Werk IQ API-aanroepen. Voor hulpprogramma's die door de connector worden ondersteund, controleert u of de aanroepende gebruiker voldoet aan de licentievereisten van die connector.
401 Unauthorized Tokendoelgroep komt niet overeen Zorg ervoor dat het token is uitgegeven voor api://workiq.svc.cloud.microsoft, niet voor een andere resource.
403 Forbidden met Required scopes = [...] Beheerderstoestemming voor WorkIQAgent.Ask niet verleend Een beheerder moet toestemming verlenen voor de app-registratie.
Agent krijgt geen antwoord of leeg resultaat Microsoft 365 inhoud niet beschikbaar is voor de aangemelde gebruiker of niet is geïndexeerd. Bevestig de bronmachtigingen van de gebruiker en probeer het opnieuw nadat het indexeren is voltooid.
Principal does not have access to API/Operation Agentidentiteit mist Foundry-gebruikersrol op projectniveau Wijs Foundry User toe op zowel accountniveau als projectniveau.