Cree una herramienta de API
Cree una herramienta de API que llame a su propio punto de conexión web durante una llamada, asóciela a un agente de voz o de WhatsApp y pruébela antes de publicar.
Qué conseguirá
Creará una herramienta como «consultar el estado de un pedido», la asociará a un agente y comprobará que funciona.
Requisitos previos
- Un punto de conexión web accesible desde internet (no una dirección privada ni localhost) que devuelva JSON o texto.
- El rol de owner o admin.
Configuración paso a paso
- Abra Tools en la barra lateral y elija Add tool.
- En New tool, rellene:
- Name: lo que ve el modelo, así que póngale el nombre de la acción, por ejemplo
lookup_order. Los espacios se convierten en guiones bajos y las letras en minúsculas. - Description: cómo decide el modelo cuándo llamarla, por ejemplo «Look up the delivery status of an order».
- Method: GET, POST, PUT, PATCH o DELETE.
- API endpoint: por ejemplo
https://api.yoursite.com/orders/{order_id}. Ponga un nombre entre llaves para incluirlo en la ruta.
- Name: lo que ve el modelo, así que póngale el nombre de la acción, por ejemplo
- Elija Create tool. Se abre la página de la propia herramienta para los detalles: parámetros, autenticación y límites.
- Añada cada Parameter que el modelo deba aportar (consulte la guía siguiente), fije Authentication si el punto de conexión la necesita y elija Save changes.
- Asóciela a un agente: abra el agente, pestaña Tools, Your tools, Add tool, Existing tool, márquela y elija Add tool. O elija ahí New tool para crearla y asociarla en un solo paso (Create and add).
- Pulse Save en el agente si muestra cambios sin guardar.
La página de la herramienta, sección por sección
| Sección | Qué contiene |
|---|---|
| What it does | Description: «Tells the model when to call this tool.» |
| When it runs | Run in the background: si el agente espera a la herramienta o sigue hablando. |
| Endpoint | Method y URL. Ponga {param} en la ruta, como /orders/{order_id}. |
| Body template | JSON opcional para POST, PUT y PATCH. Vacío significa que los parámetros se envían como JSON. |
| Read this from the response | Una ruta con puntos como data.status. Vacío devuelve todo. |
| Parameters | Lo que debe aportar el modelo, validado antes de cada solicitud. |
| Authentication | Type, Sent as, Name y el secreto. |
| Limits | Timeout y Attempts. |
| Test | Pruebe la herramienta con valores de ejemplo. |
Cómo se construye la solicitud
- Ruta.
{order_id}en la URL se sustituye por el valor, codificado para URL. - GET y DELETE. Los parámetros que no se usan en la ruta se envían como cadena de consulta.
- POST, PUT, PATCH. Los parámetros se envían como cuerpo JSON, o rellenan su Body template.
- No se siguen las redirecciones, las respuestas tienen un tope de 1 MB y se rechazan las direcciones privadas o internas.
Prueba
Use Test en la página de la herramienta (consulte Pruebe y diagnostique herramientas) y después Talk con el agente y pídale lo que hace la herramienta.
Resultado esperado
El agente responde usando el resultado de la herramienta y la fila de la herramienta en la página Tools muestra una solicitud contada como correcta.
Solución de problemas
- A tool named '…' already exists. Los nombres son únicos en un espacio de trabajo.
- El agente nunca la llama. Mejore la Description y mencione la herramienta en el system prompt.
- Consulte Fallos de herramientas.
Guías relacionadas
¿Algo de esto no coincide con lo que ve en el panel? Avísenos.