Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Importante
Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per ulteriori informazioni, vedere Condizioni supplementari per l'uso delle versioni di anteprima di Microsoft Azure.
Work IQ è il livello di intelligenza che fornisce a Microsoft 365 Copilot e ai tuoi agenti un contesto condiviso, in tempo reale, in tutta l'organizzazione. Acquisisce segnali da messaggi di posta elettronica, riunioni, file, chat e sistemi aziendali e applica la comprensione semantica in modo che gli agenti possano ragionare sui dati di lavoro e intervenire. Tutte le richieste vengono eseguite nel contesto dell'utente connesso e rispettano le autorizzazioni Microsoft 365.
È possibile connettere l'agente Foundry all'IQ aziendale tramite il protocollo da agente a agente (A2A). Il tuo agente delega a Work IQ le attività in linguaggio naturale come agente peer — ad esempio, "Riassumi le mie email recenti su Project Contoso" — e Work IQ si occupa del recupero, del ragionamento e della sintesi della risposta in base ai dati Microsoft 365 dell'utente.
Per informazioni sull'ottimizzazione dell'utilizzo degli strumenti, vedere Procedure consigliate.
Avvertimento
Quando ti connetti a Work IQ, potrebbero essere applicati costi e i dati potrebbero essere inviati al di fuori del perimetro di conformità di Azure ed elaborati in conformità alle condizioni di servizio applicabili e alle normative sulla gestione dei dati. È tua responsabilità gestire se i tuoi dati fluiranno oltre i confini di conformità e geografici della tua organizzazione e le eventuali implicazioni correlate, nonché garantire che siano predisposti i permessi, i confini e le approvazioni appropriati.
L'utente è responsabile di esaminare e testare attentamente le applicazioni compilate nel contesto dei casi d'uso specifici e di prendere tutte le decisioni e le personalizzazioni appropriate. Ciò include l'implementazione di mitigazioni di intelligenza artificiale responsabili, ad esempio metaprompt, filtri di contenuto o altri sistemi di sicurezza, e garantire che le applicazioni soddisfino gli standard di qualità, affidabilità, sicurezza e attendibilità appropriati. Vedi la nota sulla trasparenza di Foundry Agent Service.
Prerequisiti
Prima di iniziare, assicurarsi di avere:
Requisito commerciale per la connessione usata:
Percorso di connessione Tipo di requisito Requisito Usare l'API IQ tramite A2A, REST o MCP Fatturazione basata sull'uso Abilitare la fatturazione con crediti Copilot. Questo percorso non usa le licenze del connettore. Strumenti di Microsoft 365 supportati dal connettore Licenze del connettore Verificare i prerequisiti del connettore selezionato. Un connettore può richiedere una licenza Microsoft 365 Copilot per ogni utente chiamante. Un progetto Microsoft Foundry attivo con un modello distribuito.
Azure ruoli controllo degli accessi in base al ruolo:
- ruolo «Foundry User» nel progetto Foundry per l'identità dello sviluppatore, l'identità di runtime dell'agente e qualsiasi identità utente coinvolta nei flussi OAuth.
- Ruolo di Foundry Project Manager nel progetto Foundry per creare una connessione Foundry all'endpoint Work IQ.
Un amministratore globale di Microsoft Entra che può completare la configurazione di un tenant monouso effettuando il provisioning dell'entità servizio IQ aziendale e concedendo il consenso amministratore per
WorkIQAgent.Ask. Attivare questo ruolo just-in-time tramite Microsoft Entra Privileged Identity Management (PIM) e disattivarlo dopo l'installazione. Gli utenti di IQ aziendali quotidiane non hanno bisogno di questo ruolo.Foundry Toolkit: Installare Visual Studio Code e Foundry Toolkit per Visual Studio Code.
Sviluppo JavaScript: usare Node.js 22 o versione successiva e installare
@azure/ai-projects2.4.0 o versione successiva con@azure/identity.
Per le chiamate A2A dirette, Work IQ supporta le versioni del protocollo 1.0 e 0.3. Inviare A2A-Version: 1.0 per usare i nomi dei metodi v1. L'omissione dell'intestazione per impostazione predefinita è v0.3. Includere i metadati della posizione per le richieste sensibili al tempo e usare l'autenticazione utente delegata.
Seguire la mappa delle dipendenze della configurazione
Usare questa mappa per separare il flusso di utilizzo dell'agente dalle dipendenze completate da un amministratore una volta per l'organizzazione.
| Obiettivo | Dipende da | Continuare all'indirizzo |
|---|---|---|
| Aggiungere IQ lavoro a un agente e inviare una query | Una connessione IQ aziendale esistente, le autorizzazioni di Microsoft 365 dell'utente connesso e le licenze di fatturazione o connettore elencate nei prerequisiti. | Aggiungere lo strumento IQ di lavoro all'agente |
| Creare la prima connessione IQ aziendale per l'organizzazione | L'entità servizio IQ aziendale, un'app Entra a tenant singolo, l'autorizzazione delegata WorkIQAgent.Ask e il consenso amministratore a livello di tenant. |
Configurare l'app Entra |
| Usare uno strumento di Microsoft 365 supportato dal connettore | Una connessione per il connettore e qualsiasi licenza specifica del connettore necessaria per l'utente connesso. | Aggiungere lo strumento IQ di lavoro all'agente |
Completare prima il flusso di utilizzo dell'agente quando l'organizzazione ha già una connessione. Usare la configurazione di un tenant monouso solo quando un amministratore deve creare la prima connessione.
Tip
Prendere in considerazione l'aggiunta di questo strumento usando una casella degli strumenti. Usando una casella degli strumenti, è possibile riutilizzare lo strumento tra agenti e runtime, nonché centralizzare la gestione delle credenziali, il controllo delle versioni e l'imposizione dei criteri tramite un endpoint MCP gestito. Vedere la guida introduttiva alla casella degli strumenti.
Supporto per l'utilizzo
| Supporto di Microsoft Foundry | PYTHON SDK | SDK di C# | JavaScript SDK | JAVA SDK | REST API | Configurazione dell'agente di base | Configurazione dell'agente standard |
|---|---|---|---|---|---|---|---|
| IQ lavoro | ✔️ | ✔️ | ✔️ | — | ✔️ | ✔️ | ✔️ |
Come funziona
-
Il tuo agente invia una chiamata allo strumento : quando il modello agente identifica un'attività che richiede Microsoft 365 dati, genera una chiamata di strumento allo strumento /
work_iq_preview. - Foundry instrada la richiesta a Work IQ tramite A2A — Foundry utilizza il protocollo Agent-to-Agent (A2A) per inoltrare la query in linguaggio naturale a Work IQ in qualità di agente peer. L'autenticazione utilizza On-Behalf-Of (OBO) in modo che la richiesta venga eseguita nel contesto dell'utente che ha effettuato l'accesso.
- Work IQ recupera e analizza i dati di M365 — Work IQ interroga le email, le riunioni, i file, le chat e altri segnali di Microsoft 365 dell'utente. Applica la comprensione semantica per sintetizzare una risposta basata sul contesto di lavoro effettivo dell'utente, rispettando le autorizzazioni Microsoft 365 e le etichette di riservatezza.
- Il risultato viene restituito all'agente : work IQ restituisce la risposta sintetizzata a Foundry tramite A2A. L'agente lo incorpora nella risposta all'utente.
Connettersi all'IQ aziendale
Aggiungi lo strumento Work IQ al tuo agente
Usa Foundry Toolkit per Visual Studio Code per aggiungere Work IQ come strumento integrato quando crei un toolbox, quindi connetti l'agente all'endpoint pubblicato del toolbox. La casella degli strumenti espone le opzioni di IQ di lavoro selezionate tramite l'endpoint MCP.
- Selezionare Foundry Toolkit nella barra delle attività.
- In Risorse personali, espandi Il nome del tuo progetto>Strumenti.
- Selezionare l'icona + Aggiungi casella degli strumenti .
- Nella scheda Compila una casella degli strumenti personalizzata immettere il nome e la descrizione della casella degli strumenti.
- Seleziona Aggiungi strumenti e quindi seleziona Work IQ.
- In Aggiungi lo strumento Work IQ, seleziona i dati di Microsoft 365 Copilot che vuoi usare. Work IQ Chat si connette tramite un endpoint A2A. Altre opzioni si connettono tramite endpoint MCP, tra cui Copilot Chat, Teams, Word, Calendario Outlook, Posta Outlook, profilo utente Microsoft 365, SharePoint e OneDrive.
- Per ogni opzione selezionata, scegliere una connessione esistente o selezionare Crea nuova connessione.
- Seleziona Aggiungi.
- Seleziona Pubblica.
Per il flusso di lavoro completo per la creazione della casella degli strumenti, vedere Curare la casella degli strumenti basata sulle finalità in Foundry.
Per aggiungere lo strumento IQ di lavoro tramite una casella degli strumenti usando il codice o l'API REST, selezionare la scheda Python, .NET, JavaScript o API REST in questa sezione.
Installare il pacchetto:
pip install "azure-ai-projects>=2.3.0"
Impostare le seguenti variabili di ambiente:
-
FOUNDRY_PROJECT_ENDPOINT- l'endpoint del progetto, disponibile nella pagina Panoramica del progetto Foundry. -
WORK_IQ_PROJECT_CONNECTION_ID: ID di risorsa completo della connessione al progetto Work IQ.
Selezionare Prompt Agents per usare l'SDK per progetti di intelligenza artificiale Azure per creare un agente prompt sul lato server o agenti ospitati per usare Microsoft Agent Framework per creare un agente temporaneo e in-process che si connette allo strumento tramite una casella degli strumenti.
Agenti rapidi
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")
Risultato previsto: l'agente interroga Work IQ con la richiesta dell'utente. Work IQ recupera e sintetizza il contenuto Microsoft 365 pertinente dell'utente, in base alle autorizzazioni e restituisce la risposta.
Agenti ospitati
Creare una versione della casella degli strumenti con WorkIQPreviewToolboxTool. Il tipo specifico della casella degli strumenti è diverso da WorkIQPreviewTool, che aggiunge IQ di lavoro direttamente a un agente prompt.
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'esempio restituisce la nuova versione della casella degli strumenti:
Created toolbox: work-iq-toolbox, version: <version>
Connettere quindi la casella degli strumenti a un agente ospitato. Tale flusso di lavoro usa l'integrazione del runtime ospitato per mantenere il contesto di richiesta necessario per le chiamate IQ di lavoro delegate dall'utente. Per un'implementazione completa Python, vedere l'esempio di attività di Teams di Agent Framework.
Il modo consigliato per aggiungere IQ di lavoro è tramite una casella degli strumenti, quindi allegare la casella degli strumenti all'agente come strumento MCP. Vedere Che cos'è una casella degli strumenti?
Passaggio 1: Creare una casella degli strumenti contenente lo strumento IQ di lavoro:
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 casella degli strumenti espone un endpoint compatibile con MCP in {project_endpoint}/toolboxes/work-iq-toolbox/versions/<version>/mcp?api-version=v1, dove <version> è la versione restituita dalla chiamata precedente.
Passaggio 2: Creare una connessione al progetto strumento remoto che punta all'endpoint della casella degli strumenti usando un token Entra utente in modo che l'identità del chiamante venga passata (gruppo di destinatari 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
Passaggio 3: Creare l'agente con la casella degli strumenti collegata come strumento 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"
}
]
}
Passaggio 4: Creare una sessione di conversazione:
POST {project_endpoint}/openai/v1/conversations
Authorization: Bearer {token}
Content-Type: application/json
{}
La risposta include un id campo. Usarlo nel passaggio successivo.
Passaggio 5: Inviare una richiesta all'agente:
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 risposta include i metadati relativi all'esecuzione dell'agente e un text campo in content con la risposta sintetizzata.
Note
Usare l'ambito del token https://ai.azure.com/.default quando si recupera il bearer token.
Selezionare Prompt Agents per usare l'SDK per progetti di intelligenza artificiale Azure per creare un agente prompt sul lato server o agenti ospitati per usare Microsoft Agent Framework per creare un agente temporaneo e in-process che si connette allo strumento tramite una casella degli strumenti.
Agenti rapidi
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);
Agenti ospitati
Creare una versione della casella degli strumenti con WorkIQPreviewToolboxTool. Il tipo specifico della casella degli strumenti è diverso da WorkIQPreviewTool, che aggiunge IQ di lavoro direttamente a un agente prompt.
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'esempio restituisce la nuova versione della casella degli strumenti:
Created toolbox: work-iq-toolbox, version: <version>
Connettere quindi la casella degli strumenti a un agente ospitato. Per un'implementazione C# completa che registra gli strumenti della casella degli strumenti di IQ di lavoro con Agent Framework, vedere l'esempio di attività di 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);
});
Aggiungere IQ di lavoro a una casella degli strumenti con l'interfaccia della riga di comando per sviluppatori Azure
Usare l'interfaccia della riga di comando per sviluppatori di Azure per creare la connessione al progetto work IQ A2A, quindi farvi riferimento da un YAML minimo della casella degli strumenti.
# 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
Questo articolo usa l'endpoint https://workiq.svc.cloud.microsoft/a2a/IQ A2A di lavoro. Il catalogo della casella degli strumenti precedente usato https://agent365.svc.cloud.microsoft/agents/agents/workiq per il flusso di lavoro azd. Verificare l'endpoint se la connessione IQ aziendale usa una destinazione A2A o MCP diversa.
# 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
Usare l'IQ aziendale con un agente ospitato
Dopo aver creato work-iq-toolbox, seguire Usare una casella degli strumenti con un agente ospitato per connetterlo a Agent Framework, eseguirlo in locale e distribuirlo nel servizio Foundry Agent. L'integrazione ospitata mantiene il contesto per ogni richiesta che work IQ deve agire per conto di ogni utente connesso.
Per le implementazioni end-to-end, usare l'esempio di attività di Teams gestito Python o .NET esempio di attività di Teams.
Autenticazione e sicurezza
Work IQ usa l'autenticazione delegata di Microsoft Entra ID. Tutte le richieste vengono eseguite nel contesto dell'utente connesso. L'autenticazione solo applicazione (solo app) non è supportata. Le autorizzazioni di Microsoft 365 vengono applicate automaticamente: gli agenti di Work IQ non possono mai accedere ai dati che l'utente che ha effettuato l'accesso non è già autorizzato a visualizzare.
Solo l'app Bring Your Own Entra (autenticazione on-Behalf-Of) è supportata per le connessioni IQ aziendali. In questo modo, l'amministratore di Entra ha il controllo esplicito su quali applicazioni possono recuperare i dati di Microsoft 365 tramite Work IQ: l'amministratore esamina e concede l'autorizzazione WorkIQAgent.Ask specificamente per l'app registrata.
Configurare l'app Entra (una tantum, per organizzazione)
Un amministratore entra deve completare l'operazione tenant monouso seguente prima di poter creare una connessione IQ aziendale in Foundry. Per i passaggi che richiedono il ruolo amministratore globale, usare Microsoft Entra PIM per attivare il ruolo just-in-time e disattivarlo al termine dell'installazione. Gli utenti di IQ aziendali quotidiane non hanno bisogno di questo ruolo.
Eseguire il provisioning dell'entità di servizio di Work IQ (una tantum)
Prima di creare la registrazione dell'app, un amministratore globale deve effettuare il provisioning dell'entità servizio IQ aziendale come parte di questa operazione di tenant monouso. Se si ignora questo passaggio, l'opzione IQ di lavoro non verrà visualizzata quando si esegue la ricerca delle autorizzazioni dell'API.
Segui Passaggio 1: Crea il service principal di Work IQ nella guida introduttiva dell'API di Work IQ. Una risposta "201 Created" di Graph Explorer conferma il successo dell'operazione. Un errore di conflitto indica che l'entità esiste già. Continuare con il passaggio successivo.
Creare la registrazione dell'app
Vai all'interfaccia di amministrazione di Microsoft Entra. Nel riquadro di spostamento a sinistra selezionare Entra ID>Registrazioni app.
Seleziona Nuova registrazione. Assegnare all'app un nome descrittivo e impostare Tipi di account supportati su Solo per gli account in questa directory organizzativa. Selezionare Registrazione.
Copia l'ID applicazione (client). Questo valore è necessario quando si crea la connessione Foundry.
Selezionare Autorizzazioni API>Aggiungi un'autorizzazione>API usate dall'organizzazione. Cercare IQ aziendale (ID
fdcc1f02-fc51-4226-8753-f668596af7f7applicazione), selezionare Autorizzazioni delegate, selezionare WorkIQAgent.Ask e quindi selezionare Aggiungi autorizzazioni.Seleziona Concedi il consenso dell'amministratore per [il tuo tenant]. Esaminare la finestra di dialogo di conferma e selezionare Sì.
Importante
La concessione del consenso amministratore a livello di tenant è un'operazione di tenant monouso che richiede il ruolo di amministratore globale in Microsoft Entra ID. Attivare il ruolo just-in-time tramite Microsoft Entra PIM e disattivarlo dopo aver concesso il consenso. Gli utenti di IQ aziendali quotidiane non hanno bisogno di questo ruolo. Se non si ha questo ruolo, chiedere all'amministratore globale dell'organizzazione di completare questo passaggio.
- Selezionare Certificati e segreti>Nuovo segreto client. Aggiungere una descrizione e una scadenza. Selezionare Aggiungi e quindi copiare immediatamente il valore del segreto, che viene visualizzato una sola volta. Archiviare il segreto in Azure Key Vault o in un altro archivio segreto approvato. Non eseguire mai il commit del segreto nel controllo del codice sorgente o stamparlo o registrarlo. Ruotare il segreto prima della scadenza.
- Copiare l'ID Directory (tenant) dalla pagina di panoramica Microsoft Entra ID.
Compilare i valori di connessione Foundry
In Microsoft Foundry aprire il progetto e passare a Settings>Connections>Nuova connessione>Work IQ. Compilare i campi seguenti:
| Campo | Value |
|---|---|
| Client ID | ID dell'applicazione (client) del passaggio 3 |
| Segreto del cliente | Valore del segreto client dal passaggio 6 |
| URL di autorizzazione | https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize |
| Token URL | https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token |
| Aggiornare l'URL | https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token |
| Ambiti | api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask,offline_access |
Sostituire {tenant-id} con l'ID della directory (tenant) del passaggio 7. Selezionare Salva per creare la connessione.
Importante
I campi di connessione non possono essere modificati dopo la creazione. Se si immettono valori non corretti, eliminare la connessione e crearne una nuova.
Aggiungere l'URI di reindirizzamento alla registrazione dell'app
Dopo aver creato la connessione, Foundry visualizza un URL di reindirizzamento OAuth. Aggiungere questo URL alla registrazione dell'app:
- Nella Interfaccia di amministrazione di Microsoft Entra passare a Entra ID>Registrazioni app e selezionare l'app.
- Seleziona Autenticazione>Aggiungi una piattaforma>Web.
- In URI di reindirizzamento, incolla l'URL di reindirizzamento OAuth di Foundry.
- Seleziona Configura.
Creare la connessione con l'API REST
In alternativa al portale Foundry, usa l'API di Azure Resource Manager per creare tramite codice la connessione Work IQ.
Passaggio 1: Acquisire un token
ARM_TOKEN=$(az account get-access-token \
--resource https://management.azure.com \
--query accessToken -o tsv)
Passaggio 2: Creare la connessione
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"
}
}
}'
Una risposta con esito positivo restituisce HTTP 200 o 201. Il corpo della risposta include un properties.oauthRedirectUrl campo: usare tale valore come URI di reindirizzamento nella registrazione dell'app Entra (vedere Aggiungere l'URI di reindirizzamento alla registrazione dell'app).
Governance e conformità dei dati
Recupero delle autorizzazioni di IQ sul Microsoft 365. Un flusso di lavoro Foundry può anche inviare richieste e risultati recuperati all'elaborazione downstream Copilot e Foundry, quindi esaminare i limiti e la configurazione a livello di area di ogni servizio nel percorso della richiesta.
Residenza dei dati
Microsoft 365 il recupero segue le autorizzazioni e la configurazione di residenza del tenant. L'elaborazione end-to-end dipende anche dalla configurazione di fatturazione Copilot e dall'area del progetto Foundry. Per informazioni dettagliate, vedere Microsoft 365 Copilot privacy e criteri di gestione dei dati.
Privacy e gestione dei dati
Esaminare i criteri di gestione dei dati e della privacy Microsoft 365 Copilot e i requisiti di gestione dei dati foundry applicabili alla distribuzione. Confermare il percorso completo della richiesta con i team di privacy e conformità.
Controllo dell'accesso e autorizzazioni
Progettare la connessione in modo che il recupero usi le autorizzazioni di Microsoft 365 dell'utente connesso. Testare il taglio delle autorizzazioni con utenti rappresentativi e contenuto limitato prima della distribuzione:
- Vengono rispettati il controllo degli accessi in base al ruolo, le etichette di riservatezza e le barriere informative definite in Microsoft 365.
Verifica della conformità
Usare le risorse di conformità Microsoft dell'organizzazione per verificare quali certificazioni e controlli si applicano alla distribuzione completa di IQ lavoro e Foundry.
Gestione dell’amministrazione
In qualità di amministratore di Entra, controlli quali applicazioni nel tuo tenant possono accedere ai dati di Work IQ per conto degli utenti. Le sezioni seguenti descrivono i controlli chiave disponibili.
Concedere o revocare il consenso amministratore
Il consenso amministratore per WorkIQAgent.Ask è necessario prima che qualsiasi utente dell'organizzazione possa eseguire l'autenticazione tramite l'app. È possibile gestire il consenso in qualsiasi momento:
- Concedere il consenso: nel Interfaccia di amministrazione di Microsoft Entra, passare a Entra ID>Registrazioni app> e selezionare l'app >API permissions. Seleziona Concedi il consenso dell'amministratore per [il tuo tenant].
-
Revoca consenso: nella stessa pagina delle autorizzazioni API selezionare l'autorizzazione
WorkIQAgent.Aske selezionare Revoca il consenso amministratore. I token esistenti rimangono validi fino alla scadenza; non è possibile emettere nuovi token dopo la revoca.
Troubleshooting
| Sintomo | Causa possibile | Resolution |
|---|---|---|
403 Forbidden |
La fatturazione non è abilitata per l'API IQ aziendale o manca una licenza specifica del connettore. | Abilitare la fatturazione Copilot Crediti per le chiamate API IQ aziendali. Per gli strumenti supportati dal connettore, verificare che l'utente chiamante soddisfi i requisiti di licenza del connettore. |
401 Unauthorized |
Mancata corrispondenza del gruppo di destinatari del token | Assicurarsi che il token venga emesso per api://workiq.svc.cloud.microsoft, non per una risorsa diversa. |
403 Forbidden Con Required scopes = [...] |
Consenso dell'amministratore per WorkIQAgent.Ask non accordato |
Un amministratore deve concedere il consenso per la registrazione dell'app. |
| Agent non ottiene alcuna risposta o risultato vuoto | Microsoft 365 contenuto non è disponibile per l'utente connesso o non è stato indicizzato. | Confermare le autorizzazioni di origine dell'utente, quindi riprovare al termine dell'indicizzazione. |
Principal does not have access to API/Operation |
All'identità dell'agente manca il ruolo Foundry User a livello di progetto | Assegnare Utente Foundry sia a livello di account sia a livello di progetto. |