Compartir a través de

Invocación de acciones de Microsoft Graph con kernel semántico

los complementos de agente de Microsoft 365 Copilot permiten que los agentes de motor personalizados creados con kernel semántico comprendan las solicitudes del usuario y usen de forma segura las acciones de Microsoft Graph API, como el envío de correos electrónicos, la recuperación de contactos, la creación de invitaciones de calendario y el acceso a archivos. Estos complementos cierran la brecha entre los modelos de lenguaje grande (LLM) y las API REST, lo que le permite exponer datos de Microsoft 365 a través de interacciones de lenguaje natural.

¿Qué son los complementos del agente de Copilot?

Los complementos del agente de Copilot son extensiones personalizadas con tecnología de inteligencia artificial que permiten interacciones de lenguaje natural con datos de Microsoft 365 mediante la exposición de funciones a través del kernel semántico y las API de Microsoft Graph. Los complementos del agente de Copilot incluyen una descripción de OpenAPI para una API (como Microsoft Graph) y un manifiesto de complemento. Kernel semántico, con la tecnología del modelo de lenguaje que elija, analiza la intención del usuario y determina qué complemento y operación de API se van a invocar. Esto permite la orquestación directa e inteligente de los datos de Microsoft 365.

Puede generar complementos de agente de Copilot mediante Kiota, una herramienta de línea de comandos que simplifica la creación de complementos. Para obtener más información sobre los manifiestos de complemento, consulte el esquema de manifiesto del complemento de API para Microsoft 365 Copilot.

Funcionamiento de los complementos del agente de Copilot

Para cargar o instalar complementos del agente de Copilot en kernel semántico, use el ImportPluginFromCopilotAgentPluginAsync método de extensión de la Microsoft.SemanticKernel.Plugins.OpenApi.Extensions biblioteca.

El método requiere las siguientes entradas:

  • Nombre de complemento
  • Ruta de acceso al directorio del complemento
  • Filtros de parámetros: estos filtros ayudan a identificar y cargar el complemento correcto en función de sus parámetros, estructura y el servicio específico de Microsoft 365 al que se dirige.

En el ejemplo siguiente se muestra el ImportPluginFromCopilotAgentPluginAsync método .

private async Task AddCopilotAgentPluginAsync(Kernel kernel, IConfigurationRoot configuration, string pluginName)
{
    var copilotAgentPluginParameters = new CopilotAgentPluginParameters
    {
        FunctionExecutionParameters = new()
        {
            {
                "https://graph.microsoft.com/v1.0",
                new OpenApiFunctionExecutionParameters(
                    authCallback: this._bearerAuthenticationProviderWithCancellationToken.AuthenticateRequestAsync,
                    enableDynamicOperationPayload: false,
                    enablePayloadNamespacing: true)
                {
                    ParameterFilter = s_restApiParameterFilter
                }
            },
            {
                "https://graph.microsoft.com/beta",
                new OpenApiFunctionExecutionParameters(
                    authCallback: this._bearerAuthenticationProviderWithCancellationToken.AuthenticateRequestAsync,
                    enableDynamicOperationPayload: false,
                    enablePayloadNamespacing: true)
                {
                    ParameterFilter = s_restApiParameterFilter
                }
            }
        }
    };

    try
    {
        KernelPlugin plugin = await kernel.ImportPluginFromCopilotAgentPluginAsync(
            pluginName,
            GetCopilotAgentManifestPath(pluginName),
            copilotAgentPluginParameters).ConfigureAwait(false);

        AnsiConsole.MarkupLine($"[bold green]{pluginName} loaded successfully.[/]");
    }
    catch (Exception ex)
    {
        AnsiConsole.MarkupLine("[red]Failed to load {pluginName}.[/]");
        kernel.LoggerFactory.CreateLogger("Plugin Creation").LogError(ex, "Plugin creation failed. Message: {0}", ex.Message);
        throw new AggregateException($"Plugin creation failed for {pluginName}", ex);
    }
}

Cuando kernel semántico procesa un mensaje de usuario, lo siguiente:

  • Coincide con la intención del símbolo del sistema con un complemento (como CalendarPlugin).
  • Genera la llamada de Microsoft Graph API adecuada.
  • Ejecuta la solicitud con autenticación delegada.
  • Devuelve el resultado como una respuesta de lenguaje natural.

Complementos precompilados del agente de Copilot para Microsoft Graph

Microsoft proporciona un conjunto de complementos de agente copilot precompilados que puede cargar en el proyecto:

  • ContactsPlugin : administre las entradas de la libreta de direcciones.
  • MessagesPlugin : interactúe con su bandeja de entrada.
  • CalendarPlugin : crear o enumerar reuniones.
  • DriveItemsPlugin : busque, lea y cargue archivos.
  • Complemento M365 Copilot (plugin de la API de recuperación): busque contenido de archivos de Microsoft 365 a través del índice semántico.

