Agente autônomo Copilot Studio Excel: guia completo

O problema que esse padrão resolve

Boa parte do trabalho manual em operações administrativas ainda passa por uma planilha Excel parcialmente preenchida. Alguém lança datas, fornecedores e valores, e uma segunda pessoa entra depois para classificar cada linha de acordo com uma tabela de referência, seja um plano de contas, uma tabela de centros de custo ou um catálogo de categorias. É um trabalho repetitivo, baseado em regras conhecidas, e justamente por isso é um bom candidato a automação com IA.

Os agentes autônomos do Copilot Studio mudam a forma como esse tipo de tarefa pode ser resolvido. Diferente de um agente conversacional que espera uma pergunta do usuário, um agente autônomo pode ser disparado por um evento, como a criação de um arquivo em uma biblioteca do SharePoint, ler o conteúdo desse arquivo, consultar uma base de conhecimento para decidir o que fazer e escrever o resultado de volta na própria planilha, sem intervenção humana no meio do processo.

Este artigo detalha a arquitetura e a construção de um agente desse tipo: ele lê uma planilha Excel armazenada no SharePoint, usa uma base de conhecimento em PDF para decidir os valores corretos de cada linha e grava o resultado de volta no arquivo original via Graph API. O exemplo usado aqui é genérico o suficiente para ser adaptado a qualquer cenário de preenchimento de planilha guiado por regras, não apenas relatórios financeiros.

Visão geral da arquitetura

Antes de entrar nos cliques, vale entender os blocos que compõem a solução, porque cada um resolve um problema técnico específico:

• Gatilho de arquivo criado no SharePoint: dispara o agente automaticamente quando um novo Excel entra na biblioteca, sem precisar de um usuário chamando o agente no chat.
• Tópico de leitura: usa o conector do SharePoint para baixar o conteúdo do arquivo e um prompt com code interpreter para transformar o conteúdo binário em um JSON estruturado de células e valores.
• Base de conhecimento: um PDF com as regras de negócio, os códigos válidos e suas descrições, para o agente decidir com base em dados reais, não em suposição.
• Ferramenta de escrita: um agent flow que recebe a lista de células a atualizar e usa a Graph API para escrever os valores de volta na planilha, célula por célula.

O ponto central dessa arquitetura é a separação entre leitura e escrita. O agente nunca edita o Excel diretamente, ele delega essa responsabilidade a uma ferramenta determinística que fala com o Microsoft Graph. Isso é proposital: modelos de linguagem são bons em decidir o que escrever, mas a operação de escrita em si precisa ser previsível, auditável e testável fora do contexto do modelo.

Passo 1: preparar a biblioteca no SharePoint

Crie uma biblioteca de documentos dedicada, por exemplo Relatórios de Despesas ou qualquer nome que faça sentido para o processo que você está automatizando. Adicione a essa biblioteca o arquivo Excel que será processado, já parcialmente preenchido com os dados que o agente vai ler, deixando em branco as colunas que o agente deve completar.

Manter essa biblioteca separada de outras é uma decisão de arquitetura, não só de organização. O gatilho do agente reage a qualquer arquivo criado na biblioteca configurada, então misturar esse fluxo com uma biblioteca de uso geral aumenta o risco de o agente disparar em arquivos que não deveriam ser processados.

Passo 2: criar o agente e configurar orquestração generativa

Crie um novo agente no Copilot Studio, por exemplo com o nome Excel Auto Agent. Ative o modo de orquestração generativa e defina o modelo como GPT-5 Chat. A orquestração generativa é o que permite ao agente decidir sozinho a ordem de execução de tópicos e ferramentas com base nas instruções, em vez de seguir um fluxo de conversa rígido.

Use uma descrição objetiva para o agente, algo como um agente que lê e escreve em arquivos Excel armazenados em uma biblioteca do SharePoint. Essa descrição importa mais do que parece: é ela que ajuda o orquestrador a decidir quando e como invocar o agente em cenários de composição com outros agentes.

Nas instruções do agente, seja explícito sobre a sequência esperada e sobre o limite de decisão. Um exemplo de instrução funcional:

