Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Importante
Los elementos marcados (versión preliminar) de este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.
Work IQ es la capa de inteligencia que fundamenta a Microsoft 365 Copilot y a tus agentes en un contexto compartido en tiempo real dentro de toda la organización. Captura señales de correos electrónicos, reuniones, archivos, chats y sistemas empresariales, y aplica la comprensión semántica para que los agentes puedan razonar sobre los datos de trabajo y tomar medidas. Todas las solicitudes se ejecutan en el contexto del usuario que ha iniciado sesión y respetan los permisos Microsoft 365.
Conectas tu agente de Foundry a Work IQ a través del protocolo Agent-to-Agent (A2A). Su agente delega en Work IQ tareas en lenguaje natural como agente par —por ejemplo, "Resumir mis correos electrónicos recientes sobre Project Contoso"— y Work IQ se encarga de la recuperación, el razonamiento y la síntesis de respuestas a partir de los datos de Microsoft 365 del usuario.
Para obtener información sobre cómo optimizar el uso de herramientas, consulte procedimientos recomendados.
Advertencia
Al conectarse a Work IQ, es posible que se produzcan costos y datos que se envíen fuera del límite de cumplimiento de Azure y se procesen según los términos de servicio y las directivas de control de datos aplicables. Es su responsabilidad gestionar si sus datos se transferirán fuera de los límites geográficos y de cumplimiento normativo de su organización, así como cualquier implicación relacionada, y garantizar que se concedan los permisos, límites y aprobaciones adecuados.
Es responsable de revisar y probar cuidadosamente las aplicaciones que compile en el contexto de sus casos de uso específicos y de tomar todas las decisiones y personalizaciones adecuadas. Esto incluye implementar sus propias mitigaciones de IA responsables, como metaprompts, filtros de contenido u otros sistemas de seguridad, y garantizar que las aplicaciones cumplan los estándares de calidad, confiabilidad, seguridad y confiabilidad adecuados. Consulte la nota de transparencia del servicio Foundry Agent.
Prerequisites
Antes de comenzar, asegúrese de que tiene:
El requisito comercial para la conexión que use:
Ruta de acceso de conexión Tipo de requisito Requirement Work IQ API a través de A2A, REST o MCP Facturación basada en el uso Habilite la facturación con créditos de Copilot. Esta ruta de acceso no usa licencias de conector. Herramientas de Microsoft 365 respaldadas por conectores Licencias del conector Confirme los requisitos previos del conector seleccionado. Un conector puede requerir una licencia de Microsoft 365 Copilot para cada usuario que llama. Un proyecto Microsoft Foundry activo con un modelo implementado.
Azure roles de RBAC:
- Rol de usuario de Foundry en el proyecto Foundry para la identidad del desarrollador, la identidad en tiempo de ejecución del agente y cualquier identidad de usuario implicada en flujos de OAuth.
- Rol Administrador de proyectos de Foundry en el proyecto Foundry para crear una conexión de Foundry con el punto de conexión de Work IQ.
Un administrador global de Microsoft Entra que puede completar la configuración del inquilino de un solo uso mediante el aprovisionamiento de la entidad de servicio work IQ y la concesión de consentimiento del administrador para
WorkIQAgent.Ask. Active este rol justo a tiempo a través de Microsoft Entra Privileged Identity Management (PIM) y desactive este rol después de la instalación. Los usuarios de Work IQ de día a día no necesitan este rol.Foundry Toolkit: Instale Visual Studio Code y Foundry Toolkit para Visual Studio Code.
Desarrollo de JavaScript: use Node.js 22 o posterior e instale
@azure/ai-projects2.4.0 o posterior con@azure/identity.
Para llamadas A2A directas, Work IQ admite las versiones 1.0 y 0.3 del protocolo. Envíe A2A-Version: 1.0 para usar nombres de método v1. Si se omite el encabezado, el valor predeterminado es v0.3. Incluya metadatos de ubicación para las solicitudes que distinguen el tiempo y use la autenticación de usuario delegada.
Siga la asignación de dependencias de configuración.
Use este mapa para separar el flujo de uso del agente de las dependencias que un administrador completa una vez para la organización.
| Objetivo | Depende de | Continuar en |
|---|---|---|
| Adición de Work IQ a un agente y envío de una consulta | Una conexión existente de Work IQ, los permisos de Microsoft 365 del usuario que ha iniciado sesión y las licencias de facturación o conector que aparecen en los requisitos previos. | Incorporación de la herramienta Work IQ al agente |
| Creación de la primera conexión de Work IQ para la organización | La entidad de servicio work IQ, una aplicación Entra de un solo inquilino, el permiso delegado WorkIQAgent.Ask y el consentimiento del administrador para todo el inquilino. |
Configuración de la aplicación Entra |
| Uso de una herramienta de Microsoft 365 respaldada por conectores | Una conexión para ese conector y cualquier licencia específica del conector necesaria para el usuario que ha iniciado sesión. | Incorporación de la herramienta Work IQ al agente |
Complete primero el flujo de uso del agente cuando la organización ya tenga una conexión. Use la configuración de inquilino único solo cuando un administrador necesite crear la primera conexión.
Tip
Considere la posibilidad de agregar esta herramienta mediante un cuadro de herramientas. Mediante el uso de un cuadro de herramientas, puede reutilizar la herramienta entre agentes y entornos de ejecución, así como centralizar la administración de credenciales, el control de versiones y la aplicación de directivas a través de un punto de conexión de MCP administrado. Consulte el inicio rápido del cuadro de herramientas.
Soporte para el uso
| Soporte técnico de Microsoft Foundry | SDK de Python | C# SDK | SDK de JavaScript | SDK de Java | REST API | Configuración básica del agente | Configuración del agente estándar |
|---|---|---|---|---|---|---|---|
| Inteligencia laboral | ✔️ | ✔️ | ✔️ | — | ✔️ | ✔️ | ✔️ |
Cómo funciona
-
Su agente envía una llamada a la herramienta : cuando el modelo de agente identifica una tarea que requiere datos Microsoft 365, emite una llamada de herramienta a la herramienta
work_iq_preview. - Foundry enruta la solicitud a Work IQ a través de A2A : Foundry usa el protocolo Agent-to-Agent (A2A) para reenviar la consulta de lenguaje natural a Work IQ como agente del mismo nivel. La autenticación utiliza On-Behalf-Of (OBO) para que la solicitud se ejecute en el contexto del usuario que ha iniciado sesión.
- Work IQ recupera y analiza datos de M365 — Work IQ consulta los correos electrónicos, las reuniones, los archivos, los chats y otras señales de Microsoft 365 del usuario. Utiliza la comprensión semántica para sintetizar una respuesta basada en el contexto de trabajo real del usuario, respetando los permisos de Microsoft 365 y las etiquetas de confidencialidad en todo momento.
- El resultado se devuelve al agente : Work IQ devuelve la respuesta sintetizada a Foundry a través de A2A. El agente lo incorpora en su respuesta al usuario.
Conexión a Work IQ
Añadir la herramienta Work IQ al agente
Use Foundry Toolkit para Visual Studio Code para agregar Work IQ como una herramienta integrada al crear un cuadro de herramientas y, a continuación, conecte el agente al punto de conexión del cuadro de herramientas publicado. El cuadro de herramientas expone las opciones de Work IQ seleccionadas a través de su punto de conexión de MCP.
- Seleccione Foundry Toolkit en la barra de actividades.
- En Mis recursos, expanda El nombre> del proyectoHerramientas.
- Seleccione el icono + Agregar cuadro de herramientas .
- En la pestaña Crear un cuadro de herramientas personalizado , escriba el nombre y la descripción del cuadro de herramientas.
- Seleccione Añadir herramientas, y después seleccione Work IQ.
- En Agregar la herramienta Work IQ, seleccione los datos de Microsoft 365 Copilot que desea usar. Work IQ Chat se conecta a través de un punto de conexión de A2A. Otras opciones se conectan a través de puntos de conexión de MCP, como Copilot Chat, Teams, Word, calendario de Outlook, correo Outlook, perfil de usuario de Microsoft 365, SharePoint y OneDrive.
- Para cada opción seleccionada, elija una conexión existente o seleccione Crear nueva conexión.
- Selecciona Agregar.
- Seleccione Publicar.
Para consultar el flujo de trabajo completo de creación de la caja de herramientas, consulte Organizar una caja de herramientas basada en intenciones en Foundry.
Para agregar la herramienta Work IQ a través de un cuadro de herramientas mediante código o la API REST, seleccione la pestaña Python, .NET, JavaScript o API REST de esta sección.
Instala el paquete:
pip install "azure-ai-projects>=2.3.0"
Establezca estas variables de entorno:
-
FOUNDRY_PROJECT_ENDPOINT— el punto de conexión de tu proyecto, que se encuentra en la página de Información general de tu proyecto de Foundry. -
WORK_IQ_PROJECT_CONNECTION_ID: el identificador completo del recurso de la conexión del proyecto Work IQ.
Seleccione Preguntar agentes para usar el SDK de proyectos de IA de Azure para crear un agente de solicitud del lado servidor o agentes hospedados para usar el marco del agente de Microsoft para crear un agente efímero y en proceso que se conecte a la herramienta a través de un cuadro de herramientas.
Agentes rápidos
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")
Salida esperada: el agente llama a Work IQ con la consulta del usuario. Work IQ recupera y sintetiza el contenido de Microsoft 365 relevante del usuario, fundamentado en sus permisos, y devuelve la respuesta.
Agentes hospedados
Cree una versión del cuadro de herramientas con WorkIQPreviewToolboxTool. El tipo específico del cuadro de herramientas es diferente de WorkIQPreviewTool, que agrega Work IQ directamente a un agente de solicitud.
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}")
El ejemplo devuelve la nueva versión del cuadro de herramientas:
Created toolbox: work-iq-toolbox, version: <version>
A continuación, conecte el cuadro de herramientas a un agente hospedado. Ese flujo de trabajo usa la integración en tiempo de ejecución hospedada para conservar el contexto de solicitud necesario para las llamadas de Work IQ delegadas por el usuario. Para obtener una implementación completa de Python, consulte el ejemplo de actividad de Teams del marco de agente.
La manera recomendada de agregar Work IQ es a través de un cuadro de herramientas y, a continuación, adjuntar el cuadro de herramientas al agente como una herramienta MCP. Consulte ¿Qué es un cuadro de herramientas?
Paso 1: Cree un cuadro de herramientas que contenga la herramienta 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}"
}
]
}'
El cuadro de herramientas expone un punto de conexión compatible con MCP en {project_endpoint}/toolboxes/work-iq-toolbox/versions/<version>/mcp?api-version=v1, donde <version> es la versión devuelta por la llamada anterior.
Paso 2: Cree una conexión de proyecto de herramienta remota que apunte al punto de conexión del cuadro de herramientas mediante un token entra de usuario para que la identidad del autor de la llamada pase a través (audiencia 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
Paso 3: Cree el agente con el cuadro de herramientas adjunto como una herramienta 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"
}
]
}
Paso 4: Cree una sesión de conversación:
POST {project_endpoint}/openai/v1/conversations
Authorization: Bearer {token}
Content-Type: application/json
{}
La respuesta incluye un id campo. Úselo en el paso siguiente.
Paso 5: Envíe una solicitud al 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 respuesta incluye metadatos sobre la ejecución del agente y un text campo en content con la respuesta sintetizada.
Note
Use el ámbito del token https://ai.azure.com/.default al obtener el token de portador.
Seleccione Preguntar agentes para usar el SDK de proyectos de IA de Azure para crear un agente de solicitud del lado servidor o agentes hospedados para usar el marco del agente de Microsoft para crear un agente efímero y en proceso que se conecte a la herramienta a través de un cuadro de herramientas.
Agentes rápidos
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
Cree una versión del cuadro de herramientas con WorkIQPreviewToolboxTool. El tipo específico del cuadro de herramientas es diferente de WorkIQPreviewTool, que agrega Work IQ directamente a un agente de solicitud.
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}");
El ejemplo devuelve la nueva versión del cuadro de herramientas:
Created toolbox: work-iq-toolbox, version: <version>
A continuación, conecte el cuadro de herramientas a un agente hospedado. Para obtener una implementación completa de C# que registra las herramientas del cuadro de herramientas de Work IQ con Agent Framework, consulte el ejemplo de actividad de 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);
});
Adición de Work IQ a un cuadro de herramientas con la CLI para desarrolladores de Azure
Use la CLI de Azure Developer para crear la conexión del proyecto Work IQ A2A y, a continuación, haga referencia a ella desde un cuadro de herramientas mínimo yaML.
# Step 1. Create the Work IQ connection
azd ai connection create my-workiq-conn \
--kind remote-a2a \
--target https://workiq.svc.cloud.microsoft/a2a/ \
--auth-type oauth2 \
--authorization-url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize \
--token-url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token \
--client-id <oauth-client-id> \
--client-secret <oauth-client-secret> \
--scopes "api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask offline_access"
Note
En este artículo se usa el punto de conexión https://workiq.svc.cloud.microsoft/a2a/de Work IQ A2A . El catálogo de cuadros de herramientas anterior usado https://agent365.svc.cloud.microsoft/agents/agents/workiq para su flujo de trabajo azd; compruebe el punto de conexión si la conexión de Work IQ usa un destino A2A o 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
Uso de Work IQ con un agente hospedado
Después de crear work-iq-toolbox, siga Uso de un cuadro de herramientas con un agente hospedado para conectarlo a Agent Framework, ejecútelo localmente e impleméntelo en el servicio del agente Foundry. La integración hospedada conserva el contexto por solicitud que Work IQ necesita para actuar en nombre de cada usuario que ha iniciado sesión.
Para implementaciones de un extremo a otro, use el ejemplo de actividad de Teams mantenido Python o .NET ejemplo de actividad de Teams.
Autenticación y seguridad
Work IQ usa Microsoft Entra ID autenticación delegada. Todas las solicitudes se ejecutan en el contexto del usuario que ha iniciado sesión. No se admite la autenticación solo de aplicación (solo aplicación). Los permisos de Microsoft 365 se aplican automáticamente: los agentes de Work IQ nunca pueden acceder a datos que el usuario que ha iniciado sesión no tenga ya permiso para ver.
Solo se admite Traiga su propia aplicación de Entra (autenticación delegada) para las conexiones de Work IQ. Esto proporciona al administrador de Entra control explícito sobre qué aplicaciones pueden recuperar Microsoft 365 datos a través de Work IQ: los administradores revisan y conceden el permiso WorkIQAgent.Ask específicamente para la aplicación registrada.
Configuración de la aplicación Entra (una vez, por organización)
Un administrador de Entra debe completar la siguiente operación de inquilino único para poder crear una conexión de Work IQ en Foundry. Para conocer los pasos que requieren el rol de administrador global, use Microsoft Entra PIM para activar el rol just-in-time y desactivarlo cuando se complete la instalación. Los usuarios de Work IQ de día a día no necesitan este rol.
Aprovisionar la entidad de servicio de Work IQ (una sola vez)
Antes de crear el registro de la aplicación, un administrador global debe aprovisionar la entidad de servicio work IQ como parte de esta operación de inquilino único. Si omite este paso, la opción Work IQ no aparecerá cuando busque permisos de API.
Siga Paso 1: Crear la entidad de servicio de Work IQ en la guía de inicio rápido de la API de Work IQ. Una respuesta 201 Created de Graph Explorer confirma que la operación se ha realizado correctamente. Un error de conflicto significa que el principal ya existe; continúe con el siguiente paso.
Creación del registro de aplicaciones
Vaya al Centro de administración de Microsoft Entra. En el panel de navegación izquierdo, seleccione Entra ID>Registros de aplicaciones.
Seleccione Nuevo registro. Asigne a la aplicación un nombre descriptivo y establezca Tipos de cuenta admitidos en Solo las cuentas de este directorio organizativo. Seleccione Registrar.
Copie el identificador de aplicación (cliente). Necesitará este valor al crear la conexión de Foundry.
Seleccione Permisos de API>Agregar un permiso>API usadas en mi organización. Busque Work IQ (id.
fdcc1f02-fc51-4226-8753-f668596af7f7de aplicación), seleccione Permisos delegados, WorkIQAgent.Ask y, a continuación, seleccione Agregar permisos.Seleccione Conceder consentimiento de administrador para [su inquilino]. Revise el cuadro de diálogo de confirmación y seleccione Sí.
Importante
Conceder el consentimiento del administrador para todo el inquilino es una operación de inquilino única que requiere el rol administrador global en Microsoft Entra ID. Active el rol justo a tiempo a través de Microsoft Entra PIM y desactive el rol después de conceder el consentimiento. Los usuarios de Work IQ de día a día no necesitan este rol. Si no tiene este rol, pida al administrador global de su organización que complete este paso.
- Seleccione Certificados y secretos>Nuevo secreto de cliente. Agregue una descripción y una expiración. Seleccione Agregar y, a continuación, copie inmediatamente el valor secreto: solo se muestra una vez. Almacene el secreto en Azure Key Vault u otro almacén de secretos aprobado. Nunca confirme el secreto en el control de código fuente ni imprima ni registre el secreto. Gire el secreto antes de que expire.
- Copie su identificador de directorio (tenant) de la página de información general de Microsoft Entra ID.
Rellene los valores de conexión de Foundry.
En Microsoft Foundry, abra el proyecto y vaya a Settings>Connections>Nueva conexión>Work IQ. Rellene los campos siguientes:
| Campo | Value |
|---|---|
| Id de cliente | Identificador de la aplicación (cliente) del paso 3 |
| Secreto de cliente | Valor del secreto de cliente del paso 6 |
| Dirección URL de autorización | https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize |
| Token URL | https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token |
| Actualizar URL | https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token |
| Ámbitos | api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask,offline_access |
Reemplace {tenant-id} por su identificador del directorio (inquilino) del paso 7. Seleccione Guardar para crear la conexión.
Importante
Los campos de conexión no se pueden editar después de la creación. Si escribe valores incorrectos, elimine la conexión y cree una nueva.
Adición del URI de redirección al registro de la aplicación
Una vez que Foundry crea la conexión, muestra una dirección URL de redireccionamiento de OAuth. Agregue esta dirección URL al registro de la aplicación:
- En el Centro de administración Microsoft Entra, vaya a Entra ID>Registros de aplicaciones y seleccione la aplicación.
- Seleccione Autenticación>Agregar una plataforma>Web.
- En URI de redirección, pegue la dirección URL de redirección de OAuth de Foundry.
- Seleccione Configurar.
Creación de la conexión con la API REST
Como alternativa al portal de Foundry, use la API de Azure Resource Manager para crear la conexión work IQ mediante programación.
Paso 1: Adquisición de un token
ARM_TOKEN=$(az account get-access-token \
--resource https://management.azure.com \
--query accessToken -o tsv)
Paso 2: Creación de la conexión
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 respuesta correcta devuelve HTTP 200 o 201. El cuerpo de la respuesta incluye un properties.oauthRedirectUrl campo : use ese valor como URI de redirección en el registro de la aplicación Entra (consulte Agregar el URI de redirección al registro de la aplicación).
Gobernanza y cumplimiento de datos
La recuperación de recortes de permisos de IQ de work IQ en Microsoft 365. Un flujo de trabajo de Foundry también puede enviar mensajes y recuperar los resultados al procesamiento de Copilot de bajada y Foundry, por lo que revise los límites y la configuración regional de cada servicio en la ruta de acceso de solicitud.
Ubicación de almacenamiento de datos
Microsoft 365 recuperación sigue los permisos y la configuración de residencia del inquilino. El procesamiento de un extremo a otro también depende de la configuración de facturación de Copilot y la región del proyecto Foundry. Para obtener más información, consulte Microsoft 365 Copilot directivas de privacidad y control de datos.
Privacidad y control de datos
Revise las directivas de privacidad y control de datos de Microsoft 365 Copilot y los requisitos de control de datos de Foundry que se aplican a la implementación. Confirme la ruta de acceso de solicitud completa con los equipos de privacidad y cumplimiento.
Control de acceso y permisos
Diseñe la conexión para que la recuperación use los permisos de Microsoft 365 del usuario que ha iniciado sesión. Pruebe el recorte de permisos con usuarios representativos y contenido restringido antes de la implementación:
- Se respetan el control de acceso basado en rol, las etiquetas de confidencialidad y las barreras de información definidas en Microsoft 365.
Revisión de cumplimiento
Use los recursos de cumplimiento de Microsoft de su organización para confirmar qué certificaciones y controles se aplican a la implementación completa de Work IQ y Foundry.
Gestión de administradores
Como administrador de Entra, puede controlar qué aplicaciones del inquilino pueden acceder a los datos de Work IQ en nombre de los usuarios. En las secciones siguientes se describen los controles clave disponibles.
Concesión o revocación del consentimiento del administrador
Se requiere el consentimiento del administrador para WorkIQAgent.Ask antes de que cualquier usuario de su organización pueda autenticarse a través de la aplicación. Puede administrar el consentimiento en cualquier momento:
- Conceder consentimiento: en el centro de administración de Microsoft Entra, vaya a Entra ID>Registros de aplicaciones>, seleccione la aplicación >Permisos de API. Seleccione Conceder consentimiento de administrador para [su inquilino].
-
Revocar consentimiento: en la misma página permisos de API , seleccione el
WorkIQAgent.Askpermiso y seleccione Revocar consentimiento del administrador. Los tokens existentes permanecen válidos hasta que expiran; no se pueden emitir nuevos tokens después de la revocación.
Solución de problemas
| Síntoma | Causa probable | Resolution |
|---|---|---|
403 Forbidden |
La facturación no está habilitada para work IQ API o falta una licencia específica del conector. | Habilite la facturación de créditos Copilot para las llamadas API de WORK IQ. En el caso de las herramientas respaldadas por conectores, confirme que el usuario que realiza la llamada cumple los requisitos de licencia del conector. |
401 Unauthorized |
Error de discrepancia en el público del token | Asegúrese de que el token se emite para api://workiq.svc.cloud.microsoft, no para un recurso diferente. |
403 Forbidden con Required scopes = [...] |
No se ha concedido el consentimiento de administrador para WorkIQAgent.Ask |
Un administrador debe conceder consentimiento para el registro de la aplicación. |
| El agente no obtiene respuesta ni resultado vacío | Microsoft 365 contenido no está disponible para el usuario que ha iniciado sesión o no se ha indexado. | Confirme los permisos de origen del usuario y vuelva a intentarlo una vez completada la indexación. |
Principal does not have access to API/Operation |
Falta el rol de usuario de Foundry en la identidad del agente en el ámbito del proyecto | Asigne Usuario de Foundry tanto a nivel de cuenta como a nivel de proyecto. |