Hooks del Agent SDK: interceptar llamadas a herramientas y normalizar sus resultados

Bienvenidos y bienvenidas a la cápsula cinco del Módulo tres. Hoy vemos los hooks del kit de desarrollo Agent SDK, el task statement uno punto cinco de la guía: cómo interceptar las llamadas a herramientas y cómo normalizar sus resultados.

Un hook es una función tuya que el Agent SDK ejecuta en momentos fijos mientras el agente trabaja. La guía usa dos. El hook pre tool use corre antes de que la herramienta se ejecute, y sirve para interceptar: permitir la llamada, negarla o redirigirla. El hook post tool use corre después de la herramienta y antes de que el modelo vea el resultado, y sirve para transformar.

El uso de post tool use que pide la guía es normalizar formatos heterogéneos. Distintas herramientas MCP devuelven fechas como timestamp Unix, un número de segundos, o como ISO 8601, un texto estándar, y estados como códigos numéricos o como texto. Si el modelo recibe todo mezclado, puede equivocarse. Un hook que lo convierte a un solo formato antes de que el modelo lo vea elimina ese trabajo.

El uso de pre tool use es bloquear acciones que violan una política y redirigir a otro flujo. El ejemplo de la guía es un reembolso sobre quinientos dólares: el hook lo bloquea y el agente escala a una persona. En el examen, el número que importa es el del enunciado.

La distinción clave es hook contra prompt. Un hook es código que corre siempre que se cumple la condición, y su resultado es determinista. Una instrucción en el prompt es una petición, que el modelo sigue casi siempre. Si la regla exige cumplimiento garantizado, gana el hook.

La documentación del Agent SDK agrega dos detalles. En pre tool use, el campo permission decision acepta los valores allow, deny, ask y defer, y el campo permission decision reason le explica al modelo el motivo. Y si varios hooks coinciden con la misma llamada, gana el resultado más restrictivo, así que un solo deny la bloquea. Una trampa: en post tool use la herramienta ya corrió, así que para impedir la llamada hay que usar pre tool use.

Una pregunta. ¿Cuándo basta una instrucción en el prompt y cuándo hace falta un hook?

Basta para el estilo o el tono. Hace falta un hook cuando hay un límite de monto, una verificación obligatoria o datos que no deben salir.

Pregunta uno. Una fintech de pagos tiene la regla de que las transferencias sobre quinientos mil pesos requieren aprobación humana, y su agente a veces las ejecuta igual. ¿Qué cambio conviene? Opción A: un hook pre tool use que niega la transferencia sobre el umbral y redirige al flujo de escalamiento. Opción B: un hook post tool use que revise el monto de cada transferencia. Opción C: subir el énfasis de la regla en las instrucciones iniciales. Opción D: pedirle al cliente que confirme en el chat.

La correcta es A. El hook pre tool use corre antes de la herramienta y su resultado es determinista. La C sigue siendo una petición. En la B la herramienta ya corrió, así que la transferencia ya salió. La D no impone la aprobación humana.

Pregunta dos, de respuesta múltiple. Elige dos. Una empresa de courier usa herramientas MCP que devuelven las fechas como timestamp Unix o como ISO 8601, y los estados como números o como texto. El agente calcula mal los retrasos. Además, a veces intenta cancelar envíos ya despachados, contra la política. ¿Qué dos cambios corrigen los problemas? Opción A: agregar más ejemplos few-shot de cancelaciones correctas. Opción B: un hook pre tool use que niega la cancelación de envíos despachados y explica el motivo. Opción C: un hook post tool use que bloquee la cancelación de envíos despachados. Opción D: explicar en el prompt cómo leer cada formato. Opción E: un hook post tool use que normaliza fechas y estados antes de que el modelo los vea. ¿Cuáles dos?

Las correctas son B y E. La E entrega los datos en un solo formato, y la B bloquea la cancelación antes de que ocurra. La D funciona a veces y gasta contexto. En la C la herramienta ya corrió. La A sigue siendo una petición.

Resumen: pre tool use intercepta antes de la herramienta y post tool use normaliza lo que el modelo va a ver. Si la regla exige cumplimiento garantizado, gana el hook sobre el prompt. Si te sirvió, sigue el podcast, dale cinco estrellas y activa las notificaciones. En la próxima cápsula veremos cómo descomponer tareas complejas, con una cadena fija o con un plan que se adapta. Nos escuchamos en la próxima cápsula de EvoAcademy.