Eszközintegráció (API) létrehozása

Az eszközintegráció egy újrahasználható HTTP-végpont, amelyet egy ügynök hívás közben meghívhat. Ön egy JSON-séma szerinti leírást ad a ThunderPhone-nak az eszközről, valamint egy végponti URL-t; az ügynök a beszélgetés alapján dönti el, mikor hívja meg, a ThunderPhone pedig a szervereiről indítja a kimenő HTTP-kérést, és visszaadja a választ az ügynöknek.

Az irányítópult a legtöbb eszközigényt lefedi ezen API nélkül: a Kapcsolatok → Alkalmazások néhány OAuth-kattintással összeköti a Slacket, a HubSpotot, a Salesforce-t, a Google Naptárt, a Google Táblázatokat és a Cal.comot; a Kapcsolatok → API-k bármely HTTP API-t ügynökműveletté alakít (illesszen be egy cURL-parancsot, és egy AI-varázsló elkészíti az eszköz tervezetét, beépített Tesztkéréssel); a Kapcsolatok → MCP pedig MCP-szervereket ad hozzá. Lásd: Kapcsolatok. Ez az útmutató az API-k felülete mögötti nyers API-t ismerteti.

Ez az útmutató végigvezeti Önt egy időjárás-lekérdező eszköz teljes körű létrehozásán.

Egy eszköz felépítése

Két részből áll:

A séma — OpenAI-stílusú függvénydefiníció ({type: "function", function: {name, description, parameters}}), amely megmondja az LLM-nek, mit csinál az eszköz, és milyen argumentumokat fogad.
A végpont — az az URL, amelyet a ThunderPhone szerverei hívnak, amikor az LLM az eszköz használata mellett dönt. A kérés JSON POST, amelynek törzse az LLM által kiválasztott argumentumokat tartalmazza.

1. Válasszon tárolási stratégiát

Közvetlenül az ügynökön

Csatoljon egy egyszeri eszközt az ügynök tools tömbjéhez. Egyszerű, de nem újrahasználható.

Mentett integráció

Tárolja az eszközt újrahasználható integrációként, és kapcsolja össze több ügynökkel. Minden egynél többször használt eszközhöz ezt javasoljuk.

Ez az útmutató a mentett integrációs megközelítést használja.

2. Hozza létre az integrációt

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

Mentse el a visszaadott id értéket (egy UUID-t).

Fordítson kellő figyelmet az eszköz és minden paraméter description mezőjére. Az LLM ezeket a karakterláncokat használja futásidőben annak eldöntésére, hogy meghívja-e az eszközt, és ha igen, hogyan. Homályos leírások → homályos eszközhívások.

3. Tesztelje a végpontot sandboxban

Mielőtt összekapcsolja az integrációt egy ügynökkel, küldjön egy aláírt kérést a ThunderPhone szervereiről a kapcsolat ellenőrzéséhez:

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

Ez a teszt a ThunderPhone SSRF-védelmét is megerősíti — a localhostra vagy privát IP-tartományokra irányuló kérések 400 code=url_not_allowed választ adnak vissza.

4. Kapcsolja az integrációt egy ügynökhöz

Csatolja az integration_ids használatával, amikor ügynököt hoz létre vagy frissít:

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

Több integrációt is kapcsolhat egy ügynökhöz. Az ügynök promptja név szerint hivatkozhat rájuk — „használja a get_weather eszközt, amikor a hívó az időjárási körülményekről kérdez” —, vagy implicit módon is felismerheti őket a séma leírásaiból.

5. Implementálja a végpontot

Amikor az ügynök meghívja az eszközt, a ThunderPhone aláírt POST-kérést küld az Ön endpoint_url címére:

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

A szervere JSON-választ küld, amely visszakerül az LLM-hez:

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

Az LLM feldolgozza ezt a választ, és emberi összefoglalót mond a hívónak.

