Strumenti

Function calling — registrazione degli strumenti, schema JSON dei parametri, endpoint, autenticazione, retry e sicurezza.

Uno strumento è una funzione che il modello può decidere di invocare per leggere o scrivere dati sui tuoi sistemi. È il meccanismo con cui l'assistente passa dall'informare all'agire: verificare una disponibilità, creare una prenotazione, consultare lo stato di un ordine.

Come funziona

Il modello riceve nome, descrizione e schema dei parametri di ogni strumento collegato al progetto. Quando ritiene necessario invocarne uno, la piattaforma chiama il tuo endpoint HTTP, riceve il JSON di risposta e lo restituisce al modello, che formula la risposta finale o mostra un widget.

Prima di iniziare

Endpoint HTTPS raggiungibile da internet
Schema JSON dei parametri di ingresso
Credenziali di autenticazione del tuo servizio
Ruolo con permesso identity:projects:write

Registrare uno strumento

ConsoleConfigurazioneStrumentiNuovo strumento

Nome tecnico

Minuscolo, con caratteri di sottolineatura, massimo 48 caratteri: verifica_disponibilita. È immutabile e viene passato al modello.

Descrizione

È il campo che determina se e quando il modello sceglie lo strumento. Dedicagli il tempo necessario: vedi le regole più avanti.

Schema dei parametri

Definisci i parametri in JSON Schema. Il builder valida lo schema in tempo reale.

Endpoint e autenticazione

Inserisci metodo, URL e credenziali. Le credenziali sono cifrate a riposo.

Timeout, retry e collaudo

Imposta i limiti, esegui una chiamata di prova, poi collega lo strumento al progetto.

Nome e descrizione

La descrizione è l'unica informazione su cui il modello basa la scelta. Una descrizione vaga produce strumenti mai invocati o invocati a sproposito.

Regola	Motivo
Inizia con un verbo all'infinito	Dichiara l'azione in modo inequivocabile
Dichiara cosa restituisce	Il modello sa se lo strumento risolve la richiesta
Dichiara quando non usarlo	Riduce le invocazioni errate
Elenca i parametri obbligatori	Il modello li chiede all'utente prima di invocare
Massimo 400 caratteri	Descrizioni lunghe diluiscono il segnale

Descrizione efficace

Restituisce gli slot prenotabili per una prestazione sanitaria in un intervallo
di date, raggruppati per giorno e sede. Usalo ogni volta che il paziente chiede
disponibilità, orari liberi o quando si può venire. Non usarlo per confermare
una prenotazione: per quello usa crea_prenotazione. Richiede il codice della
prestazione e la data di inizio ricerca.

Descrizione inefficace

Controlla la disponibilità.

Sintomo tipico

Se il modello ignora uno strumento, nel 90% dei casi il problema è la descrizione, non la temperature. Vedi Modelli AI.

Schema dei parametri

Lo schema segue JSON Schema Draft 2020-12. Sono supportati string, number, integer, boolean, array, object, con enum, format, minimum, maximum, pattern, minItems, maxItems.

Schema dei parametri di verifica_disponibilita

{
  "type": "object",
  "properties": {
    "prestazione": {
      "type": "string",
      "description": "Codice della prestazione a catalogo, ad esempio VIS_CARD per la visita cardiologica.",
      "pattern": "^[A-Z]{3}_[A-Z]{2,8}$"
    },
    "dataInizio": {
      "type": "string",
      "format": "date",
      "description": "Primo giorno della ricerca in formato ISO 8601, ad esempio 2026-09-08."
    },
    "giorni": {
      "type": "integer",
      "description": "Ampiezza della finestra di ricerca in giorni.",
      "minimum": 1,
      "maximum": 60,
      "default": 14
    },
    "sede": {
      "type": "string",
      "description": "Codice della sede. Se omesso vengono considerate tutte le sedi.",
      "enum": ["MI01", "MI02", "BG01"]
    },
    "medico": {
      "type": "string",
      "description": "Identificativo del medico se il paziente ne ha indicato uno."
    }
  },
  "required": ["prestazione", "dataInizio"],
  "additionalProperties": false
}

Descrizioni anche nei parametri

Il campo description di ogni proprietà viene passato al modello. Includi sempre un esempio di valore: riduce drasticamente gli errori di formato.

Endpoint di destinazione

ConsoleConfigurazioneStrumentiverifica_disponibilitaEndpoint

Configurazione dell endpoint

