Tool: l'agente chiama i tuoi endpoint HTTP

Tutto quello che l'agente fa oltre a parlare passa dai tool: leggere un'agenda, prenotare, controllare un ordine, aprire un ticket. Un tool è un endpoint GET o POST dalla tua parte, descritto per il modello con uno schema JSON. Il modello decide quando chiamarlo e con quali argomenti; la piattaforma esegue la richiesta.

Definire un tool

Un tool ha un nome, una descrizione scritta per il modello, uno schema JSON degli argomenti, e la parte di runtime: URL, metodo, header e un eventuale template del body. Scrivi segnaposto {{nome}} nell'URL, nei valori degli header o nel body; ogni segnaposto va dichiarato nello schema con una descrizione. Il modello lo riempie dalla conversazione e il runtime lo sostituisce, con URL-encoding nell'URL e con escape in un body JSON.

{
  "name": "book_appointment",
  "description": "Prenota un appuntamento. Chiamalo solo dopo che il cliente ha confermato giorno, ora e nome.",
  "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": "Codice sede: sempre 'zurich'" },
    "start":  { "type": "string", "description": "Inizio, yyyy-MM-dd HH:mm" },
    "name":   { "type": "string", "description": "Nome e cognome di chi chiama" },
    "phone":  { "type": "string", "description": "Telefono di chi chiama, solo cifre" }
  }, "required": ["clinic", "start", "name", "phone"] }
}

Cosa riceve il tuo endpoint e cosa deve rispondere

Ogni richiesta porta un header token con il tool token dell'agente: controllalo per primo. Rispondi 200 con un body JSON. In caso di successo, { "success": true, "message": "…" } più eventuali dati: il messaggio è pensato per essere riferito a chi chiama. In caso di errore di business, { "success": false, "error": "…" } con l'errore scritto come una frase per il modello, per esempio cosa proporre in alternativa. Su 401 o 500 l'agente si scusa e propone un richiamo. Tieni le risposte sotto qualche secondo: il cliente è in linea.

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: 'Quell\'orario è occupato. Proponi le 11:00 o le 14:30 dello stesso giorno.' });
  await book(req.params.clinic, start, name, phone);
  res.json({ success: true, message: 'Appuntamento prenotato per ' + start + '.' });
});

Un unico elenco di tool, condiviso dagli agenti

I tool stanno nella sezione Tool del pannello e gli agenti li usano per riferimento: modifichi un tool una volta e ogni agente che lo usa viene aggiornato. Un tool assegnato a un cliente può essere usato solo dagli agenti di quel cliente. Prima di salvare, il pannello controlla la definizione con Claude e costruisce lo schema dai segnaposto.

Prova senza ospitare niente

La sandbox è un insieme di endpoint d'esempio funzionanti, con dati di prova separati per ogni account: agenda, tavoli, magazzino, richiamate, rubrica, ordini. I suoi 22 tool sono già nella sezione Tool; ognuno ha una guida con i parametri, un esempio svolto di richiesta e risposta e il codice dell'endpoint, che puoi scaricare e usare come base.

Pagine correlate

• Prenotazioni al telefono, gestite da un agente IA
• Un SIP URI per ogni agente vocale
• Un pulsante di chiamata sul tuo sito, con l'agente che risponde