Combinar Agentes Copilot com Suplementos do Office (pré-visualização)

2025-06-10

Observação

Este artigo pressupõe que está familiarizado com agentes declarativos da Copilot. Se não estiver, comece com o seguinte:

A inclusão de um agente Microsoft 365 Copilot num Suplemento do Office proporciona duas vantagens:

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 é invocado a partir de um botão ou item de menu.

Também pode pensar num Suplemento do Office como uma competência num agente copilot. Uma vez que os Suplementos do Office utilizam a Biblioteca JavaScript do Office para realizar operações de leitura e escrita em documentos do Office, estas operações tornam-se ações no agente Copilot.

Cenários

Seguem-se algumas formas selecionadas em que adicionar um agente Copilot melhora o valor de um suplemento aos utilizadores.

Aprender a utilizar o suplemento: quando um utilizador precisa de realizar 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 utilize a Biblioteca JavaScript do Office para produzir uma primeira lista de perguntas de rascunho e inseri-las num documento Word.
Análise de conteúdo: um agente pode ser utilizado para analisar o conteúdo de um documento ou folha de cálculo e tomar medidas consoante o que encontrar. Eis alguns exemplos.
- Um agente analisa um Pedido de Proposta 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 pode dizer "Reveja o documento relativamente a quaisquer itens que não tenha visto na lista de auditoria".
Inserção fidedigna de dados: se solicitar um motor de IA típico com uma pergunta, este combinará as informações que encontra e comporá 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 suplemento 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 arrendamento de espaço residencial no Indiana ser quebrado unilateralmente pelo menor?" Em seguida, o suplemento obtém conteúdo, inalterado, de precedentes e estatutos.
- Considere um suplemento que gere o inventário de um recurso digital. Na conversa do agente Copilot, um utilizador pede: "Insira uma tabela das nossas fotografias a cores com o nome de cada uma, o número de vezes que foi transferido e o tamanho em megabytes, ordenado por ordem da maioria dos transferidos." Em seguida, o suplemento obtém estes dados, inalterados, do sistema de registos e insere a tabela numa folha de cálculo do Excel.

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

Um agente Copilot é uma interface de linguagem natural para um suplemento.

Um suplemento pode ser configurado para ser apenas uma competência num agente Copilot. Não tem de incluir um painel de tarefas, botões do friso personalizados ou menus personalizados; mas pode ter qualquer um destes, além de ser uma habilidade copilot. A melhor abordagem depende dos cenários de utilizador que o suplemento deve ativar.

Se o suplemento fornecer ações simples e rápidas que não necessitem de parâmetros transmitidos aos mesmos, inclua botões ou menus personalizados do friso, denominados comandos de suplemento, no suplemento.
Se o suplemento 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 painel de tarefas no suplemento.
Se o suplemento 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.

Observação

Atualmente, apenas os suplementos excel, PowerPoint e Word podem ser configurados como uma competência no Copilot. Estamos a trabalhar para suportar o Outlook.
Os agentes copilot não são atualmente suportados no Office no Mac.
Um suplemento tem de utilizar o manifesto unificado para o Microsoft 365 ser configurado como uma competência no Copilot.
Um suplemento de conteúdo não pode ser uma competência em Copilot.

Tarefas principais

Existem duas tarefas principais para configurar um suplemento como uma competência copilot e são análogas às duas tarefas para configurar comandos de função para um suplemento.

Crie funções JavaScript que implementem as ações do agente.
Utilize JSON para especificar para o Office e os runtimes javaScript os nomes destas funções.

Configuração JSON

A configuração de um suplemento para ser uma competência copilot requer três ficheiros formatados em JSON descritos nas seguintes subsecções.

Manifesto unificado para o Microsoft 365

Existem duas partes do manifesto que configura. Primeiro, crie um objeto de ação que identifique a função JavaScript que é invocada pela ação. Segue-se um exemplo (com algumas marcações desnecessárias omitidas). Observe o seguinte sobre este código.

A propriedade "página" especifica o URL da página Web que contém uma etiqueta de script incorporado que, por sua vez, especifica o URL do ficheiro JavaScript onde a função está definida. 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.
A "actions.id" propriedade no manifesto é o mesmo ID de ação que é transmitido para a chamada de associate.
A "actions.type" propriedade está definida como "executeDataFunction", que é o tipo que pode aceitar parâmetros e pode ser invocada por Copilot.

"extensions": [

    ...

    "runtimes": [
        {
            "id": "CommandsRuntime",
            "type": "general",
            "code": {
                "page": "https://localhost:3000/commands.html"
            },
            "lifetime": "short",
            "actions": [
                {
                    "id": "fillcolor",
                    "type": "executeDataFunction",
                }
            ]
        }
    ]
]