Parametro	Tipo	Obblig.	Default	Descrizione
`method`	`string`	Sì	—	Metodo HTTP. Usa GET per le letture e POST per le operazioni che modificano dati.
`url`	`string`	Sì	—	URL completo in HTTPS. Sono ammessi segnaposto di percorso come /slots/{sede}.
`headers`	`object`	No	—	Header statici aggiunti a ogni chiamata.
`auth_type`	`string`	Sì	—	Tipo di autenticazione: none, header, bearer, api-key, hmac.
`timeout_ms`	`number`	No	—	Tempo massimo di attesa. Predefinito 8000, massimo 30000 millisecondi.
`retries`	`number`	No	—	Tentativi aggiuntivi in caso di errore ripetibile. Predefinito 2, massimo 5.
`retry_on`	`array`	No	—	Codici HTTP che attivano un nuovo tentativo. Predefinito 408, 429, 502, 503, 504.
`idempotency_header`	`string`	No	—	Header su cui inviare la chiave di idempotenza per le operazioni di scrittura.
`response_path`	`string`	No	—	Percorso JSON da estrarre dalla risposta prima di passarla al modello.

Autenticazione dello strumento

Tipo	Come viene inviata	Uso consigliato
`none`	Nessuna credenziale	Solo endpoint pubblici in sola lettura
`header`	Header personalizzato, ad esempio `X-Api-Key`	Servizi interni
`bearer`	`Authorization: Bearer <token>`	OAuth 2.0, token statici
`api-key`	Header o parametro di query configurabile	Gestionali di terze parti
`hmac`	Firma `X-Signature` calcolata sul corpo	Massima sicurezza sulle scritture

Segreto dello strumento

tls_9f21••••••••••••

Conservalo nel tuo gestore di segreti. Non compare più dopo la creazione.

Le credenziali non vanno nell URL

Non inserire token o chiavi nella query string: finiscono nei log del proxy e del server. Usa sempre un header.

Allowlist di rete

ConsoleConfigurazioneStrumentiImpostazioni di rete

Le chiamate agli strumenti partono dagli indirizzi IP statici della piattaforma. Autorizzali sul tuo firewall.

Intervalli IP in uscita (produzione, area EU)

20.61.98.0/27, 20.61.98.32/27

Aggiungi entrambi gli intervalli alla allowlist del tuo firewall.

Per motivi di sicurezza sono rifiutati gli URL che puntano a indirizzi privati (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8) e ai metadata degli hyperscaler.

Timeout, retry e gestione degli errori

Codice ricevuto	Comportamento della piattaforma	Cosa vede l'utente
`2xx`	Risposta passata al modello	Risposta normale
`400`	Nessun nuovo tentativo, errore passato al modello	Il modello chiede il dato mancante
`401` / `403`	Nessun nuovo tentativo, allarme all'amministratore	Messaggio di fallback
`404`	Nessun nuovo tentativo, trattato come risultato vuoto	"Non ho trovato risultati"
`408` / `429`	Nuovo tentativo con attesa crescente	Nessun effetto se rientra nei tempi
`5xx`	Fino a `retries` nuovi tentativi	Messaggio di fallback dopo l'ultimo
Timeout	Nuovo tentativo, poi fallback	"Il sistema non risponde, riprovo?"

Attese tra i tentativi: 1 secondo, 2 secondi, 4 secondi, con variazione casuale fino al 20% per evitare la sincronizzazione dei client.

Formato di errore consigliato per il tuo endpoint

{
  "error": {
    "code": "SLOT_NOT_AVAILABLE",
    "message": "Lo slot selezionato non è più disponibile.",
    "user_message": "Quell'orario è appena stato prenotato da un altro paziente.",
    "retryable": false
  }
}

Se presente, il campo user_message viene mostrato all'utente senza rielaborazione da parte del modello: usalo per i messaggi che devono essere esatti.

Esempio completo: verifica_disponibilita

Richiesta inviata al tuo endpoint

POSThttps://api.acme.it/v1/agenda/slotsHMAC

Endpoint del gestionale della clinica invocato dalla piattaforma.

Richiesta HTTP

POST /v1/agenda/slots HTTP/1.1
Host: api.acme.it
Content-Type: application/json
X-Bp-Tool: verifica_disponibilita
X-Bp-Session: ses_c41f7d2a9b0e4386
X-Bp-Timestamp: 1788508800
X-Signature: sha256=3f9c1ab2...
Idempotency-Key: 5f2b1c0e-8a41-4d33-9c77-2b1e04a9d7f0

