Creación de una experiencia de configuración de agente en Teams

Una experiencia de configuración de agente permite a los usuarios configurar y volver a configurar la configuración de sus agentes directamente dentro del ámbito de chat del canal o grupo después de la instalación. Esto mejora la eficacia operativa del agente desde el principio. La experiencia de configuración del agente elimina la necesidad de intervenciones repetidas de los usuarios que anteriormente dificultaban las ventajas oportunas de las aplicaciones, lo que afectaba a la experiencia del usuario.

Con la experiencia de configuración del agente, puede garantizar la relevancia y el valor continuos del agente, ya que los usuarios pueden:

• Adapte el agente a sus flujos de trabajo y preferencias específicos durante la instalación.
• Vuelva a configurar la configuración para adaptarse a los requisitos cambiantes después de la instalación.

Por ejemplo, un agente que realiza un seguimiento y comparte temas de noticias o supervisa repositorios de GitHub se puede configurar inicialmente para que coincida con los flujos de trabajo de usuario. Más adelante, se puede volver a configurar fácilmente para responder a nuevos temas o repositorios directamente desde el chat de grupo, simplificando la administración de contenido y la interacción sin salir del entorno de Teams. Esta experiencia de configuración flexible mejora significativamente la experiencia del usuario y la productividad mediante la integración de agentes sin problemas en las operaciones diarias.

Este es un ejemplo en el que un usuario agrega el agente a un chat de grupo y, a continuación, lo configura para que se alinee con sus requisitos específicos. A continuación, el usuario vuelve a configurar el agente para cambiar el estado.

Configurar

Volver a configurar

Para configurar el agente como la funcionalidad de aterrizaje predeterminada para una aplicación que admite funcionalidades de bot y pestaña, consulte Configuración de la funcionalidad de aterrizaje predeterminada.

Experiencia de configuración del agente de compilación

Nota:

La experiencia de configuración del agente solo se admite en el chat de canal o grupo.

Al compilar la experiencia de configuración del agente, debe asegurarse de que el usuario debe poder configurar un agente en la primera instalación y volver a configurarlo en cualquier momento.

Para compilar la experiencia de configuración del agente, siga estos pasos:

1. Actualizar el manifiesto de la aplicación

2. Configuración del bot

Actualizar el manifiesto de la aplicación

En el archivo de manifiesto de aplicación (anteriormente denominado manifiesto de aplicación de Teams), actualice la fetchTask propiedad en el objeto de la bots.configuration siguiente manera:

"bots": [
    {
      "botId": "${{AAD_APP_CLIENT_ID}}",
     "needsChannelSelector": false,
      "scopes": [
        "personal",
        "team",
        "groupChat"
      ],
      "configuration":{
        "groupChat":{
          "fetchTask": true
        },
        "team":{
          "fetchTask": true
        }
      },
      "isNotificationOnly": false
    }
  ],

Para obtener más información, consulte esquema de manifiesto de aplicación.

Me encontré con un problema

Configure el agente

Cuando un usuario instala el agente en el chat de canal o grupo, la fetchTask propiedad del archivo de manifiesto de la aplicación inicia config.fetch o config.submit.

Si establece la fetchTask propiedad en el manifiesto de la aplicación en:

• false: el agente no captura un cuadro de diálogo ni una tarjeta adaptable. En su lugar, el agente debe proporcionar un cuadro de diálogo estático o una tarjeta que se use cuando se invoque al agente. Para obtener más información, vea diálogos.

• true: el agente inicia o config.fetch tal como config.submit se define. Cuando se invoca el agente, puede devolver una tarjeta adaptable o un cuadro de diálogo en función del contexto proporcionado en channelData y userdata.

En la tabla siguiente se muestra el tipo de respuesta asociado a las solicitudes de invocación:

Invocación de la solicitud	Tipo de respuesta
config.fetch	Type: "continue" o Type = "auth"
config.submit	Type: "continue" o Type: "message"

• type: "continue": type: "continue" se usa para definir una continuación de un cuadro de diálogo o una tarjeta adaptable dentro de una configuración de agente. Cuando el tipo se establece en continue, indica que el agente espera una interacción adicional del usuario para continuar con el proceso de configuración.

  Cuando el usuario envía la configuración, se desencadena la config.submit invocación. Lee la entrada del usuario y devuelve una tarjeta adaptable diferente. También puede actualizar la configuración del agente para devolver un cuadro de diálogo.

C#

app.OnConfigFetch(async (context) =>
{
 var card = new AdaptiveCard
 {
     Body = new List<CardElement>
     {
         new TextBlock("Configure your agent")
         {
             Weight = TextWeight.Bolder
         }
     },
     Actions = new List<Action>
     {
         new SubmitAction
         {
             Title = "Submit"
         }
     }
 };
 var taskInfo = new TaskInfo
 {
     Title = "test card",
     Width = new Union<int, Size>(600),
     Height = new Union<int, Size>(500),
     Card = new Attachment
     {
         ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
         Content = card
     }
 };
 return new ConfigTaskResponse(
     new ContinueTask(taskInfo)
 );
});

TypeScript

app.on('config.fetch', async ({ activity }) => {
const card = new AdaptiveCard(
 {
   type: 'TextBlock',
   text: 'Configure your agent',
   weight: 'Bolder',
 }
).withActions(
 new SubmitAction().withTitle('Submit')
);
return {
 config: {
   type: 'continue',
   value: {
     card: cardAttachment('adaptive', card),
     height: 500,
     width: 600,
     title: 'test card',
   },
 },
};
});

