ThunderPhone v3 లైవ్‌లోకి వచ్చింది.మీరే ప్రారంభించవచ్చు—నిమిషానికి 2¢ నుంచి.ప్రకటనను చదవండి

Developer cookbook

టూల్ ఇంటిగ్రేషన్‌ను రూపొందించండి (API)

సంభాషణ మధ్యలో మీ ఏజెంట్ మీ APIలను కాల్ చేయనివ్వండి — డేటాబేస్‌ను శోధించండి, టికెట్‌ను సృష్టించండి, ఆర్డర్‌ను చూడండి.

టూల్ ఇంటిగ్రేషన్ అనేది ఏజెంట్ కాల్ సమయంలో ఇన్వోక్ చేయగల పునర్వినియోగ HTTP ఎండ్‌పాయింట్. మీరు ThunderPhoneకు టూల్ యొక్క JSON-స్కీమా వివరణతో పాటు ఎండ్‌పాయింట్ URL ఇస్తారు; సంభాషణ ఆధారంగా దాన్ని ఎప్పుడు కాల్ చేయాలో ఏజెంట్ నిర్ణయిస్తుంది, మరియు ThunderPhone తన సర్వర్‌ల నుంచి అవుట్‌బౌండ్ HTTP రిక్వెస్ట్ చేసి స్పందనను ఏజెంట్‌కు తిరిగి అందిస్తుంది.

ఈ గైడ్ వాతావరణాన్ని చూసే టూల్‌ను ప్రారంభం నుంచి ముగింపు వరకు రూపొందించడం గురించి వివరిస్తుంది.

టూల్ నిర్మాణం

రెండు భాగాలు:

  1. స్కీమా — OpenAI-శైలి ఫంక్షన్ నిర్వచనం ({type: "function", function: {name, description, parameters}}) ఇది టూల్ ఏమి చేస్తుందో, ఏ ఆర్గ్యుమెంట్‌లను తీసుకుంటుందో LLM‌కు తెలియజేస్తుంది.
  2. ఎండ్‌పాయింట్ — ఇంటిగ్రేషన్ అమలైనప్పుడు ThunderPhone సర్వర్‌లు కాల్ చేసే URL. ఏజెంట్-ట్రిగ్గర్ చేసిన టూల్‌ల కోసం, LLM ఎంచుకున్న ఆర్గ్యుమెంట్‌లను బాడీగా ఉంచి అభ్యర్థన JSON POST‌గా ఉంటుంది.

1. ఎడిటర్‌ను ఎంచుకోండి

డ్యాష్‌బోర్డ్

కనెక్షన్లు → APIలు తెరిచి, API కనెక్షన్‌ను సృష్టించండి లేదా సవరించండి, పారామీటర్ ఎడిటర్‌ను JSONకు మార్చి, అక్కడ ఫార్మాట్‌ను జోడించండి.

ఇంటిగ్రేషన్స్ API

POST /v1/integrationsతో స్పెక్‌ను సృష్టించండి లేదా PATCH /v1/integrations/{id}తో దాన్ని అప్‌డేట్ చేయండి.

రెండు మార్గాలూ సేవ్ చేసిన ఇంటిగ్రేషన్‌ను సృష్టిస్తాయి. సేవ్ చేసిన తర్వాత ఆ ఇంటిగ్రేషన్‌ను ఏజెంట్‌కు జతచేయండి. ఏజెంట్స్ APIలో వ్రాయగల ఇన్‌లైన్ tools ఫీల్డ్ లేదు. ఈ గైడ్ ఇంటిగ్రేషన్స్ API మార్గాన్ని ఉపయోగిస్తుంది.

2. ఇంటిగ్రేషన్‌ను సృష్టించండి

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

తిరిగి వచ్చిన id (ఒక UUID)ను సేవ్ చేయండి. హెడర్ విలువలు రైట్-ఓన్లీ: ప్రతిస్పందనలు హెడర్ పేర్లను మాత్రమే జాబితా చేస్తాయి, మరియు తర్వాతి PATCH నిల్వ చేసిన విలువను ఉంచడానికి value లేకుండానే హెడర్‌ను పంపగలదు.

చిరునామా పరామీటర్‌లపై format: "email"ను ప్రకటించండి

ఇమెయిల్ చిరునామాను స్వీకరించే పరామీటర్ దాని స్కీమాలో అలా పేర్కొనాలి:

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

