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

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

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

முகவரி அளவுருக்களில் 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" }
  }'

{
  "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 இல் உள்ளது.

பொதுவான சிக்கல்கள்#

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