> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Crea un'integrazione con strumenti (API)
> Consenti al tuo agente di chiamare le tue API durante una conversazione: cercare in un database, creare un ticket, cercare un ordine.
Un'**integrazione di strumenti** è un endpoint HTTP riutilizzabile che un agente può
richiamare durante una chiamata. Fornisci a ThunderPhone una descrizione dello schema JSON
dello strumento insieme a un URL dell'endpoint; l'agente decide quando richiamarlo
in base alla conversazione e ThunderPhone effettua la richiesta HTTP in uscita
dai propri server e restituisce la risposta all'agente.
La dashboard copre la maggior parte delle esigenze relative agli strumenti senza questa API: **Connessioni
→ App** collega Slack, HubSpot, Salesforce, Google Calendar,
Google Sheets e Cal.com in pochi clic OAuth; **Connessioni →
API** trasforma qualsiasi API HTTP in un'azione dell'agente (incolla un comando cURL
e una procedura guidata AI crea una bozza dello strumento, con una Richiesta di test integrata); e
**Connessioni → MCP** aggiunge server MCP. Vedi
[Connessioni](/it/guides/concepts). Questa guida riguarda l'API
sottostante all'interfaccia API.
Questa guida illustra la creazione completa di uno strumento per la ricerca meteo.
## Anatomia di uno strumento
Due elementi:
1. **Lo schema** — una definizione di funzione in stile OpenAI
(`{type: "function", function: {name, description, parameters}}`)
che indica al LLM cosa fa lo strumento e quali argomenti accetta.
2. **L'endpoint** — l'URL che i server di ThunderPhone richiamano quando il
LLM decide di usare lo strumento. La richiesta è un POST JSON con gli
argomenti scelti dal LLM come corpo.
## 1. Scegli una strategia di archiviazione
Collega uno strumento monouso all'array `tools` dell'agente. Semplice, ma
non riutilizzabile.
Archivia lo strumento come [integrazione](/api-reference/integrations) riutilizzabile
e collegalo a più agenti. Consigliato per tutto ciò che viene usato più
di una volta.
Questa guida utilizza il percorso dell'integrazione salvata.
## 2. Crea l'integrazione
```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/integrations \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"display_name": "Weather API",
"spec": {
"type": "function",
"function": {
"name": "get_weather",
"description": "Return the current weather for a zip code.",
"parameters": {
"type": "object",
"properties": {
"zip": { "type": "string", "description": "5-digit US ZIP code" }
},
"required": ["zip"]
}
}
},
"endpoint_url": "https://api.example.com/weather",
"endpoint_method": "GET",
"headers": [
{ "key": "X-Api-Key", "value": "your-provider-key" }
]
}'
```
Conserva l'`id` restituito (un UUID).
Dedica particolare attenzione alla `description` dello strumento e di ogni
parametro. Il LLM usa queste stringhe in fase di esecuzione per decidere se
e come richiamare lo strumento. Descrizioni vaghe → chiamate dello strumento vaghe.
## 3. Testa l'endpoint nella sandbox
Prima di collegare l'integrazione a un agente, invia una richiesta firmata
dai server di ThunderPhone per confermare la connettività:
```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/integrations/test-request \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.example.com/weather?zip=94110",
"method": "GET",
"headers": { "X-Api-Key": "your-provider-key" }
}'
```
```json Response theme={null}
{
"ok": true,
"status": 200,
"elapsed_ms": 187,
"response_headers": { "content-type": "application/json" },
"response_preview": "{\"temperature_f\": 64, ...}"
}
```
Questo test rafforza anche le protezioni SSRF di ThunderPhone — le richieste a
localhost o a intervalli di IP privati restituiscono `400 code=url_not_allowed`.
## 4. Collega l'integrazione a un agente
Collegala tramite `integration_ids` quando crei o aggiorni un agente:
```bash theme={null}
curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"integration_ids": ["f9b5a1a4-..."]
}'
```
Puoi collegare più integrazioni a un singolo agente. Il prompt dell'agente può
farvi riferimento per nome — "usa `get_weather` quando il chiamante chiede
delle condizioni meteorologiche" — oppure può individuarle implicitamente dalle
descrizioni dello schema.
## 5. Implementa l'endpoint
Quando l'agente richiama lo strumento, ThunderPhone invia un POST firmato al
tuo `endpoint_url`:
```
POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature:
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json
{"zip": "94110"}
```
Il tuo server risponde con JSON che viene restituito all'LLM:
```json theme={null}
{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}
```
L'LLM acquisisce quella risposta e comunica al chiamante un riepilogo in linguaggio naturale.
La firma viene calcolata sul corpo della richiesta non elaborato usando lo stesso
`secret` del tuo endpoint webhook. **Verificala** — gli endpoint degli strumenti
sono esposti a Internet e soggetti agli stessi rischi di spoofing dei
webhook. Vedi
[Verifica le firme dei webhook](/it/guides/verify-webhook-signatures).
## 6. Testa il ciclo
Avvia una [sessione microfono](/api-reference/mic-sessions) sull'agente
e poni la domanda gestita dal tuo strumento ("Che tempo fa a
94110?"). La trascrizione della chiamata mostra l'intero ciclo:
```json theme={null}
{
"call_id": 987654321,
"transcripts": [
{ "role": "user",
"content": "What's the weather in 94110?" },
{ "role": "tool_call",
"content": "{\"tool_call\": \"get_weather\", \"arguments\": {\"zip\": \"94110\"}}" },
{ "role": "tool_response",
"content": "{\"tool_name\": \"get_weather\", \"response\": {\"temperature_f\": 64, \"condition\": \"Partly cloudy\"}}" },
{ "role": "agent",
"content": "It's 64 degrees and partly cloudy." }
]
}
```
Puoi recuperarla tramite
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript);
il flusso di eventi non elaborato (con tempistiche per voce e offset audio) è disponibile in
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history).
## Problemi comuni
L'LLM decide in base alla descrizione dello strumento. Se la domanda del chiamante
non corrisponde alla descrizione, il modello non richiamerà
lo strumento. Rendi la descrizione più precisa (aggiungi sinonimi e formulazioni
comuni) oppure menzionalo esplicitamente nel prompt dell'agente ("Quando il
chiamante chiede del meteo, usa `get_weather`.").
Le risposte oltre 6 kB vengono troncate nell'anteprima della trascrizione. Restituisci
solo i campi necessari all'LLM — non l'intera riga.
Gli endpoint degli strumenti hanno un timeout predefinito di 10 secondi. Se ti serve più tempo,
gestiscilo in modo asincrono: restituisci `{"status": "pending", "request_id": "..."}`
e rendi disponibile il risultato tramite una chiamata separata allo strumento.
Ogni `PATCH` dell'integrazione crea una nuova revisione. Controlla
[`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history)
per vedere chi ha modificato cosa. Se comprometti lo schema di uno strumento, puoi
ripristinarlo manualmente applicando di nuovo tramite PATCH uno snapshot precedente.
***
## Passaggi successivi
CRUD, trasferimento, cronologia delle versioni.
Grammatica completa dello schema JSON e contratto dell'endpoint firmato.
Applica il modello di firma webhook agli endpoint degli strumenti.
Esamina l'intero ciclo di una chiamata a uno strumento.