Creación de agentes declarativos mediante Microsoft 365 Agents Toolkit y TypeSpec

Un agente declarativo es una versión personalizada de Microsoft 365 Copilot que los usuarios pueden personalizar declarando instrucciones, acciones y conocimientos específicos. En esta guía se muestra cómo crear un agente declarativo mediante TypeSpec y microsoft 365 Agents Toolkit.

Requisitos previos

Antes de empezar, asegúrese de que Microsoft 365 Copilot está disponible para su organización.

Para el entorno de desarrollo, use una de las siguientes opciones:

• Una organización de Espacio aislado de Microsoft 365 con Copilot (disponible en versión preliminar limitada mediante la pertenencia a TAP).
• Un entorno de producción de Microsoft 365 o Office 365 apto con una licencia de Microsoft 365 Copilot.

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

• Visual Studio Code
• Microsoft 365 Agents Toolkit Visual Studio Code extensión

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

• Estándares de cumplimiento, rendimiento, seguridad y experiencia del usuario que se describen en Las directrices de validación de la Tienda Teams.

Creación de un agente declarativo

Empiece por crear un agente declarativo básico.

1. Abrir Visual Studio Code.

2. Seleccione Microsoft 365 Agents Toolkit > Create a New Agent/App (Crear un nuevo agente o aplicación).

   

3. Seleccione Agente declarativo.

   

4. Seleccione Iniciar con TypeSpec para Microsoft 365 Copilot para crear un agente declarativo básico.

5. Seleccione 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 el agente declarativo la vea en acción.

Agregar instrucciones

Las instrucciones cambian el comportamiento de un agente.

1. Abra el main.tsp archivo y reemplace el @instructions decorador por el código siguiente.

   @instructions("""
     You are a declarative agent and were created with Team Toolkit. 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 contenido de este decorador se inserta en la instructions propiedad en el manifiesto del agente durante el aprovisionamiento. Para obtener más información, vea Objeto de manifiesto del agente declarativo.

1. Seleccione Aprovisionar en el panel Ciclo de vida del Kit de herramientas de agentes de Microsoft 365.

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

Incorporación de inicios de conversación

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

1. Abra el main.tsp archivo y reemplace 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, vea Objeto Conversation starters.

1. Seleccione Aprovisionar en el panel Ciclo de vida del Kit de herramientas de agentes de Microsoft 365.

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

Adición de contenido web

La funcionalidad de búsqueda web permite a los agentes usar el índice de búsqueda en Bing para responder a las solicitudes del usuario.

1. Abra el main.tsp archivo y agregue la WebSearch funcionalidad en el MyAgent espacio de 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 Sites matriz, el agente puede acceder a todo el contenido web.

2. Seleccione Aprovisionar en el panel Ciclo de vida del Kit de herramientas de agentes de Microsoft 365.

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 el contenido de OneDrive y SharePoint como conocimiento.

1. Abra el main.tsp archivo y agregue la OneDriveAndSharePoint funcionalidad en el MyAgent espacio de nombres con el siguiente valor, reemplazando https://contoso.sharepoint.com/sites/ProductSupport por una dirección URL del 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 objeto de SharePoint.

   Nota:

   • Las direcciones URL deben ser 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 de acceso completa o los archivos y carpetas. Haga clic con el botón derecho en el archivo o carpeta y seleccione Detalles. Vaya a Ruta de acceso y seleccione el icono de copia.
   • Si no especifica la ItemsByUrl matriz (o la matriz alternativa ItemsBySharePointIds ), el agente puede acceder a todo el contenido de OneDrive y SharePoint de la organización de Microsoft 365 al que el usuario que ha iniciado sesión puede acceder.

2. Seleccione Aprovisionar en el panel Ciclo de vida del Kit de herramientas de agentes de Microsoft 365.

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 reuniones de Teams como conocimiento.

1. Abra el main.tsp archivo y agregue la TeamsMessages funcionalidad en el MyAgent espacio de nombres con el siguiente valor, reemplazando https://teams.microsoft.com/l/team/... por un canal de Teams o una dirección URL de equipo 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 tener vínculos bien formados a un chat, equipo o chat de reunión de Teams.
   • Si no especifica la TeamsMessagesByUrl matriz, el agente puede acceder a todos los canales, equipos, reuniones, chats 1:1 y grupos de Teams de la organización de Microsoft 365 a los que el usuario autenticado puede acceder.

2. Seleccione Aprovisionar en el panel Ciclo de vida del Kit de herramientas de agentes de Microsoft 365.

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

Incorporación de conocimientos de personas

La funcionalidad de personas le permite limitar el agente para responder a preguntas sobre los usuarios de una organización.

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

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

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

1. Seleccione Aprovisionar en el panel Ciclo de vida del Kit de herramientas de agentes de Microsoft 365.

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

Incorporación de conocimientos de correo electrónico

La funcionalidad de correo electrónico le permite limitar el agente para usar 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 MyAgent espacio de 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 Email objeto .

   Nota:

   • En este ejemplo se accede al usuario del buzón del agente. Para acceder a un buzón compartido en su lugar, agregue la propiedad opcional shared_mailbox establecida en 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 de correo, omita la folders matriz.

2. Seleccione Aprovisionar en el panel Ciclo de vida del Kit de herramientas de agentes de Microsoft 365.

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 funcionalidad del generador de imágenes permite a los agentes generar imágenes en función de las solicitudes del usuario.

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

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

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

1. Seleccione Aprovisionar en el panel Ciclo de vida del Kit de herramientas de agentes de Microsoft 365.

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

Agregar intérprete de código

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

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

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

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

1. Seleccione Aprovisionar en el panel Ciclo de vida del Kit de herramientas de agentes de Microsoft 365.

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

Adición de contenido de conectores de Copilot

Agregue los elementos ingeridos por un conector copilot a los conocimientos disponibles para el agente.

1. Abra el main.tsp archivo y agregue la GraphConnectors funcionalidad en el MyAgent espacio de nombres con el siguiente valor, reemplazando policieslocal por un identificador de conector de Copilot válido en la organización de Microsoft 365. Para obtener más información sobre cómo buscar identificadores de conector de Copilot, consulte Recuperación de identificadores de funcionalidades 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, vea Copilot connectors object (Objeto de conectores de Copilot).

   Nota:

   Si no especifica la Connections matriz, el agente obtiene contenido de todos los conectores de Copilot de la 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 del Kit de herramientas de agentes de Microsoft 365.

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

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

• Obtenga información sobre cómo escribir instrucciones eficaces para el agente.
• Pruebe el agente con el modo de desarrollador de Copilot para comprobar si el orquestador copilot selecciona los orígenes de conocimiento para usarlos en respuesta a las indicaciones dadas.
• Obtenga respuestas a las preguntas más frecuentes.
• Obtenga información sobre un método alternativo de creación de agentes declarativos con Copilot Studio.

Pasos siguientes