Depurar un Power que no dispara

Cuando un Power no se comporta como esperabas, la tentación es revisar el código del webhook primero. Casi nunca es ahí donde está el problema: en la enorme mayoría de los casos, la causa vive en uno de los dos extremos de la conversación, no en el medio. Esta guía es el orden en el que conviene mirar.

Primero: ¿el agente lo está llamando?

Antes de sospechar del webhook, confirma que el Power se invocó. Si el agente nunca lo llamó, revisa su descripción: probablemente no le dice con suficiente claridad cuándo aplica, o compite de forma ambigua con otro Power similar. Prueba una conversación donde el caso de uso sea inequívoco y observa si ahí sí dispara.

Segundo: ¿los parámetros llegaron completos?

Si el Power se invocó pero con datos vacíos o incorrectos, el problema suele estar en la descripción de los parámetros, no en el modelo. Un parámetro sin descripción clara, o marcado como opcional cuando debería ser obligatorio, deja al agente adivinando o enviándolo en blanco.

Tercero: ¿qué respondió realmente tu endpoint?

• Revisa el código de estado HTTP: un 4xx casi siempre apunta a un parámetro mal formado o una cabecera de autenticación ausente.
• Revisa el cuerpo de la respuesta: si no es el formato que el agente espera interpretar, el resultado se comunica mal aunque la llamada haya sido exitosa.
• Prueba el mismo endpoint por fuera de Arko, con curl o Postman, usando exactamente los parámetros que el agente habría enviado.

Reproduce fuera del chat antes de tocar nada

El instinto de cambiar la descripción del Power y volver a probar en el chat es lento: cada intento implica una conversación completa. Aísla el problema fuera del chat primero —¿el endpoint responde bien con esos parámetros?— y solo vuelve al agente cuando confirmaste que el resto de la cadena funciona.

Cuando nada de esto explica el fallo

Si el endpoint responde bien de forma aislada, los parámetros llegan completos y el agente lo invoca en el momento correcto, pero el resultado igual se comunica mal, revisa cómo describiste la respuesta esperada. El agente necesita saber qué forma tiene una respuesta exitosa para poder explicársela al usuario con sus propias palabras.