{
  "prestazione": "VIS_CARD",
  "dataInizio": "2026-09-08",
  "giorni": 14,
  "sede": "MI01"
}

Risposta attesa

Risposta 200 del tuo endpoint

{
  "prestazione": {
    "codice": "VIS_CARD",
    "nome": "Visita cardiologica",
    "prezzo": 120,
    "durata": 30,
    "preparazione": "Porta con te eventuali esami precedenti ed elettrocardiogrammi."
  },
  "sede": {
    "codice": "MI01",
    "indirizzo": "Via Vittor Pisani 12, Milano"
  },
  "giorni": [
    {
      "data": "2026-09-09",
      "slots": [
        { "id": "slt_8812", "orario": "2026-09-09T09:00:00+02:00", "occupato": false, "remaining": 1 },
        { "id": "slt_8813", "orario": "2026-09-09T09:30:00+02:00", "occupato": true, "remaining": 0 },
        { "id": "slt_8814", "orario": "2026-09-09T15:00:00+02:00", "occupato": false, "remaining": 2 }
      ]
    },
    {
      "data": "2026-09-11",
      "slots": [
        { "id": "slt_8901", "orario": "2026-09-11T11:00:00+02:00", "occupato": false, "remaining": 3 }
      ]
    }
  ]
}

Questa struttura alimenta direttamente il widget slot_disponibili documentato in Widget Builder.

Nome dello strumento da citare nel prompt e nei flussi

verifica_disponibilita

Usalo nell azione Chiama strumento dei flussi conversazionali.

Collaudo dello strumento

ConsoleConfigurazioneStrumentiverifica_disponibilitaProva

Scheda	Verifica
Richiesta	Compila i parametri e invia una chiamata reale
Risposta	Corpo, codice HTTP, latenza e header ricevuti
Validazione	Conformità della risposta allo schema atteso
Simulazione modello	Il modello sceglie lo strumento data una frase dell'utente
Log	Ultime 100 invocazioni con esito, latenza e tentativi

Collauda la scelta, non solo la chiamata

Nella scheda Simulazione modello inserisci 10 frasi reali degli utenti e verifica che lo strumento venga selezionato quando serve e ignorato quando non serve.

Sicurezza

Operazioni distruttive

Non registrare strumenti che cancellano dati, annullano ordini, emettono rimborsi o modificano anagrafiche senza un passo di conferma esplicito nel flusso. Il modello può invocare uno strumento sulla base di un'interpretazione errata.

Regole da applicare sempre:

Separa lettura e scrittura. Uno strumento di lettura non deve avere credenziali che consentano la scrittura.
Applica il minimo privilegio. Le credenziali dello strumento devono poter fare solo ciò che lo strumento dichiara.
Richiedi conferma per le scritture. Inserisci un passo Chiedi con conferma esplicita prima di ogni azione irreversibile.
Usa l'idempotenza. Onora l'header Idempotency-Key: i nuovi tentativi non devono generare doppie prenotazioni.
Non restituire dati non necessari. La risposta entra nel contesto del modello: escludi codici fiscali, dati sanitari non pertinenti, campi interni.
Valida sul tuo server. Non fidarti dei parametri ricevuti: il modello può produrre valori inattesi. Rivalida sempre lato tuo.
Verifica la firma HMAC. Accetta solo richieste firmate e con timestamp recente. Vedi Firma HMAC.
Limita la frequenza. Applica un limite per sessione sul tuo endpoint.

Rischio	Mitigazione
Esfiltrazione di dati altrui	Filtra sempre per identificativo della sessione o dell'utente
Prenotazioni duplicate	Chiave di idempotenza e vincolo univoco a database
Enumerazione di anagrafiche	Nessuno strumento che accetti liste o caratteri jolly
Iniezione di istruzioni via risposta	Non restituire testo generato da terzi non filtrato
Consumo eccessivo	Limite di invocazioni per sessione, predefinito 10

Collegare lo strumento al progetto

ConsoleConfigurazioneProgettiacme-srlStrumenti

Attiva lo strumento sul progetto e sull'ambiente desiderato. In development puoi usare un endpoint di prova diverso da quello di produzione.

Passi successivi

Flussi conversazionali — usa lo strumento in un percorso guidato.
Widget Builder — trasforma la risposta in una scheda.
Automazioni e RPA — esponi i tuoi robot come strumenti.

Strumenti

In questa pagina