Crear agentes declarativos mediante Microsoft 365 Agents Toolkit y TypeSpec

Un agente declarativo proporciona una experiencia conversacional dirigida a un objetivo con tecnología de Microsoft 365 Copilot. Usted define su propósito, instrucciones, conocimiento y acciones. En esta guía se muestra cómo crear un agente declarativo mediante TypeSpec y Microsoft 365 Agents Toolkit.

Requisitos previos

• Un inquilino de Microsoft 365 donde puede cargar aplicaciones personalizadas. Se produce un error de aprovisionamiento si la carga de aplicaciones personalizadas no está habilitada. Para habilitar la carga de aplicaciones personalizadas, consulte Requisitos del kit de herramientas de agentes de Microsoft 365. Para conocer el entorno de desarrollo y las opciones de licencia, consulte el entorno de desarrollo de Copilot.

Para completar los pasos descritos en este artículo, necesita los siguientes recursos:

• Visual Studio Code
• Kit de herramientas de agentes de Microsoft 365 Extensión de Visual Studio Code

Familiarícese con los siguientes estándares y directrices para agentes declarativos para Microsoft 365 Copilot:

• Estándares de cumplimiento, rendimiento, seguridad y experiencia de usuario descritos en las directrices de validación de la tienda de Teams.

Crear un agente declarativo

Comience por crear un agente declarativo básico.

1. Abrir Visual Studio Code.

2. Seleccione Kit de herramientas de > agentes de Microsoft 365 para crear un nuevo agente o aplicación.

   

3. Seleccione Agente declarativo.

   

4. Seleccione Empezar con TypeSpec para que Microsoft 365 Copilot cree un agente declarativo básico.

5. Seleccione la carpeta predeterminada para almacenar la carpeta raíz del proyecto en la ubicación predeterminada.

6. Escriba My Agent como nombre de la aplicación y presione Entrar.

7. En la nueva ventana de Visual Studio Code que se abre, seleccione Kit de herramientas de agentes de Microsoft 365. En el panel Ciclo de vida , seleccione Aprovisionar.

   

Prueba del agente

1. Vaya a la aplicación Copilot en https://m365.cloud.microsoft/chat.

2. Junto al botón Nuevo chat, seleccione el icono del cajón de conversaciones.

3. Seleccione el agente declarativo Mi agente.

   

4. Escriba una pregunta para que su agente declarativo la vea en acción.

Agregar instrucciones

Las instrucciones cambian el comportamiento de un agente.

1. Abre el main.tsp archivo y reemplaza el @instructions decorador con el siguiente código.

   @instructions("""
     You are an expert at creating poems.
     Every time a user asks a question, you **must** turn the answer into a poem. The poem **must** not use the quote markdown and use regular text.
   """)
   

   El proceso de aprovisionamiento inserta el contenido de este decorador en la instructions propiedad en el manifiesto del agente. Para obtener más información, vea Objeto manifiesto de agente declarativo.

2. Seleccione Aprovisionar en el panel Ciclo de vida de Agents Toolkit.

El agente declarativo usa las instrucciones actualizadas después de volver a cargar la página.

Agregar iniciadores de conversación

Los iniciadores de conversación son sugerencias que Copilot muestra a los usuarios para mostrarles cómo pueden empezar a usar el agente declarativo.

1. Abre el main.tsp archivo y sustituye el decorador comentado @conversationStarter por el siguiente contenido:

   @conversationStarter(#{
     title: "Getting started",
     text: "How can I get started with Agents Toolkit?"
   })
   
   @conversationStarter(#{
     title: "Getting Help",
     text: "How can I get help with Agents Toolkit?"
   })
   

   Para obtener más información, consulte el objeto Iniciadores de conversación.

2. Seleccione Aprovisionar en el panel Ciclo de vida de Agents Toolkit.

Los iniciadores de conversación actualizados están disponibles en el agente declarativo después de actualizar la página.

Agregar contenido web

La funcionalidad de búsqueda web permite a los agentes usar el índice de búsqueda de Bing para responder a las indicaciones de los usuarios.

1. Abra el main.tsp archivo y agregue la WebSearch funcionalidad en el espacio de MyAgent nombres con el siguiente contenido.

   namespace MyAgent {
     op webSearch is AgentCapabilities.WebSearch<Sites = [
       {
         url: "https://learn.microsoft.com",
       },
     ]>;
   }
   

   Para obtener más información, vea Objeto de búsqueda web.

   Nota:

   Si no especifica la matriz, el agente podrá acceder a todo el Sites contenido web.

