Llamar a la extensión desde un paso

Para llamar a una extensión personalizada desde una acción:

1. En el editor de acciones, cree o abra el paso desde el que desea llamar a la extensión.

2. Opcional: En el campo El asistente indica, escriba un mensaje que se mostrará al cliente antes de llamar a la extensión (por ejemplo, Please wait while I retrieve your account balance...).

   La salida de este paso se envía al canal con la variable de contexto global skip_user_input establecida en true. Esta variable indica al canal que muestre el mensaje, pero no que solicite una respuesta al cliente. En su lugar, el canal envía un mensaje vacío, lo que permite al asistente continuar con la llamada a la extensión.

   Todas las integraciones de canal incorporadas (como la conversación web) respetan la variable de contexto skip_user_input. Si está utilizando la API para desarrollar un cliente personalizado, es su responsabilidad incluir la comprobación lógica para esta variable. Para obtener más información, consulte Proceso de entrada de usuario.

3. En el editor de pasos, pulse Y luego.

4. Haga clic en Utilizar una extensión.

5. En la ventana Configuración de la extensión, especifique la siguiente información:

   • En el campo Extensión, seleccione la extensión a la que desea llamar.

   • En el campo Operación, seleccione la operación que desea realizar. (Una operación es un método o función soportados por la extensión).

6. Especifique valores para cada uno de los parámetros de entrada necesarios. Un parámetro es un valor de entrada enviado a una operación, como el ID de un registro de cliente que desea recuperar o la ubicación que se debe utilizar para un pronóstico meteorológico.

   Para asignar un valor a un parámetro, pulse el campo de entrada correspondiente al valor. A continuación, puede seleccionar en la lista de variables disponibles o escribir una expresión para especificar el valor.

   

   Cada parámetro tiene un tipo de datos (como número o serie). La variable que seleccione debe ser compatible con el tipo de datos del parámetro; para más información, consulte Variables compatibles para parámetros.

   Debe especificar valores para todos los parámetros necesarios para poder continuar.

7. Si desea especificar un valor para algún parámetro opcional, pulse Parámetros opcionales. A continuación, puede repetir este proceso para cada parámetro opcional que desee utilizar.

8. Haga clic en Aplicar. (Si el botón Aplicar no está disponible, compruebe que haya especificado valores para todos los parámetros necesarios).

La sección Y luego del editor de pasos muestra ahora una visión general de la llamada a la extensión:

Si necesita realizar cambios, pulse Editar extensión para volver a abrir la ventana Configuración de la extensión.

Acceso a los datos de respuesta de la extensión

Después de llamar a una extensión, los valores de los datos de respuesta se almacenan en variables de acción especiales a las que puede acceder en los pasos posteriores.

Puede acceder a estas variables de la misma manera que a otras variables de acción. Puede hacer referencia a ellas en el texto de El asistente dic:, evaluarlas como parte de una condición de paso o asignarlas a una variable de sesión para que otras acciones puedan acceder a ellas. Las variables de respuesta se muestran en la lista de variables disponibles, categorizadas bajo el nombre de la extensión y el paso desde el que se han llamado:

Cada llamada a una extensión crea un conjunto separado de variables de respuesta. Si la acción llama varias vaces a la misma extensión desde distintos pasos, asegúrese de seleccionar las variables del paso correcto.

Cada variable representa un valor del cuerpo de la respuesta. Para facilitar el acceso a estos valores, los datos se extraen de objetos complejos anidados y se correlacionan con variables de respuesta individuales. El nombre de cada variable refleja su ubicación dentro del cuerpo de la respuesta (por ejemplo, body.name o body.customer.address.zipcode).

Por ejemplo, este paso de acción utiliza una expresión para comprobar la propiedad availability en una respuesta de extensión:

Si una variable de respuesta contiene una matriz, puede escribir una expresión que utilice métodos de matriz para acceder a los elementos de la matriz. Por ejemplo, puede utilizar el método contains() en una condición de paso para probar si la matriz contiene un valor determinado, o el método join() para formatear datos de la matriz como una serie que puede incluir en una respuesta de asistente. Para obtener más información sobre los métodos de matriz, consulte Métodos de matriz.

Comprobar el éxito o el fracaso

Es posible que desee que el asistente pueda manejar los errores que se producen al llamar a una extensión personalizada. Puede hacerlo comprobando la variable de respuesta Ran successfully que se devuelve junto con la respuesta de la llamada a la extensión. Esta variable es un valor booleano (true o false).