Objetivo: o agente deve preencher um relatório com os códigos e nomes de conta corretos, usando sua base de conhecimento.
Instruções:
1. Execute o tópico “Ler um Arquivo Excel”.
2. Consulte o arquivo de conhecimento com a lista de códigos válidos.
3. Execute a ferramenta “Escrever Valores de Célula em uma Planilha Excel” para atualizar o arquivo.
NÃO atribua um código ou nome de conta que não apareça na base de conhecimento.

Essa última linha é a que evita alucinação. Sem essa restrição explícita, o modelo pode inventar um código plausível quando não encontra uma correspondência exata na base de conhecimento, o que é pior do que deixar a célula em branco.

Passo 3: configurar o gatilho de criação de arquivo

No painel geral do agente, adicione um gatilho e selecione quando um arquivo é criado (somente propriedades). Escolha o site e a biblioteca do SharePoint configurados no passo 1 e confirme a criação do gatilho.

O “somente propriedades” no nome do gatilho importa: ele dispara com base em metadados do evento, sem carregar o conteúdo binário do arquivo automaticamente. É por isso que o próximo passo precisa buscar o conteúdo explicitamente.

Passo 4: ler o conteúdo do Excel

Crie um novo tópico chamado Ler um Arquivo Excel. Ele precisa de uma variável de entrada com o caminho completo do arquivo capturado no gatilho. Na seção de detalhes do tópico, adicione uma variável de entrada:

• Nome: CreatedFileFullPath
• Preenchimento: dinâmico, com a melhor opção decidida pelo agente
• Tipo: string
• Descrição: caminho completo do arquivo que disparou o agente

Defina o tipo de gatilho do tópico como “o agente escolhe” e descreva o propósito do tópico de forma clara: obter o conteúdo de um arquivo Excel e extrair seus dados para um array JSON. Adicione um node do conector SharePoint, Obter Conteúdo do Arquivo Usando Caminho, apontando para o endereço do site e usando a variável CreatedFileFullPath como caminho do arquivo.

Transformar o Excel em JSON com um prompt de code interpreter

O conteúdo bruto retornado pelo conector é binário. Para transformá-lo em algo que o agente consiga interpretar célula por célula, use um node de prompt com code interpreter habilitado. Crie um prompt chamado, por exemplo, Valores da Planilha Excel para JSON, com uma variável de entrada do tipo documento recebendo o arquivo Excel.

As instruções do prompt precisam ser específicas sobre o formato de saída esperado, porque é esse JSON que alimenta todo o resto da automação:

Objetivo: ler um arquivo Excel e extrair os valores das células em cada planilha.
Instruções:
1. Abra a pasta de trabalho e obtenha todas as planilhas.
2. Obtenha o intervalo usado de cada planilha.
3. Extraia o valor de todas as células não vazias do intervalo usado como strings.
4. Retorne a resposta em formato JSON, conforme o esquema abaixo.

O esquema de saída deve seguir este formato:

{
  "worksheets": [
    {
      "worksheet_name": "Plan1",
      "cells": [
        {"range": "A1", "value": "valor1"},
        {"range": "B1", "value": "valor2"},
        {"range": "C3", "value": "valor3"}
      ]
    }
  ]
}

Habilite o code interpreter no prompt, isso é o que dá a ele capacidade de abrir o arquivo Excel como um documento real e processar seu conteúdo em vez de tratá-lo como texto simples. Defina o tipo de saída como JSON e rode um teste antes de seguir adiante, para confirmar que o esquema retornado bate com o esperado.

Armazenar o resultado em uma variável de saída estruturada

O JSON produzido pelo prompt precisa virar uma variável de saída do tópico, porque outros componentes do agente vão consumir esse dado. Nos detalhes do tópico, seção de saídas, crie uma variável:

• Nome: ExcelFileValues
• Tipo: Record
• Descrição: localização das células e valores de cada planilha do arquivo Excel

O esquema do Record deve refletir a estrutura aninhada do JSON: um objeto raiz com uma tabela de planilhas, cada uma com nome e uma tabela de células, cada célula com um endereço de intervalo e um valor em texto. Definir esse schema corretamente evita que o orquestrador trate o resultado como texto livre, o que quebraria a passagem de dados para a ferramenta de escrita mais adiante.