format కేవలం సూచన కంటే ఎక్కువ. పరిష్కరించబడిన ఇమెయిల్ స్కీమా కోసం, మీ ఎండ్‌పాయింట్‌ను కాల్ చేయడానికి ముందు ThunderPhone విలువలోని అదనపు ఖాళీలను తొలగిస్తుంది, డొమైన్‌ను లోయర్‌కేస్‌గా మారుస్తుంది, స్వతంత్ర ఆంగ్ల పదాలైన at, dot, underscore, dash, మరియు hyphenలను వాటి అక్షరాలుగా మారుస్తుంది, అలాగే @, ., _, మరియు - చుట్టూ నేరుగా ఉన్న ఖాళీలను తొలగిస్తుంది. ట్రాన్స్‌క్రిప్ట్‌లో ఇప్పటికే అక్షరాలా @ ఉన్నా లేకపోయినా ఈ పదాలకు ఒకే అర్థం ఉంటుంది: "john dot smith at gmail dot com" ఇలా మారుతుంది john.smith@gmail.com.

ఇతర అంతర్గత ఖాళీలను నిశ్శబ్దంగా కలపకుండా తిరస్కరిస్తుంది. పలికే విభజన పదాలు ఆంగ్లానికి మాత్రమే వర్తిస్తాయి; ఆంగ్లేతర లేదా గుర్తించబడని ఖాళీలతో ఉన్న రూపాలు సురక్షితంగా విఫలమవుతాయి. చెల్లుబాటు అయ్యే అంతర్జాతీయీకరించిన డొమైన్‌లు మరియు SMTPUTF8 లోకల్ పార్ట్‌లు ఆమోదించబడతాయి. పార్సర్ సాధారణీకరణ తర్వాత Punycode ఇన్‌పుట్ Punycodeగానే, Unicode డొమైన్ ఇన్‌పుట్ Unicodeగానే ఉంటుంది; కాబట్టి మీ APIకి కాలర్ అందించిన సాంప్రదాయిక రూపమే అందుతుంది. తుది విలువ చెల్లనిది అయితే, టూల్‌ను కాల్ చేయరు. స్పెల్లింగ్‌ను కాలర్‌తో నిర్ధారించి అక్షరాలా ఉన్న చిరునామాను మళ్లీ పంపమని ఏజెంట్‌కు తెలిపే invalid_email_argument అందుతుంది.

వదిలివేయబడిన ఐచ్ఛిక ఇమెయిల్‌లో ఎలాంటి మార్పు ఉండదు. ప్రాపర్టీ ఐచ్ఛికం లేదా nullable అయినప్పుడు null, ఖాళీ స్ట్రింగ్ లేదా ఖాళీలతో మాత్రమే ఉన్న స్ట్రింగ్ కూడా మార్పు లేకుండానే ఉంటుంది; అవసరమైన, non-nullable ఇమెయిల్‌కు అదే విలువలు తిరస్కరించబడతాయి.

#/$defs/email, #/definitions/email వంటి స్థానిక స్కీమా రిఫరెన్స్‌లతో పాటు anyOf, oneOf, మరియు allOfలను సైకిల్ మరియు డెప్త్ పరిమితులతో పరిశీలిస్తారు. స్థానికం కాని లేదా పరిష్కరించలేని $ref తెలిసిన అమలు పరిమితి; ఉపయోగించదగిన స్కీమా లేని టూల్ స్నాప్‌షాట్‌తో చేసే కాల్‌ల మాదిరిగానే దానిని మార్పులేకుండా పంపుతారు. ఈ గేట్ వర్తించాల్సి ఉన్నప్పుడు ఇమెయిల్ స్కీమాలను స్థానికంగానే ఉంచండి.

అమలు చేయబడిన ఇమెయిల్ ఫార్మాట్ లేని పరామీటర్‌లను మోడల్ రూపొందించిన విధంగానే మార్పులేకుండా పంపుతారు.

మద్దతు ఉన్న ఫార్మాట్‌లు date-time, time, date, duration, email, hostname, ipv4, ipv6, మరియు uuid; ప్రస్తుతం email మాత్రమే సాధారణీకరించబడి అమలు చేయబడుతుంది.

3. ఎండ్‌పాయింట్‌ను సాండ్‌బాక్స్‌లో పరీక్షించండి

ఇంటిగ్రేషన్‌ను ఏజెంట్‌కు లింక్ చేసే ముందు, కనెక్టివిటీని నిర్ధారించడానికి ThunderPhone సర్వర్‌ల నుండి సంతకం చేసిన రిక్వెస్ట్‌ను పంపండి:

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_code": 200,
  "reason": "OK",
  "latency_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_body_preview": "{\"temperature_f\": 64, ...}",
  "response_truncated": false
}

