Compartilhar via

Criar plug-ins de API para Microsoft 365 Copilot com a Biblioteca JavaScript do Office (pré-visualização)

Observação

A funcionalidade de desenvolvimento descrita neste artigo está em pré-visualização. Recomendamos que experimente esta funcionalidade, mas não deve ser utilizada num plug-in de produção. Seguem-se as limitações durante a pré-visualização inicial:

  • A funcionalidade só está ativada para o Office no Windows e Office na Web. Estamos a trabalhar para disponibilizar suporte para o Office no Mac.
  • A funcionalidade só está ativada para o Excel, PowerPoint ou Word. Estamos a trabalhar para trazer suporte para o Outlook.

Um plug-in de um agente declarativo pode chamar as APIs na Biblioteca JavaScript do Office para realizar operações de leitura e escrita nos conteúdos e metadados de um documento do Office que está atualmente aberto numa aplicação do Office. Esta capacidade permite que o Copilot trabalhe com documentos do Office de formas precisas e isentas de erros que, de outra forma, exigiriam um Suplemento do Office.

A relação dos agentes copilot com a arquitetura de Suplemento do Office

Tanto os Suplementos do Office como os plug-ins declarativos do agente chamam APIs na Biblioteca JavaScript do Office e uma extensão do Microsoft 365 que utiliza a biblioteca pode incluir um plug-in, um suplemento ou ambos. A melhor abordagem depende dos cenários de utilizador que a extensão deve ativar.

  • Se a extensão fornecer ações simples e rápidas que não precisam de parâmetros transmitidos aos mesmos, inclua apenas um suplemento com botões ou menus personalizados do friso, denominados comandos de suplemento.
  • Se a extensão precisar de uma experiência dashboard, precisar que o utilizador configure as definições, precisar de apresentar metadados sobre o conteúdo do documento do Office ou precisar de uma experiência semelhante a uma página por qualquer outro motivo, inclua um suplemento com um painel de tarefas.
  • Se a extensão precisar de fornecer ações complexas que exijam parâmetros transmitidos no runtime ou precise de uma interface de linguagem natural, inclua um agente Copilot.

Cenários

Seguem-se algumas formas selecionadas de um agente copilot que chama apIs da Biblioteca JavaScript do Office melhorar o valor de uma extensão do Microsoft 365.

  • Análise de conteúdo: Um agente pode ser utilizado para analisar o conteúdo de um documento, apresentação ou folha de cálculo e tomar medidas consoante o que encontrar. Eis alguns exemplos.

    • Um agente analisa um Pedido de Proposta (RFP) e, em seguida, obtém as respostas às perguntas no RFP a partir de um sistema de back-end. O utilizador pede simplesmente ao agente para "Preencher as respostas que sabe sobre as perguntas".
    • Um agente analisa um documento, ou uma tabela numa folha de cálculo, relativamente a conteúdos que impliquem determinadas ações que têm de ser realizadas, quer no próprio documento, quer noutro local nos sistemas empresariais do cliente. O utilizador poderá pedir ao agente para "Rever o documento relativamente aos itens que não vi na lista de auditoria".

  • Inserção fidedigna de dados: Se fizer uma pergunta a um motor de IA típico, este combina as informações que encontra e compõe uma resposta; um processo que pode introduzir imprecisões. No entanto, um agente Copilot baseado num suplemento pode inserir dados inalterados a partir de uma origem fidedigna. Alguns exemplos:

    • Considere um agente que permite a inserção de investigação legal em Word onde pode ser editado. Um utilizador pergunta ao agente "Em que circunstâncias pode um menor ou unilateralmente quebrar um arrendamento de espaço residencial no Indiana?" Em seguida, o agente obtém conteúdo, inalterado, de precedentes e estatutos, e insere-o no documento.
    • Considere um agente que gere o inventário de recursos digitais. Na conversa do agente Copilot, um utilizador pergunta "Insira uma tabela das nossas fotografias a cores com o nome de cada uma, o número de vezes que foi transferido e o respetivo tamanho em megabytes, ordenados por ordem da maioria dos transferidos". Em seguida, o agente obtém estes dados, inalterados, do sistema de registos e insere a tabela numa folha de cálculo do Excel.