Em segundo lugar, crie um objeto de agente declarativo que identifique o ficheiro que contém a configuração detalhada do agente. Apresentamos um exemplo a seguir.

"copilotAgents": {
    "declarativeAgents": [
        {
        "id": "ContosoCopilotAgent",
        "file": "declarativeAgent.json"
        }
    ]
}

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

Configuração do agente declarativo

O ficheiro de configuração do agente inclui instruções para o agente e especifica um ou mais ficheiros de configuração do plug-in da API que irão conter a configuração detalhada das ações do agente. Apresentamos um exemplo a seguir. Tenha em atenção o seguinte sobre este JSON.

O iniciador de conversação é apresentado na tela de chat de Copilot.
A "actions.id" propriedade neste ficheiro é o ID coletivo de todas as funções no ficheiro especificado em "actions.file". Não tem de corresponder ao "actions.id" no manifesto.

{
    "$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"
        }
    ]
}

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

Configuração do plug-in da API Copilot

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, incluindo as instruções para a ação. Também configura o runtime de JavaScript para Copilot. Apresentamos um exemplo a seguir. Acerca deste JSON, tenha em atenção o seguinte:

O "functions.name" tem de corresponder à "extensions.runtimes.actions.id" propriedade no manifesto do suplemento.
Veja "reasoning.description" e "reasoning.instructions" refere-se a uma função JavaScript, não a uma API REST.
A "responding.instructions" propriedade fornece apenas orientações para Copilot sobre como responder. Não coloca limites nem requisitos estruturais na resposta.
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 é nova e ainda não está na documentação de referência main para o esquema de plug-ins da API. Veja abaixo para obter mais informações. Neste caso, especifica que a função JavaScript associada à cadeia "fillcolor" está disponível num Suplemento do Office, em vez de num ponto final REST. -A "runtimes.spec.allowed_host" propriedade é nova e ainda não está na documentação de referência main para o esquema de plug-ins da API. Veja abaixo para obter mais informações. Neste caso, especifica que o agente só deve estar visível no Excel.

{
    "$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 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"]
        }
    ]
}

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. Segue-se a documentação para duas novas propriedades da "runtimes.spec" propriedade.

Propriedade	Tipo	Descrição
`local_endpoint`	String	Opcional. O ID de um conjunto de funções JavaScript disponíveis. Esta propriedade é aproximadamente análoga à `"runtimes.spec.url"` propriedade, mas para funções locais no cliente, não apIs REST. Atualmente, o único valor permitido é "Microsoft.Office.Addin".
`allowed_host`	String	Opcional. Especifica que aplicação do Office Copilots pode alojar o agente. Os valores possíveis são "documento", "correio", "apresentação" e "livro".

Criar as funções JavaScript

As funções JavaScript que serão invocadas pelo agente Copilot são criadas exatamente como os comandos de função são criados. Apresentamos um exemplo a seguir. Observe o seguinte sobre este código.

Ao contrário de um comando de função, uma função associada a uma ação Copilot pode tomar parâmetros.
O primeiro parâmetro do associate método tem de corresponder à "extensions.runtimes.actions.id" propriedade no manifesto do suplemento e à "functions.name" propriedade no JSON do plug-in da API.

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, color} = JSON.parse(message);
        await fillColor(cell, color);
        return "Cell color changed.";
    });
});

Depois de criar as funções, crie um ficheiro HTML sem IU que contenha uma <script> etiqueta que carregue o ficheiro JavaScript com as funções. O URL deste ficheiro HTML tem de corresponder ao valor da "extensions.runtimes.code.page" propriedade no manifesto. Veja o manifesto unificado do Microsoft 365 anteriormente neste artigo.

Resolução de problemas de agentes e suplementos combinados

Seguem-se alguns problemas comuns e soluções sugeridas.

A ação do agente falha com uma mensagem a indicar que a ação não foi encontrada no suplemento. Seguem-se algumas causas possíveis.
- O "functions.name" valor da propriedade no JSON do plug-in não corresponde exatamente a nenhuma "extensions.runtimes.actions.id" propriedade no manifesto do suplemento.
- Existe uma correspondência "actions.id" no manifesto, mas o valor colateral "actions.type" para o mesmo objeto de ação não é "executeDataFunction".
A ação do agente falha com uma mensagem a indicar que o registo do processador de ações não foi encontrado. Segue-se uma possível causa.
- O JavaScript do suplemento não tem uma chamada de Office.actions.associate com o primeiro parâmetro que corresponda exatamente ao "functions.name" valor da propriedade no JSON do plug-in.