Agente do Copilot Studio não consegue enviar cartão adaptável: correção

Ao criar um agente personalizado no Copilot Studio, pode ser que ele não consiga enviar um cartão adaptável para um usuário no Microsoft Teams ou em outro canal. O agente retorna um texto simples alternativo ou mostra um erro de que o cartão não pôde ser entregue. Esse problema geralmente ocorre porque o JSON do cartão adaptável não atende aos requisitos de esquema impostos pelo canal de destino, ou porque o tópico do agente não tem a ação correta configurada. Este artigo explica a causa técnica da falha e fornece uma correção passo a passo para fazer seu agente enviar cartões adaptáveis de forma confiável.

Por que os agentes do Copilot Studio falham ao enviar cartões adaptáveis

O Copilot Studio gera respostas por meio de tópicos que contêm uma sequência de nós. Quando você deseja enviar um cartão adaptável, deve usar o nó Enviar uma mensagem e definir seu tipo de cartão como Cartão adaptável. O agente então serializa o payload JSON e o passa para o canal de destino, como Microsoft Teams, Microsoft 365 Chat ou um conector personalizado. O canal valida o JSON do cartão em relação à versão do esquema de cartão adaptável que ele suporta.

O ponto de falha mais comum é um JSON inválido. Uma vírgula ausente, um colchete extra ou um nome de propriedade incorreto fará com que o canal rejeite o cartão. O agente pode então recorrer a uma mensagem de texto simples que diz algo como “Encontrei um erro ao enviar o cartão.” Uma segunda causa comum é exceder o limite de tamanho do canal. O Teams, por exemplo, limita os cartões adaptáveis a 28 KB de JSON serializado. Um cartão com muitas colunas, imagens ou botões de ação pode facilmente exceder esse limite sem acionar um erro claro no Copilot Studio.

Uma terceira causa é usar um elemento não suportado. O esquema do cartão adaptável evolui através das versões 1.0, 1.1, 1.2 e 1.3. O Teams atualmente suporta até a versão 1.3, mas alguns elementos como ToggleVisibility ou Action.ToggleVisibility exigem a versão 1.2 ou posterior. Se o seu cartão usar um elemento que o canal não suporta, todo o cartão é rejeitado. Finalmente, o agente deve ter o nó de ação correto configurado. Se você usar um nó Enviar uma mensagem, mas não definir explicitamente o tipo de cartão, o agente enviará texto simples em vez do cartão.

Etapas para corrigir um cartão adaptável que não é enviado

1. Abra o tópico que contém o cartão
   No Copilot Studio, vá para Tópicos e selecione o tópico onde o cartão está definido. Expanda a árvore de nós para encontrar o nó Enviar uma mensagem que deve conter o cartão.
2. Verifique se o tipo de cartão está definido como Cartão adaptável
   Clique no nó Enviar uma mensagem. No painel de propriedades, localize o menu suspenso Tipo de cartão. Se mostrar Nenhum ou Texto, altere para Cartão adaptável. Se o menu suspenso estiver ausente, seu nó pode ser uma versão mais antiga. Exclua o nó e adicione um novo nó Enviar uma mensagem da paleta de nós.
3. Cole um esqueleto JSON de cartão adaptável validado
   Abra o editor JSON dentro do nó. Substitua o JSON existente por um esqueleto mínimo válido:
   {"type":"AdaptiveCard","$schema":"http://adaptivecards.io/schemas/adaptive-card.json","version":"1.3","body":[{"type":"TextBlock","text":"Olá mundo","wrap":true}]}
   Teste o agente. Se o cartão aparecer no Teams, o problema está no seu JSON original.
4. Valide seu JSON do cartão externamente
   Copie o JSON do nó. Acesse o Adaptive Cards Designer em adaptivecards.io/designer. Cole o JSON no painel esquerdo. O designer mostrará um selo de erro vermelho se o JSON for inválido. Corrija quaisquer erros mostrados no painel de validação de esquema.
5. Verifique o tamanho do cartão
   Após a validação, copie o JSON para um editor de texto e salve-o como um arquivo .json. Verifique o tamanho do arquivo no seu sistema operacional. Se exceder 28 KB, reduza o cartão removendo colunas, imagens ou botões de ação. Use imagens menores compactando-as antes de incorporar como URIs de dados, ou hospede imagens em uma CDN e referencie-as por URL.