Quando o agente é combinado com um suplemento, são ativados ainda mais cenários. A inclusão de um agente de Microsoft 365 Copilot com um Suplemento do Office proporciona, pelo menos, duas vantagens para o suplemento:

  • O Copilot torna-se uma interface de linguagem natural para a funcionalidade do suplemento.
  • O agente pode transmitir parâmetros para o JavaScript que invoca, o que não é possível quando um comando de função num suplemento é invocado a partir de um botão ou item de menu.

Aprender a utilizar o suplemento é uma forma de um agente melhorar um suplemento. Quando um utilizador precisa de executar vários passos ou tarefas com o suplemento para atingir um objetivo, a interface de chat da Copilot pode facilitar o processo de introdução ao suplemento. Por exemplo, considere uma empresa jurídica que precisa de ter uma lista de perguntas que têm de ser respondidas sobre cada arrendamento que prepara. Criar esta lista de perguntas pode ser moroso e de mão-de-obra intensiva. No entanto, pode ser pedido a um agente copilot que produza um primeiro rascunho de lista de perguntas e que as insira num documento Word com a Biblioteca JavaScript do Office.

Criar o seu primeiro plug-in da Biblioteca JavaScript do Office

Seguem-se os principais passos para criar um plug-in de API para um agente copilot que chama as APIs da Biblioteca JavaScript do Office.

Pré-requisitos

Criar o projeto

Comece por criar um agente declarativo básico.

  1. Abra o Visual Studio Code.

  2. Selecione Toolkit de Agentes do Microsoft 365 na barra de atividade.

  3. Selecione Criar um Novo Agente/Aplicação.

    Uma captura de ecrã do botão Criar um Novo Agente/Aplicação na barra de aplicações do Toolkit de Agentes do Microsoft 365

  4. Selecione Agente Declarativo.

    Captura de ecrã das opções Novo Projeto com o Agente Declarativo na parte superior.

  5. Selecione Sem Ação para criar um agente declarativo básico.

  6. Na lista Pastas da Área de Trabalho, selecione Pasta predefinida para armazenar a pasta raiz do projeto na localização predefinida ou navegue para uma pasta onde pretende colocar o novo projeto de agente.

  7. Introduza Excel Agent como o Nome da Aplicação e prima Enter.

  8. O projeto é aberto numa nova janela de Visual Studio Code. Feche a janela de Visual Studio Code original.

Configurar o manifesto

Os passos seguintes configuram o manifesto.

  1. Abra o ficheiro manifest.json na pasta appPackage .

  2. Tem de utilizar a versão de pré-visualização do esquema de manifesto, por isso, substitua as $schema propriedades e manifestVersion pelo seguinte.

    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
"manifestVersion": "devPreview",

  3. Na raiz do manifesto, adicione a seguinte propriedade de autorização . Esta propriedade dá ao seu agente permissão para ler e escrever em documentos do Office.

    "authorization": {
  "permissions": {
    "resourceSpecific": [
      {
        "name": "Document.ReadWrite.User",
        "type": "Delegated"
      }
    ]
  }
}

  4. Na raiz do manifesto, adicione a seguinte propriedade extensions . Acerca deste código, tenha em atenção o seguinte.

    • A requirements.scopes propriedade garante que o agente só está disponível no Excel e não noutras aplicações do Office.
    • O objeto no configura o runtimes runtime javaScript que o Office utiliza para executar as APIs da Biblioteca JavaScript do Office que o seu agente invoca.
    • A code.script propriedade especifica o URL de um ficheiro JavaScript que contém as funções que chamam as APIs da Biblioteca JavaScript do Office. Esse mesmo ficheiro contém uma invocação do método Office.actions.associate para mapear a função para um ID de ação. Irá criar este ficheiro num passo posterior.
    • A code.page propriedade especifica o URL de uma página Web que contém uma etiqueta incorporada <script> que carrega o ficheiro que é referência na code.page propriedade . Irá criar este ficheiro num passo posterior.
    • O objeto runtime inclui uma actions matriz que inclui um objeto de ação
    • O valor da actions.id propriedade é o mesmo ID de ação que é transmitido à chamada de associate.
    • A actions.type propriedade está definida como executeDataFunction, que é o tipo que pode aceitar parâmetros quando invocada por Copilot.
    "extensions": [
  {
    "requirements": {
      "scopes": [
        "workbook"
      ]
    },
    "runtimes": [
      {
        "id": "ContosoAgentRuntime",
        "type": "general",
        "code": {
          "page": "https://localhost:3000/commands.html",
          "script": "https://localhost:3000/commands.js"
        },
        "lifetime": "short",
        "actions": [
          {
            "id": "FillColor",
            "type": "executeDataFunction"
          }
        ]
      }
    ]
  }
]

