Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Importante
Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.
Work IQ é a camada de inteligência que fundamenta Microsoft 365 Copilot e seus agentes em contexto compartilhado em tempo real em toda a sua organização. Ele captura sinais de emails, reuniões, arquivos, chats e sistemas de negócios e aplica a compreensão semântica para que os agentes possam raciocinar sobre dados de trabalho e tomar medidas. Todas as solicitações são executadas no contexto do usuário conectado e respeitam as permissões de Microsoft 365.
Conecte o agente do Foundry ao Work IQ por meio do protocolo Agente para Agente (A2A). Seu agente delega tarefas em linguagem natural ao Work IQ como agente par — por exemplo, "Resumir meus e-mails recentes sobre o Projeto Contoso" — e o Work IQ cuida da recuperação, do raciocínio e da síntese da resposta com base nos dados do usuário no Microsoft 365.
Para obter informações sobre como otimizar o uso da ferramenta, consulte as práticas recomendadas.
Warning
Ao se conectar ao IQ do Trabalho, você pode incorrer em custos e os dados podem ser enviados fora do limite de conformidade Azure e processados de acordo com os termos de serviço e as políticas de tratamento de dados aplicáveis. É sua responsabilidade gerenciar se seus dados fluirão fora dos limites geográficos e de conformidade da sua organização e quaisquer implicações relacionadas, e que as permissões, os limites e as aprovações apropriados sejam provisionados.
Você é responsável por examinar e testar cuidadosamente os aplicativos que cria no contexto de seus casos de uso específicos e tomar todas as decisões e personalizações apropriadas. Isso inclui implementar suas próprias mitigações de IA responsáveis, como metaprompts, filtros de conteúdo ou outros sistemas de segurança, e garantir que seus aplicativos atendam aos padrões adequados de qualidade, confiabilidade, segurança e confiabilidade. Consulte a nota de transparência do Foundry Agent Service.
Pré-requisitos
Antes de começar, verifique se você tem:
O requisito comercial para a conexão que você usa:
Caminho da conexão Tipo de requisito Requirement API de IQ de trabalho por meio de A2A, REST ou MCP Faturamento baseado no uso Habilitar a cobrança com Copilot Créditos. Esse caminho não usa o licenciamento do conector. Ferramentas de Microsoft 365 com backup do conector Licenciamento do conector Confirme os pré-requisitos do conector selecionado. Um conector pode exigir uma licença de Microsoft 365 Copilot para cada usuário de chamada. Um projeto ativo Microsoft Foundry com um modelo implantado.
Azure funções RBAC:
- Função Usuário do Foundry no projeto Foundry para a identidade do desenvolvedor, a identidade de runtime do agente e qualquer identidade do usuário envolvida em fluxos do OAuth.
- Função Gerente de Projetos do Foundry função no projeto do Foundry para criar uma conexão do Foundry com o ponto de extremidade do Work IQ.
Um administrador global do Microsoft Entra que pode concluir a configuração de locatário único provisionando a entidade de serviço de Qi de Trabalho e concedendo consentimento do administrador.
WorkIQAgent.AskAtive essa função bem a tempo por meio de Microsoft Entra Privileged Identity Management (PIM) e desative-a após a instalação. Os usuários de qi de trabalho diário não precisam dessa função.Foundry Toolkit: instale Visual Studio Code e Foundry Toolkit for Visual Studio Code.
Desenvolvimento do JavaScript: use Node.js 22 ou posterior e instale
@azure/ai-projects2.4.0 ou posterior com@azure/identity.
Para chamadas A2A diretas, o Work IQ dá suporte às versões de protocolo 1.0 e 0.3. Enviar A2A-Version: 1.0 para usar nomes de método v1. Omitindo o cabeçalho padrão para v0.3. Inclua metadados de localização para solicitações sensíveis ao tempo e use a autenticação delegada do usuário.
Siga o mapa de dependência de instalação
Use este mapa para separar o fluxo de uso do agente das dependências que um administrador conclui uma vez para a organização.
| Objetivo | Depende de | Continuar em |
|---|---|---|
| Adicionar o IQ do Trabalho a um agente e enviar uma consulta | Uma conexão de Qi de Trabalho existente, as permissões de Microsoft 365 do usuário conectado e o licenciamento de cobrança ou conector listado nos pré-requisitos. | Adicionar a ferramenta de qi de trabalho ao seu agente |
| Criar a primeira conexão de qi de trabalho para a organização | A entidade de serviço do Work IQ, um aplicativo Entra de locatário único, permissão delegada WorkIQAgent.Ask e consentimento do administrador em todo o locatário. |
Configurar seu aplicativo Entra |
| Usar uma ferramenta de Microsoft 365 com suporte de conector | Uma conexão para esse conector e qualquer licença específica do conector necessária para o usuário conectado. | Adicionar a ferramenta de qi de trabalho ao seu agente |
Conclua o fluxo de uso do agente primeiro quando sua organização já tiver uma conexão. Use a configuração de locatário único somente quando um administrador precisar criar a primeira conexão.
Dica
Considere adicionar essa ferramenta usando uma caixa de ferramentas. Usando uma caixa de ferramentas, você pode reutilizar a ferramenta entre agentes e runtimes, bem como centralizar o gerenciamento de credenciais, controle de versão e imposição de política por meio de um ponto de extremidade MCP gerenciado. Consulte o início rápido da caixa de ferramentas.
Suporte de uso
| Suporte ao Microsoft Foundry | SDK do Python | C# SDK | SDK para JavaScript | SDK do Java | API REST | Configuração básica do agente | Configuração do agente padrão |
|---|---|---|---|---|---|---|---|
| QI de trabalho | ✔️ | ✔️ | ✔️ | — | ✔️ | ✔️ | ✔️ |
Como funciona
-
Seu agente faz uma chamada de ferramenta — Quando o modelo do agente identifica uma tarefa que exige dados do Microsoft 365, ele faz uma chamada para a ferramenta
work_iq_preview. - Foundry encaminha a solicitação ao Work IQ via A2A — Foundry usa o protocolo Agent-to-Agent (A2A) para encaminhar a consulta em linguagem natural ao Work IQ como um agente par. A autenticação usa o OBO (On-Behalf-Of) para que a solicitação seja executada no contexto do usuário conectado.
- Work IQ recupera e raciocina com base em dados do M365 — O Work IQ consulta os e-mails, as reuniões, os arquivos, as conversas e outros sinais do Microsoft 365 do usuário. Ela aplica entendimento semântico para sintetizar uma resposta baseada no contexto real de trabalho do usuário, respeitando as permissões e os rótulos de confidencialidade do Microsoft 365 em todo o processo.
- O resultado é devolvido ao seu agente — o Work IQ retorna a resposta sintetizada ao Foundry via A2A. Seu agente o incorpora em sua resposta ao usuário.
Conectar-se ao IQ do Trabalho
Adicione a ferramenta Work IQ ao seu agente
Use Foundry Toolkit for Visual Studio Code para adicionar o Work IQ como uma ferramenta integrada ao criar uma caixa de ferramentas e, em seguida, conectar seu agente ao endpoint da caixa de ferramentas publicada. O kit de ferramentas disponibiliza as opções selecionadas do Work IQ em seu endpoint MCP.
- Selecione o Foundry Toolkit na Barra de Atividades.
- Em Meus Recursos, expanda o nome do projeto>Ferramentas.
- Selecione o ícone + Adicionar Caixa de Ferramentas .
- Na guia Criar uma Caixa de Ferramentas Personalizada , insira o nome e a descrição da caixa de ferramentas.
- Selecione Adicionar ferramentas e, em seguida, selecione Qi de Trabalho.
- Em Adicionar a ferramenta Work IQ, selecione os dados do Microsoft 365 Copilot que você deseja usar. O Work IQ Chat se conecta via um endpoint A2A. Outras opções se conectam por meio de endpoints MCP, incluindo Copilot Chat, Teams, Word, Calendário do Outlook, Email do Outlook, perfil de usuário do Microsoft 365, SharePoint e OneDrive.
- Para cada opção selecionada, escolha uma conexão existente ou selecione Criar nova conexão.
- Selecione Adicionar.
- Selecione Publicar.
Para ver o fluxo de trabalho completo de criação da caixa de ferramentas, consulte Organizar a caixa de ferramentas baseada em intenções no Foundry.
Para adicionar a ferramenta de Qi de Trabalho por meio de uma caixa de ferramentas usando o código ou a API REST, selecione a guia Python, .NET, JavaScript ou API REST nesta seção.
Instale o pacote:
pip install "azure-ai-projects>=2.3.0"
Defina as seguintes variáveis de ambiente:
-
FOUNDRY_PROJECT_ENDPOINT— o endpoint do seu projeto, encontrado na página Visão geral do seu projeto no Foundry. -
WORK_IQ_PROJECT_CONNECTION_ID– a ID totalmente qualificada do recurso da conexão do projeto Work IQ.
Selecione Agentes de Prompt para usar o SDK de projetos de IA Azure para criar um agente de prompt do lado do servidor ou Agentes Hospedados para usar o Microsoft Agent Framework para criar um agente efêmero em processo que se conecta à ferramenta por meio de uma caixa de ferramentas.
Agentes de prompt
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")
Saída esperada: O agente invoca o Work IQ usando a consulta do usuário. O Work IQ recupera e sintetiza o conteúdo relevante do Microsoft 365 do usuário, com base nas permissões dele, e retorna a resposta.
Agentes hospedados
Criar uma versão da caixa de ferramentas com WorkIQPreviewToolboxTool. O tipo específico da caixa de ferramentas é diferente do que adiciona o Qi de WorkIQPreviewToolTrabalho diretamente a um agente de 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}")
O exemplo retorna a nova versão da caixa de ferramentas:
Created toolbox: work-iq-toolbox, version: <version>
Em seguida, conecte a caixa de ferramentas a um agente hospedado. Esse fluxo de trabalho usa a integração de runtime hospedada para preservar o contexto de solicitação necessário para chamadas de Qi de Trabalho delegadas pelo usuário. Para obter uma implementação Python completa, consulte o exemplo de atividade do Agent Framework Teams.
A maneira recomendada de adicionar o IQ do Trabalho é por meio de uma caixa de ferramentas e, em seguida, anexar a caixa de ferramentas ao seu agente como uma ferramenta MCP. Veja o que é uma caixa de ferramentas?
Etapa 1: Crie uma caixa de ferramentas que contenha a ferramenta de Qi de Trabalho:
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 ponto de extremidade compatível com MCP em {project_endpoint}/toolboxes/work-iq-toolbox/versions/<version>/mcp?api-version=v1, onde <version> está a versão retornada pela chamada anterior.
Etapa 2: Crie uma conexão de projeto de ferramenta remota que aponte para o ponto de extremidade da caixa de ferramentas, usando um token entra do usuário 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
Etapa 3: Crie o agente com a caixa de ferramentas anexada como uma 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"
}
]
}
Etapa 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. Use-o na próxima etapa.
Etapa 5: Envie uma solicitação 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 escopo do token https://ai.azure.com/.default ao obter o token de portador.
Selecione Agentes de Prompt para usar o SDK de projetos de IA Azure para criar um agente de prompt do lado do servidor ou Agentes Hospedados para usar o Microsoft Agent Framework para criar um agente efêmero em processo que se conecta à ferramenta por meio de uma caixa de ferramentas.
Agentes de prompt
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 hospedados
Criar uma versão da caixa de ferramentas com WorkIQPreviewToolboxTool. O tipo específico da caixa de ferramentas é diferente do que adiciona o Qi de WorkIQPreviewToolTrabalho diretamente a um agente de 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}");
O exemplo retorna a nova versão da caixa de ferramentas:
Created toolbox: work-iq-toolbox, version: <version>
Em seguida, conecte a caixa de ferramentas a um agente hospedado. Para obter uma implementação completa do C# que registra ferramentas de caixa de ferramentas de Qi de Trabalho com o Agent Framework, consulte o exemplo 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);
});
Adicionar o IQ do Trabalho a uma caixa de ferramentas com a CLI do desenvolvedor do Azure
Use a CLI do desenvolvedor Azure para criar a conexão de projeto do IQ A2A de trabalho e, em seguida, referenciá-la a partir de um YAML de caixa de ferramentas mínimo.
# 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 usa o ponto de extremidade https://workiq.svc.cloud.microsoft/a2a/do Work IQ A2A. O catálogo de caixas de ferramentas anterior usado https://agent365.svc.cloud.microsoft/agents/agents/workiq para seu fluxo de trabalho azd; verifique o ponto de extremidade se sua conexão de Qi de Trabalho usa um destino 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
Usar o Work IQ com um agente hospedado
Depois de criar work-iq-toolbox, siga Usar uma caixa de ferramentas com um agente hospedado para conectá-la ao Agent Framework, executá-la localmente e implantá-la no Serviço do Foundry Agent. A integração hospedada preserva o contexto por solicitação que o IQ de Trabalho precisa para agir em nome de cada usuário conectado.
Para implementações de ponta a ponta, use o exemplo de atividade do teams Python mantido ou .NET exemplo de atividade do Teams.
Autenticação e segurança
O Work IQ usa autenticação delegada do Microsoft Entra ID. Todas as solicitações são executadas no contexto do usuário conectado. A autenticação somente aplicativo (app-only) não é compatível. As permissões do Microsoft 365 são aplicadas automaticamente — os agentes do Work IQ nunca podem acessar dados que o usuário autenticado já não esteja autorizado a ver.
Somente Traga o próprio aplicativo do Entra (autenticação em nome de) é compatível para conexões do Work IQ. Isso dá ao administrador do Entra controle explícito sobre quais aplicativos podem recuperar dados do Microsoft 365 por meio do Work IQ: o administrador revisa e concede a permissão WorkIQAgent.Ask especificamente para o seu aplicativo registrado.
Configurar seu aplicativo Entra (uma vez, por organização)
Um administrador do Entra deve concluir a seguinte operação de locatário único antes de criar uma conexão de Qi de Trabalho no Foundry. Para as etapas que exigem a função de Administrador Global, use Microsoft Entra PIM para ativar a função just-in-time e desative-a quando a instalação for concluída. Os usuários de qi de trabalho diário não precisam dessa função.
Provisionar a entidade de segurança do Work IQ (uma única vez)
Antes de criar o registro do aplicativo, um Administrador Global deve provisionar a entidade de serviço de Qi de Trabalho como parte desta operação de locatário único. Se você ignorar essa etapa, a opção de Qi de Trabalho não aparecerá quando você pesquisar permissões de API.
Siga Etapa 1: Criar a entidade de segurança de serviço do Work IQ no início rápido da API do Work IQ. Uma resposta criada 201 pelo Explorador de gráficos confirma o êxito. Um erro de conflito significa que a entidade de segurança já existe – avance à próxima etapa.
Criar o registro do aplicativo
Acesse o centro de administração do Microsoft Entra. Na navegação à esquerda, selecione Entra ID>Registros de aplicativo.
Selecione Novo registro. Dê ao aplicativo um nome descritivo e defina Tipos de conta com suporte para Contas somente neste diretório organizacional. Selecione Registrar.
Copie o ID da Aplicação (cliente). Você precisa desse valor ao criar a conexão Foundry.
Selecione Permissões de API>Adicionar uma permissão>APIs usadas por minha organização. Pesquise o IQ do Trabalho (ID
fdcc1f02-fc51-4226-8753-f668596af7f7do aplicativo), selecione Permissões delegadas, selecione WorkIQAgent.Ask e, em seguida, selecione Adicionar permissões.Selecione Conceder consentimento do administrador para [o seu inquilino]. Reveja a caixa de diálogo de confirmação e selecione Sim.
Importante
A concessão de consentimento do administrador em todo o locatário é uma operação de locatário única que requer a função de Administrador Global em Microsoft Entra ID. Ative a função bem a tempo por meio Microsoft Entra PIM e desative-a após a concessão de consentimento. Os usuários de qi de trabalho diário não precisam dessa função. Se você não tiver essa função, peça ao Administrador Global da sua organização para concluir esta etapa.
- Selecione Certificados e segredos>Novo segredo do cliente. Adicione uma descrição e uma expiração. Selecione Adicionar e, em seguida, copie imediatamente o valor secreto - ele só é mostrado uma vez. Armazene o segredo em Azure Key Vault ou em outro repositório de segredos aprovado. Nunca confirme o segredo no controle do código-fonte, imprima ou registre-o. Gire o segredo antes de expirar.
- Copie a ID do diretório (locatário) da página de visão geral Microsoft Entra ID.
Preencher os valores de conexão do Foundry
Em Microsoft Foundry, abra seu projeto e vá para Configurações>Conexões>Nova conexão>Work IQ. Preencha os seguintes campos:
| Campo | Valor |
|---|---|
| ID do cliente | ID do aplicativo (cliente) da etapa 3 |
| Segredo do cliente | Valor de segredo do cliente da etapa 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} pela sua ID de Diretório (locatário) obtida na etapa 7. Selecione Salvar para criar a conexão.
Importante
Os campos de conexão não podem ser editados após a criação. Se você inserir valores incorretos, exclua a conexão e crie uma nova.
Adicionar o URI de redirecionamento ao registro do aplicativo
Depois que o Foundry cria a conexão, ele exibe uma URL de redirecionamento OAuth. Adicione essa URL ao registro do aplicativo:
- No centro de administração do Microsoft Entra, vá para Entra ID>Registros de aplicativo e selecione seu aplicativo.
- Selecione Autenticação>Adicionar uma plataforma>Web.
- Em URIs de Redirecionamento, cole a URL de redirecionamento OAuth do Foundry.
- Selecione Configurar.
Criar a conexão com a API REST
Como alternativa ao portal Foundry, use a API do Azure Resource Manager para criar programaticamente a conexão do Work IQ.
Etapa 1: Adquirir um token
ARM_TOKEN=$(az account get-access-token \
--resource https://management.azure.com \
--query accessToken -o tsv)
Etapa 2: Criar a conexã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 retorna HTTP 200 ou 201. O corpo da resposta inclui um properties.oauthRedirectUrl campo – use esse valor como o URI de redirecionamento no registro do aplicativo Entra (consulte Adicionar o URI de redirecionamento ao registro do aplicativo).
Governança e conformidade de dados
Recuperação de permissões de qi de trabalho em Microsoft 365. Um fluxo de trabalho do Foundry também pode enviar prompts e resultados recuperados para Copilot downstream e processamento do Foundry, portanto, examine os limites e a configuração regional de cada serviço no caminho da solicitação.
Residência de dados
Microsoft 365 recuperação segue as permissões do locatário e a configuração de residência. O processamento de ponta a ponta também depende da configuração de cobrança do Copilot e da região do projeto foundry. Para obter detalhes, consulte Microsoft 365 Copilot políticas de privacidade e tratamento de dados.
Privacidade e manipulação de dados
Examine os Microsoft 365 Copilot políticas de privacidade e tratamento de dados e os requisitos de tratamento de dados do Foundry que se aplicam à sua implantação. Confirme o caminho de solicitação completo com suas equipes de privacidade e conformidade.
Controle de acesso e permissões
Projete a conexão para que a recuperação use as permissões de Microsoft 365 do usuário conectado. Corte de permissão de teste com usuários representativos e conteúdo restrito antes da implantação:
- O controle de acesso baseado em função, os rótulos de confidencialidade e as barreiras de informações definidas em Microsoft 365 são respeitadas.
Revisão de conformidade
Use os recursos de conformidade Microsoft da sua organização para confirmar quais certificações e controles se aplicam à implantação completa do IQ de Trabalho e do Foundry.
Gerenciamento de administração
Como administrador do Entra, você controla quais aplicativos em seu tenant podem acessar os dados do Work IQ em nome dos usuários. As seções a seguir descrevem os controles de chave disponíveis para você.
Conceder ou revogar o consentimento do administrador
O consentimento WorkIQAgent.Ask do administrador é necessário para que qualquer usuário em sua organização possa se autenticar por meio do aplicativo. Você pode gerenciar o consentimento a qualquer momento:
- Conceder consentimento: No centro de administração do Microsoft Entra, vá para Entra ID>Registros de aplicativo> e selecione o aplicativo >Permissões de API. Selecione Conceder consentimento do administrador para [o seu inquilino].
-
Revogar consentimento: na mesma página de permissões de API , selecione a
WorkIQAgent.Askpermissão e selecione Revogar consentimento do administrador. Os tokens existentes permanecem válidos até expirarem; nenhum novo token pode ser emitido após a revogação.
Troubleshooting
| Sintoma | Causa provável | Resolução |
|---|---|---|
403 Forbidden |
A cobrança não está habilitada para a API de Qi de Trabalho ou uma licença específica do conector está ausente. | Habilite a cobrança de créditos Copilot para chamadas à API de Qi de Trabalho. Para ferramentas com backup de conector, confirme se o usuário de chamada atende aos requisitos de licença desse conector. |
401 Unauthorized |
Incompatibilidade de destinatário do token | Verifique se o token seja emitido para api://workiq.svc.cloud.microsoft, não para um recurso diferente. |
403 Forbidden por Required scopes = [...] |
Consentimento do administrador para WorkIQAgent.Ask não concedido |
Um administrador deve conceder consentimento para o registro do aplicativo. |
| O agente não obtém nenhuma resposta ou resultado vazio | Microsoft 365 conteúdo não está disponível para o usuário conectado ou não foi indexado. | Confirme as permissões de origem do usuário e tente novamente após a conclusão da indexação. |
Principal does not have access to API/Operation |
Função de usuário do Foundry não encontrada na identidade do agente no escopo do projeto | Atribua Usuário do Foundry nos escopos de conta e projeto. |