6. Remova elementos não suportados para o Teams
   O Teams suporta a versão 1.3 do cartão adaptável. Remova elementos que exigem a versão 1.4 ou posterior, como Action.Execute. Substitua Action.Execute por Action.Submit. Remova quaisquer estilos personalizados que não façam parte do esquema padrão.
7. Publique o agente e teste no canal de destino
   Após fazer as alterações, clique em Publicar no Copilot Studio. Abra o canal de destino (por exemplo, Microsoft Teams). Inicie uma conversa com seu agente e acione o tópico. Se o cartão ainda falhar, abra o painel de depuração no Copilot Studio clicando no botão Depurar. Procure por mensagens de erro no painel de Saída. O erro geralmente contém o caminho JSON exato que falhou.

Método alternativo: usar um fluxo do Power Automate para gerar o cartão

Se o JSON do cartão for complexo e você não conseguir reduzir seu tamanho, crie um fluxo do Power Automate que gere o cartão adaptável e o envie para o Teams. No Copilot Studio, chame o fluxo usando o nó Chamar uma ação. Esse método transfere a geração do cartão para um serviço que possui tratamento de erros e registro mais robustos.

Se o cartão adaptável ainda tiver problemas após a correção principal

Agente do Copilot Studio envia cartão apenas como texto simples

Isso indica que o canal recebeu o cartão, mas não conseguiu renderizá-lo. A causa mais comum é um cabeçalho ContentType ausente ou incorreto. No Copilot Studio, certifique-se de que o tipo de conteúdo do nó Enviar uma mensagem esteja definido como application/vnd.microsoft.card.adaptive. Se o nó não expor essa opção, adicione um novo nó e defina manualmente o tipo de conteúdo nas propriedades avançadas.

Cartão aparece no painel de teste do Copilot Studio, mas não no Teams

O painel de teste do Copilot Studio usa um mecanismo de renderização diferente do Teams. Um cartão pode renderizar corretamente no painel de teste, mas falhar no Teams devido a restrições específicas do Teams. Por exemplo, o Teams não suporta o estilo de destino Action.OpenUrl que abre uma URL em uma nova janela. Use Action.OpenUrl com o estilo padrão. Além disso, o Teams limita o número de ações a seis por cartão. Reduza a contagem de ações se exceder seis.

Agente retorna um erro genérico em vez do cartão

Um erro genérico geralmente significa que o JSON do cartão causou uma exceção no lado do servidor. Abra o painel de depuração do Copilot Studio e procure por uma linha que diga “AdaptiveCardRenderException” ou “CardRenderException.” A mensagem de erro geralmente contém o índice do elemento problemático. Por exemplo, “body[3].columns[1].items[0]” aponta para o primeiro item na segunda coluna do quarto elemento do corpo. Edite esse elemento no editor JSON e remova ou corrija a propriedade que causou a exceção.

Cartão é enviado, mas mostra uma caixa branca vazia no Teams

Um cartão em branco significa que o JSON é válido, mas o cartão não possui elementos de corpo visíveis. Certifique-se de que a matriz body contenha pelo menos um elemento como TextBlock, Image ou ColumnSet. Verifique também se a propriedade text do elemento não está vazia e se a propriedade wrap do elemento está definida como true para blocos de texto.

Copilot Studio vs Power Automate para entrega de cartões adaptáveis

Item	Nó Enviar uma Mensagem do Copilot Studio	Fluxo do Power Automate
Geração do cartão	JSON embutido no nó	JSON construído por ações ou expressões do fluxo
Validação de esquema	Manual — você precisa testar externamente	Automática — o fluxo falha com uma mensagem de erro clara
Tratamento de limite de tamanho	Nenhuma verificação de tamanho embutida	Você pode adicionar uma condição para verificar o comprimento do JSON
Registro de erros	Painel de depuração no Copilot Studio	Histórico de execução do fluxo com saída detalhada da etapa
Suporte a canais	Teams, Microsoft 365 Chat, conector personalizado	Teams, Outlook, webhook e mais de 300 conectores

Agora você pode identificar e corrigir as três principais causas de falha de cartão adaptável no Copilot Studio: JSON inválido, payload muito grande e elementos de esquema não suportados. Use o validador externo em adaptivecards.io/designer antes de colar qualquer cartão em um tópico. Para cartões complexos que exigem dados dinâmicos, mude para um fluxo do Power Automate para obter melhor tratamento de erros e registro. Uma dica avançada final: defina a propriedade version no JSON do seu cartão como 1.3 para corresponder à versão máxima suportada pelo Teams e sempre teste no cliente real do Teams em vez de confiar apenas no painel de teste do Copilot Studio.