Python

@app.on_config_open
async def handle_config_open(
 ctx: ActivityContext[ConfigFetchInvokeActivity]
) -> ConfigInvokeResponse:
 card = AdaptiveCard(
     body=[
         TextBlock(text="Configure your agent", weight="Bolder")
     ],
     actions=[
         SubmitAction(title="Submit")
     ]
 )

 return ConfigResponse(
     config=TaskModuleContinueResponse(
         value=CardTaskModuleTaskInfo(
             card=card_attachment(AdaptiveCardAttachment(content=card)),
             height=500,
             width=600,
             title="test card",
         )
     )
 )

• type: "auth": también puede solicitar al usuario que se autentique como respuesta a la config.fetch solicitud. La type: "auth" configuración solicita al usuario que inicie sesión a través de una dirección URL especificada, que debe estar vinculada a una página de autenticación válida que se pueda abrir en un explorador. La autenticación es esencial para escenarios en los que el agente requiere que el usuario se autentique. Garantiza que la identidad del usuario se compruebe, mantenga la seguridad y las experiencias personalizadas dentro de la funcionalidad del agente.

  Nota:

  Solo type: "auth" se admite la autenticación de terceros. No se admite el inicio de sesión único (SSO). Para obtener más información sobre la autenticación de terceros, consulte Agregar autenticación.

C#

app.OnConfigFetch(async (context) =>
{
 return new ConfigAuthResponse(
     new ConfigAuth
     {
         SuggestedActions = new SuggestedActions
         {
             Actions = new List<CardAction>
             {
                 new CardAction
                 {
                     Type = "openUrl",
                     Value = "https://example.com/auth",
                     Title = "Sign in to this app"
                 }
             }
         }
     }
 );
});

TypeScript

app.on('config.fetch', async ({ activity }) => {
return {
 config: {
   type: 'auth',
   suggestedActions: {
     actions: [
       {
         type: 'openUrl',
         value: 'https://example.com/auth',
         title: 'Sign in to this app',
       },
     ],
   },
 },
};
});

Python

@app.on_config_open
async def handle_config_open(
 ctx: ActivityContext[ConfigFetchInvokeActivity]
) -> ConfigInvokeResponse:
 return ConfigResponse(
     config=ConfigAuth(
         suggested_actions=SuggestedActions(
             to=[],
             actions=[
                 CardAction(
                     type="openUrl",
                     value="https://example.com/auth",
                     title="Sign in to this app",
                 )
             ],
         )
     )
 )

• type="message": cuando el tipo se establece en message, indica que el agente envía un mensaje simple al usuario, que indica el final de la interacción o proporciona información sin necesidad de más entradas.

C#

app.OnConfigSubmit(async (context) =>
{
 return new ConfigTaskResponse(
     new MessageTask("You have chosen to finish setting up agent")
 );
});

TypeScript

app.on('config.submit', async ({ activity, send }) => {
return {
 config: {
   type: 'message',
   value: 'You have chosen to finish setting up agent',
 },
};
});

Python

@app.on_config_submit
async def handle_config_submit(
 ctx: ActivityContext[ConfigSubmitInvokeActivity]
) -> ConfigInvokeResponse:
 return ConfigResponse(
     config=TaskModuleMessageResponse(
         value="You have chosen to finish setting up agent",
     )
 )

Cuando un usuario vuelve a configurar el agente, la fetchTask propiedad del archivo de manifiesto de la aplicación se config.fetch inicia en la lógica del agente. El usuario puede volver a configurar la configuración del agente después de la instalación de dos maneras:

• @mention el agente en el área de redacción del mensaje. Seleccione la opción Configuración que aparece encima del área de redacción del mensaje. Aparece un cuadro de diálogo, actualiza o cambia la configuración del agente en el cuadro de diálogo.

  

• Mantenga el puntero sobre el agente, aparecerá la tarjeta de perfil del agente. Para actualizar o cambiar la configuración del agente, seleccione el icono de configuración en la tarjeta de perfil del agente.

  

Me encontré con un problema

Procedimientos recomendados

• Si desea tener una configuración de nivel de canal individual del agente, asegúrese de realizar un seguimiento de la configuración según el canal. Los datos de configuración no se almacenan y la carga de invocación incluye el channelData suficiente.

• Proporcione un cuadro de diálogo claro y descriptivo que pida al usuario que escriba la información necesaria para que el agente funcione correctamente, como una dirección URL, una ruta de acceso de área o un vínculo de panel.

• Evite enviar varias notificaciones o solicitudes de configuración después de la instalación, ya que podría confundir a los usuarios.

Ejemplo de código

Ejemplo de nombre	Descripción	.NET	Node.js	Manifiesto
Aplicación de configuración del agente	En este ejemplo se muestra un agente para configurar y volver a configurar tarjetas adaptables en equipos y chats de grupo.	View	View	View
Aplicación de configuración del agente con autenticación	Este agente de Teams habilita la configuración y la reconfiguración con funcionalidades de búsqueda dinámica en tarjetas adaptables.	View	View	Ver

Consulte también

• Creación de agentes para Teams
• Tarjetas adaptables