Creación de un agente de motor personalizado mediante la biblioteca de inteligencia artificial de Teams y el kit de herramientas de Teams
Puede crear un agente de motor personalizado para Microsoft Teams para obtener un control preciso sobre las operaciones ligeras. Esto muestra la eficacia del modelo de lenguaje para comprender y ejecutar con precisión la intención del usuario y alinearlo con las acciones de la aplicación.
En este tutorial, aprenderá lo siguiente:
- Cómo configurar un nuevo proyecto con Teams Toolkit.
- Cómo importar las funcionalidades de la biblioteca de IA de Teams.
- Cómo implementar el agente de motor personalizado en Teams y controlar las operaciones ligeras.
Puede ver la siguiente salida:
Requisitos previos
Esta es una lista de herramientas que necesita para compilar e implementar el agente de motor personalizado.
| Instalar | Para usar... | |
|---|---|---|
| Kit de herramientas de Teams | Microsoft Visual Studio Code extensión que crea un scaffolding de proyecto para la aplicación. Use la versión más reciente. | |
| Microsoft Teams | Para colaborar con todos, trabaja con aplicaciones para chat, reuniones y llamadas a todo en un solo lugar. | |
| Node.js | Entorno de tiempo de ejecución de JavaScript de back-end. Para obtener más información, vea Node.js tabla de compatibilidad de versiones para el tipo de proyecto. | |
| Microsoft Edge (recomendado) o Google Chrome | Un explorador con herramientas de desarrollo. | |
| Visual Studio Code | Entornos de compilación de JavaScript, TypeScript y Python. Use la versión más reciente. | |
| OpenAI o Azure OpenAI | En primer lugar, cree la clave de API de OpenAI para usar la GPT de OpenAI. Si desea hospedar la aplicación o acceder a los recursos en Microsoft Azure, debe crear un servicio Azure OpenAI antes de empezar. | |
| Cuenta de desarrollador de Microsoft 365 | Acceso a la cuenta de Teams con los permisos adecuados para instalar una aplicación. |
Preparación del entorno de desarrollo
Después de instalar las herramientas necesarias, configure el entorno de desarrollo.
Instalación del kit de herramientas de Teams
Teams Toolkit ayuda a simplificar el proceso de desarrollo con herramientas para aprovisionar e implementar recursos en la nube para la aplicación, publicar en la Tienda Teams y mucho más.
Puede usar el kit de herramientas con Visual Studio Code.
También puede usar la CLI (interfaz de línea de comandos), denominada teamsapp.
Abra Visual Studio Code y seleccione la vista Extensiones (Ctrl+Mayús+X / ⌘⇧-X o Ver > extensiones).
En el cuadro de búsqueda, escriba Kit de herramientas de Teams.
Seleccione Instalar junto al kit de herramientas de Teams.
El icono del kit de herramientas de Teams aparece en la barra de actividad de Visual Studio Code después de instalarlo.
También puede encontrar el kit de herramientas de Teams en Visual Studio Code Marketplace.
Configuración del inquilino de desarrollo de Teams
Un inquilino es como un espacio o un contenedor para su organización en Teams, donde chatea, comparte archivos y ejecuta reuniones. Este espacio también es donde carga y prueba la aplicación personalizada. Vamos a comprobar si está listo para desarrollar con el inquilino.
Comprobación de la opción de carga de aplicaciones personalizadas
Después de crear la aplicación, debe cargarla en Teams sin distribuirla. Este proceso se conoce como carga de aplicaciones personalizada. Inicie sesión en su cuenta de Microsoft 365 para ver esta opción.
Nota:
La carga de aplicaciones personalizada es necesaria para obtener una vista previa y probar aplicaciones en el entorno local de Teams. Si no está habilitada, no puede obtener una vista previa y probar la aplicación en el entorno local de Teams.
¿Ya tiene un inquilino y tiene acceso de administrador? ¡Vamos a comprobar si realmente lo haces!
Compruebe si puede cargar una aplicación personalizada en Teams:
En el cliente de Teams, seleccione el icono Aplicaciones .
Seleccione Administrar las aplicaciones.
Seleccione Cargar una aplicación.
Busque la opción Cargar una aplicación personalizada. Si ve la opción , la carga de aplicaciones personalizada está habilitada.
Nota:
Póngase en contacto con el administrador de Teams si no encuentra la opción de cargar una aplicación personalizada.
Creación de un inquilino para desarrolladores de Teams gratuito (opcional)
Si no tiene una cuenta de desarrollador de Teams, puede obtenerla de forma gratuita. ¡Únete al programa para desarrolladores de Microsoft 365!
Seleccione Unirse ahora y siga las instrucciones en pantalla.
En la pantalla de bienvenida, seleccione Configurar suscripción A5.
Configure su cuenta de administrador. Cuando haya terminado, aparecerá la siguiente pantalla.
Inicie sesión en Teams con la cuenta de administrador que acaba de configurar. Compruebe que tiene la opción Cargar una aplicación personalizada en Teams.
Obtener una cuenta gratuita de Azure
Si desea hospedar la aplicación o acceder a los recursos en Azure, debe tener una suscripción a Azure. Cree una cuenta gratuita antes de empezar.
Ahora tiene todas las herramientas para configurar su cuenta. El entorno de desarrollo está listo para empezar a compilar el proyecto de aplicación.
Creación del área de trabajo del proyecto para la aplicación de agente de motor personalizada
Vamos a crear la primera aplicación de agente de motor personalizada.
La funcionalidad del agente del motor personalizado de una aplicación de Teams crea un bot de chat de IA. Se usa para ejecutar tareas sencillas y automatizadas, por ejemplo, proporcionar servicio al cliente. Un agente de motor personalizado habla con un servicio web y le ayuda a usar sus ofertas. Puede obtener la previsión meteorológica, realizar reservas o cualquier otro servicio ofrecido mediante el agente de motor personalizado.
Como ya ha preparado para crear la aplicación o el agente de motor personalizado, puede configurar un nuevo proyecto de Teams para crear el agente de motor personalizado.
En este tutorial, aprenderá lo siguiente:
- Cómo configurar un nuevo proyecto de agente de motor personalizado con Teams Toolkit.
- Acerca de la estructura de directorios del proyecto de aplicación.
Creación del área de trabajo del proyecto del agente de motor personalizado
Si se cumplen los requisitos previos, comencemos.
Abrir Visual Studio Code.
Seleccione el icono Kit de herramientas de
Teams en la barra de actividad de Visual Studio Code.Seleccione Crear una nueva aplicación.
Seleccione Agente de motor personalizado.
Seleccione Bot de chat de IA básica.
Seleccione TypeScript como lenguaje de programación.
Seleccione OpenAI o Azure OpenAI.
Escriba la clave OpenAI o la clave de Azure OpenAI y el punto de conexión de Azure OpenAI.
Seleccione Carpeta predeterminada para almacenar la carpeta raíz del proyecto en la ubicación predeterminada.
También puede cambiar la ubicación predeterminada mediante los pasos siguientes:
Seleccione Examinar.
Seleccione la ubicación del área de trabajo del proyecto.
Seleccione seleccionar carpeta.
Escriba un nombre adecuado para la aplicación y, a continuación, seleccione Entrar.
Aparece un cuadro de diálogo. Seleccione Sí, Confío en los autores o No, no confío en los autores según sus necesidades.
El agente de motor personalizado se crea en unos segundos.
Una vez creada la aplicación, el kit de herramientas de Teams muestra el siguiente mensaje:
Resumen rápido de la creación de una aplicación de Teams.
Vea este breve resumen para crear una aplicación de Teams.
Realice un recorrido por el código fuente de la aplicación.
Una vez realizado el scaffolding, vea los directorios y archivos del proyecto en el área Explorador de Visual Studio Code.
| Nombre de la carpeta | Contenido |
|---|---|
env/.env.local.user |
Archivo de configuración para el entorno local utilizado por teamsapp.yml para personalizar las reglas de aprovisionamiento e implementación. |
index.ts |
Punto de entrada principal de la aplicación. |
teamsBot.ts |
Controlador de actividad de Teams. |
appPackage |
Archivos de plantilla de manifiesto de aplicación e iconos de aplicación (color.png y outline.png). |
appPackage/manifest.json |
Manifiesto de aplicación para ejecutar la aplicación en un entorno local y remoto. |
config.ts |
config.ts ajusta el acceso a las variables de entorno que se usan para configurar el adaptador de bots. |
teamsapp.yml |
Este es el proyecto principal del kit de herramientas de Teams que define las propiedades y las definiciones de la fase de configuración. |
teamsapp.local.yml |
Esto invalida teamsapp.yml con acciones que permiten la ejecución y depuración locales. |
Compilación y ejecución del primer agente de motor personalizado
Después de configurar el área de trabajo del proyecto con Teams Toolkit, compile el proyecto. Asegúrese de que ha iniciado sesión en su cuenta de Microsoft 365.
Inicio de sesión en su cuenta de Microsoft 365
Use esta cuenta para iniciar sesión en Teams. Si usa un inquilino del programa para desarrolladores de Microsoft 365, la cuenta de administrador que configuró al registrarse es la cuenta de Microsoft 365.
Abrir Visual Studio Code.
Seleccione el icono kit de herramientas de
Teams en la barra lateral.Seleccione Iniciar sesión en M365.
Se abre el explorador web predeterminado para permitirle iniciar sesión en la cuenta.
Inicie sesión en su cuenta de Microsoft 365 con sus credenciales.
Cierre el explorador cuando se le solicite y vuelva a Visual Studio Code.
Vuelva al kit de herramientas de Teams en Visual Studio Code.
Use esta cuenta para iniciar sesión en Teams. Si usa un inquilino del programa para desarrolladores de Microsoft 365, la cuenta de administrador que configuró al registrarse es la cuenta de Microsoft 365.
Ahora ya está listo para compilar la aplicación y ejecutarla localmente.
Actualización del agente de motor personalizado con las funcionalidades de la biblioteca de inteligencia artificial de Teams
Teams Toolkit es la manera más fácil de aplicar scaffolding y obtener un agente de motor personalizado en ejecución. Teams Toolkit crea la estructura básica para empezar a configurar el agente de motor personalizado.
Comencemos a configurar las funcionalidades de la biblioteca de IA de Teams:
Vaya a Visual Studio Code y abra una ventana de terminal.
Ejecute el siguiente comando en el terminal para instalar
yarn:npm install npm install @microsoft/teams-aiNota:
Si va a crear el ejemplo a través del kit de herramientas de Teams, encontrará el
.env.local.userarchivo en la configuración que se crea automáticamente. Si el archivo no está disponible, cree el.env.local.userarchivo y actualice la clave OpenAI o la clave de Azure OpenAI y el punto de conexión de Azure OpenAI.Vaya al
app.tsarchivo:Agregue
TurnContexta la instrucción import de la siguiente manera:import { MemoryStorage, TurnContext} from 'botbuilder';Agregue
DefaultConversationState, Memory, TurnStatea la instrucción import de la"@microsoft/teams-ai"siguiente manera:// See https://aka.ms/teams-ai-library to learn more about the Teams AI library. import { Application, ActionPlanner, DefaultConversationState, Memory, TurnState, OpenAIModel, PromptManager } from "@microsoft/teams-ai";Después de "@microsoft/teams-ai", agregue lo siguiente:
// eslint-disable-next-line @typescript-eslint/no-empty-interface interface ConversationState extends DefaultConversationState { lightsOn: boolean; } type ApplicationTurnState = TurnState<ConversationState>; if (!process.env.OPENAI_API_KEY) { throw new Error('Missing environment variables - please check that OPENAI_KEY or AZURE_OPENAI_KEY is set.'); }Después de
Define storage and application code, agregue lo siguiente:// Define a prompt function for getting the current status of the lights planner.prompts.addFunction('getLightStatus', async (context: TurnContext, memory: Memory) => { return memory.getValue('conversation.lightsOn') ? 'on' : 'off'; });Después de
return memory.getValue('conversation.lightsOn') ? 'on' : 'off';, agregue lo siguiente:// Register action handlers app.ai.action('LightsOn', async (context: TurnContext, state: ApplicationTurnState) => { state.conversation.lightsOn = true; await context.sendActivity(`[lights on]`); return `the lights are now on`; }); app.ai.action('LightsOff', async (context: TurnContext, state: ApplicationTurnState) => { state.conversation.lightsOn = false; await context.sendActivity(`[lights off]`); return `the lights are now off`; }); interface PauseParameters { time: number; } app.ai.action('Pause', async (context: TurnContext, state: ApplicationTurnState, parameters: PauseParameters) => { await context.sendActivity(`[pausing for ${parameters.time / 1000} seconds]`); await new Promise((resolve) => setTimeout(resolve, parameters.time)); return `done pausing`; });
Vaya al
adapter.tsarchivo:En
Import required bot services., quite el código existente y actualice lo siguiente:// Import required bot services. // See https://aka.ms/bot-services to learn more about the different parts of a bot. import { TeamsAdapter } from '@microsoft/teams-ai'; import { ConfigurationServiceClientCredentialFactory } from 'botbuilder';Quite el código siguiente en
This bot's main dialog.:// This bot's main dialog. import config from "./config"; const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication( {}, new ConfigurationServiceClientCredentialFactory(config) );Después de
import { ConfigurationServiceClientCredentialFactory } from 'botbuilder';, reemplace el código bajoCreate adapter.por lo siguiente:// Create adapter. // See https://aka.ms/about-bot-adapter to learn more about how bots work. const adapter = new TeamsAdapter( {}, new ConfigurationServiceClientCredentialFactory({ MicrosoftAppId: process.env.BOT_ID, MicrosoftAppPassword: process.env.BOT_PASSWORD, MicrosoftAppType: 'MultiTenant' }) );
Vaya al
index.tsarchivo:En , después
console.log(deCreate HTTP server.\nbot iniciado, ${server.name} que escucha ${server.url});agregue lo siguiente:console.log('\nGet Bot Framework Emulator: https://aka.ms/botframework-emulator'); console.log('\nTo test your bot in Teams, sideload the app manifest.json within Teams Apps.');
En la carpeta raíz, cree una nueva estructura de carpetas: secuencia de> mensajes.
En secuencia, cree los siguientes archivos:
- config.json
- skprompt.txt
- actions.json
Vaya al
config.jsonarchivo y agregue el código siguiente para crear la configuración del modelo de aviso:{ "schema": 1.1, "description": "A bot that can turn the lights on and off", "type": "completion", "completion": { "model": "gpt-3.5-turbo", "completion_type": "chat", "include_history": true, "include_input": true, "max_input_tokens": 2800, "max_tokens": 1000, "temperature": 0.2, "top_p": 0.0, "presence_penalty": 0.6, "frequency_penalty": 0.0, "stop_sequences": [] }, "augmentation": { "augmentation_type": "sequence" } }El agente de motor personalizado usa OpenAI o Azure OpenAI para su modelado de lenguaje natural. El
config.jsonarchivo controla el procesamiento de lenguaje para el agente de motor personalizado. Este archivo, iniciado por desdePromptManagerelindex.tsarchivo, supervisa el procesamiento del lenguaje del agente. Al iniciar una solicitud, el administrador de mensajes busca el archivo de configuración del símbolo del sistema (secuencia/config.json) y pasa la configuración del aviso a OpenAI o Azure OpenAI.Vaya al
skprompt.txtarchivo. Agregue las siguientes instrucciones para OpenAI o Azure OpenAI para llevar a cabo y facilitar la conversación:The following is a conversation with an AI assistant. The assistant can turn a light on or off. context: The lights are currently {{getLightStatus}}.El
skprompt.txtarchivo contiene mensajes de texto con los que los usuarios interactúan con OpenAI o Azure OpenAI. OpenAI o Azure OpenAI intenta usar estas indicaciones para generar la siguiente serie de palabras que es más probable que sigan del texto anterior.Vaya al
actions.jsonarchivo. Agregue el código siguiente para definir las acciones del agente de motor personalizado:{ { "name": "LightsOn", "description": "Turn the lights on", "parameters": [] }, { "name": "LightsOff", "description": "Turn the lights off", "parameters": [] }, { "name": "Pause", "description": "Delays for a period of time", "parameters": { "type": "object", "properties": { "time": { "type": "number", "description": "The amount of time to delay in milliseconds" } }, "required": [ "time" ] } } }El
actions.jsonarchivo contiene las acciones que el agente de motor personalizado puede realizar. desdeActionPlannerelindex.tsarchivo usa las acciones definidas en elactions.jsonarchivo para realizar las acciones.
En este ejemplo se usa OpenAI o Azure OpenAI para todo su modelado de lenguaje natural; el usuario puede comunicarse con el agente de motor personalizado en cualquier idioma que elija. El agente del motor personalizado entiende y responde correctamente sin código adicional.
Compilación y ejecución del agente de motor personalizado localmente
Para compilar y ejecutar la aplicación en el entorno local:
Seleccione la tecla F5 para ejecutar la aplicación en modo de depuración.
Nota:
Si el kit de herramientas de Teams no puede comprobar un requisito previo determinado, se le pedirá que lo compruebe.
Obtenga información sobre lo que ocurre al ejecutar la aplicación localmente en el depurador.
En caso de que se pregunte, al presionar la tecla F5 , el kit de herramientas de Teams:
- Comprueba todos los siguientes requisitos previos:
- Ha iniciado sesión con una cuenta de Microsoft 365.
- La carga de la aplicación personalizada está habilitada para su cuenta de Microsoft 365.
- Se instala la versión de Node.js compatible.
- El puerto requerido por la aplicación de bot está disponible.
- Instale paquetes npm.
- Inicia Dev Tunnel para crear un túnel HTTP.
- Registra la aplicación en Microsoft Entra ID y configura la aplicación.
- Registra la aplicación en Bot Framework SDK y configura la aplicación.
- Registra la aplicación en el Portal para desarrolladores de Teams y configura la aplicación.
- Inicia la aplicación.
- Inicia Teams en un explorador web y carga la aplicación.
Nota:
Al ejecutar la aplicación por primera vez, se descargan todas las dependencias y se compila la aplicación. Cuando se complete la compilación, se abrirá automáticamente una ventana del explorador. Este proceso puede tardar entre tres y cinco minutos en completarse.
Teams ejecuta la aplicación en un explorador web.
Inicie sesión con su cuenta de Microsoft 365, si se le solicita.
Seleccione Agregar cuando se le pida que cargue la aplicación en Teams en el equipo local.
Ahora, el agente de motor personalizado se ejecuta correctamente en Teams. Una vez cargada la aplicación, se abre una sesión de chat con el agente de motor personalizado.
Puede escribir
LightsOnpara empezar a interactuar con el agente de motor personalizado.
Obtenga información sobre cómo solucionar problemas si la aplicación no se ejecuta localmente.
Para ejecutar correctamente la aplicación en Teams, asegúrese de que ha habilitado la carga de aplicaciones personalizadas en su cuenta de Teams. Puede obtener más información sobre la carga de aplicaciones personalizadas en la sección requisitos previos.
Importante
La carga de aplicaciones personalizadas está disponible en los entornos de Government Community Cloud (GCC), GCC-High y Department of Defense (DOD).
Sugerencia
Compruebe si hay problemas antes de cargar una aplicación personalizada mediante la herramienta de validación de aplicaciones. Esta herramienta se incluye en el kit de herramientas. Corrija los errores para cargar la aplicación.
Implementación del agente de motor personalizado
Ha aprendido a crear, compilar y ejecutar un agente de motor personalizado. El último paso es implementar la aplicación en Azure.
Vamos a implementar el agente de motor personalizado en Azure mediante el kit de herramientas de Teams.
Inicio de sesión en su cuenta de Azure
Use esta cuenta para acceder a microsoft Azure Portal y aprovisionar nuevos recursos en la nube para admitir la aplicación.
Abrir Visual Studio Code.
Abra la carpeta del proyecto en la que creó la aplicación.
Seleccione el icono kit de herramientas de
Teams en la barra lateral.Seleccione Iniciar sesión en Azure.
Sugerencia
Si tiene instalada la extensión cuenta de Azure y usa la misma cuenta, puede omitir este paso. Use la misma cuenta que usa en otras extensiones.
Se abre el explorador web predeterminado para permitirle iniciar sesión en la cuenta.
Inicie sesión en su cuenta de Azure con sus credenciales.
Cierre el explorador cuando se le solicite y vuelva a Visual Studio Code.
La sección CUENTAS de la barra lateral muestra las dos cuentas por separado. También muestra el número de suscripciones de Azure utilizables disponibles. Asegúrese de que tiene al menos una suscripción de Azure utilizable disponible. Si no es así, cierre la sesión y use otra cuenta.
Ahora está listo para implementar la aplicación en Azure.
Enhorabuena, ha creado un agente de motor personalizado.
Implementar la aplicación en Azure
La implementación consta de dos pasos. En primer lugar, se crean los recursos en la nube necesarios (también conocidos como aprovisionamiento). A continuación, el código de la aplicación se copia en los recursos en la nube creados. En este tutorial, implementará el agente de motor personalizado.
¿Cuál es la diferencia entre Aprovisionar e Implementar?
El paso Aprovisionar crea recursos en Azure y Microsoft 365 para la aplicación, pero no se copia ningún código (HTML, CSS, JavaScript) en los recursos. El paso Implementar copia el código de la aplicación en los recursos que creó durante el paso de aprovisionamiento. Es habitual implementar varias veces sin aprovisionar nuevos recursos. Dado que el paso de aprovisionamiento puede tardar algún tiempo en completarse, es independiente del paso de implementación.
Seleccione icono del Kit de herramientas de Teams en la barra lateral de Visual Studio Code.
Seleccione Aprovisionar.
Seleccione una suscripción que se usará para los recursos de Azure.
La aplicación se hospeda mediante recursos de Azure.
Un cuadro de diálogo le advierte de que es posible que se produzcan costos al ejecutar recursos en Azure.
Seleccione Aprovisionar.
El proceso de aprovisionamiento crea recursos en la nube de Azure. Puede tardar algún tiempo. Para supervisar el progreso, vea los diálogos en la esquina inferior derecha. Después de unos minutos, verá el siguiente aviso:
Si lo desea, puede ver los recursos aprovisionados. En este tutorial, no es necesario ver los recursos.
El recurso aprovisionado aparece en la sección ENTORNO .
Seleccione Implementar en el panel CICLO DE VIDA una vez completado el aprovisionamiento.
Al igual que con el aprovisionamiento, la implementación tarda algún tiempo. Para supervisar el proceso, vea los diálogos en la esquina inferior derecha. Después de unos minutos, verá un aviso de finalización.
Ahora, puede usar el mismo proceso para implementar el agente de motor personalizado en Azure.
Ejecución de la aplicación implementada
Una vez completados los pasos de aprovisionamiento e implementación:
Abra el panel de depuración (Ctrl+Mayús+D / ⌘⇧-D o Ver > ejecución) desde Visual Studio Code.
Seleccione Iniciar remoto (Edge) en la lista desplegable de configuración de inicio.
Seleccione Iniciar depuración (F5) para iniciar la aplicación desde Azure.
Seleccione Agregar.
El kit de herramientas muestra un mensaje para indicar que la aplicación se agrega a Teams.
La aplicación se carga en el cliente de Teams.
Obtenga información sobre lo que sucede cuando implementó la aplicación en Azure.
Antes de la implementación, la aplicación se ejecuta de forma local:
- El back-end se ejecuta con Azure Functions Core Tools.
- El punto de conexión HTTP de la aplicación, donde Microsoft Teams carga la aplicación, se ejecuta de forma local.
La implementación es un proceso de dos pasos. Aprovisione los recursos en una suscripción de Azure activa y, a continuación, implemente o cargue el código de back-end y front-end de la aplicación en Azure.
- El back-end, si está configurado, usa varios servicios de Azure, incluidos Azure App Service y Azure Storage.
- La aplicación de front-end se implementa en una cuenta de Azure Storage configurada para el hospedaje web estático.
Antes de la implementación, la aplicación se ejecuta de forma local:
- El back-end se ejecuta con Azure Functions Core Tools.
- El punto de conexión HTTP de la aplicación, donde Microsoft Teams carga la aplicación, se ejecuta de forma local.
La implementación es un proceso de dos pasos. Aprovisione los recursos en una suscripción de Azure activa y, a continuación, implemente o cargue el código de back-end y front-end de la aplicación en Azure.
- El back-end, si está configurado, usa varios servicios de Azure, incluidos Azure App Service y Azure Storage.
- La aplicación de front-end se implementa en una cuenta de Azure Storage configurada para el hospedaje web estático.
Enhorabuena.
¡Lo has hecho!
Ha creado un agente de motor personalizado para controlar las luces.
Ha completado el tutorial.
¿Tiene algún problema con esta sección? Si es así, envíenos sus comentarios para que podamos mejorarla.