Cuando crea un agente personalizado en Copilot Studio, es posible que no logre enviar una tarjeta adaptable a un usuario en Microsoft Teams u otro canal. El agente devuelve un texto sin formato como alternativa o muestra un error de que la tarjeta no se pudo entregar. Este problema suele ocurrir porque el JSON de la tarjeta adaptable no cumple con los requisitos de esquema que exige el canal de destino, o porque el tema del agente no tiene la acción correcta configurada. Este artículo explica la causa técnica del error y proporciona una solución paso a paso para que su agente envíe tarjetas adaptables de forma confiable.
Puntos clave: Cómo solucionar la entrega de tarjetas adaptables en Copilot Studio
- Copilot Studio > Temas > Agregar nodo > Enviar un mensaje > Tipo de tarjeta > Tarjeta adaptable: La ruta de nodo correcta para adjuntar una tarjeta adaptable a la respuesta de un tema.
- Validación del esquema JSON de la tarjeta adaptable: La causa principal de la mayoría de los errores de entrega: campos $schema o version faltantes o tipos de elementos no compatibles.
- Límite de tamaño de tarjeta de 28 KB específico del canal: Las tarjetas que superan este límite serán rechazadas por Teams y otros canales sin un error explícito en Copilot Studio.
Por qué los agentes de Copilot Studio no pueden enviar tarjetas adaptables
Copilot Studio genera respuestas a través de temas que contienen una secuencia de nodos. Cuando desea enviar una tarjeta adaptable, debe usar el nodo Enviar un mensaje y establecer su tipo de tarjeta en Tarjeta adaptable. Luego, el agente serializa la carga útil JSON y la pasa al canal de destino, como Microsoft Teams, Microsoft 365 Chat o un conector personalizado. El canal valida el JSON de la tarjeta según la versión del esquema de tarjeta adaptable que admite.
El punto de falla más común es un JSON no válido. Una coma faltante, un corchete adicional o un nombre de propiedad incorrecto harán que el canal rechace la tarjeta. El agente puede entonces recurrir a un mensaje de texto sin formato que diga algo como “Se produjo un error al enviar la tarjeta”. Una segunda causa común es superar el límite de tamaño del canal. Teams, por ejemplo, limita las tarjetas adaptables a 28 KB de JSON serializado. Una tarjeta con muchas columnas, imágenes o botones de acción puede superar fácilmente este límite sin desencadenar un error claro en Copilot Studio.
Una tercera causa es usar un elemento no compatible. El esquema de tarjeta adaptable evoluciona a través de las versiones 1.0, 1.1, 1.2 y 1.3. Teams actualmente admite hasta la versión 1.3, pero algunos elementos como ToggleVisibility o Action.ToggleVisibility requieren la versión 1.2 o posterior. Si su tarjeta usa un elemento que el canal no admite, se rechaza toda la tarjeta. Por último, el agente debe tener configurado el nodo de acción correcto. Si usa un nodo Enviar un mensaje pero no establece explícitamente el tipo de tarjeta, el agente enviará texto sin formato en lugar de la tarjeta.
Pasos para solucionar una tarjeta adaptable que no se envía
- Abra el tema que contiene la tarjeta
En Copilot Studio, vaya a Temas y seleccione el tema donde se define la tarjeta. Expanda el árbol de nodos para encontrar el nodo Enviar un mensaje que debe contener la tarjeta. - Verifique que el tipo de tarjeta esté establecido en Tarjeta adaptable
Haga clic en el nodo Enviar un mensaje. En el panel de propiedades, busque la lista desplegable Tipo de tarjeta. Si muestra Ninguno o Texto, cámbielo a Tarjeta adaptable. Si la lista desplegable no aparece, es posible que su nodo sea una versión anterior. Elimine el nodo y agregue un nuevo nodo Enviar un mensaje desde la paleta de nodos. - Pegue un esqueleto JSON de tarjeta adaptable validado
Abra el editor JSON dentro del nodo. Reemplace el JSON existente con un esqueleto mínimo válido:{"type":"AdaptiveCard","$schema":"http://adaptivecards.io/schemas/adaptive-card.json","version":"1.3","body":[{"type":"TextBlock","text":"Hello world","wrap":true}]}
Pruebe el agente. Si la tarjeta aparece en Teams, el problema está en su JSON original. - Valide el JSON de su tarjeta externamente
Copie el JSON del nodo. Vaya al Diseñador de tarjetas adaptables en adaptivecards.io/designer. Pegue el JSON en el panel izquierdo. El diseñador mostrará una insignia de error roja si el JSON no es válido. Corrija los errores que se muestren en el panel de validación de esquema. - Verifique el tamaño de la tarjeta
Después de la validación, copie el JSON en un editor de texto y guárdelo como un archivo .json. Verifique el tamaño del archivo en su sistema operativo. Si supera los 28 KB, reduzca la tarjeta eliminando columnas, imágenes o botones de acción. Use imágenes más pequeñas comprimiéndolas antes de incrustarlas como URI de datos, o aloje las imágenes en una CDN y haga referencia a ellas por URL. - Elimine los elementos no compatibles para Teams
Teams admite la versión 1.3 de la tarjeta adaptable. Elimine los elementos que requieren la versión 1.4 o posterior, como Action.Execute. Reemplace Action.Execute por Action.Submit. Elimine los estilos personalizados que no formen parte del esquema estándar. - Publique el agente y pruébelo en el canal de destino
Después de realizar cambios, haga clic en Publicar en Copilot Studio. Abra el canal de destino (por ejemplo, Microsoft Teams). Inicie una conversación con su agente y active el tema. Si la tarjeta aún falla, abra el panel de depuración en Copilot Studio haciendo clic en el botón Depurar. Busque mensajes de error en el panel Salida. El error suele contener la ruta JSON exacta que falló.
Método alternativo: Use un flujo de Power Automate para generar la tarjeta
Si el JSON de la tarjeta es complejo y no puede reducir su tamaño, cree un flujo de Power Automate que genere la tarjeta adaptable y la envíe a Teams. Desde Copilot Studio, llame al flujo usando el nodo Llamar a una acción. Este método delega la generación de la tarjeta a un servicio que tiene un manejo de errores y registro más sólidos.
Si la tarjeta adaptable aún tiene problemas después de la solución principal
El agente de Copilot Studio envía la tarjeta solo como texto sin formato
Esto indica que el canal recibió la tarjeta pero no pudo representarla. La causa más común es un encabezado ContentType faltante o incorrecto. En Copilot Studio, asegúrese de que el Tipo de contenido del nodo Enviar un mensaje esté establecido en application/vnd.microsoft.card.adaptive. Si el nodo no expone esta opción, agregue un nuevo nodo y establezca manualmente el tipo de contenido en las propiedades avanzadas.
La tarjeta aparece en el panel de prueba de Copilot Studio pero no en Teams
El panel de prueba de Copilot Studio usa un motor de representación diferente al de Teams. Una tarjeta puede representarse correctamente en el panel de prueba pero fallar en Teams debido a restricciones específicas de Teams. Por ejemplo, Teams no admite el estilo de destino Action.OpenUrl que abre una URL en una nueva ventana. Use Action.OpenUrl con el estilo predeterminado. Además, Teams limita el número de acciones a seis por tarjeta. Reduzca el número de acciones si supera seis.
El agente devuelve un error genérico en lugar de la tarjeta
Un error genérico a menudo significa que el JSON de la tarjeta provocó una excepción del lado del servidor. Abra el panel de depuración de Copilot Studio y busque una línea que diga “AdaptiveCardRenderException” o “CardRenderException”. El mensaje de error suele contener el índice del elemento problemático. Por ejemplo, “body[3].columns[1].items[0]” apunta al primer elemento de la segunda columna del cuarto elemento body. Edite ese elemento en el editor JSON y elimine o corrija la propiedad que causó la excepción.
La tarjeta se envía pero muestra un cuadro blanco vacío en Teams
Una tarjeta en blanco significa que el JSON es válido pero la tarjeta no tiene elementos body visibles. Asegúrese de que la matriz body contenga al menos un elemento como TextBlock, Image o ColumnSet. También verifique que la propiedad text del elemento no esté vacía y que la propiedad wrap del elemento esté establecida en true para los bloques de texto.
Copilot Studio vs Power Automate para la entrega de tarjetas adaptables
| Elemento | Nodo Enviar un mensaje de Copilot Studio | Flujo de Power Automate |
|---|---|---|
| Generación de tarjetas | JSON insertado en el nodo | JSON creado por acciones o expresiones del flujo |
| Validación de esquema | Manual: debe probar externamente | Automática: el flujo falla con un mensaje de error claro |
| Manejo del límite de tamaño | Sin comprobación de tamaño integrada | Puede agregar una condición para verificar la longitud del JSON |
| Registro de errores | Panel de depuración en Copilot Studio | Historial de ejecución del flujo con salida detallada de pasos |
| Compatibilidad de canales | Teams, Microsoft 365 Chat, conector personalizado | Teams, Outlook, webhook y más de 300 conectores |
Ahora puede identificar y solucionar las tres causas principales de fallas de tarjetas adaptables en Copilot Studio: JSON no válido, carga útil demasiado grande y elementos de esquema no compatibles. Use el validador externo en adaptivecards.io/designer antes de pegar cualquier tarjeta en un tema. Para tarjetas complejas que requieren datos dinámicos, cambie a un flujo de Power Automate para obtener un mejor manejo de errores y registro. Un consejo avanzado final: establezca la propiedad version en el JSON de su tarjeta en 1.3 para que coincida con la versión máxima compatible de Teams, y siempre pruebe en el cliente real de Teams en lugar de confiar únicamente en el panel de prueba de Copilot Studio.