Passo 5: a base de conhecimento que guia as decisões

Sem uma base de conhecimento, o agente teria que adivinhar os valores corretos com base apenas no seu treinamento geral, o que é inaceitável em qualquer processo que dependa de uma tabela de referência específica da organização. Faça upload de um PDF com a lista de códigos, nomes e descrições válidos na seção de conhecimento do agente.

Escreva uma descrição de uso para esse arquivo de conhecimento, explicando ao agente para que ele serve, por exemplo: este arquivo contém a lista de códigos válidos, seus nomes e descrições, e deve ser usado para classificar cada linha de um relatório. Essa descrição é o que orienta o modelo a consultar o documento certo no momento certo, em vez de tratá-lo como um anexo qualquer.

Um ponto de atenção real aqui: a qualidade da classificação do agente é diretamente proporcional à qualidade e à granularidade do PDF de referência. Um documento com descrições vagas gera classificações inconsistentes. Vale investir tempo em deixar essa base de conhecimento bem escrita antes de testar o agente em produção.

Passo 6: a ferramenta que escreve de volta no Excel via Graph API

Depois de decidir os valores corretos, o agente precisa de uma forma confiável de gravá-los na planilha. Essa parte não é feita por um prompt, é feita por um agent flow, que funciona como uma ferramenta determinística chamada pelo orquestrador.

Na seção de ferramentas do agente, adicione uma nova ferramenta do tipo agent flow. O gatilho padrão será “quando um agente chama o flow”. Configure quatro entradas de texto:

• Drive ID
• Drive Item ID
• Worksheet Name
• Cell Values

Convertendo os valores de célula em array JSON

A entrada Cell Values chega como texto, mas o flow precisa dela como array estruturado para iterar item a item. Adicione uma ação de Analisar JSON, apontando o conteúdo para essa variável de entrada, e use o seguinte esquema:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "range": { "type": "string" },
      "value": { "type": "string" }
    },
    "required": ["range", "value"]
  }
}

Gravando cada célula com uma chamada PATCH ao Graph API

Adicione um loop “Aplicar a cada” usando o corpo da ação de Analisar JSON como coleção de origem. Dentro do loop, insira uma ação HTTP com Microsoft Entra ID (pré-autorizado), Invocar uma solicitação HTTP. Essa variante do conector HTTP é o que permite autenticar contra o Graph API usando a identidade do próprio ambiente, sem precisar gerenciar tokens manualmente.

Configure a conexão com:

• Tipo de autenticação: entrar com Microsoft Entra ID
• URI de recurso do Entra ID: https://graph.microsoft.com
• URL base do recurso: https://graph.microsoft.com

O método da requisição deve ser PATCH, já que estamos atualizando um intervalo existente, não criando um recurso novo. A URI da requisição referencia o drive, o item e a planilha recebidos como entrada, além do endereço do intervalo vindo do item atual do loop:

v1.0/drives/@{triggerBody()?['text']}/items/@{triggerBody()?['text_1']}/workbook/worksheets/@{triggerBody()?['text_2']}/range(address='@{items('Apply_to_each')?['range']}')

Use o cabeçalho Content-Type com valor application/json, e o corpo da requisição no formato exigido pela API de workbook do Graph, que espera os valores como uma matriz bidimensional mesmo quando é uma única célula:

{
  "values": [["@{items('Apply_to_each')?['value']}"]]
}

Finalize o flow respondendo ao agente, para que o orquestrador saiba que a ferramenta concluiu a execução e possa seguir com a conversa ou encerrar a tarefa.

Descrevendo a ferramenta para o orquestrador

De volta ao Copilot Studio, abra a ferramenta recém-criada e escreva uma descrição objetiva, por exemplo esta ferramenta é usada para escrever valores em uma planilha Excel. Depois, descreva cada entrada individualmente, porque é esse texto que o modelo usa para decidir o que passar em cada campo:

