Criar uma experiência de configuração de agente no Teams

Uma experiência de configuração de agente permite que os usuários configurem e reconfigurem as configurações de seus agentes diretamente no escopo do canal ou chat em grupo após a instalação. Isso aumenta a eficiência operacional do agente desde o início. A experiência de configuração do agente elimina a necessidade de intervenções repetidas do usuário que anteriormente prejudicavam os benefícios oportunos dos aplicativos, afetando a experiência do usuário.

Com a experiência de configuração do agente, você pode garantir a relevância e o valor contínuos do agente, pois os usuários podem:

• Adapte o agente aos seus fluxos de trabalho e preferências específicos durante a instalação.
• Redefina as configurações para se adaptar às mudanças de requisitos após a instalação.

Por exemplo, um agente que rastreia e compartilha tópicos de notícias ou monitora repositórios do GitHub pode ser configurado inicialmente para corresponder aos fluxos de trabalho do usuário. Posteriormente, ele pode ser facilmente reconfigurado para responder a novos tópicos ou repositórios diretamente do chat em grupo, simplificando o gerenciamento de conteúdo e a interação sem sair do ambiente do Teams. Essa experiência de configuração flexível melhora significativamente a experiência do usuário e a produtividade, integrando os agentes perfeitamente às operações diárias.

Aqui está um exemplo, em que um usuário adiciona o agente a um bate-papo em grupo e, em seguida, o configura para se alinhar aos seus requisitos específicos. Em seguida, o usuário reconfigura o agente para alterar o status.

Configurar

Reconfigurar

Para configurar o agente como a funcionalidade de aterrissagem padrão para um aplicativo que dá suporte a recursos de bot e guia, consulte Configurar a funcionalidade de aterrissagem padrão.

Experiência de configuração do agente de compilação

Ao criar a experiência de configuração do agente, você deve garantir que o usuário seja capaz de configurar um agente na primeira instalação e reconfigurá-lo a qualquer momento.

Para criar a experiência de configuração do agente, siga estas etapas:

1. Atualizar manifesto do aplicativo

2. Configurar seu bot

Atualizar manifesto do aplicativo

No arquivo de manifesto do aplicativo (anteriormente chamado de manifesto do aplicativo do Teams), atualize a fetchTask propriedade sob o objeto da bots.configuration seguinte maneira:

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

Para obter mais informações, consulte Esquema de manifesto do aplicativo.

Configure seu agente

Quando um usuário instala o agente no canal ou chat em grupo, a fetchTask propriedade no arquivo de manifesto do aplicativo inicia ou config.submitconfig.fetch .

Se você definir a fetchTask propriedade no manifesto do aplicativo como:

• false: O agente não busca uma caixa de diálogo ou um Cartão Adaptável. Em vez disso, o agente deve fornecer uma caixa de diálogo estática ou um card que é usado quando o agente é invocado. Para obter mais informações, consulte diálogos.

• true: O agente inicia um ou config.fetchconfig.submit conforme definido. Quando o agente é invocado, você pode retornar um Cartão Adaptável ou uma caixa de diálogo, dependendo do contexto fornecido em channelData e userdata.

A tabela a seguir lista o tipo de resposta associado às solicitações de invocação:

• type: "continue": type: "continue" é usado para definir uma continuação de uma caixa de diálogo ou Cartão Adaptável em uma configuração de agente. Quando o tipo é definido como continue, isso indica que o agente está esperando uma interação adicional do usuário para continuar com o processo de configuração.

  Quando o usuário envia a configuração, a config.submit invocação é acionada. Ele lê a entrada do usuário e retorna um Cartão Adaptável diferente. Você também pode atualizar a configuração do agente para retornar uma caixa de diálogo.

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)
 );
});

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',
   },
 },
};
});

@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": você também pode solicitar que o usuário se autentique como uma resposta à config.fetch solicitação. A type: "auth" configuração solicita que o usuário entre por meio de uma URL especificada, que deve ser vinculada a uma página de autenticação válida que pode ser aberta em um navegador. A autenticação é essencial para cenários em que o agente exige que o usuário seja autenticado. Ele garante que a identidade do usuário seja verificada, mantendo a segurança e as experiências personalizadas dentro da funcionalidade do agente.

  Observação

  Pois type: "auth" apenas a autenticação de terceiros é suportada. O logon único (SSO) não é compatível. Para obter mais informações sobre autenticação de terceiros, consulte adicionar autenticação.

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"
                 }
             }
         }
     }
 );
});

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',
       },
     ],
   },
 },
};
});

@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": Quando o tipo é definido como mensagem, isso indica que o agente está enviando uma mensagem simples de volta ao usuário, indicando o fim da interação ou fornecendo informações sem a necessidade de entrada adicional.

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

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

@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",
     )
 )

Quando um usuário reconfigura o agente, a fetchTask propriedade no arquivo de manifesto do aplicativo é config.fetch iniciada na lógica do agente. O usuário pode reconfigurar as configurações do agente após a instalação de duas maneiras:

• @mention o agente na área de redação de mensagem. Selecione a opção Configurações que aparece acima da área de redação da mensagem. Uma caixa de diálogo aparece, atualiza ou altera as definições de configuração do agente na caixa de diálogo.

  

• Passe o mouse sobre o agente, o card de perfil do agente aparece. Para atualizar ou alterar as definições de configuração do agente, selecione o ícone de configurações na card de perfil do agente.

  

Práticas recomendadas

• Se você quiser ter uma configuração individual no nível do canal do seu agente, certifique-se de rastrear a configuração de acordo com o canal. Os dados de configuração não são armazenados e o conteúdo de invocação inclui o channelData suficiente.

• Forneça uma caixa de diálogo clara e amigável que solicite que o usuário insira as informações necessárias para que o agente funcione corretamente, como uma URL, um caminho de área ou um link de dashboard.

• Evite enviar várias notificações ou solicitações de configuração após a instalação, pois isso pode confundir os usuários.

Exemplo de código

Confira também

• Criar agentes para o Teams
• Cartões Adaptáveis