Como gerar documento Word no Copilot Studio com template

O que muda quando o agente entrega o Word pronto

A maioria das automações de documento que vemos em operações de qualquer porte segue o mesmo roteiro manual: alguém recebe um pedido, abre um modelo, copia dados de uma planilha ou de um sistema, cola no lugar certo, revisa e salva. Cotações, contratos, laudos, propostas, relatórios de avaliação. O documento final é sempre um Word ou algo derivado dele, e o trabalho humano está quase todo em transcrever informação de um lugar para outro.

Um agente do Copilot Studio pode assumir essa transcrição. O usuário descreve o que precisa em linguagem natural, o agente interpreta o pedido, busca o que falta em fontes de conhecimento como Excel, SharePoint ou Dataverse, preenche um template Word já formatado e devolve um link para o arquivo pronto, editável, dentro da própria conversa. Não é geração de texto livre em um documento genérico. É preenchimento estruturado de um modelo que a organização já usa e já aprovou visualmente.

O resto deste artigo detalha a arquitetura completa: como desenhar o template com placeholders, como montar o agent flow que faz o preenchimento, como salvar o arquivo e devolver um link em vez do binário, e como aterrar o agente em dados reais para que ele precise de cada vez menos informação explícita do usuário.

Desenhando o template Word com placeholders

O ponto de partida é um documento Word comum, com a formatação que a organização já usa para o tipo de documento em questão. Pode ser um template de fatura, um modelo de contrato ou um layout de laudo técnico. A diferença para um documento normal é a inserção de placeholders nos pontos onde o valor precisa ser dinâmico.

O formato de placeholder é {{NomeDoCampo}}, digitado diretamente no corpo do texto, em qualquer lugar do documento. Cada nome de campo precisa ser único no template inteiro. Se o campo faz parte de uma lista repetida, como linhas de produto em uma cotação, o formato muda para {{NomeDaTabela.NomeDoCampo}}, e esse placeholder precisa necessariamente estar dentro de uma tabela do Word, não em um parágrafo solto. Essa é a primeira armadilha real do processo: um placeholder de tabela fora de uma tabela não é reconhecido como estrutura repetível, e o preenchimento falha silenciosamente ou gera um resultado com uma única linha em vez de uma lista completa.

Para uma cotação comercial, um conjunto de placeholders típico seria:

• {{QuoteDate}}, {{QuoteNumber}}
• {{CustomerNumber}}, {{CustomerName}}, {{CustomerAddress}}, {{CustomerCity}}, {{CustomerState}}, {{CustomerZipCode}}
• Dentro de uma tabela: {{Product.Quantity}}, {{Product.Description}}, {{Product.UnitPrice}}, {{Product.Total}}
• {{TotalAmount}}

O mesmo racional vale para qualquer outro tipo de documento. Um contrato teria placeholders para partes, vigência e cláusulas variáveis. Um laudo teria placeholders para item avaliado, data da vistoria, parecer e responsável técnico. A lógica de construção é idêntica, só muda o vocabulário dos campos.

Construindo o agent flow que preenche o template

Dentro do Copilot Studio, o mecanismo que conecta a conversa ao preenchimento do Word é um agent flow, que por baixo dos panos é um fluxo de nuvem do Power Automate acionado pelo agente. No menu de ferramentas do agente, adiciona-se uma nova ferramenta do tipo Agent flow.

O gatilho desse fluxo precisa de uma entrada de texto, geralmente chamada de user message, que carrega toda a informação que o agente conseguiu extrair da conversa. É essa string que alimenta o passo seguinte.

A ação Run a Prompt: da linguagem natural ao Word preenchido

Dentro do fluxo, adiciona-se uma ação Run a Prompt com um prompt customizado, referenciando o template Word carregado anteriormente e usando um texto de instrução do tipo:

Create a quote based on the user's message [User Message]

É importante testar esse prompt com uma mensagem de exemplo que já traga todos os valores explícitos, mesmo sabendo que na prática o usuário raramente escreveria uma mensagem tão detalhada. O objetivo desse teste inicial é validar que o mapeamento de placeholders está correto antes de introduzir aterramento em fontes externas. Uma mensagem de teste razoável:

Preciso de uma cotação para o cliente ABC Company, endereço Rua das Cerejeiras 123, Boston, MA, 90021. Número de cliente C1099. Itens: Produto A, 3 unidades a R$100 cada, total R$300; Produto B, 1 unidade a R$75; Produto C, 6 unidades a R$250 cada, total R$1500. Data da cotação 2026-01-01. Número da cotação 9999.

