Criar agentes declarativos usando o Microsoft 365 Agents Toolkit e o TypeSpec

Um agente declarativo fornece uma experiência de conversação orientada por objetivos com a tecnologia 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.

Observação

O agente criado neste tutorial destina-se a utilizadores licenciados Microsoft 365 Copilot. Também pode criar agentes para Microsoft 365 Copilot Chat utilizadores com capacidades limitadas. Para obter detalhes, consulte Microsoft 365 Copilot licenças de desenvolvedor.

Dica

Recomendado: Comece com o Work IQ Dev Tools para cenários de agente declarativo e plug-in pro-código suportados. Consulte o guia de início rápido do WIQD. As instruções baseadas em toolkits permanecem disponíveis para projetos e fluxos de trabalho existentes que o exigem. Verifique o suporte à capacidade e à experiência de destino antes de escolher uma ferramenta: o WIQD não tem como alvo agentes de mecanismo personalizados.

Observação

Os agentes declarativos baseados em Microsoft 365 Copilot são agora suportados no Word e PowerPoint.

Pré-requisitos

  • Um inquilino do Microsoft 365 onde pode carregar aplicações personalizadas. O aprovisionamento falha se o carregamento da aplicação personalizada não estiver ativado. Para ativar o carregamento personalizado da aplicação, consulte os requisitos do Microsoft 365 Agents Toolkit. Para obter informações sobre o ambiente de desenvolvimento e as opções de licenciamento, consulte Ambiente de desenvolvimento do Copilot.

Para concluir os passos descritos neste artigo, necessita dos seguintes recursos:

Observação

As capturas de ecrã e referências de interface de utilizador neste artigo utilizam uma versão de lançamento do Microsoft 365 Agents Toolkit. As versões de pré-lançamento poderão ser diferentes da interface de utilizador apresentada.

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

Criar um agente declarativo

Comece criando um agente declarativo básico.

  1. Abra Visual Studio Code.

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

    Uma captura de ecrã do botão Criar uma Nova Aplicação na barra lateral do Microsoft 365 Agents Toolkit

  3. Selecione Agente declarativo.

    Uma captura de ecrã das opções de Novo Projeto com o Agente selecionado

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

  5. Selecione 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 de Visual Studio Code que é aberta, selecione Microsoft 365 Agents Toolkit. No painel Ciclo de Vida , selecione Provisão.

    Uma captura de ecrã da opção Aprovisionamento no painel Ciclo de Vida do Microsoft 365 Agents Toolkit

Testar o agente

  1. Aceda à aplicação Copilot em https://m365.cloud.microsoft/chat.

  2. Junto ao botão Novo Chat, selecione o ícone de gaveta de conversas.

  3. Selecione o agente declarativo My Agent.

    Uma captura de ecrã do agente declarativo no Copilot

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

Adicionar instruções

As instruções mudam a forma como um agente se comporta.

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

    @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 processo de provisionamento insere o conteúdo desse decorador na instructions propriedade no manifesto do agente. Para obter mais informações, consulte Objeto de manifesto do agente declarativo.

  2. Selecione Provisionar no painel Ciclo de Vida do Agents Toolkit.

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

Uma captura de ecrã de uma resposta de um agente declarativo com base em instruções atualizadas

Adicionar iniciadores de conversação

Os iniciadores de conversação são sugestões que o Copilot apresenta aos utilizadores para mostrar como podem começar a utilizar 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 iniciadores de conversação.

  2. Selecione Provisionar no painel Ciclo de Vida do Agents Toolkit.

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

Uma captura de ecrã a mostrar os inícios de conversação a partir do agente declarativo no Microsoft 365 Copilot

Adicionar conteúdo da Web

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

  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 Sites matriz, o agente poderá acessar todo o conteúdo da Web.

  2. Selecione Provisionar no painel Ciclo de Vida do Agents Toolkit.

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

Uma captura de ecrã a mostrar uma resposta do agente declarativo que contém conteúdo Web

Adicionar conteúdo do OneDrive e SharePoint

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

  1. Abra o main.tsp ficheiro e adicione a OneDriveAndSharePoint funcionalidade no MyAgent espaço de nomes com o seguinte valor, substituindo-a https://contoso.sharepoint.com/sites/ProductSupport pelo URL de um 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 os 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 até Caminho e selecione o ícone de cópia.
    • Se não especificar a ItemsByUrl matriz (ou a matriz alternativa ItemsBySharePointIds ), o agente pode aceder a todos os conteúdos do OneDrive e do SharePoint na sua organização do Microsoft 365 aos quais o utilizador com sessão iniciada pode aceder.
  2. Selecione Provisionar no painel Ciclo de Vida do Agents Toolkit.

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

Uma captura de ecrã a mostrar uma resposta do agente declarativo que contém conteúdos do SharePoint e do OneDrive

Adicionar mensagens do Teams

A funcionalidade de mensagens do Teams permite ao agente utilizar os canais do Teams, a equipa e o chat de reunião como conhecimento.

  1. Abra o main.tsp ficheiro e adicione a TeamsMessages funcionalidade 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<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

    • O URL na url propriedade tem de ser uma ligação bem formada para uma conversa do Teams, conversa de equipa ou conversa de reunião.
    • Se não especificar a TeamsMessagesByUrl matriz, o agente pode aceder a todos os canais do Teams, equipas, reuniões, conversas individuais e conversas de grupo na sua organização do Microsoft 365 aos quais o utilizador autenticado pode aceder.
  2. Selecione Provisionar no painel Ciclo de Vida do Agents Toolkit.

O agente declarativo pode aceder aos dados do Teams para gerar as suas respostas após recarregar a página.

Uma captura de ecrã a mostrar uma resposta do agente declarativo que contém conteúdo do Teams

Acrescente conhecimentos às pessoas

A capacidade de pessoas permite-lhe definir o seu agente no sentido de responder a perguntas sobre indivíduos numa 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 People objeto.

  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.

Uma captura de tela mostrando uma resposta do agente declarativo que contém conhecimento de pessoas

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.

Uma captura de tela mostrando uma resposta do agente declarativo que contém conhecimento de email

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.

Uma captura de tela mostrando uma resposta do agente declarativo que contém arte gráfica gerada

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.

Uma captura de tela mostrando uma resposta do agente declarativo que contém um grafo gerado

Uma captura de tela mostrando o código Python usado para gerar o grafo solicitado

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.

Uma captura de tela mostrando uma resposta do agente declarativo que contém conteúdo do conector do Copilot

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.

Próximas etapas