Herramientas: el agente llama a tus endpoints HTTP

Todo lo que el agente hace además de hablar pasa por herramientas: leer una agenda, reservar, comprobar un pedido, abrir un ticket. Una herramienta es un endpoint GET o POST de tu lado, descrito para el modelo con un esquema JSON. El modelo decide cuándo llamarlo y con qué argumentos; la plataforma realiza la petición.

Definir una herramienta

Una herramienta tiene un nombre, una descripción escrita para el modelo, un esquema JSON de sus argumentos y la parte de ejecución: URL, método, cabeceras y una plantilla de cuerpo opcional. Escribe marcadores {{nombre}} en la URL, en los valores de cabecera o en el cuerpo; cada marcador debe declararse en el esquema con una descripción. El modelo lo rellena a partir de la conversación y la ejecución lo sustituye, codificado en la URL y escapado en un cuerpo JSON.

{
  "name": "book_appointment",
  "description": "Reserva una cita. Llamar solo después de que quien llama confirme día, hora y nombre.",
  "method": "POST",
  "url": "https://api.example.ch/clinics/{{clinic}}/appointments",
  "headers": { "Authorization": "Bearer sk_…" },
  "body": "{ \"start\": \"{{start}}\", \"name\": \"{{name}}\", \"phone\": \"{{phone}}\" }",
  "schema": { "type": "object", "properties": {
    "clinic": { "type": "string", "description": "Código del centro: siempre 'zurich'" },
    "start":  { "type": "string", "description": "Inicio, yyyy-MM-dd HH:mm" },
    "name":   { "type": "string", "description": "Nombre y apellidos de quien llama" },
    "phone":  { "type": "string", "description": "Teléfono de quien llama, solo cifras" }
  }, "required": ["clinic", "start", "name", "phone"] }
}

Qué recibe tu endpoint y qué debe responder

Cada petición lleva una cabecera token con el token de herramientas del agente: compruébalo primero. Responde 200 con un cuerpo JSON. Con éxito, { "success": true, "message": "…" } más los datos que quieras: el mensaje está pensado para transmitirse a quien llama. Con un error de negocio, { "success": false, "error": "…" } con el error escrito como una frase para el modelo, por ejemplo qué proponer en su lugar. Ante 401 o 500 el agente se disculpa y ofrece devolver la llamada. Mantén las respuestas por debajo de unos segundos: el cliente espera en línea.

app.post('/clinics/:clinic/appointments', express.json(), async (req, res) => {
  if (req.get('token') !== process.env.SWISSAI_TOOL_TOKEN) return res.status(401).end();
  const { start, name, phone } = req.body;
  if (!(await isFree(req.params.clinic, start)))
    return res.json({ success: false, error: 'Esa hora está ocupada. Ofrece las 11:00 o las 14:30 del mismo día.' });
  await book(req.params.clinic, start, name, phone);
  res.json({ success: true, message: 'Cita reservada para ' + start + '.' });
});

Una sola lista de herramientas, compartida por los agentes

Las herramientas viven en la sección Herramientas del panel y los agentes las usan por referencia: editas una herramienta una vez y todos los agentes que la usan quedan actualizados. Una herramienta asignada a un cliente solo pueden usarla los agentes de ese cliente. Antes de guardar, el panel comprueba la definición con Claude y construye el esquema a partir de los marcadores.

Probar sin alojar nada

El sandbox es un conjunto de endpoints de ejemplo en funcionamiento, con datos de prueba separados para cada cuenta: agenda, mesas de restaurante, stock, devoluciones de llamada, contactos, pedidos. Sus 22 herramientas ya están en la sección Herramientas; cada una tiene una guía con los parámetros, un ejemplo resuelto de petición y respuesta y el código del endpoint, que puedes descargar y usar como base.

Páginas relacionadas

• Reserva de citas por teléfono, gestionada por un agente IA
• Una URI SIP para cada agente de voz
• Un botón de llamada en tu web, atendido por el agente