Ao rodar o teste, o resultado deve mostrar todos os placeholders do template já substituídos pelos valores correspondentes. Se algum campo ficar com o placeholder intacto no documento final, o nome usado no prompt ou na descrição da entrada não bate com o nome usado no template, e vale revisar a grafia exata de cada {{Campo}}.

Salvando o arquivo e devolvendo um link, não o binário

Depois que o Word é gerado, a tentação natural é devolver o arquivo inteiro para o Copilot Studio. Essa não é a arquitetura correta. Toda resposta enviada de volta a um agente, seja via agent flow, seja via qualquer chamada de API, tem limite de tamanho. Um documento com imagens, tabelas grandes ou formatação pesada pode facilmente estourar esse limite. A prática correta é salvar o arquivo em um repositório, como o OneDrive do usuário ou uma biblioteca do SharePoint, e devolver ao agente apenas um link de download.

O fluxo típico usa uma ação OneDrive – Create file, apontando para uma pasta específica e recebendo o conteúdo do documento gerado pela ação Run a Prompt no campo de conteúdo do arquivo.

Nome de arquivo único e caminho completo

O nome do arquivo passado para a ação de criação precisa ser único, senão o Power Automate sobrescreve ou falha ao gerar o arquivo, dependendo da configuração. Uma técnica simples é concatenar um prefixo com um valor aleatório:

concat(concat('QuoteFile_', rand(1000, 9999)), '.docx')

Em produção, prefira um timestamp ou um identificador vindo do próprio processo de negócio, como o número da cotação, em vez de um número aleatório entre 1000 e 9999, que tem chance real de colisão em volumes maiores.

Para montar o link completo do documento, é preciso o nome de usuário principal (UPN) de quem está usando o agente. Uma ação Office 365 Users – Get my profile (V2) retorna esse dado. O UPN contém caracteres como @ e ., que não são seguros dentro de uma URL montada por concatenação, então é preciso normalizá-los antes de compor o caminho:

replace(replace(outputs('Get_my_profile_(V2)')?['body/userPrincipalName'], '@', '_'), '.', '_')

Com o UPN normalizado e o domínio do tenant, que pode ser copiado direto da barra de endereço do navegador ao abrir o OneDrive, monta-se o caminho completo do arquivo em uma ação Compose.

Codificando a URL corretamente

A última etapa antes de devolver o resultado ao agente é a codificação da URL. Espaços, acentos e caracteres especiais no caminho do arquivo quebram o link se não forem tratados. A função encodeUriComponent resolve isso:

encodeUriComponent(outputs('Compose:_Full_Path'))

O fluxo termina com uma ação Respond to the Agent, expondo uma variável de texto, algo como FullPath, com uma descrição clara do que ela representa, por exemplo “link de download da cotação gerada pelo agente”. É essa descrição que orienta o modelo do Copilot Studio sobre como apresentar o link de volta ao usuário no chat.

Configurando o agente no Copilot Studio

Com o agent flow publicado, volta-se ao Copilot Studio para configurar a ferramenta. Na aba de ferramentas, abre-se o fluxo recém-criado e adiciona-se uma descrição objetiva, do tipo “use esta ação para gerar uma cotação”. Em seguida, configura-se a descrição da variável de entrada (a user message), detalhando exatamente quais informações o agente deve reunir antes de acionar o fluxo:

Inclua as seguintes informações na mensagem passada para o fluxo: data da cotação, número da cotação, número do cliente (somente se identificado, no padrão C0000), nome do cliente, endereço completo, tabela de produtos com quantidade, descrição, preço unitário e total da linha, e o valor total da cotação.

Por fim, na aba de instruções gerais do agente, define-se o comportamento esperado de forma direta:

Quando uma cotação for solicitada:
1. Execute a ferramenta [Generate New Quote]

Instruções curtas e específicas funcionam melhor do que parágrafos longos. O modelo por trás do agente já sabe conversar; o que ele precisa é de um gatilho claro para saber quando acionar a ferramenta certa.

Testando o fluxo básico

Com tudo configurado, o teste no chat do Copilot Studio usa a mesma mensagem detalhada empregada antes, com todos os dados explícitos. O agente deve responder com um resumo textual da cotação e um link de download. Ao abrir o link, o Word aparece com todos os placeholders substituídos corretamente. No mapa de atividade do agente é possível conferir exatamente quais dados foram extraídos da mensagem e passados para o fluxo, o que ajuda a depurar qualquer campo que tenha ficado vazio ou mal interpretado.