Az aláírás a nyers kéréstörzs alapján készül, ugyanazzal a secret értékkel, mint a webhook-végpontjánál. Ellenőrizze — az eszközvégpontok internet felől elérhetők, és a webhookokhoz hasonló hamisítási kockázatoknak vannak kitéve. Lásd: Webhook-aláírások ellenőrzése.

6. Tesztelje a folyamatot

Indítson egy mikrofonos munkamenetet az ügynökkel, és tegye fel az eszköze által kezelt kérdést („Milyen idő van 94110-ben?”). A hívás átirata a teljes oda-vissza folyamatot mutatja:

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

Ezt lekérheti a GET /v1/calls/{call_id}/transcript végponton; a nyers eseményfolyam (bejegyzésenkénti időzítéssel és hangeltolásokkal) itt érhető el: GET /v1/calls/{call_id}/history.

Gyakori buktatók

Az ügynök soha nem hívja meg az eszközt

Az LLM az eszköz leírása alapján dönt. Ha a hívó kérdése nem egyezik a leírással, a modell nem fogja meghívni az eszközt. Pontosítsa a leírást (adjon hozzá gyakori szinonimákat és megfogalmazásokat), vagy említse meg kifejezetten az ügynök promptjában („Amikor a hívó az időjárásról kérdez, használja a get_weather eszközt.”).

Az eszköz túl sok adatot ad vissza

A 6 kB-nál nagyobb válaszok csonkolva jelennek meg az átirat előnézetében. Csak azokat a mezőket adja vissza, amelyekre az LLM-nek szüksége van — ne a teljes rekordot.

Időtúllépések

Az eszközvégpontok alapértelmezett időtúllépése 10 másodperc. Ha hosszabb időre van szüksége, kezelje aszinkron módon: adja vissza a {"status": "pending", "request_id": "..."} választ, és jelenítse meg az eredményt külön eszközhíváson keresztül.

Verziókezelés

Minden integrációs PATCH új revíziót hoz létre. Vizsgálja meg a GET /v1/integrations/{id}/versions végpontot, hogy lássa, ki mit módosított. Ha hibásan módosítja egy eszköz sémáját, manuálisan visszaállíthatja egy régebbi pillanatkép PATCH-csel történő visszaírásával.

Következő lépések

Integrációk referenciája

CRUD, átvitel, verzióelőzmények.

Function Tools specifikáció

Teljes JSON-sémanyelvtan és az aláírt végpont szerződése.

Aláírások ellenőrzése

Alkalmazza a webhook-aláírási mintát az eszközvégpontokra.

Átirat + előzmények API

Vizsgálja meg egy eszközhívás teljes oda-vissza folyamatát.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Eszközintegráció (API) létrehozása

Egy eszköz felépítése

1. Válasszon tárolási stratégiát

Közvetlenül az ügynökön

Mentett integráció

2. Hozza létre az integrációt

3. Tesztelje a végpontot sandboxban

4. Kapcsolja az integrációt egy ügynökhöz

5. Implementálja a végpontot

6. Tesztelje a folyamatot

Gyakori buktatók

Következő lépések

Integrációk referenciája

Function Tools specifikáció

Aláírások ellenőrzése

Átirat + előzmények API

​Egy eszköz felépítése

​1. Válasszon tárolási stratégiát

Közvetlenül az ügynökön

Mentett integráció

​2. Hozza létre az integrációt

​3. Tesztelje a végpontot sandboxban

​4. Kapcsolja az integrációt egy ügynökhöz

​5. Implementálja a végpontot

​6. Tesztelje a folyamatot

​Gyakori buktatók

​Következő lépések

Integrációk referenciája

Function Tools specifikáció

Aláírások ellenőrzése

Átirat + előzmények API

Egy eszköz felépítése

1. Válasszon tárolási stratégiát

2. Hozza létre az integrációt

3. Tesztelje a végpontot sandboxban

4. Kapcsolja az integrációt egy ügynökhöz

5. Implementálja a végpontot

6. Tesztelje a folyamatot

Gyakori buktatók

Következő lépések