Criar o seu primeiro suplemento como uma competência copilot

2025-06-10

Neste artigo, irá percorrer o processo de criação de um agente do Excel Copilot simples que pode realizar ações no conteúdo de um livro do Excel. A aplicação também inclui um suplemento do painel de tarefas do Excel.

Pré-requisitos de conhecimento

Uma compreensão básica dos agentes declarativos no Microsoft 365 Copilot. Se ainda não estiver familiarizado com os mesmos, recomendamos as seguintes ações.
- Leia Agentes declarativos para Microsoft 365 Copilot descrição geral.
- Conclua o tutorial que começa em Criar agentes declarativos com o Toolkit de Agentes do Microsoft 365.

Pré-requisitos de software

Todos os pré-requisitos listados em Criar agentes declarativos com o Microsoft 365 Agent Toolkit.
O Toolkit de Agentes do Microsoft 365.

Começar com um Suplemento do Office

Crie um suplemento básico do Excel com os seguintes passos.

Crie um Suplemento do Office no Toolkit de Agentes do Microsoft 365 ao seguir as instruções em Criar projetos de Suplemento do Office com o Toolkit de Agentes do Microsoft 365. Pare depois de o projeto ser criado. Não execute os passos na secção sideloading.

Observação

Quando lhe for pedido para atribuir um nome ao suplemento, utilize "Suplemento do Excel + Agente".
O projeto é aberto numa nova janela de Visual Studio Code. Feche a janela de Visual Studio Code original.
Numa linha de comandos ou Visual Studio Code TERMINAL na raiz do projeto, execute npm install.

Sideload and test the add-in (Sideload and test the add-in)

Teste se o suplemento funciona ao realizar os seguintes passos.
1. Selecionar Ver | Execute em Visual Studio Code. No menu pendente EXECUTAR E DEPURAR, selecione Excel Desktop (Edge Chromium).
2. Pressione F5. O projeto é compilação e é aberta uma janela Dev-Server do Nó. Este processo pode demorar alguns minutos. Eventualmente, o Excel é aberto.
Observação

Se esta for a primeira vez que tem sideload de um Suplemento do Office no seu computador (ou a primeira vez em mais de um mês), poderá ser-lhe pedido para eliminar um certificado antigo e/ou para instalar um novo. Concorde com ambos os pedidos.
1. Selecione o botão Suplementos no friso Base e, em seguida, na lista de opções que é aberta, selecione o seu suplemento.
2. Será apresentado um grupo de Suplementos da Contoso com o botão Mostrar Painel de Tarefasno friso Base. Utilize o botão para abrir o painel de tarefas do suplemento.
Observação

Se for apresentada uma linha de comandos Parar Ao Carregar da WebView , selecione OK.
1. Quando o painel de tarefas for aberto, selecione Executar. Uma célula na folha de cálculo muda para amarelo.
2. Pare a depuração e desinstale o suplemento ao encerrar o Excel e executar npm run stop numa linha de comandos ou Visual Studio Code TERMINAL na raiz do projeto.
  
  Importante
  
  Parar a depuração na IU do Visual Studio Code não funciona atualmente devido a um erro. Além disso, não fechar o Excel nem fechar manualmente a janela do servidor dev encerrou de forma fiável o servidor ou faz com que o Excel não requisira o suplemento. Tem de executar npm run stop.

Adicionar um agente declarativo copilot

Adicione o agente com os seguintes passos.

No ficheiro de manifesto, faça as seguintes alterações.
1. Adicione o seguinte objeto à raiz. Por convenção, é colocado imediatamente abaixo da propriedade "validDomains". Crie o ficheiro "declarativeAgent.json" num passo posterior.
```
"copilotAgents": {
  "declarativeAgents": [
    {
      "id": "ContosoCopilotAgent",
      "file": "declarativeAgent.json"
    }
  ]
},
```
2. Existem vários objetos na "extensions.runtimes" matriz. Localize aquele cujo "id" é "CommandRuntime" e copie-o como um objeto de runtime adicional na matriz.
3. Faça as seguintes alterações a este objeto de runtime adicional.
  1. Altere de "id" "CommandRuntime" para "CopilotAgentActionsRuntime".
  2. Altere a respetiva "actions.id" propriedade para "fillcolor". Este é o ID de uma função que adiciona num passo posterior.
  3. Altere a "actions.type" propriedade para "executeDataFunction".
