Una acción es una herramienta que el agente puede invocar durante la conversación o que un flujo puede llamar en un paso tool_call. Cada acción es un endpoint HTTP tuyo, descrito con un esquema JSON de entrada.
Catálogo de conectores
Los conectores son plantillas de acciones con esquema ya definido:
- Internos: Firmer (facturación DIAN), CashHero (deducciones de delivery), Bigger, Parkia, Comparendos.
- Genéricos: webhook personalizado, correo saliente, Google Sheets vía webhook.
Desde Acciones instancias un conector, indicas tu URL y queda disponible para tus agentes y flujos.
Cómo llama talkHero a tu endpoint
POST con JSON en el cuerpo, timeout de 10 segundos, y estas cabeceras:
| Cabecera | Contenido |
|---|---|
x-talkhero-tool |
Nombre de la acción. |
x-talkhero-timestamp |
Milisegundos Unix. |
x-talkhero-signature |
sha256=<HMAC_SHA256(secreto, timestamp + "." + cuerpo)> |
X-Dry-Run |
1 cuando es una prueba y la acción declara soportarlo. |
El secreto de firma de cada acción se muestra en el panel. Verifica la firma igual que en los webhooks.
Responde 2xx con JSON: esa respuesta es lo que el agente usa para redactar o lo que el flujo guarda como output.
Seguridad por acción
| Ajuste | Comportamiento |
|---|---|
| Requiere confirmación | El agente pregunta al usuario antes de ejecutar y solo acepta la confirmación en el turno inmediato siguiente. |
| Irreversible | Igual que la anterior, obligatoria; pensada para acciones que no se pueden deshacer (reenviar un documento, cancelar). |
| Soporta dry run | Recibe X-Dry-Run: 1 en pruebas; si no lo soporta, la prueba se simula sin llamarte. |
| Habilitada | Un interruptor para retirar la acción sin borrarla. |
Buenas prácticas
- Devuelve mensajes de error claros en el JSON: el agente los usa para explicar qué pasó, nunca inventa un resultado.
- Mantén las respuestas pequeñas; el agente resume, no necesita el registro completo.
- Registra
x-talkhero-timestampy rechaza firmas viejas.