Developer cookbook

Crea un

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.

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#

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

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

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

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#

Passaggi successivi#