Creați o integrare de instrumente (API)

O integrare de instrumente este un endpoint HTTP reutilizabil pe care un agent îl poate invoca în timpul unui apel. Oferiți ThunderPhone o descriere JSON Schema a instrumentului plus un URL de endpoint; agentul decide când să îl apeleze pe baza conversației, iar ThunderPhone efectuează cererea HTTP de ieșire de pe serverele sale și returnează răspunsul agentului.

Tabloul de bord acoperă majoritatea nevoilor de instrumente fără acest API: Conexiuni → Aplicații conectează Slack, HubSpot, Salesforce, Google Calendar, Google Sheets și Cal.com prin câteva clicuri OAuth; Conexiuni → API-uri transformă orice API HTTP într-o acțiune a agentului (lipiți o comandă cURL și un asistent AI creează o schiță a instrumentului, cu o opțiune integrată de Testare cerere); iar Conexiuni → MCP adaugă servere MCP. Consultați Conexiuni. Acest ghid prezintă API-ul de bază de sub suprafața API-urilor.

Acest ghid prezintă crearea completă a unui instrument de căutare a vremii.

Anatomia unui instrument

Două componente:

Schema — o definiție de funcție în stil OpenAI ({type: "function", function: {name, description, parameters}}) care îi indică LLM-ului ce face instrumentul și ce argumente acceptă.
Endpointul — URL-ul apelat de serverele ThunderPhone atunci când LLM-ul decide să utilizeze instrumentul. Cererea este un POST JSON, cu argumentele alese de LLM în corpul cererii.

1. Alegeți o strategie de stocare

Inclus direct în agent

Atașați un instrument punctual la matricea tools a agentului. Simplu, dar nereutilizabil.

Integrare salvată

Stocați instrumentul ca integrare reutilizabilă și conectați-l de la mai mulți agenți. Recomandat pentru orice este utilizat de mai multe ori.

Acest ghid utilizează varianta cu integrare salvată.

2. Creați integrarea

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

Salvați id returnat (un UUID).

Acordați atenție reală câmpului description al instrumentului și al fiecărui parametru. LLM-ul utilizează aceste șiruri în timpul execuției pentru a decide dacă și cum să apeleze instrumentul. Descrieri vagi → apeluri de instrumente vagi.

3. Testați endpointul în sandbox

Înainte de a conecta integrarea la un agent, trimiteți o cerere semnată de pe serverele ThunderPhone pentru a confirma conectivitatea:

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, ...}"
}

Acest test consolidează și protecțiile SSRF ale ThunderPhone — cererile către localhost sau intervale IP private returnează 400 code=url_not_allowed.

4. Conectați integrarea la un agent

Atașați prin integration_ids atunci când creați sau actualizați un agent:

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

Puteți conecta mai multe integrări la un singur agent. Instrucțiunea agentului le poate referi după nume — „utilizează get_weather atunci când apelantul întreabă despre condițiile meteo” — sau le poate descoperi implicit din descrierile schemei.

5. Implementați endpointul

Când agentul invocă instrumentul, ThunderPhone trimite un POST semnat către 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"}

Serverul dumneavoastră răspunde cu JSON, care este transmis înapoi către LLM:

{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}

LLM-ul preia acel răspuns și îi comunică apelantului un rezumat natural.

Semnătura este calculată pe corpul brut al solicitării, folosind același secret ca endpointul dumneavoastră de webhook. Verificați-o — endpointurile instrumentelor sunt accesibile de pe internet și sunt supuse acelorași riscuri de falsificare ca webhookurile. Consultați Verificarea semnăturilor webhook.

6. Testați fluxul

Rulați o sesiune de microfon pentru agent și puneți întrebarea pe care o gestionează instrumentul dumneavoastră („Cum este vremea în 94110?”). Transcrierea apelului arată întregul circuit:

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

Puteți prelua aceasta prin GET /v1/calls/{call_id}/transcript; fluxul brut de evenimente (cu temporizarea fiecărei intrări și decalajele audio) este disponibil la GET /v1/calls/{call_id}/history.

Probleme frecvente

Agentul nu apelează niciodată instrumentul

LLM-ul decide pe baza descrierii instrumentului. Dacă întrebarea apelantului nu corespunde descrierii, modelul nu va invoca instrumentul. Precizați descrierea (adăugați sinonime și formulări frecvente) sau menționați-l explicit în instrucțiunea agentului („Când apelantul întreabă despre vreme, utilizați get_weather.”).

Instrumentul returnează prea multe date

Răspunsurile de peste 6 kB sunt trunchiate în previzualizarea transcrierii. Returnați doar câmpurile de care are nevoie LLM-ul — nu întregul rând.

Expirări

Endpointurile instrumentelor au un timeout implicit de 10 secunde. Dacă aveți nevoie de mai mult timp, gestionați procesul asincron: returnați {"status": "pending", "request_id": "..."} și afișați rezultatul printr-un apel separat al instrumentului.

Versionare

Fiecare PATCH al unei integrări creează o revizie nouă. Consultați GET /v1/integrations/{id}/versions pentru a vedea cine a modificat ce. Dacă deteriorați schema unui instrument, puteți reveni manual aplicând prin PATCH un instantaneu mai vechi.

Pașii următori

Referință integrări

CRUD, transfer, istoric al versiunilor.

Specificația instrumentelor de funcție

Gramatica completă a schemei JSON și contractul pentru endpointuri semnate.

Verificați semnăturile

Aplicați modelul de semnătură webhook la endpointurile instrumentelor.

API pentru transcrieri și istoric

Inspectați întregul circuit al unui apel de instrument.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Creați o integrare de instrumente (API)

Anatomia unui instrument

1. Alegeți o strategie de stocare

Inclus direct în agent

Integrare salvată

2. Creați integrarea

3. Testați endpointul în sandbox

4. Conectați integrarea la un agent

5. Implementați endpointul

6. Testați fluxul

Probleme frecvente

Pașii următori

Referință integrări

Specificația instrumentelor de funcție

Verificați semnăturile

API pentru transcrieri și istoric

​Anatomia unui instrument

​1. Alegeți o strategie de stocare

Inclus direct în agent

Integrare salvată

​2. Creați integrarea

​3. Testați endpointul în sandbox

​4. Conectați integrarea la un agent

​5. Implementați endpointul

​6. Testați fluxul

​Probleme frecvente

​Pașii următori

Referință integrări

Specificația instrumentelor de funcție

Verificați semnăturile

API pentru transcrieri și istoric

Anatomia unui instrument

1. Alegeți o strategie de stocare

2. Creați integrarea

3. Testați endpointul în sandbox

4. Conectați integrarea la un agent

5. Implementați endpointul

6. Testați fluxul

Probleme frecvente

Pașii următori