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

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

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

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

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

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

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

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

రెండు మార్గాలూ సేవ్ చేసిన ఇంటిగ్రేషన్‌ను సృష్టిస్తాయి. సేవ్ చేసిన తర్వాత ఆ ఇంటిగ్రేషన్‌ను ఏజెంట్‌కు జతచేయండి. ఏజెంట్స్ 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" }
  }'

{
  "ok": true,
  "status": 200,
  "elapsed_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_preview": "{\"temperature_f\": 64, ...}"
}

ఈ పరీక్ష 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లో ఉంటుంది.

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

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

తదుపరి దశలు#