ThunderPhone v3 இப்போது கிடைக்கிறது.நீங்களே தொடங்கலாம்; நிமிடத்திற்கு 2¢ முதல்.அறிவிப்பைப் படிக்கவும்

Developer cookbook

ஒரு கருவி ஒருங்கிணைப்பை உருவாக்குங்கள் (API)

உரையாடலின் நடுவில் உங்கள் ஏஜென்ட் உங்கள் API-களை அழைக்க அனுமதியுங்கள் — தரவுத்தளத்தில் தேடவும், டிக்கெட்டை உருவாக்கவும், ஆர்டரைப் பார்க்கவும்.

ஒரு கருவி ஒருங்கிணைப்பு என்பது அழைப்பின்போது ஒரு ஏஜென்ட் அழைக்கக்கூடிய மறுபயன்படுத்தத்தக்க HTTP எண்ட்பாயிண்ட் ஆகும். கருவியின் JSON-schema விளக்கத்தையும் ஒரு எண்ட்பாயிண்ட் URL-ஐயும் நீங்கள் ThunderPhone-க்கு வழங்குகிறீர்கள்; உரையாடலின் அடிப்படையில் அதை எப்போது அழைப்பது என்பதை ஏஜென்ட் தீர்மானிக்கும், மேலும் 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, வெற்று சரம் அல்லது வெற்றிடம் மட்டுமே உள்ள சரமும் மாற்றப்படாது; தேவையான, 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 அமைக்கவும் (Tools பார்க்கவும்). ஒரு நபர் அல்லது மெதுவான பணிக்காகக் காத்திருக்கும் டூலுக்கு, 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 செய்து கைமுறையாகப் பின்வாங்கலாம்.


அடுத்த படிகள்