2. Seleccione Aprovisionar en el panel Ciclo de vida de Agents Toolkit.

El agente declarativo puede acceder al contenido web para generar sus respuestas después de volver a cargar la página.

Agregar contenido de OneDrive y SharePoint

La funcionalidad de SharePoint permite al agente usar contenido de OneDrive y SharePoint como conocimiento.

1. Abra el main.tsp archivo y agregue la funcionalidad en el espacio de MyAgent nombres con el siguiente valor, reemplazándolo https://contoso.sharepoint.com/sites/ProductSupport por una dirección URL del OneDriveAndSharePoint sitio de SharePoint en su organización de Microsoft 365.

   namespace MyAgent {
     // Omitted for brevity
     op od_sp is AgentCapabilities.OneDriveAndSharePoint<ItemsByUrl = [
       {
         url: "https://contoso.sharepoint.com/sites/ProductSupport"
       }
     ]>;
     // Omitted for brevity
   }
   

   Para obtener más información, vea OneDrive y un objeto de SharePoint.

   Nota:

   • Las direcciones URL deben ser la ruta de acceso completa a elementos de SharePoint (sitio, biblioteca de documentos, carpeta o archivo). Puede usar la opción "Copiar vínculo directo" en SharePoint para obtener la ruta completa de los archivos y carpetas. Haga clic con el botón derecho en el archivo o carpeta y seleccione Detalles. Vaya a Ruta y seleccione el icono de copia.
   • Si no especifica la matriz (o la matriz alternativaItemsBySharePointIds), el agente podrá acceder a todo el ItemsByUrl contenido de OneDrive y SharePoint de su organización de Microsoft 365 al que pueda acceder el usuario que ha iniciado sesión.

2. Seleccione Aprovisionar en el panel Ciclo de vida de Agents Toolkit.

El agente declarativo tiene acceso al contenido de OneDrive y SharePoint para generar sus respuestas después de volver a cargar la página.

Agregar mensajes de Teams

La funcionalidad de mensajes de Teams permite al agente usar los canales, el equipo y el chat de reunión de Teams como conocimiento.

1. Abra el main.tsp archivo y agregue la TeamsMessages funcionalidad en el espacio de MyAgent nombres con el siguiente valor, reemplazándolo https://teams.microsoft.com/l/team/... por una dirección URL de equipo o canal de Teams de su organización.

   namespace MyAgent {
     // Omitted for brevity
     op teamsMessages is AgentCapabilities.TeamsMessages<TeamsMessagesByUrl = [
       {
         url: "https://teams.microsoft.com/l/team/...",
       }
     ]>;
     // Omitted for brevity
   }
   

   Para obtener más información, vea Objeto de mensajes de Microsoft Teams.

   Nota:

   • La dirección URL de la url propiedad debe ser un vínculo bien formado a un chat de Teams, un equipo o un chat de reunión.
   • Si no especifica la TeamsMessagesByUrl matriz, el agente podrá acceder a todos los canales, equipos, reuniones, chats individuales y chats grupales de Teams de su organización de Microsoft 365 a los que pueda acceder el usuario autenticado.

2. Seleccione Aprovisionar en el panel Ciclo de vida de Agents Toolkit.

El agente declarativo puede acceder a los datos de Teams para generar sus respuestas después de volver a cargar la página.

Agregar información de personas

La funcionalidad de personas le permite definir el ámbito del agente para que responda a preguntas sobre las personas de una organización.

1. Abra el main.tsp archivo y agregue la People funcionalidad en el espacio de MyAgent nombres con el siguiente contenido.

   namespace MyAgent {
     // Omitted for brevity
     op people is AgentCapabilities.People;
     // Omitted for brevity
   }
   

   Para obtener más información, consulte el objeto People.

2. Seleccione Aprovisionar en el panel Ciclo de vida de Agents Toolkit.

El agente declarativo tiene acceso al conocimiento de las personas después de volver a cargar la página.

Agregar conocimiento de correo electrónico

La funcionalidad de correo electrónico permite limitar el ámbito del agente para que use el correo electrónico del buzón del usuario o un buzón compartido como origen de conocimiento.