ఈ పరీక్ష, లైవ్ టూల్ కాల్‌లో ఉండే అదే ThunderPhone హెడర్‌లను కలిగి ఉంటుంది. ఇది మీ సంస్థ యొక్క webhook సీక్రెట్‌తో సంతకం చేయబడుతుంది, కాబట్టి మీ సిగ్నేచర్ తనిఖీని కూడా పరీక్షిస్తుంది: X-ThunderPhone-Call-ID: test-request, X-ThunderPhone-Signature-V2 మరియు X-ThunderPhone-Signature. body JSONగా పంపబడుతుంది మరియు పంపిన విధంగానే సంతకం చేయబడుతుంది; GETతో, ఆర్గ్యుమెంట్‌లను URLలో ఉంచండి. పరీక్షకు కాల్ ఉండదు కాబట్టి, కాల్ యొక్క ఫోన్ నంబర్‌లు పంపబడవు.

ఈ పరీక్ష ThunderPhone యొక్క SSRF రక్షణలను కూడా బలోపేతం చేస్తుంది — localhost లేదా ప్రైవేట్ IP పరిధులకు చేసే రిక్వెస్ట్‌లు 400 code=url_not_allowedను అందిస్తాయి.

4. ఇంటిగ్రేషన్‌ను ఏజెంట్‌కు లింక్ చేయండి

ఏజెంట్‌ను సృష్టించినప్పుడు లేదా అప్‌డేట్ చేసినప్పుడు 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-..."]
  }'

మీరు ఒక ఏజెంట్‌కు అనేక ఇంటిగ్రేషన్‌లను లింక్ చేయవచ్చు. ఏజెంట్ prompt వాటిని పేరు ద్వారా సూచించవచ్చు — కాలర్ పరిస్థితుల గురించి అడిగినప్పుడు get_weather ఉపయోగించండి — లేదా స్కీమా వివరణల నుంచి వాటిని సూచ్యంగా గుర్తించవచ్చు.

5. ఎండ్‌పాయింట్‌ను అమలు చేయండి

ఏజెంట్ టూల్‌ను ఇన్‌వోక్ చేసినప్పుడు, ThunderPhone మీ endpoint_urlకు సంతకం చేసిన POST‌ను పంపుతుంది:

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

మీ సర్వర్ LLMకు తిరిగి అందించబడే JSONతో ప్రతిస్పందిస్తుంది:

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

LLM ఆ ప్రతిస్పందనను స్వీకరించి, కాలర్‌కు మానవీయ సారాంశాన్ని చెబుతుంది.

6. లూప్‌ను పరీక్షించండి

ఏజెంట్‌పై ఒక మైక్ సెషన్ను నడిపి, మీ టూల్ నిర్వహించే ప్రశ్నను అడగండి ("94110లో వాతావరణం ఎలా ఉంది?"). కాల్ ట్రాన్స్‌క్రిప్ట్ పూర్తి రౌండ్ ట్రిప్‌ను చూపిస్తుంది:

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

మీరు దీన్ని GET /v1/calls/{call_id}/transcript ద్వారా పొందవచ్చు; ప్రతి ఎంట్రీ సమయం మరియు ఆడియో ఆఫ్‌సెట్‌లతో కూడిన ముడి ఈవెంట్ స్ట్రీమ్ GET /v1/calls/{call_id}/historyలో ఉంటుంది.

Zeusలో, దీర్ఘ కాల్ ట్రాన్స్‌క్రిప్ట్‌లలో ఇప్పుడు కాల్ ప్రారంభం మరియు ముగింపు ఉంటాయి; అవసరమైనప్పుడు మధ్య భాగం పేజీలుగా విభజించబడుతుంది, కాబట్టి కాల్ ఎలా ముగిసిందో మీరు ఇంకా చూడవచ్చు.

కాల్ జాబితా మరియు విశ్లేషణ విభాగాల్లో, ThunderPhone ఇప్పుడు టెస్ట్ కాల్‌లను నిజమైన ట్రాఫిక్ నుండి వేరుగా నివేదిస్తుంది. బ్రౌజర్ టాక్ టెస్ట్‌లు మరియు సిమ్యులేషన్‌లు నిజమైన ఫోన్ నంబర్‌ను మళ్లీ ఉపయోగించవచ్చు మరియు ఇన్‌బౌండ్‌గా కనిపించవచ్చు, కానీ అవి ప్రొడక్షన్ కాల్ మొత్తం సంఖ్యలు, గ్రేడ్‌లు లేదా సమస్య మెట్రిక్‌లలో లెక్కించబడవు.

సాధారణ సమస్యలు