Esse teste valida a mecânica completa: template com placeholders, prompt de preenchimento, geração do arquivo, salvamento e devolução do link. O próximo passo é reduzir a dependência de o usuário digitar tudo isso manualmente.

Aterrando o agente em dados reais

Pedir para o vendedor, o analista ou o técnico de campo escrever endereço completo, preço unitário e todos os detalhes de cada item é o mesmo trabalho manual que a automação deveria eliminar. O ganho real aparece quando o agente busca esses dados sozinho, a partir de uma referência curta como o nome do cliente ou o nome do produto.

Lista de produtos no Excel como conhecimento

Uma planilha Excel com nome, descrição, categoria e preço de lista de cada produto pode ser adicionada como fonte de conhecimento do agente. A descrição dessa fonte, no painel de conhecimento, deve orientar claramente o uso pretendido, por exemplo “use esta fonte para obter nome, descrição, categoria e preço de lista de produtos”. Essa descrição não é decorativa: é o que o modelo usa para decidir quando consultar aquela fonte específica em meio a várias.

Contas de clientes no Dataverse

Para dados de cliente, como número de conta, nome e endereço completo, uma tabela Accounts no Dataverse é a opção mais robusta, especialmente quando essa mesma tabela já alimenta outros processos da organização. Ao configurar o aterramento por Dataverse na ação Run a Prompt, é preciso incluir explicitamente os campos relevantes, como número da conta, nome, rua, cidade, estado e CEP, e ajustar o limite máximo de registros considerados para a busca. Em ambientes com muitos clientes cadastrados, o valor padrão de registros pode ser insuficiente e cortar contas fora do alcance do agente sem aviso nenhum, então vale revisar esse parâmetro nas configurações do prompt.

Data automática com Power Fx

A data do documento raramente deveria depender de o usuário informá-la. Uma frase adicional no prompt, do tipo “a data da cotação é [TodaysDate]”, combinada com a função Power Fx Today(), resolve isso de forma automática:

Today()

Número da cotação como entrada manual ou gerada

Nem todo campo precisa vir de conhecimento ou de linguagem natural. O número da cotação pode ser um valor fixo de teste no início do desenvolvimento e, depois, evoluir para um gerador de sequência real, seja por um contador no Dataverse, seja por uma consulta ao último número emitido. Trate isso como um débito técnico explícito desde a primeira versão do agente, para não esquecer de resolver antes de colocar em produção.

Ajustando instruções e descrição da ferramenta após o aterramento

Depois que Excel, Dataverse e Power Fx entram em cena, a descrição da entrada do agent flow deve mudar. Em vez de pedir todos os campos explicitamente, ela passa a listar apenas o essencial que o usuário realmente precisa informar, deixando o restante por conta do conhecimento do agente:

Inclua na mensagem passada ao fluxo: número do cliente (se identificado, padrão C0000), nome do cliente, tabela de produtos com quantidade, descrição, preço unitário e total da linha, e o valor total da cotação.

As instruções gerais do agente também ganham um passo a mais, orientando a consulta prévia ao conhecimento:

Quando uma cotação for solicitada:
1. Consulte a lista de preços para encontrar nome e preço de lista de cada produto mencionado.
2. Execute a ferramenta [Generate New Quote]

Testando o agente com aterramento completo

Com essa configuração, uma mensagem curta como “crie uma cotação para a empresa Beta Indústria com 3 cadeiras ErgoPro, 1 mesa MetroWood e 2 armários Titan Storage” já é suficiente. O agente busca o cliente no Dataverse, os preços no Excel, calcula os totais de linha e o total geral, preenche o template e devolve o link do documento pronto. O mapa de atividade mostra exatamente como a mensagem curta foi traduzida na estrutura completa esperada pelo fluxo, o que é útil tanto para depuração quanto para explicar o comportamento do agente a outras pessoas da equipe.

Armadilhas conhecidas e como evitar

Alguns comportamentos não são óbvios na primeira tentativa e vale antecipar.

