Criar agentes declarativos com o Toolkit e o TypeSpec de Agentes do Microsoft 365

Um agente declarativo é uma versão personalizada do Microsoft 365 Copilot que permite aos utilizadores criar experiências personalizadas ao declarar instruções, ações e conhecimentos específicos. Este guia demonstra como criar um agente declarativo com o TypeSpec e o Toolkit de Agentes do Microsoft 365.

Pré-requisitos

Antes de começar, certifique-se de que Microsoft 365 Copilot está disponível para a sua organização.

As seguintes opções estão disponíveis para o seu ambiente de desenvolvimento:

• Uma organização do Microsoft 365 de sandbox com o Copilot (disponível em pré-visualização limitada através da associação tap).
• Um ambiente de produção do Microsoft 365 ou Office 365 elegível com uma licença de Microsoft 365 Copilot.

São necessários os seguintes recursos para concluir os passos descritos neste artigo:

• Visual Studio Code
• Extensão de Visual Studio Code do Toolkit de Agentes do Microsoft 365

Deve estar familiarizado com as seguintes normas e diretrizes para agentes declarativos para Microsoft 365 Copilot:

• Normas de conformidade, desempenho, segurança e experiência de utilizador descritas nas diretrizes de validação da Loja Teams.

Criar um agente declarativo

Comece por criar um agente declarativo básico.

1. Abra o Visual Studio Code.

2. Selecione Microsoft 365 Agents Toolkit > Criar um Novo Agente/Aplicação.

   

3. Selecione Agente Declarativo.

   

4. Selecione Iniciar com TypeSpec para Microsoft 365 Copilot para criar um agente declarativo básico.

5. Selecione Pasta predefinida para armazenar a pasta raiz do projeto na localização predefinida.

6. Introduza My Agent como o Nome da Aplicação e prima Enter.

7. Na nova janela Visual Studio Code que é aberta, selecione Toolkit de Agentes do Microsoft 365. No painel Ciclo de Vida , selecione Aprovisionar.

   

Testar o agente

1. Navegue para a aplicação Copilot com o URL https://m365.cloud.microsoft/chat.

2. Junto ao botão Novo Chat , selecione o ícone da gaveta de conversação.

3. Selecione o agente declarativo O Meu Agente.

   

4. Introduza uma pergunta para o agente declarativo vê-la em ação.

Adicionar instruções

As instruções alteram o comportamento de um agente.

1. Abra o main.tsp ficheiro e substitua o @instructions decorador pelo seguinte.

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

Os conteúdos deste decorador são inseridos na instructions propriedade no manifesto do agente durante o aprovisionamento. Para obter mais informações, veja Objeto de manifesto do agente declarativo.

1. Selecione Aprovisionar no painel Ciclo de Vida do Toolkit de Agentes do Microsoft 365.

O agente declarativo utilizará as instruções atualizadas depois de recarregar a página.

Adicionar iniciadores de conversação

Os iniciadores de conversação são sugestões que são apresentadas ao utilizador para demonstrar como podem começar a utilizar o agente declarativo.

1. Abra o main.tsp ficheiro e substitua o decorador comentado @conversationStarter pelo seguinte conteúdo:

   @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 obter mais informações, veja Objeto Iniciadores de conversação.

1. Selecione Aprovisionar no painel Ciclo de Vida do Toolkit de Agentes do Microsoft 365.

Os iniciadores de conversação atualizados estarão disponíveis no seu agente declarativo depois de atualizar a página.

Adicionar conteúdo Web

A capacidade de pesquisa na Web permite que os agentes utilizem o índice de pesquisa no Bing para responder a pedidos do utilizador.

1. Abra o main.tsp ficheiro e adicione a WebSearch capacidade no MyAgent espaço de nomes com o seguinte conteúdo.

   namespace MyAgent {
     op webSearch is AgentCapabilities.WebSearch<Sites = [
       {
         url: "https://learn.microsoft.com",
       },
     ]>;
   }
   

   Para obter mais informações, veja Objeto de pesquisa na Web.

   Observação

   Não especificar a Sites matriz faz com que todos os conteúdos Web estejam disponíveis para o agente.