Si define condiciones de paso que comprueban la variable Ran successfully, puede crear pasos que permitan al asistente responder de forma diferente en función de si la llamada a la extensión ha sido satisfactoria. (Para obtener más información sobre las condiciones de paso, consulte Condiciones de paso).

El ejemplo siguiente muestra una condición de paso que comprueba una anomalía de una extensión en el paso 3. Mediante esta condición, puede crear un paso que indique al cliente que se ha producido un error, y tal vez ofrezca la posibilidad de conectarse a un agente para obtener más ayuda.

Condicionamiento del estado HTTP

Además de la variable Ran successfully, es posible que también desee crear una condición de paso basada en el estado HTTP de la respuesta. Al hacerlo, puede crear pasos que manejen la situación de forma diferente en función de la causa del error. Por ejemplo, si la llamada falló debido a un error de tiempo de espera ( HTTP status 408), es posible que desee volver a intentar la llamada.

Hay muchos códigos de estado HTTP posibles, y diferentes métodos utilizan códigos de estado diferentes para indicar varios tipos de éxito o anomalía. Para condicionar el estado HTTP, necesita saber qué códigos de estado HTTP devuelve el servicio externo y en qué circunstancias. Estos códigos de estado suelen especificarse en el documento OpenAPI que describe la API externa.

Para crear una condición de paso basada en el código de estado HTTP, siga estos pasos:

1. Para el valor que desea probar, pulse Expresión.

2. En el campo de expresión, escriba un signo de dólar ($) para mostrar la lista de variables disponibles.

3. Seleccione cualquier variable que sea un valor de respuesta de la extensión. (No importa qué variable seleccione, siempre y cuando sea una variable de respuesta de extensión).

   La expresión se actualiza automáticamente para mostrar una referencia a la variable que ha seleccionado, en el formato ${step_xxx_result_y.body.variablename}. Por ejemplo, si ha seleccionado una variable de respuesta denominada body.id, la referencia puede ser ${step_596_result_1.body.id}.

4. Dentro de las llaves, ({}), edite esta referencia para eliminar .body.variablename. Debería quedar algo parecido a ${step_596_result_1}.

5. Después de la llave de cierre (}), añada .status. La referencia resultante identifica el código de estado devuelto desde la llamada a la extensión (por ejemplo, ${step_596_result_1}.status).

   Para obtener más información sobre cómo escribir expresiones, consulte Cómo escribir expresiones.

6. Complete la expresión añadiendo un operador y un valor de comparación, de modo que la expresión se evalúe como un valor booleano (true/false). Por ejemplo, la siguiente expresión comprueba el estado HTTP 408, que indica un error de tiempo de espera:

   ${step_549_result_1}.status==408
   

Errores de depuración de la extensión personalizada

Si sus llamadas a una extensión están fallando, es posible que desee depurar el problema viendo información detallada sobre lo que se envía y devuelve desde la API del sistema. Para ello, puede utilizar el Inspector del panel Vista previa:

1. Vaya a la página Acciones, o al editor de acciones, y haga clic en Vista previa para abrir el panel Vista previa.

   No puede acceder al Inspector desde la vista previa del Asistente en la página Vista previa, que sólo muestra lo que vería un cliente. En su lugar, utilice la característica de vista previa que forma parte de la página Acciones, que le proporciona acceso a información adicional.

2. Interactúa con tu Asistente como lo haría un cliente.

3. Cada vez que se llama a una extensión, el panel de vista previa muestra un mensaje que le proporciona acceso a información detallada:

   Pulse Inspeccionar para ver detalles sobre la llamada a la extensión.

   También puede hacer clic en el para mostrar u ocultar el Inspector. Sin embargo, debe hacer clic en Inspeccionar en el panel de vista previa para mostrar información sobre una llamada concreta a una extensión.

   La pestaña Resumen del Inspector muestra la siguiente información sobre una llamada a una extensión:

   Opción de depuración	Descripción
   Extensión	El nombre de la extensión, tal como se especifica en los valores de extensión.
   Operación	La operación a la que se ha llamado.
   Estado	El código de estado HTTP de la respuesta. Este código puede ayudarle a determinar si se devuelve un error desde el servicio externo.
   Parámetros de solicitud	Los parámetros de entrada que se enviaron a la API del sistema como parte de la solicitud.
   Propiedades de respuesta	Los valores de todas las propiedades incluidas en la respuesta de la API del sistema. Estos son los valores que se correlacionan con las variables de acción después de que se complete la llamada a la extensión.

   En las tablas Parámetros de solicitud y Propiedades de respuesta, los nombres de propiedad largos pueden truncarse para mostrar sólo la última parte de la vía de acceso JSON. Para ver la vía de acceso completa y el nombre de propiedad, pase el puntero del ratón sobre el nombre de propiedad en la tabla.

