Crea un'integrazione con strumenti (API)

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. 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:

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.
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

In linea sull'agente

Collega uno strumento monouso all’array tools dell’agente. Semplice, ma non riutilizzabile.

Integrazione salvata

Archivia lo strumento come integrazione 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

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à:

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" }
  }'

Response

{
  "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:

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: <HMAC-SHA256 hex>
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json

{"zip": "94110"}

Il tuo server risponde con JSON che viene restituito all’LLM:

{"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.

6. Testa il ciclo

Avvia una sessione microfono sull’agente e poni la domanda gestita dal tuo strumento (“Che tempo fa a 94110?”). La trascrizione della chiamata mostra l’intero ciclo:

{
  "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; il flusso di eventi non elaborato (con tempistiche per voce e offset audio) è disponibile in GET /v1/calls/{call_id}/history.

Problemi comuni

L'agente non richiama mai lo strumento

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.”).

Lo strumento restituisce troppi dati

Le risposte oltre 6 kB vengono troncate nell’anteprima della trascrizione. Restituisci solo i campi necessari all’LLM — non l’intera riga.

Timeout

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.

Versionamento

Ogni PATCH dell’integrazione crea una nuova revisione. Controlla GET /v1/integrations/{id}/versions 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

Riferimento delle integrazioni

CRUD, trasferimento, cronologia delle versioni.

Specifiche degli strumenti funzione

Grammatica completa dello schema JSON e contratto dell’endpoint firmato.

Verifica le firme

Applica il modello di firma webhook agli endpoint degli strumenti.

API di trascrizione + cronologia

Esamina l’intero ciclo di una chiamata a uno strumento.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Crea un'integrazione con strumenti (API)

Anatomia di uno strumento

1. Scegli una strategia di archiviazione

In linea sull'agente

Integrazione salvata

2. Crea l’integrazione

3. Testa l’endpoint nella sandbox

4. Collega l’integrazione a un agente

5. Implementa l’endpoint

6. Testa il ciclo

Problemi comuni

Passaggi successivi

Riferimento delle integrazioni

Specifiche degli strumenti funzione

Verifica le firme

API di trascrizione + cronologia

​Anatomia di uno strumento

​1. Scegli una strategia di archiviazione

In linea sull'agente

Integrazione salvata

​2. Crea l’integrazione

​3. Testa l’endpoint nella sandbox

​4. Collega l’integrazione a un agente

​5. Implementa l’endpoint

​6. Testa il ciclo

​Problemi comuni

​Passaggi successivi

Riferimento delle integrazioni

Specifiche degli strumenti funzione

Verifica le firme

API di trascrizione + cronologia

Anatomia di uno strumento

1. Scegli una strategia di archiviazione

2. Crea l’integrazione

3. Testa l’endpoint nella sandbox

4. Collega l’integrazione a un agente

5. Implementa l’endpoint

6. Testa il ciclo

Problemi comuni

Passaggi successivi