2. Selecione Aprovisionar no painel Ciclo de Vida do Toolkit de Agentes do Microsoft 365.

O agente declarativo tem acesso ao conteúdo Web para gerar as respetivas respostas depois de recarregar a página.

Adicionar conteúdo do OneDrive e do SharePoint

A capacidade do SharePoint permite que o agente utilize conteúdos do OneDrive e do SharePoint como conhecimento.

1. Abra o main.tsp ficheiro e adicione a OneDriveAndSharePoint capacidade no MyAgent espaço de nomes com o seguinte valor, substituindo https://contoso.sharepoint.com/sites/ProductSupport por um URL de site do SharePoint na sua organização do 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 obter mais informações, consulte OneDrive e objeto do SharePoint.

   Observação

   • Os URLs devem ser o caminho completo para itens do SharePoint (site, biblioteca de documentos, pasta ou ficheiro). Pode utilizar a opção "Copiar ligação direta" no SharePoint para obter o caminho completo ou ficheiros e pastas. Clique com o botão direito do rato no ficheiro ou pasta e selecione Detalhes. Navegue para Caminho e selecione o ícone de cópia.
   • Não especificar a ItemsByUrl matriz (ou a matriz alternativa ItemsBySharePointIds ) faz com que todos os conteúdos do OneDrive e do SharePoint na sua organização do Microsoft 365 que estejam disponíveis para o utilizador com sessão iniciada estejam disponíveis para o agente.

2. Selecione Aprovisionar no painel Ciclo de Vida do Toolkit de Agentes do Microsoft 365.

O agente declarativo tem acesso aos conteúdos do OneDrive e do SharePoint para gerar as respetivas respostas depois de recarregar a página.

Adicionar mensagens do Teams

A capacidade de mensagens do Teams permite que o agente utilize canais do Teams, a equipa e o chat de reunião como conhecimento.

1. Abra o main.tsp ficheiro e adicione a TeamsMessages capacidade no MyAgent espaço de nomes com o seguinte valor, substituindo https://teams.microsoft.com/l/team/... por um canal do Teams ou url de equipa da sua organização.

   namespace MyAgent {
     // Omitted for brevity
     op teamsMessages is AgentCapabilities.TeamsMessages<Urls = [
       {
         url: "https://teams.microsoft.com/l/team/...",
       }
     ]>;
     // Omitted for brevity
   }
   

   Para obter mais informações, consulte Objeto de mensagens do Microsoft Teams.

   Observação

   • O URL na url propriedade tem de ter ligações bem formadas para um chat, equipa ou chat de reunião do Teams.
   • Não especificar a Urls matriz faz com que todos os canais, equipas, reuniões, chats 1:1 e chats de grupo do Teams na sua organização do Microsoft 365 que estejam disponíveis para o utilizador com sessão iniciada estejam disponíveis para o agente.

2. Selecione Aprovisionar no painel Ciclo de Vida do Toolkit de Agentes do Microsoft 365.

O agente declarativo tem acesso aos dados do Teams para gerar as respetivas respostas depois de recarregar a página.

Adicionar conhecimentos de pessoas

A capacidade de pessoas) permite-lhe definir o âmbito do seu agente para responder a perguntas sobre indivíduos numa organização.

1. Abra o main.tsp ficheiro e adicione a People capacidade no MyAgent espaço de nomes com o seguinte conteúdo.

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

Para obter mais informações, veja Pessoas objeto.

1. Selecione Aprovisionar no painel Ciclo de Vida do Toolkit de Agentes do Microsoft 365.

O agente declarativo tem acesso ao conhecimento das pessoas depois de recarregar a página.

Adicionar conhecimentos de e-mail

A capacidade de e-mail permite-lhe definir o âmbito do agente para utilizar o e-mail da caixa de correio do utilizador ou de uma caixa de correio partilhada como uma origem de dados de conhecimento.