4. Pulse la pestaña Avanzado en el inspector de extensión si desea ver los datos de solicitud y respuesta sin formato:

   • La solicitud se muestra como un mandato cURL, que puede ejecutar en un indicador de mandatos o importar en una herramienta como Postman. (Por razones de seguridad, el contenido de cualquier cabecera Authorization no se incluye.)
   • La respuesta se muestra como los datos JSON completos devueltos por la API del sistema.

Depuración de fallos en la búsqueda conversacional o en las acciones basadas en habilidades

Si tus llamadas a la búsqueda conversacional o a las acciones basadas en habilidades fallan, puede que quieras depurar el problema viendo la información detallada sobre lo que se está enviando y devolviendo desde la API del sistema.

El inspector de búsqueda conversacional sólo aparece cuando la búsqueda conversacional está activada en tu integración de búsqueda. Si está utilizando la integración de búsqueda de servicios personalizados, debe utilizar sólo la búsqueda del lado del servidor cuando configure la integración de búsqueda. La búsqueda del lado del cliente no es compatible con el inspector de búsqueda conversacional.

Para ver la información detallada para analizar el problema, utilice el Inspector en el panel Vista previa:

1. Vaya a la página Acciones o, en el editor de acciones, haga clic en Vista previa para abrir el panel Vista previa.

   No se puede acceder al Inspector desde la vista previa del Asistente en la página Vista previa. En su lugar, utilice la característica de vista previa que forma parte de la página Acciones, que le proporciona acceso a información adicional.

2. Interactúa con tu Asistente como lo haría un cliente.

3. Cada vez que se llama a una extensión, el panel de vista previa muestra un mensaje para acceder a la información detallada: También puede pulsar el icono para mostrar u ocultar el inspector de extensión. Haga clic en Inspeccionar en el panel de vista previa para mostrar información sobre una llamada concreta a la integración de búsqueda.

