Devolver respuestas enriquecidas con tarjetas adaptables

  • 2 minutos

Cuando un agente usa una acción con un complemento de API para devolver una respuesta, toma la información de la API y la procesa mediante el modelo de lenguaje. El modelo de lenguaje devuelve una respuesta fácil de usar que coincida con las instrucciones del agente. La creación de respuestas dinámicamente en función de las instrucciones predefinidas o del usuario hace que el agente sea muy flexible. Por ejemplo, puede pedirle que proporcione la información como una lista con viñetas o una tabla. Esta flexibilidad viene, sin embargo, a un precio: es posible que el agente no siempre entienda cuál es la mejor manera de presentar la información.

Dado que las API normalmente devuelven datos estructurados, es posible que desee controlar cómo el agente presenta la información al usuario. Para controlar cómo el agente presenta datos de la API, defina una plantilla de tarjeta adaptable en el complemento de API.

Para definir la plantilla de tarjeta adaptable que el agente debe usar para mostrar los datos de la API, use la propiedad static_template en la parte semántica de respuesta de la definición del complemento de API. En el fragmento de código siguiente se muestra una plantilla de tarjeta adaptable de ejemplo:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "Image",
          "url": "${image_url}",
          "size": "large"
        },
        {
          "type": "TextBlock",
          "text": "${name}",
          "weight": "Bolder"
        },
        {
          "type": "TextBlock",
          "text": "${description}",
          "wrap": true
        },
        {
          "type": "TextBlock",
          "text": "Allergens: ${if(count(allergens) > 0, join(allergens, ', '), 'none')}",
          "weight": "Lighter"
        },
        {
          "type": "TextBlock",
          "text": "**Price:** €${formatNumber(price, 2)}",
          "weight": "Lighter",
          "spacing": "None"
        }
      ]
    }
  ]
}

Observe las expresiones ${...} que hacen referencia a las propiedades de la respuesta de API y que forman parte de la plantillas de tarjeta adaptable. En tiempo de ejecución, el agente toma los datos que devuelve la función y los superpone sobre la plantilla que proporcione, creando una tarjeta adaptable llena de datos.

Cuando la API devuelve varios elementos, el agente usa la tarjeta adaptable para mostrar un solo elemento. Los usuarios ven la tarjeta al mantener el puntero sobre una cita:

Captura de pantalla de un agente declarativo que muestra una respuesta con información del plato mediante una tarjeta adaptable.

Importante

Al compilar tarjetas adaptables para funciones, tenga en cuenta que siempre muestran un solo elemento. Al principio, podría resultar contraintuitado crear una tarjeta para un solo elemento al implementar funciones que devuelven varios elementos. Recuerde que el agente construye la respuesta al usuario mediante un LLM, pero todavía quiere ofrecer la capacidad de mostrar una vista previa más completa de cada elemento, por lo que debe proporcionar una plantilla para un solo elemento en lugar de toda la respuesta de la API.

Cuando la API devuelve un solo elemento, el agente podría incluir la tarjeta directamente en su respuesta:

Captura de pantalla de un agente declarativo que muestra una respuesta con información de pedido mediante una tarjeta adaptable.

Sugerencia

Al crear tarjetas adaptables para usarlas con funciones, le resultará más conveniente compilar cada plantilla de tarjeta en un archivo independiente. Con la extensión Adaptive Card Previewer Microsoft 365 Agents Toolkit, puede crear un archivo de datos y obtener una vista previa de la tarjeta directamente en Visual Studio Code. Cuando la tarjeta esté lista, copie su contenido en el archivo de definición del complemento de API.