• O arquivo salvo vira um JSON em vez de um .docx. Isso acontece quando o campo de conteúdo da ação de criação de arquivo recebe o objeto inteiro retornado pelo prompt, que na prática é uma estrutura com propriedades como nome do arquivo, tipo MIME e o conteúdo em base64, em vez do binário já decodificado. A correção passa por referenciar especificamente a propriedade de conteúdo do arquivo através do seletor de conteúdo dinâmico, ou, quando isso não estiver disponível diretamente, aplicar a função de decodificação sobre a propriedade correta antes de gravar, por exemplo algo equivalente a base64ToBinary(outputs('Run_a_Prompt')?['contentBytes']). Se o arquivo aberto mostra texto JSON em vez de um documento formatado, esse é o primeiro lugar a revisar.
• Limite de tamanho na resposta ao agente. Esse limite existe em qualquer chamada de API que devolve dados a um agente, não é peculiaridade do Copilot Studio. Documentos com muitas imagens ou tabelas extensas podem ultrapassar o limite se enviados como binário. Devolver apenas o link resolve isso na origem.
• Nomes de placeholder duplicados ou mal grafados. Cada campo precisa de um nome único no template inteiro. Um placeholder repetido com propósitos diferentes gera preenchimento inconsistente, e um placeholder mal grafado simplesmente não é substituído, aparecendo intacto no documento final.
• Placeholder de tabela fora de uma tabela real. A sintaxe {{Tabela.Campo}} só funciona como lista repetida quando está dentro de uma tabela do Word. Fora dela, o comportamento é imprevisível.
• Nome de arquivo não único. Sem um componente variável no nome, como timestamp ou número sequencial, execuções concorrentes podem colidir ou sobrescrever arquivos anteriores.

Variações de arquitetura: SharePoint, contratos e propostas com trecho gerado por IA

O mesmo padrão descrito aqui se aplica igualmente bem a uma biblioteca de documentos do SharePoint em vez do OneDrive pessoal do usuário, o que costuma ser preferível quando o documento gerado precisa ficar acessível a uma equipe inteira e sujeito a versionamento, permissões de biblioteca e políticas de retenção. A troca é direta: em vez da ação de criação de arquivo do OneDrive, usa-se a ação equivalente do conector SharePoint, apontando para o site e a biblioteca corretos, e o restante do fluxo, incluindo a construção do link e a codificação da URL, permanece o mesmo.

Para documentos como contratos ou propostas em que parte do conteúdo precisa ser redigida, não apenas preenchida, o mesmo agent flow pode combinar campos estruturados vindos de Dataverse ou Excel com trechos gerados livremente pelo prompt, desde que o placeholder correspondente no template aceite texto de tamanho variável sem quebrar a formatação da página. Vale testar esse tipo de campo com textos propositalmente longos e curtos, para garantir que o layout do template absorve bem a variação.

Existe também uma abordagem alternativa e mais tradicional dentro do próprio Power Automate, a ação Populate a Microsoft Word template, do conector Word Online (Business), que usa controles de conteúdo do Word em vez de placeholders com chaves duplas, e espera um corpo de dados já estruturado, tipicamente JSON, em vez de uma instrução em linguagem natural. Essa rota é mais determinística, porque não depende de um modelo interpretar a mensagem do usuário, mas exige que os dados já cheguem organizados antes de chegar à ação, o que normalmente significa um passo anterior de extração ou consulta separado. A escolha entre as duas abordagens depende de onde a organização quer concentrar a inteligência do processo: no prompt que interpreta linguagem natural, ou em um pipeline de dados que já entrega tudo pronto para um preenchimento mecânico.

Licenciamento e arquitetura a considerar

Um agent flow do Copilot Studio roda como um fluxo de nuvem do Power Automate por baixo, e isso tem implicações de licenciamento que vale mapear antes de levar o agente para produção. Conectores como OneDrive for Business, SharePoint e Office 365 Users são padrão e normalmente já cobertos pela licença de Microsoft 365 da organização. O conector Dataverse, por outro lado, é premium e depende de um ambiente habilitado para Dataverse, o que por sua vez exige alguma licença qualificada, seja Power Apps por usuário ou por aplicativo, seja Dynamics 365, seja a capacidade específica incluída em determinados planos do próprio Copilot Studio. As regras de o que conta como incluído mudam com frequência, então antes de desenhar a arquitetura final vale confirmar a situação atual do licenciamento com o time responsável pelo tenant, em vez de assumir que o que funcionou em um ambiente de teste vale automaticamente para produção.

Outro ponto de arquitetura relevante é o volume de execuções. Cada geração de documento consome uma execução do agent flow subjacente, e planos de Power Automate têm limites de execução mensal que podem ser um gargalo real em operações de alto volume, como emissão de muitas cotações por dia. Vale monitorar esse consumo desde o início, não apenas quando o limite já foi ultrapassado.

Se a sua operação ainda depende de copiar e colar dados em modelos Word, esse é exatamente o tipo de processo que compensa desenhar como agente antes de tentar automatizar tudo de uma vez. A Trinapse ajuda a mapear onde esse padrão se encaixa na sua realidade e a construir a arquitetura de dados por trás dele, não só o fluxo visível no chat.