4. Utilice la pestaña Visión general para encontrar las razones del fracaso de sus llamadas a la búsqueda conversacional.

   Comprenda las dos fases de la extensión de búsqueda antes de conocer los campos que se muestran en la pestaña Descripción general.

   • Fase de recuperación

     Representa la fase de búsqueda inicial en la que se llama a un motor de búsqueda de documentos externo para recuperar el conjunto inicial de resultados.

   • Fase de generación de respuestas

     Representa la fase en la que se recuperan los datos durante la fase de recuperación y se envían a un LLM para generar una respuesta legible para el usuario.

   La pestaña Visión general del Inspector muestra la siguiente información sobre la llamada a la integración de búsqueda.

   Opción de depuración	Descripción
   Extensión	El nombre de la extensión, tal como se especifica en los valores de extensión.
   Índice	El nombre del índice Elasticsearch utilizado por la búsqueda, visible sólo cuando la extensión de búsqueda está configurada para utilizar Elasticsearch.
   ID de proyecto	El ID del proyecto utilizado por IBM Watson® Discovery durante la fase de recuperación de la búsqueda. Este campo sólo es visible cuando se configura la extensión de búsqueda para utilizar IBM Watson® Discovery.
   Consulta	La consulta utilizada por el sistema para iniciar la búsqueda en el motor de documentosElasticsearch, IBM Watson® Discovery, o servicio personalizado del lado del servidor). El valor de este campo refleja la consulta reescrita del sistema.
   Consulta original	La consulta a través de la cual el usuario inició la búsqueda. Este campo sólo es visible cuando el sistema reescribe la consulta cuando está activada la búsqueda conversacional multivuelta.
   Filtro de resultados personalizado	Muestra el filtro de resultados personalizado, si se proporciona en el desencadenante de búsqueda, que activó la búsqueda conversacional. Es posible que este campo no aparezca siempre en las respuestas.
   Tipo de LLM	El LLM que fue llamado durante la fase de generación de la respuesta. Este valor es watsonx.ai. Para saber más sobre cómo configurar LLM en tu Assistant, consulta LLM Base.
   Modelo	El modelo utilizado por el LLM base durante la fase de generación de respuestas de la búsqueda.
   Motivo del cierre del arroyo	Indica el motivo por el que el flujo ha finalizado o se ha cerrado con el valor correspondiente en la interfaz de usuario. Este campo sólo es visible cuando se activa la transmisión en tiempo real en el Chat web.
   Recuento de tokens de entrada LLM	Indica el número de tokens de la petición que se envió al LLM en la fase de generación de respuestas de la búsqueda.
   Recuento de tokens generados por LLM	Indica el número de tokens de la respuesta con la que responde el LLM, en la fase de generación de respuestas de la búsqueda.
   Respuesta IDK	Este campo sólo es visible cuando la respuesta a la búsqueda se resuelve con una respuesta IDK (No lo sé).
   IDK razón	El motivo por el que el sistema ha resuelto una respuesta de búsqueda como IDK (no lo sé) se muestra con el valor correspondiente.
   IDK desencadenar frase de apertura	El campo muestra la frase de apertura estándar detectada que desencadenó una respuesta IDK (No lo sé), visible sólo cuando el motivo IDK se debe a esta frase.
   IDK frase desencadenante	El campo muestra la frase desencadenante detectada que provocó una respuesta IDK (No lo sé), visible sólo cuando el motivo IDK se debe a esta frase.
   Tiempo total de retorno	El tiempo total que tardó el sistema en completar la ejecución de la búsqueda conversacional.
   Tiempo de búsqueda	El tiempo que tarda el sistema en llamar al motor de búsqueda y obtener resultados en la fase de recuperación de la búsqueda.
   Tiempo de generación de la respuesta	Tiempo que tarda el sistema en completar la fase de generación de respuestas de la búsqueda.
   Umbral de confianza	Valor numérico que representa el umbral de confianza de la búsqueda, también conocido como Tendencia a decir "No sé" en la configuración del Asistente.
   Extractividad	La puntuación refleja la parte de la respuesta que se cita directamente de las fuentes. Una puntuación más alta indica una cita más directa y una puntuación más baja indica una reformulación de la fuente o la falta de apoyo de la fuente.
   Recuperación de la confianza	El valor de confianza indica hasta qué punto el sistema está seguro de los resultados de la búsqueda. Si está por debajo del umbral, el sistema responde con IDK y el motivo Recuperación de confianza demasiado baja.
   Confianza de respuesta	El valor de confianza indica la certeza del sistema ante la respuesta generada. Si está por debajo del umbral, el sistema responde con IDK y la razón Response confidence too low.

Reconfiguración de una extensión que falta

Una extensión puede dejar de estar disponible si alguien la elimina del asistente en la página Integraciones, o si la acción se exporta y, a continuación, se importa a un asistente diferente donde la extensión necesaria no está configurada. Si esto sucede, cualquier paso de acción que llame a la extensión no será válido.

Para corregir el problema, siga estos pasos:

1. Si es necesario, vuelva a crear la extensión utilizando la misma especificación OpenAPI que se utilizaba antes. (Para obtener más información, consulte Creación de una extensión personalizada.)

2. Asegúrese de que la extensión se haya añadido al asistente. (Para obtener más información, consulte Adición de una extensión al asistente.)

3. En el editor de acciones, edite el paso de acción que llama a la extensión y compruebe si la llamada a la extensión se ha configurado correctamente. Si watsonx Assistant reconoce la extensión necesaria, la configuración de extensión se restaura automáticamente.

   Si ve el mensaje Extension not fully configured, significa que watsonx Assistant no ha encontrado la extensión necesaria. Pulse Editar extensión.

4. En la ventana de configuración de la extensión, seleccione la extensión a la que desea llamar.

   Si watsonx Assistant reconoce una extensión disponible que se ha creado utilizando el mismo documento OpenAPI, aparece un mensaje que sugiere que seleccione esta extensión. Sin embargo, puede seleccionar cualquier extensión disponible.

5. Verifique que se han especificado los valores correctos en los campos Operación y Parámetros.

6. Haga clic en Aplicar.

7. Si ha seleccionado una extensión que no es idéntica a la que se ha utilizado para crear la acción, es posible que tenga que modificar los pasos posteriores que acceden a las propiedades de respuesta de extensión. Compruebe los pasos posteriores que hagan referencia a las propiedades de respuesta y asegúrese de que las referencias siguen siendo válidas y correctas.