Criar agentes declarativos usando o Microsoft 365 Agents Toolkit e TypeSpec

Um agente declarativo fornece uma experiência de conversação direcionada a objetivos da plataforma Microsoft 365 Copilot. Você define seu propósito, instruções, conhecimento e ações. Este guia mostra como criar um agente declarativo usando o TypeSpec e o Microsoft 365 Agents Toolkit.

Pré-requisitos

• Um locatário do Microsoft 365 onde você pode carregar aplicativos personalizados. O provisionamento falhará se o upload de aplicativo personalizado não estiver habilitado. Para habilitar o upload de aplicativo personalizado, consulte Requisitos do Kit de Ferramentas de Agentes do Microsoft 365. Para obter opções de licenciamento e ambiente de desenvolvimento, consulte Ambiente de desenvolvimento do Copilot.

Para concluir as etapas descritas neste artigo, você precisará dos seguintes recursos:

• Visual Studio Code
• Microsoft 365 Agents Toolkit Extensão do Visual Studio Code

Familiarize-se com os seguintes padrões e diretrizes para agentes declarativos do Microsoft 365 Copilot:

• Padrões de conformidade, desempenho, segurança e experiência do usuário descritos nas diretrizes de validação da Loja do Teams.

Criar um agente declarativo

Comece criando um agente declarativo básico.

1. Abra o Visual Studio Code.

2. Selecione Microsoft 365 Agents Toolkit > Criar um novo agente/aplicativo.

   

3. Selecione o Agente Declarativo.

   

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

5. Selecione a pasta padrão para armazenar a pasta raiz do projeto no local padrão.

6. Digite My Agent como o Nome do Aplicativo e pressione Enter.

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

   

Testar o agente

1. Acesse o aplicativo Copilot em https://m365.cloud.microsoft/chat.

2. Ao lado do botão New Chat, selecione o ícone da gaveta de conversas.

3. Selecione o agente declarativo Meu Agente.

   

4. Insira uma pergunta para que seu agente declarativo o veja em ação.

Adicionar instruções

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

1. Abra o main.tsp arquivo e substitua o @instructions decorador pelo código a seguir.

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

   O conteúdo deste decorador é inserido instructions na propriedade no manifesto do agente durante o provisionamento. Para obter mais informações, consulte Objeto de manifesto do agente declarativo.

2. Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.

O agente declarativo usa suas instruções atualizadas depois que você recarrega a página.

Adicionar iniciadores de conversa

Os iniciadores de conversa são dicas que o Copilot exibe aos usuários para mostrar como eles podem começar a usar o agente declarativo.

1. Abra o main.tsp arquivo 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, consulte Objeto de iniciação de conversa.

2. Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.

Os iniciadores de conversa atualizados estão disponíveis em seu agente declarativo depois que você atualiza a página.

Adicionar conteúdo da Web

O recurso de pesquisa na Web permite que os agentes usem o índice de pesquisa no Bing para responder às solicitações do usuário.

1. Abra o main.tsp arquivo e adicione o WebSearch recurso no MyAgent namespace com o conteúdo a seguir.

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

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

   Observação

   Se você não especificar a matriz, o agente poderá acessar todo o Sites conteúdo da web.

2. Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.

O agente declarativo pode acessar o conteúdo da Web para gerar suas respostas depois que você recarregar a página.

Adicionar conteúdo do OneDrive e do SharePoint

A funcionalidade do SharePoint permite que o agente use o conteúdo do OneDrive e do SharePoint como conhecimento.

1. Abra o main.tsp arquivo e adicione a OneDriveAndSharePoint funcionalidade no MyAgent namespace com o valor a seguir, substituindo https://contoso.sharepoint.com/sites/ProductSupport por uma URL do site do SharePoint em 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 Objeto do OneDrive e do SharePoint.

   Observação

   • As URLs devem ser o caminho completo para itens do SharePoint (site, biblioteca de documentos, pasta ou arquivo). Você pode usar a opção "Copiar link direto" no SharePoint para obter o caminho completo ou arquivos e pastas. Clique com o botão direito do mouse no arquivo ou na pasta e selecione Detalhes. Navegue até Caminho e selecione o ícone de cópia.
   • Se você não especificar a ItemsByUrl matriz (ou a matriz alternativa ItemsBySharePointIds ), o agente poderá acessar todo o conteúdo do OneDrive e do SharePoint em sua organização do Microsoft 365 que o usuário conectado puder acessar.

2. Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.

O agente declarativo tem acesso ao conteúdo do OneDrive e do SharePoint para gerar suas respostas depois que você recarregar a página.

Adicionar mensagens do Teams