1. Abra o main.tsp ficheiro e adicione a Email capacidade no MyAgent espaço de nomes com o seguinte conteúdo.

   namespace MyAgent {
     // Omitted for brevity
     op email is AgentCapabilities.Email<Folders = [
       {
         folder_id: "Inbox",
       }
     ]>;
     // Omitted for brevity
   }
   

   Para obter mais informações, veja Email objeto.

   Observação

   • Este exemplo acede ao utilizador da caixa de correio do agente. Para aceder a uma caixa de correio partilhada, adicione a propriedade opcional shared_mailbox definida ao endereço de e-mail da caixa de correio partilhada.
   • A Folders matriz limita o acesso da caixa de correio a pastas específicas. Para aceder a toda a caixa de correio, omita a folders matriz.

2. Selecione Aprovisionar no painel Ciclo de Vida do Toolkit de Agentes do Microsoft 365.

O agente declarativo tem acesso aos conhecimentos de e-mail depois de recarregar a página.

Adicionar gerador de imagens

A capacidade do gerador de imagens permite que os agentes gerem imagens com base em pedidos do utilizador.

1. Abra o main.tsp ficheiro e adicione a GraphicArt capacidade no MyAgent espaço de nomes com o seguinte conteúdo.

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

Para obter mais informações, veja Objeto gráfico artístico.

1. Selecione Aprovisionar no painel Ciclo de Vida do Toolkit de Agentes do Microsoft 365.

O agente declarativo tem a capacidade de gerar imagens depois de recarregar a página.

Adicionar interpretador de código

A capacidade de intérprete de código é uma ferramenta avançada concebida para resolver tarefas complexas através do código Python.

1. Abra o main.tsp ficheiro e adicione a CodeInterpreter capacidade no MyAgent espaço de nomes com o seguinte conteúdo.

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

Para obter mais informações, veja Objeto de intérprete de código.

1. Selecione Aprovisionar no painel Ciclo de Vida do Toolkit de Agentes do Microsoft 365.

O agente declarativo tem a capacidade de intérprete de código depois de recarregar a página.

Adicionar conteúdo dos conectores Copilot

Pode adicionar itens ingeridos por um conector Copilot aos conhecimentos disponíveis para o agente.

1. Abra o main.tsp ficheiro e adicione a GraphConnectors capacidade no MyAgent espaço de nomes com o seguinte valor, substituindo policieslocal por um ID de conector Copilot válido na sua organização do Microsoft 365. Para obter mais informações sobre como localizar IDs do conector Copilot, veja Obter IDs de capacidades para o manifesto declarativo do agente.

   namespace MyAgent {
     // Omitted for brevity
     op copilotConnectors is AgentCapabilities.GraphConnectors<Connections = [
       {
         connectionId: "policieslocal",
       }
     ]>;
     // Omitted for brevity
   }
   

   Para obter mais informações, veja Objeto de conectores Copilot.

   Observação

   Não especificar a Connections matriz faz com que o conteúdo de todos os conectores copilot na sua organização do Microsoft 365 que estejam disponíveis para o utilizador com sessão iniciada esteja disponível para o agente.

2. Selecione Aprovisionar no painel Ciclo de Vida do Toolkit de Agentes do Microsoft 365.

O agente declarativo tem acesso ao conteúdo dos conectores Copilot para gerar as respetivas respostas depois de recarregar a página.

Concluído

Concluiu o guia do agente declarativo para Microsoft 365 Copilot. Agora que está familiarizado com a utilização do TypeSpec para criar um agente declarativo, pode saber mais nos seguintes artigos.

• Saiba como escrever instruções eficazes para o seu agente.
• Teste o agente com o modo de programador Copilot para verificar se e como o orquestrador copilot seleciona as suas origens de conhecimento para utilização em resposta a determinados pedidos.
• Obtenha respostas às perguntas mais frequentes.
• Saiba mais sobre um método alternativo de criação de agentes declarativos com Copilot Studio.

Próximas etapas