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

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

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

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

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

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

1. స్టోరేజ్ వ్యూహాన్ని ఎంచుకోండి

ఈ గైడ్ సేవ్ చేసిన ఇంటిగ్రేషన్ మార్గాన్ని ఉపయోగిస్తుంది.

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) సేవ్ చేయండి.

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: <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లో ఉంటుంది.

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

తదుపరి దశలు