O recurso de mensagens do Teams permite que o agente use os canais, a equipe e o chat de reunião do Teams como conhecimento.

1. Abra o main.tsp arquivo e adicione a TeamsMessages funcionalidade no MyAgent namespace com o valor a seguir, substituindo https://teams.microsoft.com/l/team/... por um canal do Teams ou URL da equipe da sua organização.

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

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

   Observação

   • A URL na url propriedade deve ser um link bem formado para um chat do Teams, uma equipe ou um chat de reunião.
   • Se você não especificar a TeamsMessagesByUrl matriz, o agente poderá acessar todos os canais, equipes, reuniões, chat 1:1 e chats em grupo do Teams em sua organização do Microsoft 365 que o usuário autenticado pode acessar.

2. Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.

O agente declarativo pode acessar os dados do Teams para gerar suas respostas depois que você recarregar a página.

Adicionar conhecimento às pessoas

O recurso pessoas permite que você defina o escopo do seu agente para responder a perguntas sobre indivíduos em uma organização.

1. Abra o main.tsp arquivo e adicione o People recurso no MyAgent namespace com o conteúdo a seguir.

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

   Para obter mais informações, consulte o objeto People.

2. Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.

O agente declarativo tem acesso ao conhecimento das pessoas depois que você recarrega a página.

Adicionar conhecimento de email

O recurso de email permite que você defina o escopo do seu agente para usar o email da caixa de correio do usuário ou de uma caixa de correio compartilhada como uma fonte de conhecimento.

1. Abra o main.tsp arquivo e adicione o Email recurso no MyAgent namespace com o conteúdo a seguir.

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

   Para obter mais informações, consulte Objeto de Email.

   Observação

   • Este exemplo acessa o usuário da caixa de correio do agente. Para acessar uma caixa de correio compartilhada, adicione a propriedade opcional shared_mailbox definida ao endereço de email da caixa de correio compartilhada.
   • A Folders matriz limita o acesso da caixa de correio a pastas específicas. Para acessar a caixa de correio inteira, omita a folders matriz.

2. Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.

O agente declarativo tem acesso ao conhecimento de email depois que você recarrega a página.

Adicionar gerador de imagens

O recurso de gerador de imagens permite que os agentes gerem imagens com base em solicitações do usuário.

1. Abra o main.tsp arquivo e adicione o GraphicArt recurso no MyAgent namespace com o conteúdo a seguir.

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

   Para obter mais informações, consulte Objeto de arte gráfica.

2. Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.

O agente declarativo pode gerar imagens depois que você recarregar a página.

Adicionar interpretador de código

O recurso interpretador de código é uma ferramenta avançada projetada para resolver tarefas complexas por meio do código Python.

1. Abra o main.tsp arquivo e adicione o CodeInterpreter recurso no MyAgent namespace com o conteúdo a seguir.

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

   Para obter mais informações, consulte Objeto interpretador de código.

2. Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.

O agente declarativo tem o recurso interpretador de código depois que você recarrega a página.

Adicionar conteúdo de conectores do Copilot

Adicione itens ingeridos por um conector do Copilot ao conhecimento disponível para o agente.

1. Abra o main.tsp arquivo e adicione a GraphConnectors funcionalidade no MyAgent namespace com o valor a seguir, substituindo policieslocal por uma ID válida do conector do Copilot em sua organização do Microsoft 365. Para obter mais informações sobre como encontrar IDs de conector do Copilot, consulte Recuperar IDs de funcionalidade para o manifesto do agente declarativo.

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

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

   Observação

   Se você não especificar a Connections matriz, o agente obterá conteúdo de todos os conectores do Copilot em sua organização do Microsoft 365 que o usuário conectado pode acessar.

2. Selecione Provisionar no painel Ciclo de Vida do Kit de Ferramentas de Agentes.

O agente declarativo pode acessar o conteúdo dos conectores do Copilot para gerar suas respostas depois que você recarregar a página.

Concluído

Você concluiu o guia do agente declarativo para o Microsoft 365 Copilot. Agora que você já está familiarizado com o uso do TypeSpec para criar um agente declarativo, saiba mais nos artigos a seguir.

• Saiba como escrever instruções eficazes para seu agente.
• Teste seu agente com o modo de desenvolvedor para verificar se e como o orquestrador do Copilot seleciona suas fontes de conhecimento para uso em resposta a prompts fornecidos. Para obter mais informações, consulte Testar e depurar agentes no Microsoft 365 Agents Toolkit usando o modo de desenvolvedor.
• Obtenha respostas para perguntas frequentes.
• Saiba mais sobre outras maneiras de criar agentes declarativos: sem código no Construtor de Agentes ou com pouco código no Copilot Studio.

Próximas etapas