A documentação de referência para o manifesto JSON está em Referência do esquema de manifesto da aplicação Microsoft 365.

Configurar o agente declarativo

  1. Abra o ficheiro declarativeAgent.json na pasta appPackage .

  2. Substitua o respetivo conteúdo pelo seguinte código. Acerca deste JSON, tenha em atenção o seguinte:

    • A actions.id propriedade neste ficheiro é o ID coletivo de todas as funções no ficheiro especificado em actions.file. Normalmente, não deve corresponder ao extensions.runtimes.actions.id no manifesto, que é o ID de uma ação específica.
    • Crie o ficheiro que especificar na actions.file propriedade num passo seguinte.
    {
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json",
  "version": "v1.4",
  "name": "Excel Agent",
  "description": "Agent for working with Excel cells.",
  "instructions": "You are an agent for working with an add-in. You can work with any cells, not just a well-formatted table.",
  "conversation_starters": [
    {
      "title": "Change cell color",
      "text": "I want to change the color of cell B2 to orange"
    }
  ],
  "actions": [
    {
      "id": "ExcelActions",
      "file": "Office-API-local-plugin.json"
    }
  ]
}

A documentação de referência para agentes declarativos está em Esquema de agente declarativo 1.4 para Microsoft 365 Copilot.

Configurar o plug-in

  1. Crie um ficheiro na pasta appPackage e atribua-lhe o nome atribuído à actions.file propriedade no ficheiro declarativeAgent.json : Office-API-local-plugin.json.

  2. Cole o seguinte conteúdo no ficheiro. Sobre este JSON, tenha em atenção os seguintes detalhes:

    • O ficheiro de configuração do plug-in da API especifica as funções do plug-in no sentido das ações do agente e não das funções JavaScript. Inclui as instruções para cada ação. Também configura o runtime para Copilot. (Configurou o runtime para o Office no manifesto num passo anterior.)
    • O functions.name tem de corresponder à extensions.runtimes.actions.id propriedade no manifesto do suplemento: FillColor.
    • A runtimes.run_for_functions matriz tem de incluir a mesma cadeia de carateres ou functions.name uma cadeia de carateres universais que corresponda à mesma.
    • A runtimes.spec.local_endpoint propriedade especifica que a função JavaScript associada à FillColor cadeia está disponível na Biblioteca JavaScript do Office, em vez de em algum ponto final REST.
    {
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
  "schema_version": "v2.3",
  "name_for_human": "Excel Agent",
  "description_for_human": "Excel actions in agent",
  "namespace": "addInFunction",
  "functions": [
    {
      "name": "FillColor",
      "description": "FillColor changes a single cell location to a specific color.",
      "parameters": {
        "type": "object",
        "properties": {
          "Cell": {
            "type": "string",
            "description": "A cell location in the format of A1, B2, etc.",
            "default": "B2"
          },
          "Color": {
            "type": "string",
            "description": "A color in hex format, e.g., #30d5c8",
            "default": "#30d5c8"
          }
        },
        "required": [
          "Cell",
          "Color"
        ]
      },
      "returns": {
        "type": "string",
        "description": "A string indicating the result of the action."
      },
      "states": {
        "reasoning": {
          "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
          "instructions": "The user will pass ask for a color that isn't in the hex format needed in most cases, make sure to convert to the closest approximation in the right format."
        },
        "responding": {
          "description": "`FillColor` changes the color of a single cell based on the grid location and a color value.",
          "instructions": "If there is no error present, tell the user the cell location and color that was set."
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "LocalPlugin",
      "spec": {
        "local_endpoint": "Microsoft.Office.Addin"
      },
      "run_for_functions": [
        "FillColor"
      ]
    }
  ]
}

A documentação de referência para plug-ins de API está no esquema de manifesto de plug-in da API 2.3 para Microsoft 365 Copilot.

Criar as funções JavaScript

  1. Na raiz do projeto, crie uma pasta com o nome src e, em seguida, crie uma subpasta com o nome comandos.

  2. Na pasta de comandos , crie um ficheiro com o nome commands.ts e atribua-lhe o seguinte conteúdo. Tenha em atenção os seguintes detalhes sobre este código.

    • A fillColor função define a cor de fundo da célula especificada para a cor especificada. Chama objetos e métodos da Biblioteca JavaScript do Office, que é carregada para o runtime javaScript por um ficheiro que cria num passo posterior.
    • O primeiro parâmetro do associate método tem de corresponder exatamente à extensions.runtimes.actions.id propriedade no manifesto e à functions.name propriedade nos plug-ins da API JSON.
    • O message parâmetro é um objeto transmitido pelo runtime copilot para o runtime javaScript no Office. É um objeto que contém o endereço da célula e os parâmetros de cor como o utilizador especificou num pedido de linguagem natural, como "Definir a célula C4 como verde".
    async function fillColor(cell, color) {
  // @ts-ignore
  await Excel.run(async (context) => {
    context.workbook.worksheets.getActiveWorksheet().getRange(cell).format.fill.color = color;
    await context.sync();
  })
}
// @ts-ignore
Office.onReady((info) => {
  // @ts-ignore
  Office.actions.associate("FillColor", async (message) => {
    const { Cell: cell, Color: color } = JSON.parse(message);
    await fillColor(cell, color);
    return "Cell color changed.";
  })
});

  3. Na pasta de comandos , crie um ficheiro com o nome commands.html e atribua-lhe o seguinte conteúdo. Este ficheiro é necessário porque os ficheiros JavaScript não podem ser carregados diretamente para o tipo de runtime que o Office utiliza para plug-ins da API copilot. Em vez disso, um ficheiro HTML com um <script> elemento carrega o JavaScript. Tenha em atenção os seguintes detalhes sobre este ficheiro.

    • Uma vez que a única finalidade do ficheiro é carregar outros ficheiros, o <body> elemento está vazio. O ficheiro não tem IU e nunca é apresentado aos utilizadores.
    • Carrega o ficheiro office.js, que é a Biblioteca JavaScript do Office, a partir de um servidor Microsoft.
    • Não tem um <script> elemento para carregar um ficheiro decommands.js (transpiado do commands.ts que criou) porque este <script> elemento é adicionado no momento da compilação por um ficheiro que adiciona num passo posterior.
    • Quando o projeto é criado e servido num servidor, o URL deste ficheiro HTML corresponde ao valor da extensions.runtimes.code.page propriedade no manifesto. Veja Configurar o manifesto anteriormente neste artigo.
    <html>

<head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />

    <!-- Office JavaScript API -->
    <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>
</head>

<body>
</body>

</html>

Copiar ficheiros de configuração do projeto

O Office utiliza a infraestrutura dos Suplementos do Office para executar plug-ins de API para a biblioteca javaScript do Office. Durante o período de pré-visualização inicial dos plug-ins locais da API do Office, não existe um modelo do Toolkit de Agentes para este tipo de projeto. Por este motivo, alguns ficheiros utilizados pelo Toolkit de Agentes para o desenvolvimento de Suplementos do Office têm de ser adicionados ao projeto. A forma mais rápida de gerar esses ficheiros é criar um projeto de suplemento, copiar os ficheiros necessários do projeto de suplemento para este projeto de agente e, em seguida, fazer algumas edições leves.

  1. Abra uma nova janela de Visual Studio Code.

  2. Selecione Toolkit de Agentes do Microsoft 365 na barra de atividade.

  3. Selecione Criar um Novo Agente/Aplicação.

  4. Selecione Suplemento do Office.

  5. Selecione Painel de tarefas.

  6. Na lista Pastas da Área de Trabalho, selecione Pasta predefinida para armazenar a pasta raiz do projeto na localização predefinida ou navegue para uma pasta onde pretende colocar o novo projeto de agente.

  7. Introduza qualquer cadeia como o Nome da Aplicação e prima Enter.

  8. O projeto é aberto numa nova janela de Visual Studio Code. Feche a nova janela Visual Studio Code e a janela a partir da qual criou o projeto.

  9. Copie os seguintes ficheiros da raiz do projeto de suplemento que criou para a raiz do projeto de plug-in da API. Depois de copiar os ficheiros, elimine a pasta do projeto do suplemento.

    • babel.config.json
    • package.json
    • tsconfig.json
    • webpack.config.js

    Observação

    Alguns dos conteúdos destes ficheiros não são necessários para o projeto de plug-in da API. Nos restantes passos desta secção, só faz as alterações mínimas a estes ficheiros necessários para garantir que o plug-in é executado corretamente. Estamos a trabalhar arduamente para desenvolver um modelo de projeto do Toolkit de Agentes para plug-ins que chamam APIs da Biblioteca JavaScript do Office.

  10. Em Visual Studio Code, abra o ficheiro webpack.config.js.

  11. Localize a definição do entry objeto e, em seguida, elimine a taskpane propriedade do mesmo. Quando terminar, a propriedade deverá ter o entry seguinte aspeto.

    entry: {
  polyfill: ["core-js/stable", "regenerator-runtime/runtime"],
  commands: "./src/commands/commands.ts",
},

  12. Localize a definição da plugins matriz. Na parte superior encontra-se uma chamada de para um painel de new HtmlWebpackPlugin tarefas de suplemento. Elimine esta chamada de new HtmlWebpackPlugin. Quando terminar, toda plugins a matriz deverá ter o seguinte aspeto.

    plugins: [
  new CopyWebpackPlugin({
    patterns: [
      {
        from: "appPackage/assets/*",
        to: "assets/[name][ext][query]",
      },
      {
        from: "appPackage/manifest*.json",
        to: "[name]" + "[ext]",
        transform(content) {
          if (dev) {
            return content;
          } else {
            return content.toString().replace(new RegExp(urlDev, "g"), urlProd);
          }
        },
      },
    ],
  }),
  new HtmlWebpackPlugin({
    filename: "commands.html",
    template: "./src/commands/commands.html",
    chunks: ["polyfill", "commands"],
  }),
],

  13. Na pasta appPackage , existem dois ficheiros de imagem; color.png e outline.png. Para trabalhar com a infraestrutura de ferramentas de suplementos, estes ficheiros têm de ser movidos. Crie uma subpasta com o nome assets na pasta appPackage e mova os dois ficheiros para a mesma.

  14. Abra manifest.json e altere os valores das color propriedades e outline para corresponderem às novas localizações. Quando terminar, a propriedade deverá ter o icons seguinte aspeto.

    "icons": {
    "outline": "assets/outline.png",
    "color": "assets/color.png"
},

Testar o agente e o plug-in

  1. Na interface de linha de comandos (CLI), navegue para a raiz do projeto de plug-in da API e, em seguida, execute npm install. Aguarde a instalação ser concluída.

  2. Feche todos os aplicativos do Office.

  3. No Visual Studio Code, selecione Microsoft 365 Agents Toolkit na barra de atividade e, em seguida, no painel CONTAS, certifique-se de que tem sessão iniciada numa conta do Microsoft 365 na qual o suporte está ativado para o Copilot e para carregar aplicações personalizadas.

  4. Selecione Aprovisionar no painel CICLO DE VIDA .

    Uma captura de ecrã da opção Aprovisionar no painel Ciclo de Vida do Toolkit de Agentes

    Entre outras coisas, o aprovisionamento cria uma pasta de criação dentro da pasta appPackage com o ficheiro zip do pacote. O ficheiro contém o manifesto e os ficheiros JSON para o agente e plug-in.

  5. Na sua CLI na raiz do projeto, execute npm run dev-server para iniciar o servidor no localhost.

    Observação

    Se lhe for pedido para eliminar um certificado antigo e/ou para instalar um novo, aceite ambos os pedidos.

    Aguarde até ver uma linha na janela do servidor semelhante ao seguinte exemplo que indica que a aplicação foi compilada com êxito. Esta saída significa que o servidor está a executar e a servir os ficheiros.

    webpack 5.99.8 compiled successfully in 1090 ms

  6. O primeiro passo no teste depende da plataforma.

    • Para testar no Office no Windows, abra o Excel e, em seguida, abra (ou crie) um livro.
    • Para testar no Office na Web, num browser, navegue até https://excel.cloud.microsofte, em seguida, abra (ou crie) um livro.

  7. Abra Copilot a partir do friso e selecione o controlo de hambúrguer no painel Copilot . O Agente do Excel deve estar na lista de agentes. (Poderá ter de selecionar Ver mais para garantir que todos os agentes estão listados.) Se o agente não estiver listado, experimente uma ou ambas as ações seguintes.

    • Aguarde alguns minutos e recarregue o Copilot.
    • Com Copilot aberto à lista de agentes, coloque o cursor na janela Copilot e prima Ctrl+R.

    Uma captura de ecrã da lista de agentes no painel Copilot numa aplicação do Office

  8. Selecione Agente do Excel, selecione o iniciador de conversação Alterar cor da célula e, em seguida, selecione o controlo Enviar na caixa de conversação na parte inferior do painel. Em alguns segundos, deverá ver um pedido de confirmação semelhante ao seguinte.

    Uma captura de ecrã do agente do Excel a dizer

  9. Selecione Confirmar em resposta ao pedido de confirmação. A cor da célula deve mudar.

    Uma captura de ecrã de um livro do Excel com a célula B2 cor de laranja. À direita, o agente do Excel no painel Copilot diz

    Dica

    Se Copilot comunicar um erro, repita o pedido, mas adicione a seguinte frase ao pedido: "Se receber um erro, comunique-me o texto completo do erro."

  10. Experimente introduzir outras combinações de célula e cor na caixa de conversação, como "Definir a célula G5 para a cor do céu".

Efetuar alterações no agente

O recarregamento em direto e o recarregamento frequente de um plug-in da API do Office não são suportados no período de pré-visualização. Para fazer alterações, primeiro encerre o servidor e desinstale o agente com estes passos.

  1. Encerrar o servidor depende da janela em que está a ser executado.

    • Se o servidor Web estiver em execução na mesma linha de comandos ou Visual Studio Code TERMINAL onde executou npm run dev-server, concentre-se na janela e prima Ctrl+C. Para terminar o processo, selecione "Y" em resposta ao pedido.
    • Se o servidor Web estiver em execução numa janela separada, numa linha de comandos, shell bash ou Visual Studio Code TERMINAL na raiz do projeto, execute npm run stop. A janela do servidor é fechada.

  2. Limpe a cache do Office ao seguir as instruções em Limpar manualmente a cache.

  3. Abra o Teams e selecione Aplicações na barra de atividade e, em seguida, selecione Gerir as suas aplicações na parte inferior do painel Aplicações .

  4. Localize o Excel Agentdev na lista de aplicações.

  5. Para expandir a linha, selecione a seta de cabeça para a esquerda do nome.

    Captura de ecrã da linha da aplicação Agente do Excel na página aplicações do Teams. Existe um ícone de caixote do lixo no lado direito da linha.

  6. Selecione o ícone do caixote do lixo junto à extremidade direita da linha e, em seguida, selecione Remover na linha de comandos.

Faça as alterações e, em seguida, repita os passos em Testar o agente e o plug-in.