Vytvoření integrace nástroje (API)

Umožněte svému agentovi volat vaše API během konverzace — vyhledávat v databázi, vytvářet tikety nebo dohledávat objednávky.

Integrace nástroje je opakovaně použitelný koncový bod HTTP, který může agent vyvolat během hovoru. Poskytnete ThunderPhone popis nástroje ve formátu schématu JSON spolu s adresou URL koncového bodu; agent na základě konverzace rozhodne, kdy jej vyvolat, a ThunderPhone odešle ze svých serverů odchozí požadavek HTTP a vrátí odpověď agentovi.

Tento průvodce vás provede vytvořením nástroje pro vyhledávání počasí od začátku do konce.

Anatomie nástroje#

Dvě části:

1. Schéma — definice funkce ve stylu OpenAI ({type: "function", function: {name, description, parameters}}), která LLM říká, co nástroj dělá a jaké argumenty přijímá.
2. Koncový bod — adresa URL, kterou servery ThunderPhone volají, když se LLM rozhodne nástroj použít. Požadavek je JSON POST s argumenty vybranými LLM v těle.

1. Zvolte editor#

Obě cesty vytvoří uloženou integraci. Po uložení integraci přiřaďte agentovi. API agentů nemá zapisovatelné vložené pole tools. Tento průvodce používá cestu API integrací.

2. Vytvořte integraci#

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

Uložte vrácené id (UUID). Hodnoty hlaviček jsou pouze pro zápis: odpovědi uvádějí pouze názvy hlaviček a pozdější PATCH může odeslat hlavičku bez value, aby se zachovala uložená hodnota.

U parametrů adresy uveďte format: "email"#

Parametr, který přijímá e-mailovou adresu, by to měl uvádět ve svém schématu:

"email": { "type": "string", "format": "email", "description": "The caller's email address" }

format je více než jen nápověda. U vyřešeného e-mailového schématu ThunderPhone před voláním vašeho endpointu ořízne hodnotu, převede doménu na malá písmena, samostatná anglická slova at, dot, underscore, dash a hyphen převede na příslušné znaky a odstraní mezery přímo kolem @, ., _ a -. Slova mají stejný význam bez ohledu na to, zda přepis již obsahuje doslovné @: "john dot smith at gmail dot com" se změní na john.smith@gmail.com.

Jakékoli jiné vnitřní mezery jsou odmítnuty, nikoli potichu spojeny. Slova pro mluvené oddělovače jsou pouze v angličtině; neanglické nebo nerozpoznané varianty s mezerami jsou bezpečně odmítnuty. Platné internacionalizované domény a lokální části SMTPUTF8 jsou přijímány. Vstup v punycode zůstává punycode a vstup s doménou Unicode zůstává po normalizaci parserem v Unicode, takže vaše API obdrží běžnou reprezentaci zadanou volajícím. Pokud je výsledná hodnota neplatná, nástroj se nezavolá. Agent obdrží invalid_email_argument, které mu sdělí, aby s volajícím potvrdil pravopis a znovu odeslal doslovnou adresu.

Vynechaný volitelný e-mail zůstává beze změny. null, prázdný řetězec nebo řetězec obsahující pouze mezery rovněž zůstávají beze změny, pokud je vlastnost volitelná nebo umožňuje hodnotu null; stejné hodnoty jsou odmítnuty u povinného e-mailu, který hodnotu null neumožňuje.

Lokální odkazy na schéma, například #/$defs/email a #/definitions/email, spolu s anyOf, oneOf a allOf, jsou kontrolovány s limity pro cykly a hloubku. Nelokální nebo nevyřešitelný $ref představuje známé omezení vynucování a je předán beze změny, stejně jako volání, jehož snímek nástroje nemá použitelné schéma. Pokud potřebujete, aby se kontrola použila, zachovejte e-mailová schémata lokální.

Parametry bez vynucovaného e-mailového formátu jsou předány přesně tak, jak je model vytvořil.

Podporované formáty jsou date-time, time, date, duration, email, hostname, ipv4, ipv6 a uuid; v současnosti se normalizuje a vynucuje pouze email.

3. Otestujte endpoint v sandboxu#

Než integraci propojíte s agentem, odešlete podepsaný požadavek ze serverů ThunderPhone a ověřte připojení:

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

Tento test také posiluje ochrany ThunderPhone proti SSRF — požadavky na localhost nebo privátní rozsahy IP vracejí 400 code=url_not_allowed.

4. Propojte integraci s agentem#

Při vytváření nebo aktualizaci agenta ji připojte pomocí integration_ids:

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

K jednomu agentovi můžete připojit více integrací. Prompt agenta na ně může odkazovat podle názvu — „použij get_weather, když se volající zeptá na podmínky“ — nebo je může nepřímo rozpoznat z popisů schématu.

5. Implementujte endpoint#

Když agent vyvolá nástroj, ThunderPhone odešle podepsaný požadavek POST na váš endpoint_url:

POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<HMAC-SHA256 hex>
X-ThunderPhone-Signature: <HMAC-SHA256 hex>
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json

{"zip": "94110"}

Váš server odpoví JSONem, který se předá zpět LLM:

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

LLM tuto odpověď zpracuje a volajícímu sdělí srozumitelné shrnutí.

6. Otestujte celý proces#

Spusťte relaci s mikrofonem proti agentovi a položte otázku, kterou váš nástroj zpracovává („Jaké je počasí v 94110?“). Přepis hovoru zobrazuje celý průběh:

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

Můžete jej získat pomocí GET /v1/calls/{call_id}/transcript; nezpracovaný proud událostí (včetně časování jednotlivých záznamů a posunů zvuku) je na GET /v1/calls/{call_id}/history.

V seznamech hovorů a analytických přehledech ThunderPhone nyní uvádí testovací hovory odděleně od skutečného provozu. Testy a simulace v Browser Talk mohou znovu použít skutečné telefonní číslo a mohou vypadat jako příchozí, ale nezapočítávají se do celkového počtu produkčních hovorů, hodnocení ani metrik problémů.

Časté problémy#

Další kroky#