También puede crear complementos para otros servicios mediante Kiota y un archivo de descripción de OpenAPI.

Funcionalidades y ejemplos de complementos

En la tabla siguiente se proporcionan ejemplos de mensajes y los complementos del agente de Copilot que invocan.

Prompt Descripción Complemento invocado Resultado previsto Notas
¿Qué puede decirme de mi contacto? Recupera los detalles de contacto. ContactsPlugin Devuelve el perfil de contacto estructurado. Sugerencia: El prefijo con "mi contacto" mejora la precisión.
¿Tengo algún correo electrónico de mi compañero de trabajo? Busca correos electrónicos recientes en el buzón. MessagesPlugin Muestra asuntos de correo electrónico, marcas de tiempo y remitente. El nombre completo mejora la calidad de la coincidencia.
Enviar un correo electrónico a mi contacto... Redacta y envía un correo electrónico. MessagesPlugin Confirma que el envío se realizó correctamente. Nota: Los dominios externos pueden bloquear los envíos.
¿Qué reuniones tengo esta semana? Listas reuniones basadas en la semana actual. CalendarPlugin Devuelve los tiempos de evento y los asistentes. Se admiten fechas de lenguaje natural.
Cree un evento de calendario denominado Sync Meeting. Crea un nuevo evento de calendario. CalendarPlugin Confirma la creación con la hora de inicio y finalización. Los formatos de tiempo como "1500 a 1530 Eastern" funcionan.
Muéstreme en qué ha trabajado un usuario para el kernel semántico. Recupera los metadatos de contenido del archivo. Complemento Microsoft 365 Copilot Resume los detalles del documento. Requiere un archivo accesible (por ejemplo, OneDrive).
Consulte mi correo electrónico de mi administrador, resumalo y configure una reunión. Recupera el correo electrónico, resume y crea un evento. Varios complementos Confirma la configuración y el resumen de la reunión. Usa los complementos Contactos, Mensajes y Calendario.

Introducción a los complementos del agente de Copilot

Requisitos previos

Antes de empezar, asegúrese de que tiene:

Registro de la aplicación Microsoft Identity Platform

  1. Vaya a Azure Active Directory > Registros de aplicaciones > Nuevo registro.
  2. Rellene el nombre y los tipos de cuenta admitidos.
  3. Establezca el URI de redireccionamiento: http://localhost.
  4. Registre el identificador de aplicación (cliente) y el identificador de directorio (inquilino).

Configurar permisos

  1. Vaya a Permisos > de API Agregar un permiso.
  2. Elija Permisos delegados de Microsoft Graph > .
  3. Agregar: Contacts.Read, Mail.Read, , Files.ReadCalendars.Read.
  4. Seleccione Conceder consentimiento de administrador.

Configuración de secretos (si procede)

  1. Vaya a Certificados & secretos > Nuevo secreto de cliente.
  2. Copie el valor del secreto.

Actualización de la configuración de la aplicación

  1. Copie appsettings.json en appsettings.Development.json.
  2. Rellene: TenantId, ClientId, , ClientSecret, RedirectUri.
  3. Para OpenAI o Azure OpenAI: también establezca ApiKey, ModelId.

Ejecución de la aplicación

Opción 1: Ejecución de una aplicación de ejemplo

Puede ejecutar la aplicación de ejemplo, como se muestra en el ejemplo siguiente.

dotnet run demo
# or for debug mode:
dotnet run demo --debug

Siga las indicaciones para autenticarse, elija el LLM, seleccione complementos y ejecute consultas.

Opción 2: Integrar en su propia aplicación

Si va a integrar la funcionalidad del complemento del agente de Copilot en su propia aplicación .NET, debe configurar el proyecto con las bibliotecas adecuadas. Esto incluye ensamblados para la configuración, autenticación, registro y compatibilidad con complementos de Microsoft Graph y kernel semántico. Para asegurarse de que el proyecto se compila correctamente y tiene acceso a todas las características necesarias, agregue los siguientes paquetes NuGet necesarios.

dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Json 
dotnet add package Microsoft.Identity.Client 
dotnet add package Microsoft.Extensions.Logging 
dotnet add package Microsoft.SemanticKernel 
dotnet add package Microsoft.SemanticKernel.Plugins.Core 
dotnet add package Microsoft.SemanticKernel.Plugins.OpenApi 
dotnet add package Microsoft.SemanticKernel.Planners.OpenAI 
dotnet add package Microsoft.SemanticKernel.Plugins.MSGraph 
dotnet add package Microsoft.SemanticKernel.Plugins.OpenApi.Extensions

Contenido relacionado