ఏజెంట్ టూల్‌ను ఎప్పుడూ కాల్ చేయదు

LLM టూల్ వివరణ ఆధారంగా నిర్ణయిస్తుంది. కాలర్ ప్రశ్న వివరణతో సరిపోలకపోతే, మోడల్ టూల్‌ను ఇన్‌వోక్ చేయదు. వివరణను మరింత స్పష్టంగా చేయండి (సాధారణ పర్యాయపదాలు మరియు పదబంధాలను జోడించండి) లేదా ఏజెంట్ promptలో స్పష్టంగా పేర్కొనండి (కాలర్ వాతావరణం గురించి అడిగినప్పుడు, get_weather ఉపయోగించండి.).

టూల్ చాలా ఎక్కువ డేటాను తిరిగి ఇస్తుంది

టూల్ ఫలితం సంభాషణలోనే ఉంటుంది, మరియు ఏజెంట్ దానిని ప్రతి తదుపరి టర్న్‌లో మళ్లీ చదువుతుంది, కాబట్టి పెద్ద ఫలితం కాల్‌లోని మిగతా భాగానికి ఖర్చు మరియు ఆలస్యాన్ని పెంచుతుంది. 100,000 అక్షరాలకు మించిన ఫలితాన్ని ప్రివ్యూకు కుదిస్తారు, మరియు అది అసంపూర్ణమని ఏజెంట్‌కు తెలియజేస్తారు. చాలా సుదీర్ఘ కాల్‌లో, పాత టూల్ ఫలితాలు ఏజెంట్ మెమరీ నుంచి తొలగించబడవచ్చు; అవి అవసరమైతే అది టూల్‌ను మళ్లీ కాల్ చేయగలదు.

ఫలితాలను చిన్నగా ఉంచడానికి:

  • మీ మొత్తం వరుసను కాకుండా, ఏజెంట్‌కు అవసరమైన ఫీల్డ్‌లను మాత్రమే తిరిగి ఇవ్వండి.
  • ప్రతిదీ ఫెచ్ చేయడానికి బదులుగా, ఏజెంట్ ఒకేసారి ఒక అంశం లేదా వర్గాన్ని చూసేలా ఒక పారామీటర్‌ను జోడించండి.
  • పెద్ద రిఫరెన్స్ కంటెంట్‌ను (మెనూలు, కేటలాగ్‌లు, విధానాలు) బదులుగా ఒక నాలెడ్జ్ బేస్లో ఉంచండి.

డ్యాష్‌బోర్డ్‌లోని పరీక్ష అభ్యర్థన పంపండి ఫలితం ఎంత పెద్దదో చూపిస్తుంది మరియు అది పెద్దదిగా ఉన్నప్పుడు హెచ్చరిస్తుంది.

సమయ పరిమితులు

టూల్ ఎండ్‌పాయింట్‌లకు డిఫాల్ట్ సమయ పరిమితి 20 సెకన్లు. గరిష్ఠంగా 180 సెకన్ల వరకు అనుమతించడానికి spec.timeout సెట్ చేయండి (టూల్స్ చూడండి). వ్యక్తి కోసం లేదా నెమ్మదిగా జరిగే జాబ్ కోసం వేచి ఉండే టూల్‌కు spec.wait_modeను "hold"గా సెట్ చేయండి: మాట్లాడే అప్‌డేట్‌ల బదులు కాలర్ హోల్డ్ సంగీతాన్ని వింటారు, మరియు spec.timeoutను గరిష్ఠంగా 600 సెకన్ల వరకు సెట్ చేయవచ్చు. మీ ఎండ్‌పాయింట్ ఇప్పటికీ 180 సెకన్లలోపు స్పందిస్తుంది; ఎక్కువసేపు వేచి ఉండడానికి, వెంటనే {"status": "pending", "request_id": "..."}ను రిటర్న్ చేసి, తర్వాత ఈ విధంగా ఫలితాన్ని అందించండి: POST /v1/calls/{call_id}/tool-results. సుదీర్ఘ నిరీక్షణలు చూడండి.

వెర్షనింగ్

ప్రతి ఇంటిగ్రేషన్ PATCH కొత్త రివిజన్‌ను సృష్టిస్తుంది. ఎవరు ఏమి మార్చారో చూడటానికి GET /v1/integrations/{id}/versionsను పరిశీలించండి. మీరు టూల్ స్కీమాను దెబ్బతీస్తే, పాత స్నాప్‌షాట్‌ను తిరిగి PATCH చేయడం ద్వారా మాన్యువల్‌గా రోల్‌బ్యాక్ చేయవచ్చు.


తదుపరి దశలు