Crie um ficheiro na pasta appPackage com o nome declarativeAgent.json.

Cole o seguinte conteúdo no ficheiro. (Crie o ficheiro Excel-API-local-plugin.json mencionado neste JSON num passo posterior.)

{
     "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json",
     "version": "v1.4",
     "name": "Excel Add-in + 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": "localExcelPlugin",
             "file": "Excel-API-local-plugin.json"
         }
     ]
 }

Crie um ficheiro na pasta appPackage com o nome Excel-API-local-plugin.json.

Cole o seguinte conteúdo no ficheiro.

{
     "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.3/schema.json",
     "schema_version": "v2.3",
     "name_for_human": "Excel Add-in + Agent",
     "description_for_human": "Add-in Actions in Agents",
     "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",
                 "allowed_host": ["workbook"]
             },
             "run_for_functions": ["fillcolor"]
         }
     ]
 }

Abra o ficheiro \src\commands\commands.ts e adicione o seguinte código no final do mesmo.

async function fillcolor(cell, color) {
    await Excel.run(async (context) => {
         context.workbook.worksheets
             .getActiveWorksheet()
             .getRange(cell).format.fill.color = color;
         await context.sync();
     })
}

Office.onReady((info) => {
     Office.actions.associate("fillcolor", async (message) => {
         const {Cell: cell, Color: color} = JSON.parse(message);
         await fillcolor(cell, color);
         return "Cell color changed.";
     });
});

Atualizar ficheiros de configuração do projeto para um suplemento combinado e um agente Copilot

Existe um ficheiro chamado teamsapp.yaml ou m365agents.yaml na raiz do projeto. Substitua o respetivo conteúdo pelo seguinte:

# yaml-language-server: $schema=https://aka.ms/teams-toolkit/v1.7/yaml.schema.json
# Visit https://aka.ms/teamsfx-v5.0-guide for details on this file
# Visit https://aka.ms/teamsfx-actions for details on actions
version: v1.7

environmentFolderPath: ./env

# Triggered when 'teamsapp provision' is executed
provision:
# Creates a Teams app
  - uses: teamsApp/create
    with:
     # Teams app name
     name: Contoso Agent ${{APP_NAME_SUFFIX}}
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     teamsAppId: TEAMS_APP_ID

# Build Teams app package with latest env value
  - uses: teamsApp/zipAppPackage
    with:
     # Path to manifest template
     manifestPath: ./appPackage/manifest.json
     outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
     outputFolder: ./appPackage/build
# Validate app package using validation rules
  - uses: teamsApp/validateAppPackage
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Extend your Teams app to Outlook and the Microsoft 365 app
  - uses: teamsApp/extendToM365
    with:
     # Relative path to the build app package.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     titleId: M365_TITLE_ID
     appId: M365_APP_ID

# Triggered when 'teamsapp publish' is executed
publish:
# Build Teams app package with latest env value
  - uses: teamsApp/zipAppPackage
    with:
     # Path to manifest template
     manifestPath: ./appPackage/manifest.json
     outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
     outputFolder: ./appPackage/build
# Validate app package using validation rules
  - uses: teamsApp/validateAppPackage
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Apply the Teams app manifest to an existing Teams app in
# Teams Developer Portal.
# Will use the app id in manifest file to determine which Teams app to update.
  - uses: teamsApp/update
    with:
     # Relative path to this file. This is the path for built zip file.
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
# Publish the app to
# Teams Admin Center (https://admin.teams.microsoft.com/policies/manage-apps)
# for review and approval
  - uses: teamsApp/publishAppPackage
    with:
     appPackagePath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
    # Write the information of created resources into environment file for
    # the specified environment variable(s).
    writeToEnvironmentFile:
     publishedAppId: TEAMS_APP_PUBLISHED_APP_ID
projectId: da53b0a2-1561-415e-919a-5b870bcd2f49

