Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Importante
Os itens assinalados como (pré-visualização) neste artigo estão atualmente em pré-visualização pública. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e não a recomendamos para trabalhos em produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos Suplementares de Utilização para Microsoft Azure Previews.
QI de trabalho é a camada de inteligência que fundamenta Microsoft 365 Copilot e os seus agentes num contexto partilhado e em tempo real em toda a sua organização. Capta sinais de emails, reuniões, ficheiros, chats e sistemas empresariais, e aplica compreensão semântica para que os agentes possam raciocinar sobre os dados do trabalho e agir. Todas as solicitações são executadas no contexto do utilizador com sessão iniciada e respeitam as permissões do Microsoft 365.
Liga o seu agente da Foundry ao Work IQ através do protocolo Agent-to-Agent (A2A). O seu agente delega tarefas em linguagem natural ao Work IQ como agente par — por exemplo, "Resuma os meus emails recentes sobre o Project Contoso" — e o Work IQ trata da recuperação, raciocínio e síntese de respostas contra os dados do utilizador no Microsoft 365.
Para informações sobre como otimizar o uso de ferramentas, consulte as melhores práticas.
Warning
Quando se liga ao Work IQ, pode incorrer em custos e os dados podem ser enviados para fora do limite de conformidade com o Azure e processados de acordo com os termos de serviço e políticas de tratamento de dados aplicáveis. É sua responsabilidade gerir se os seus dados irão fluir para além dos limites de conformidade e geográficos da sua organização e quaisquer implicações relacionadas, e que sejam fornecidas as permissões, limites e aprovações apropriadas.
És responsável por rever e testar cuidadosamente as aplicações que constróis no contexto dos teus casos de uso específicos e por tomar todas as decisões e personalizações apropriadas. Isto inclui implementar as suas próprias mitigações de IA responsável, como metaprompts, filtros de conteúdo ou outros sistemas de segurança, e assegurar que as suas aplicações cumprem os padrões adequados de qualidade, fiabilidade, segurança e confiabilidade. Consulte a nota de transparência do Foundry Agent Service.
Pré-requisitos
Antes de começar, certifique-se de que tem:
O requisito comercial para a ligação que utiliza:
Caminho de ligação Tipo de requisito Requisito API do Work IQ através de A2A, REST ou MCP Faturação baseada no uso Ative a faturação com os Créditos Copilot. Este caminho não utiliza licença de conectores. Ferramentas Microsoft 365 suportadas por Connector Licenciamento de conectores Confirme os pré-requisitos do conector selecionado. Um conector pode exigir uma licença Microsoft 365 Copilot para cada utilizador a chamar. Um projeto ativo Microsoft Foundry com um modelo implementado.
Azure RBAC roles:
- Papel de utilizador do Foundry no projeto Foundry para a identidade do programador, a identidade de runtime do agente e qualquer identidade de utilizador envolvida nos fluxos OAuth.
- Gestor de Projetos do Foundry função no projeto Foundry para criar uma ligação do Foundry ao endpoint do Work IQ.
Um Administrador Global Microsoft Entra que pode completar a configuração do inquilino único ao provisionar o principal do serviço Work IQ e conceder consentimento do administrador para
WorkIQAgent.Ask. Ativa esta função mesmo a tempo através do Microsoft Entra Privileged Identity Management (PIM) e desativa-a após a configuração. Os utilizadores do Work IQ no dia a dia não precisam deste cargo.Foundry Toolkit: Instale Visual Studio Code e Foundry Toolkit para Visual Studio Code.
Desenvolvimento JavaScript: Use Node.js 22 ou posterior e instale
@azure/ai-projectsa versão 2.4.0 ou posterior com@azure/identity.
Para chamadas A2A diretas, o Work IQ suporta as versões 1.0 e 0.3 dos protocolos. Enviar A2A-Version: 1.0 para usar nomes de métodos v1. Omitir o cabeçalho passa por defeito à v0.3. Inclua metadados de localização para pedidos sensíveis ao tempo e utilize autenticação de utilizadores delegada.
Siga o mapa de dependências de configuração
Use este mapa para separar o fluxo de utilização do agente das dependências que um administrador completa uma vez para a organização.
| Goal | Depende de | Continuar em |
|---|---|---|
| Adicione o Work IQ a um agente e envie uma consulta | Uma ligação Work IQ existente, as permissões Microsoft 365 do utilizador iniciado e a faturação ou licença de ligação listados nos pré-requisitos. | Adicione a ferramenta Work IQ ao seu agente |
| Criar a primeira ligação Work IQ para a organização | O principal do serviço Work IQ, uma aplicação Entra de inquilino único, permissões WorkIQAgent.Ask delegadas e consentimento administrativo para todo o inquilino. |
Configure a sua aplicação Entra |
| Use uma ferramenta Microsoft 365 com conector | Uma ligação para esse conector e qualquer licença específica de conector exigida para o utilizador com entrada. | Adicione a ferramenta Work IQ ao seu agente |
Complete primeiro o fluxo de utilização do agente quando a sua organização já tiver uma ligação. Usa a configuração do tenant único apenas quando um administrador precisar de criar a primeira ligação.
Tip
Considera adicionar esta ferramenta usando uma caixa de ferramentas. Ao utilizar uma caixa de ferramentas, pode reutilizar a ferramenta entre agentes e runtimes, bem como centralizar a gestão de credenciais, versionamento e aplicação de políticas através de um endpoint MCP gerido. Veja o quickstart da caixa de ferramentas.
Suporte de utilização
| Suporte ao Microsoft Foundry | Python SDK | C# SDK | SDK de JavaScript | SDK de Java | API REST | Configuração básica do agente | Configuração padrão do agente |
|---|---|---|---|---|---|---|---|
| QI de trabalho | ✔️ | ✔️ | ✔️ | — | ✔️ | ✔️ | ✔️ |
Como funciona
-
O seu agente despacha uma chamada de ferramenta — Quando o modelo do agente identifica uma tarefa que requer Microsoft 365 dados, emite uma chamada de ferramenta para a ferramenta
work_iq_preview. - A Foundry encaminha o pedido para o Work IQ via A2A — a Foundry utiliza o protocolo Agent-to-Agent (A2A) para encaminhar a consulta em linguagem natural para o Work IQ como agente par. A autenticação utiliza On-Behalf-Of (OBO), para que o pedido seja executado no contexto do utilizador com sessão iniciada.
- Work IQ recupera e raciocina sobre dados M365 — O Work IQ consulta os emails, reuniões, ficheiros, conversas e outros sinais de Microsoft 365 do utilizador. Aplica compreensão semântica para sintetizar uma resposta fundamentada no contexto real de trabalho do utilizador, respeitando as permissões e etiquetas de sensibilidade do Microsoft 365 ao longo de todo o processo.
- O resultado é devolvido ao seu agente — o Work IQ devolve a resposta sintetizada à Foundry via A2A. O seu agente incorpora-a na sua resposta ao utilizador.
Liga-te ao QI do Trabalho
Adicione a ferramenta Work IQ ao seu agente
Usa o Foundry Toolkit para Visual Studio Code para adicionar o Work IQ como ferramenta incorporada quando criares uma toolbox, e depois liga o teu agente ao endpoint da toolbox publicado. A caixa de ferramentas expõe as opções selecionadas do Work IQ através do seu endpoint MCP.
- Selecione Foundry Toolkit na barra de atividades.
- Na secção Meus Recursos, expanda o nome> do seuprojeto Ferramentas.
- Selecione o ícone + Adicionar Caixa de Ferramentas .
- No separador Criar uma Caixa de Ferramentas Personalizada, introduza o nome e a descrição da caixa de ferramentas.
- Seleciona Adicionar ferramentas e depois seleciona Work IQ.
- Em Add the Work IQ Tool, seleciona os dados Microsoft 365 Copilot que queres usar. O Work IQ Chat liga-se através de um endpoint A2A. Outras opções ligam-se através dos endpoints MCP, incluindo Copilot Chat, Teams, Word, Outlook Calendar, Outlook Mail, perfil de utilizador do Microsoft 365, SharePoint e OneDrive.
- Para cada opção selecionada, escolha uma ligação existente ou selecione Criar nova ligação.
- Selecione Adicionar.
- Selecione Publicar.
Para o fluxo de trabalho completo para criar a caixa de ferramentas, consulte Criar uma caixa de ferramentas baseada em intenções no Foundry.
Para adicionar a ferramenta Work IQ através de uma caixa de ferramentas usando código ou a API REST, selecione o separador Python, .NET, JavaScript ou REST API nesta secção.
Instale o pacote:
pip install "azure-ai-projects>=2.3.0"
Defina as seguintes variáveis de ambiente:
-
FOUNDRY_PROJECT_ENDPOINT— o ponto de extremidade do seu projeto, encontrado na página Descrição geral do seu projeto Foundry. -
WORK_IQ_PROJECT_CONNECTION_ID— o identificador de recurso totalmente qualificado da ligação ao projeto Work IQ.
Selecione Prompt Agents para usar o Azure AI Projects SDK para criar um agente de prompts do lado do servidor, ou Hosted Agents para usar o Microsoft Agent Framework para construir um agente efémero em processo que se liga à ferramenta através de uma caixa de ferramentas.
Agentes de comando
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")
Resultado esperado: O agente chama o Work IQ com a consulta do utilizador. O Work IQ recupera e sintetiza o conteúdo relevante do utilizador para Microsoft 365, baseado nas suas permissões, e devolve a resposta.
Agentes alojados
Crie uma versão da caixa de ferramentas com WorkIQPreviewToolboxTool. O tipo específico da caixa de ferramentas é diferente de WorkIQPreviewTool, que adiciona Work IQ diretamente a um agente de prompts.
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}")
O exemplo devolve a nova versão da caixa de ferramentas:
Created toolbox: work-iq-toolbox, version: <version>
De seguida, liga a caixa de ferramentas a um agente alojado. Esse fluxo de trabalho utiliza a integração em tempo de execução alojada para preservar o contexto de pedido necessário para chamadas Work IQ delegadas pelo utilizador. Para uma implementação completa em Python, consulte o exemplo de atividade Agent Framework Teams.
A forma recomendada de adicionar o Work IQ é através de uma caixa de ferramentas e depois associar a caixa de ferramentas ao seu agente como uma ferramenta MCP. Veja O que é uma caixa de ferramentas?
Passo 1: Crie uma caixa de ferramentas que contenha a ferramenta 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}"
}
]
}'
A caixa de ferramentas expõe um endpoint compatível com MCP em {project_endpoint}/toolboxes/work-iq-toolbox/versions/<version>/mcp?api-version=v1, onde <version> é a versão devolvida pela chamada anterior.
Passo 2: Crie uma ligação remota a um projeto de ferramenta que aponte para o endpoint da caixa de ferramentas, usando um token Entra de utilizador para que a identidade do chamador seja passada (audiência 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
Passo 3: Crie o agente com a caixa de ferramentas anexada como ferramenta 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"
}
]
}
Passo 4: Crie uma sessão de conversa:
POST {project_endpoint}/openai/v1/conversations
Authorization: Bearer {token}
Content-Type: application/json
{}
A resposta inclui um id campo. Usa-o no passo seguinte.
Passo 5: Envie um pedido ao 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}"
}
}
A resposta inclui metadados sobre a execução do agente e um campo text em content com a resposta sintetizada.
Note
Use o âmbito do token https://ai.azure.com/.default ao obter o token de portador.
Selecione Prompt Agents para usar o Azure AI Projects SDK para criar um agente de prompts do lado do servidor, ou Hosted Agents para usar o Microsoft Agent Framework para construir um agente efémero em processo que se liga à ferramenta através de uma caixa de ferramentas.
Agentes de comando
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);
Agentes alojados
Crie uma versão da caixa de ferramentas com WorkIQPreviewToolboxTool. O tipo específico da caixa de ferramentas é diferente de WorkIQPreviewTool, que adiciona Work IQ diretamente a um agente de prompts.
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}");
O exemplo devolve a nova versão da caixa de ferramentas:
Created toolbox: work-iq-toolbox, version: <version>
De seguida, liga a caixa de ferramentas a um agente alojado. Para uma implementação completa em C# que regista ferramentas do Work IQ com o Agent Framework, consulte a amostra de atividade do 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);
});
Adicione o Work IQ a uma caixa de ferramentas com o Azure Developer CLI
Usa a CLI do Azure Developer para criar a ligação ao projeto Work IQ A2A, depois referencia-a a partir de um YAML da caixa de ferramentas mínima.
# 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
Este artigo utiliza o endpoint https://workiq.svc.cloud.microsoft/a2a/Work IQ A2A. O catálogo anterior da toolbox usado https://agent365.svc.cloud.microsoft/agents/agents/workiq para o seu fluxo de trabalho azd; verifica o endpoint se a tua ligação Work IQ usa um alvo A2A ou MCP diferente.
# Step 2. Define the toolbox (my-toolbox.yaml)
description: Work IQ toolbox
tools:
- type: work_iq_preview
project_connection_id: my-workiq-conn
# Step 3. Create the toolbox
azd ai toolbox create my-toolbox --from-file my-toolbox.yaml
Use o Work IQ com um agente hospedado
Depois de criar work-iq-toolbox, use uma caixa de ferramentas com um agente hospedado para o ligar ao Agent Framework, execute-o localmente e implemente-o no Foundry Agent Service. A integração alojada preserva o contexto por pedido que o Work IQ precisa para agir em nome de cada utilizador iniciado sessão.
Para implementações de ponta a ponta, utilize a amostra de atividade mantida do Python Teams ou a amostra de atividade do .NET Teams.
Autenticação e segurança
O Work IQ utiliza autenticação delegada pelo Microsoft Entra ID. Todos os pedidos são executados no contexto do utilizador com sessão iniciada. A autenticação apenas por aplicação (apenas por app) não é suportada. As permissões do Microsoft 365 são aplicadas automaticamente — Os agentes do Work IQ nunca podem aceder a dados que o utilizador iniciado não esteja autorizado a ver.
Apenas a aplicação Bring your own Entra (autenticação On-Behalf-Of) é suportada para ligações Work IQ. Isto dá ao seu administrador do Entra controlo explícito sobre que aplicações podem recuperar dados do Microsoft 365 através do Work IQ: o administrador analisa e concede a permissão WorkIQAgent.Ask especificamente para a sua aplicação registada.
Configure a sua aplicação Entra (uma única vez, por organização)
Um administrador do Entra deve completar a seguinte operação de inquilino único antes de poder criar uma ligação Work IQ no Foundry. Para passos que requerem o papel de Administrador Global, use o Microsoft Entra PIM para ativar o papel a tempo e desative-o quando a configuração estiver concluída. Os utilizadores do Work IQ no dia a dia não precisam deste cargo.
Provisão do principal do serviço Work IQ (pontual)
Antes de criar o registo da aplicação, um Administrador Global deve provisionar o principal do serviço Work IQ como parte desta operação única de inquilino. Se saltar este passo, a opção Work IQ não aparecerá quando pesquisar permissões da API.
Siga o Passo 1: Criar o principal de serviço do Work IQ no início rápido da API do Work IQ. Uma resposta 201 de criação do Graph Explorer confirma que a operação foi bem-sucedida. Um erro de conflito significa que o principal já existe — continue para o passo seguinte.
Criar o registo de aplicações
Vai ao centro de administração Microsoft Entra. Na navegação à esquerda, selecione Entra ID>Registos de aplicações.
Selecione Novo registo. Dê à aplicação um nome descritivo e defina os tipos de conta suportados apenas como Contas neste diretório organizacional. Selecione Registar.
Copie o ID da Aplicação (cliente). Precisa deste valor ao criar a ligação Foundry.
Selecione >APIs que minha organização usa. Procure por Work IQ (ID
fdcc1f02-fc51-4226-8753-f668596af7f7da aplicação), selecione Permissões Delegadas, selecione WorkIQAgent.Ask e depois selecione Adicionar permissões.Selecione Conceder consentimento do administrador para [o seu inquilino]. Veja o diálogo de confirmação e selecione Sim.
Importante
Conceder consentimento de administrador a nível de inquilino é uma operação única que requer o papel de Administrador Global no Microsoft Entra ID. Ative a função mesmo a tempo através do Microsoft Entra PIM e desative-a após conceder o consentimento. Os utilizadores do Work IQ no dia a dia não precisam deste cargo. Se não tiver esta função, peça ao Administrador Global da sua organização para completar este passo.
- Selecione Certificados e segredos>Novo segredo de cliente. Adicione uma descrição e um prazo de validade. Seleciona Adicionar e depois copia imediatamente o valor secreto – só aparece uma vez. Guarde o segredo no Azure Key Vault ou noutra loja secreta aprovada. Nunca comprometas o segredo no controlo de versão, nem o imprimas ou loges. Roda o segredo antes que expire.
- Copie o seu ID do Diretório (inquilino) da página de descrição geral do Microsoft Entra ID.
Preencha os valores da ligação ao Foundry
Em Microsoft Foundry, abra o seu projeto e vá a Settings>Connections>Nova ligação>Work IQ. Preencha os seguintes campos:
| Campo | Value |
|---|---|
| ID de Cliente | ID da aplicação (cliente) do passo 3 |
| Segredo do cliente | Valor do segredo do cliente do passo 6 |
| URL de autorização | https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize |
| Token URL | https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token |
| Atualizar URL | https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token |
| Escopos | api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask,offline_access |
Substitua {tenant-id} pelo identificador do seu Diretório (inquilino) obtido no passo 7. Selecione Guardar para criar a ligação.
Importante
Os campos de ligação não podem ser editados após a criação. Se introduzires valores incorretos, apaga a ligação e cria uma nova.
Adicione o URI de redirecionamento ao registo da sua aplicação
Depois de o Foundry criar a ligação, apresenta um URL de redirecionamento OAuth. Adicione este URL ao registo da sua aplicação:
- No centro de administração Microsoft Entra, vai a Entra ID>Registos de aplicações e seleciona a tua aplicação.
- Selecione Autenticação>Adicionar uma plataforma>Web.
- Em URIs de redirecionamento, cole o URL de redirecionamento OAuth a partir do Foundry.
- Selecione Configurar.
Crie a ligação com a API REST
Como alternativa ao portal Foundry, utilize a API do Azure Resource Manager para criar a ligação Work IQ de forma programática.
Passo 1: Adquirir um token
ARM_TOKEN=$(az account get-access-token \
--resource https://management.azure.com \
--query accessToken -o tsv)
Passo 2: Criar a ligação
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"
}
}
}'
Uma resposta bem-sucedida devolve HTTP 200 ou 201. O corpo de resposta inclui um properties.oauthRedirectUrl campo — use esse valor como URI de redirecionamento no registo da sua aplicação Entra ( veja Adicionar o URI de redirecionamento ao registo da sua aplicação).
Governação e conformidade de dados
O Work IQ reduz a obtenção de permissões contra o Microsoft 365. Um fluxo de trabalho do Foundry também pode enviar prompts e resultados recuperados para o processamento a jusante do Copilot e do Foundry, pelo que deve rever os limites e a configuração regional de cada serviço no caminho do pedido.
Residência dos dados
A recuperação do Microsoft 365 segue as permissões do seu inquilino e a configuração de residência. O processamento de ponta a ponta também depende da configuração de faturação do Copilot e da região do projeto Foundry. Para mais detalhes, consulte Microsoft 365 Copilot políticas de privacidade e tratamento de dados.
Privacidade e tratamento de dados
Consulte as políticas de privacidade e gestão de dados do Microsoft 365 Copilot e os requisitos de tratamento de dados do Foundry que se aplicam à sua implementação. Confirme o percurso completo do pedido com as suas equipas de privacidade e conformidade.
Controle de acesso e permissões
Projete a ligação de modo a que a recuperação utilize as permissões Microsoft 365 do utilizador iniciado. Teste o corte de permissões com utilizadores representativos e conteúdo restrito antes da implementação:
- O controlo de acesso baseado em funções, as etiquetas de sensibilidade e as barreiras de informação definidas no Microsoft 365 são respeitados.
Revisão de conformidade
Utilize os recursos de conformidade da Microsoft da sua organização para confirmar quais certificações e controlos se aplicam à implementação completa do Work IQ e do Foundry.
Gestão administrativa
Como administrador do Entra, controla quais as aplicações no seu tenant que podem aceder aos dados do Work IQ em nome dos utilizadores. As secções seguintes descrevem os principais controlos disponíveis para si.
Conceder ou revogar o consentimento do administrador
É necessário consentimento WorkIQAgent.Ask do administrador antes de qualquer utilizador da sua organização poder autenticar-se através da aplicação. Pode gerir o consentimento a qualquer momento:
- Conceder autorização: No Centro de administração do Microsoft Entra, aceda a Entra ID>Registos de aplicações> selecione a aplicação >Permissões de API. Selecione Conceder consentimento do administrador para [o seu inquilino].
-
Revogar consentimento: Na mesma página de permissões da API , selecione a
WorkIQAgent.Askpermissão e selecione Revogar consentimento de administrador. Os tokens existentes permanecem válidos até expirarem; Não podem ser emitidos novos tokens após a revogação.
Resolução de problemas
| Symptom | Causa provável | Resolução |
|---|---|---|
403 Forbidden |
A faturação não está ativada para a API do Work IQ, ou falta uma licença específica para conectores. | Ativar a faturação de créditos Copilot para chamadas API do Work IQ. Para ferramentas suportadas por conectores, confirme que o utilizador que chama cumpre os requisitos de licença desse conector. |
401 Unauthorized |
Incompatibilidade do destinatário do token | Certifique-se de que o token é emitido para api://workiq.svc.cloud.microsoft, e não para outro recurso. |
403 Forbidden com Required scopes = [...] |
Consentimento do administrador para WorkIQAgent.Ask não concedido |
Um administrador tem de conceder consentimento para o registo da aplicação. |
| O agente não obtém resposta nem resultado vazio | O conteúdo do Microsoft 365 não está disponível para o utilizador iniciado sessão ou não foi indexado. | Confirme as permissões de origem do utilizador e depois tente novamente após a indexação concluir. |
Principal does not have access to API/Operation |
A identidade do agente não tem a função de Utilizador do Foundry ao nível do projeto | Atribua Foundry User ao nível da conta e do projeto. |