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 permite a los usuarios crear experiencias personalizadas 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 (una evolución del kit de herramientas de Teams).

Nota:

El agente que se compila en este tutorial se dirige a usuarios con licencia Microsoft 365 Copilot. También puede crear agentes para Microsoft 365 Copilot Chat usuarios, con funcionalidades limitadas. Para obtener más información, consulte Funcionalidades del agente para usuarios de Microsoft 365.

Nota:

Los agentes declarativos basados en Microsoft 365 Copilot ahora se admiten en Word y PowerPoint.

Requisitos previos

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

Las siguientes opciones están disponibles para el entorno de desarrollo:

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

Los siguientes recursos son necesarios para completar los pasos descritos en este artículo:

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

Nota:

Las capturas de pantalla y las referencias a la interfaz de usuario del Kit de herramientas de agentes de Microsoft 365 (una evolución del kit de herramientas de Teams) de este documento se generaron con la versión más reciente, 6.0. Las versiones preliminares del kit de herramientas de agentes pueden diferir de la interfaz de usuario de este documento.

Debe estar familiarizado 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 con la dirección URL 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 lo 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.

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

El agente declarativo usará 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 se muestran al usuario para demostrar 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.

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

Los inicios de conversación actualizados estará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<TSites = [
       {
         url: "https://learn.microsoft.com",
       },
     ]>;
   }
   

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

   Nota:

   Si no se especifica la TSites matriz, todo el contenido web estará disponible para el agente.

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 web para generar sus respuestas después de volver a cargar la página.

Agregar contenido de OneDrive y SharePoint

La funcionalidad de OneDrive y 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<TItemsByUrl = [
       {
         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.
   • No especificar la TItemsByUrl matriz (o la matriz alternativa TItemsBySharePointIds ) hace que todo el contenido de OneDrive y SharePoint de la organización de Microsoft 365 que está disponible para el usuario que ha iniciado sesión esté disponible para el agente.

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<TUrls = [
       {
         url: "https://teams.microsoft.com/l/team/...",
       }
     ]>;
     // Omitted for brevity
   }
   

   Para obtener más información, vea Objeto de mensajes de 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 se especifica la TUrls matriz, todos los canales de Teams, los equipos, las reuniones, el chat 1:1 y los chats de grupo de la organización de Microsoft 365 que están disponibles para el usuario que ha iniciado sesión estarán disponibles para el agente.

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

El agente declarativo tiene acceso 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 Personas objeto.

2. 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<TFolders = [
       {
         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 TFolders 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.

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

El agente declarativo tiene la capacidad de 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 mediante 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.

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

Puede agregar 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<TConnections = [
       {
         connectionId: "policieslocal",
       }
     ]>;
     // Omitted for brevity
   }
   

   Para obtener más información, vea Copilot connectors object (Objeto de conectores de Copilot).

   Nota:

   Si no se especifica la TConnections matriz, el contenido de todos los conectores de Copilot de la organización de Microsoft 365 que están disponibles para el usuario que ha iniciado sesión estará disponible para el agente.

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 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 generador de agentes.

Pasos siguientes

Compilación de una acción con TypeSpec