Substitua o valor de projectId na última linha de conteúdo que colou no passo anterior por um novo GUID gerado aleatoriamente.
Abra o ficheiro \env.env.dev e adicione as seguintes linhas ao final do ficheiro, logo após a linha "ADDIN_ENDPOINT=".
```
TEAMS_APP_ID=
TEAMS_APP_TENANT_ID=
M365_TITLE_ID=
M365_APP_ID=
```

Testar o suplemento e o agente

Feche todos os aplicativos do Office.
Abra o Toolkit de Agentes do Microsoft 365.
No painel Ciclo de Vida , selecione Aprovisionar. Entre outras coisas, o aprovisionamento faz o seguinte:
- Defina valores para as quatro linhas que adicionou ao ficheiro .env.dev.
- Crie uma pasta /build 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.
Numa linha de comandos ou Visual Studio Code TERMINAL na raiz do projeto, execute npm run dev-server para iniciar o servidor no localhost. Aguarde até ver uma linha na janela do servidor que a aplicação compilou com êxito. Isto significa que o servidor está a executar e a servir os ficheiros.

Observação

Se esta for a primeira vez que executa um servidor local para um Suplemento do Office no seu computador, poderá ser-lhe pedido que elimine um certificado antigo e/ou que instale um novo. Concorde com ambos os pedidos.
O primeiro passo no teste depende da plataforma.
- Para testar no Office no Windows, abra o Excel. Dentro de momentos, o botão Mostrar Painel de Tarefas é apresentado no friso Base do grupo Suplemento Contoso. (Se não aparecer no friso, selecione o botão Suplementos no friso e, em seguida, selecione a aplicação Suplemento do Excel + Agente na lista de opções que é aberta.)
- Para testar no Office na Web, num browser, navegue para https://excel.cloud.microsoft.com/e, em seguida, crie um novo livro.
Abra Copilot a partir do friso e selecione o controlo de hambúrguer no painel Copilot . O Suplemento do Excel + Agente 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, experimente uma ou ambas as ações seguintes.
- Aguarde alguns minutos e recarregue o Copilot.
- Com Copilot aberto à lista de agentes, clique no cursor na janela Copilot e prima Ctrl+R.
Quando o agente estiver listado, selecione-o. O painel Suplemento do Excel + Agente é aberto.
Selecione o iniciador de conversação Alterar cor da célula e, em seguida, prima o controlo Enviar na caixa de conversação na parte inferior do painel. Selecione Confirmar em resposta ao pedido de confirmação. A cor da célula deve mudar.

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."
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 suplemento ou no agente

O recarregamento dinâmico e o recarregamento frequente de um suplemento combinado e do agente não são suportados no período de pré-visualização. Para fazer alterações, encerre primeiro o servidor e desinstale a extensão com estes passos.

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. Escolha "Y" em resposta ao pedido para terminar o processo.
- Se o servidor Web estiver em execução numa janela separada, numa linha de comandos ou Visual Studio Code TERMINAL na raiz do projeto, execute npm run stop.
Limpe a cache do Office ao seguir as instruções em Limpar manualmente a cache.
Abra o Teams, selecione Aplicações na barra de aplicações e, em seguida, selecione Gerir as suas aplicações na parte inferior do painel Aplicações .
Localize o Suplemento do Excel + Agente na lista de aplicações e selecione a seta de cabeça para a esquerda do nome para expandir a linha.
Selecione o ícone do caixote do lixo junto à extremidade direita da linha e, em seguida, selecione Remover na linha de comandos.

Faça as suas alterações e, em seguida, repita os passos em Testar o suplemento e o agente.

Compartilhar via

Criar o seu primeiro suplemento como uma competência copilot

Pré-requisitos de conhecimento

Pré-requisitos de software

Começar com um Suplemento do Office

Sideload and test the add-in (Sideload and test the add-in)

Adicionar um agente declarativo copilot

Atualizar ficheiros de configuração do projeto para um suplemento combinado e um agente Copilot

Testar o suplemento e o agente

Efetuar alterações no suplemento ou no agente

Solução de problemas

Próximas etapas

Confira também

Comentários

Recursos adicionais