Conexión de agentes a Microsoft 365 con Work IQ (versión preliminar)

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.

Soporte para el uso

Prerequisites

Antes de comenzar, asegúrese de que tiene:

• Licencia Microsoft 365 Copilot. Los usuarios que usan las herramientas de Work IQ a través de su agente también deben tener esta licencia.
• Un proyecto Microsoft Foundry activo con un modelo implementado.
• Roles RBAC de Azure:
  • 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 conceder el consentimiento del administrador para WorkIQAgent.Ask en su inquilino y crear o delegar registros de aplicaciones.
• Foundry Toolkit: Instale Visual Studio Code y Foundry Toolkit para Visual Studio Code.

Cómo funciona

1. 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.
2. 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.
3. 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.
4. 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

pip install "azure-ai-projects>=2.2.0" python-dotenv

import os
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WorkIQPreviewTool

load_dotenv()

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=os.environ["FOUNDRY_MODEL_NAME"],
            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")

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": "work_iq_preview",
      "project_connection_id": "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}/connections/{connection-name}"
    }
  ]
}

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

{}

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

using Azure.AI.Projects;
using Azure.Identity;

var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
var modelDeploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME");
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: modelDeploymentName)
{
    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);

const { DefaultAzureCredential } = require("@azure/identity");
const { AIProjectClient } = require("@azure/ai-projects");
require("dotenv/config");

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"];
const deploymentName = process.env["FOUNDRY_MODEL_NAME"];
const workIqProjectConnectionId = process.env["WORKIQ_CONNECTION_ID"];

async function main() {
  const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
  const openAIClient = project.getOpenAIClient();

  const tool = {
    type: "work_iq_preview",
    project_connection_id: workIqProjectConnectionId,
  };

  const agent = await project.agents.createVersion("MyWorkIQAgent", {
    kind: "prompt",
    model: deploymentName,
    instructions: "Use the available Work IQ tools to answer questions and perform tasks.",
    tools: [tool],
  });
  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 openAIClient.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);
});

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 los pasos siguientes para poder crear una conexión work IQ en Foundry.

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 principal de Work IQ en su inquilino. Si se 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

1. Vaya al Centro de administración de Microsoft Entra. En el panel de navegación izquierdo, seleccione Entra ID>Registros de aplicaciones.

2. 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.

3. Copie el identificador de aplicación (cliente). Necesitará este valor al crear la conexión de Foundry.

4. 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.

   

   

5. Seleccione Conceder consentimiento de administrador para [su inquilino]. Revise el cuadro de diálogo de confirmación y seleccione Sí.

   Importante

   Otorgar el consentimiento del administrador para todo el inquilino requiere el rol de Global Administrator en Microsoft Entra ID. Si no tiene este rol, pida al administrador global de su organización que complete este paso.

6. 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.

7. 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:

Reemplace {tenant-id} por su identificador del directorio (inquilino) del paso 7. Seleccione Guardar para crear la conexión.

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:

1. En el Centro de administración Microsoft Entra, vaya a Entra ID>Registros de aplicaciones y seleccione la aplicación.
2. Seleccione Autenticación>Agregar una plataforma>Web.
3. En URI de redirección, pegue la dirección URL de redirección de OAuth de Foundry.
4. 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

Work IQ funciona completamente dentro del límite de confianza de Microsoft 365. Los siguientes compromisos se aplican al enrutar las solicitudes del agente a través de Work IQ.

Ubicación de almacenamiento de datos

Work IQ recupera datos del inquilino de Microsoft 365 de su organización. Los datos no salen de su entorno ni cruzan los límites regionales durante la recuperación. La ubicación de los datos sigue la configuración de residencia de datos de su inquilino de Microsoft 365, no la región de su proyecto de Foundry. Para obtener más información, consulte Microsoft 365 Copilot directivas de privacidad y control de datos.

Privacidad y control de datos

Todas las solicitudes de Work IQ se rigen por las directivas de privacidad y control de datos Microsoft 365 Copilot. Compromisos clave:

• Work IQ no usa contenido de cliente para entrenar o mejorar los modelos de inteligencia artificial subyacentes.

Control de acceso y permisos

Work IQ aplica automáticamente los permisos de Microsoft 365 en cada solicitud. Los agentes solo pueden acceder a los datos que el usuario que ha iniciado sesión ya está autorizado para ver; no es posible realizar ninguna elevación de privilegios:

• Se respetan el control de acceso basado en rol, las etiquetas de confidencialidad y las barreras de información definidas en Microsoft 365.

Certificaciones de cumplimiento

Work IQ hereda las certificaciones de cumplimiento de Microsoft 365. Para obtener más información, consulte Microsoft 365 Copilot directivas de privacidad y control de datos.

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.Ask permiso 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

Contenido relacionado

• Introducción a work IQ API (versión preliminar)
• Inicio rápido de Work IQ API (versión preliminar)
• Conexión a un punto de conexión del agente de A2A desde Foundry Agent Service