• Cell Values: um array de objetos com as propriedades range e value, no formato [{"range": "A1", "value": "XYZ"}, {"range": "B2", "value": "XYZ"}].
• Drive ID: valor da propriedade {DriveId} do gatilho de criação de arquivo.
• Drive Item ID: valor da propriedade {DriveItemId} do mesmo gatilho.
• Worksheet Name: o nome da planilha onde os valores devem ser gravados.

Deixe a propriedade de identificação como a resposta inteira do usuário. Essas descrições substituem, na prática, a documentação de uma API tradicional: é o texto que o modelo lê para decidir como preencher os parâmetros da chamada.

Passo 7: publicar e testar

Publique o agente e rode um teste disparando o gatilho de criação de arquivo no SharePoint. O fluxo esperado é: o agente lê o Excel, consulta a base de conhecimento, decide os valores corretos linha a linha e grava o resultado de volta no arquivo original, célula por célula, via Graph API.

Vale conferir o histórico de execução do agente depois do teste, não só o resultado final na planilha. Nele é possível ver exatamente qual raciocínio o modelo seguiu para chegar em cada valor, o que ajuda a calibrar as instruções e a base de conhecimento quando alguma classificação sai errada.

Limites reais e decisões de arquitetura que a fonte não cobre

Esse padrão funciona bem, mas tem restrições que valem a pena conhecer antes de colocar em produção.

• Timeout em arquivos grandes: cada ação de flow tem um limite máximo de execução. Planilhas com centenas de linhas podem estourar esse limite no meio do loop de escrita. A saída prática é dividir a escrita em lotes, processando um intervalo de linhas por execução, ou reestruturar a chamada para gravar múltiplos intervalos em uma única requisição em vez de uma PATCH por célula.
• Consumo de mensagens do code interpreter: prompts com code interpreter habilitado consomem mais capacidade de mensagens do que um prompt de texto simples, porque o Copilot Studio precisa provisionar um ambiente de execução de código para processar o arquivo. Em ambientes com muitos agentes autônomos rodando em paralelo, isso pesa no consumo de licença e merece ser monitorado.
• Permissões da Graph API: a ação HTTP com Entra ID pré-autorizado depende de uma identidade com escopo adequado sobre o drive do SharePoint, tipicamente Files.ReadWrite.All ou Sites.ReadWrite.All. Isso exige consentimento de administrador e uma decisão consciente sobre o escopo mínimo necessário, já que conceder acesso amplo demais a um flow que escreve arquivos é um risco de governança, não só um detalhe técnico.
• Concorrência: se dois arquivos forem criados quase ao mesmo tempo na mesma biblioteca, duas execuções do agente podem rodar em paralelo. Isso normalmente não é problema quando cada execução trabalha em um arquivo diferente, mas merece atenção se o processo depender de algum estado compartilhado entre execuções.
• Qualidade da base de conhecimento: o agente só é tão bom quanto o documento que orienta suas decisões. Vale tratar esse PDF como um artefato vivo, revisado quando as regras de negócio mudam, e não como um upload único feito na configuração inicial.

Onde esse padrão se encaixa na operação

O valor real desse tipo de agente não está em substituir uma pessoa, está em eliminar o intervalo de tempo entre o lançamento de um dado bruto e sua classificação final. Qualquer processo em que alguém preenche parcialmente uma planilha e outra pessoa completa depois com base em uma tabela de referência fixa é candidato: reconciliação de lançamentos, enriquecimento de cadastros, classificação de itens em um inventário, ou preenchimento de campos derivados em relatórios operacionais.

A arquitetura descrita aqui, leitura via code interpreter, decisão via base de conhecimento e escrita via Graph API, é reaproveitável para qualquer desses cenários trocando apenas o PDF de referência e as instruções do agente. É esse desacoplamento entre lógica de negócio e mecânica de leitura e escrita que torna o padrão sustentável para além de um único caso de uso.

Se sua operação tem esse tipo de gargalo repetitivo em planilhas e você quer avaliar se um agente autônomo no Copilot Studio se paga no seu contexto, a Trinapse pode ajudar a desenhar essa arquitetura considerando licenciamento, governança de dados e integração com o restante do ambiente Microsoft 365.