1. Abra el main.tsp archivo y agregue la Email funcionalidad en el espacio de MyAgent nombres con el siguiente contenido.

   namespace MyAgent {
     // Omitted for brevity
     op email is AgentCapabilities.Email<Folders = [
       {
         folder_id: "Inbox",
       }
     ]>;
     // Omitted for brevity
   }
   

   Para obtener más información, vea Objeto de Email.

   Nota:

   • En este ejemplo se accede al usuario del buzón del agente. Para acceder a un buzón compartido en su lugar, agregue el conjunto de propiedades opcionales shared_mailbox a la dirección de correo electrónico del buzón compartido.
   • La Folders matriz limita el acceso del buzón a carpetas específicas. Para acceder a todo el buzón, omita la folders matriz.

2. Seleccione Aprovisionar en el panel Ciclo de vida de Agents Toolkit.

El agente declarativo tiene acceso al conocimiento del correo electrónico después de volver a cargar la página.

Agregar generador de imágenes

La capacidad del generador de imágenes permite a los agentes generar imágenes basándose en las indicaciones de los usuarios.

1. Abra el main.tsp archivo y agregue la GraphicArt funcionalidad en el espacio de MyAgent nombres con el siguiente contenido.

   namespace MyAgent {
     // Omitted for brevity
     op graphicArt is AgentCapabilities.GraphicArt;
     // Omitted for brevity
   }
   

   Para obtener más información, consulte Objeto de arte gráfico.

2. Seleccione Aprovisionar en el panel Ciclo de vida de Agents Toolkit.

El agente declarativo puede generar imágenes después de volver a cargar la página.

Agregar intérprete de código

La capacidad de intérprete de código es una herramienta avanzada diseñada para resolver tareas complejas a través del código Python.

1. Abra el main.tsp archivo y agregue la CodeInterpreter funcionalidad en el espacio de MyAgent nombres con el siguiente contenido.

   namespace MyAgent {
     // Omitted for brevity
     op codeInterpreter is AgentCapabilities.CodeInterpreter;
     // Omitted for brevity
   }
   

   Para obtener más información, consulte Objeto del intérprete de código.

2. Seleccione Aprovisionar en el panel Ciclo de vida de Agents Toolkit.

El agente declarativo tiene la capacidad de intérprete de código después de volver a cargar la página.

Agregar contenido de conectores de Copilot

Agregue los elementos ingeridos por un conector de Copilot al conocimiento disponible para el agente.

1. Abra el main.tsp archivo y agregue la GraphConnectors funcionalidad en el espacio de MyAgent nombres con el siguiente valor, reemplazándolo policieslocal por un identificador de conector de Copilot válido en su organización de Microsoft 365. Para obtener más información sobre cómo buscar identificadores de conector de Copilot, consulte Recuperar identificadores de funcionalidad para el manifiesto de agente declarativo.

   namespace MyAgent {
     // Omitted for brevity
     op copilotConnectors is AgentCapabilities.GraphConnectors<Connections = [
       {
         connectionId: "policieslocal",
       }
     ]>;
     // Omitted for brevity
   }
   

   Para obtener más información, consulte el objeto Conectores de Copilot.

   Nota:

   Si no especifica la Connections matriz, el agente obtiene contenido de todos los conectores de Copilot de su organización de Microsoft 365 a los que puede acceder el usuario que ha iniciado sesión.

2. Seleccione Aprovisionar en el panel Ciclo de vida de Agents Toolkit.

El agente declarativo puede acceder al contenido de los conectores de Copilot para generar sus respuestas después de volver a cargar la página.

Completado

Completó la guía del agente declarativo para Microsoft 365 Copilot. Ahora que ya está familiarizado con el uso de TypeSpec para crear un agente declarativo, puede obtener más información en los siguientes artículos.

• Aprenda a escribir instrucciones efectivas para su agente.
• Pruebe el agente con el modo de desarrollador para comprobar si Copilot Orchestrator selecciona los orígenes de conocimiento para usarlos en respuesta a indicaciones dadas. Para obtener más información, consulte Prueba y depuración de agentes en el Kit de herramientas de agentes de Microsoft 365 con el modo de desarrollador.
• Obtenga respuestas a las preguntas más frecuentes.
• Obtenga información sobre otras formas de crear agentes declarativos: sin código en Agent Builder o con poco código en Copilot Studio.

Pasos siguientes