ഒരു ടൂൾ ഇന്റഗ്രേഷൻ (API) നിർമ്മിക്കുക

സംഭാഷണത്തിനിടയിൽ നിങ്ങളുടെ API-കളെ വിളിക്കാൻ നിങ്ങളുടെ ഏജന്റിനെ അനുവദിക്കുക — ഒരു ഡാറ്റാബേസ് തിരയുക, ഒരു ടിക്കറ്റ് സൃഷ്ടിക്കുക, ഒരു ഓർഡർ പരിശോധിക്കുക.

ഒരു ടൂൾ ഇന്റഗ്രേഷൻ എന്നത് ഒരു കോളിനിടെ ഏജന്റിന് വിളിക്കാനാകുന്ന പുനരുപയോഗിക്കാവുന്ന HTTP എൻഡ്‌പോയിന്റാണ്. ടൂളിന്റെ JSON-schema വിവരണവും ഒരു എൻഡ്‌പോയിന്റ് URL-ഉം നിങ്ങൾ ThunderPhone-ന് നൽകുന്നു; സംഭാഷണത്തെ അടിസ്ഥാനമാക്കി അത് എപ്പോൾ വിളിക്കണമെന്ന് ഏജന്റ് തീരുമാനിക്കുന്നു, ThunderPhone അതിന്റെ സെർവറുകളിൽ നിന്ന് ഔട്ട്‌ബൗണ്ട് HTTP റിക്വസ്റ്റ് നടത്തി പ്രതികരണം ഏജന്റിന് നൽകുന്നു.

ഒരു കാലാവസ്ഥ-തിരയൽ ടൂൾ അവസാനംവരെ നിർമ്മിക്കുന്നതിലൂടെ ഈ ഗൈഡ് നിങ്ങളെ നയിക്കുന്നു.

ഒരു ടൂളിന്റെ ഘടന#

രണ്ട് ഘടകങ്ങൾ:

1. സ്കീമ — ഒരു OpenAI-ശൈലിയിലുള്ള ഫംഗ്ഷൻ നിർവചനം ({type: "function", function: {name, description, parameters}}) ടൂൾ എന്താണ് ചെയ്യുന്നതെന്നും അത് സ്വീകരിക്കുന്ന ആർഗ്യുമെന്റുകൾ എന്തൊക്കെയാണെന്നും LLM-നോട് പറയുന്നു.
2. എൻഡ്‌പോയിന്റ് — ടൂൾ ഉപയോഗിക്കാൻ LLM തീരുമാനിക്കുമ്പോൾ ThunderPhone-ന്റെ സെർവറുകൾ വിളിക്കുന്ന URL. LLM തിരഞ്ഞെടുത്ത ആർഗ്യുമെന്റുകൾ ബോഡിയായി ഉൾക്കൊള്ളുന്ന JSON POST റിക്വസ്റ്റാണിത്.

1. ഒരു എഡിറ്റർ തിരഞ്ഞെടുക്കുക#

രണ്ട് മാർഗങ്ങളും സേവ് ചെയ്ത ഒരു ഇന്റഗ്രേഷൻ സൃഷ്ടിക്കുന്നു. സേവ് ചെയ്ത ശേഷം ആ ഇന്റഗ്രേഷൻ ഏജന്റിലേക്ക് അറ്റാച്ച് ചെയ്യുക. Agents 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, ശൂന്യ സ്ട്രിംഗ്, അല്ലെങ്കിൽ ഒഴിവിടങ്ങൾ മാത്രമുള്ള സ്ട്രിംഗ് എന്നിവയും മാറ്റമില്ലാതെ തുടരും; ആവശ്യമായ, non-nullable ഇമെയിലിന് ഇതേ മൂല്യങ്ങൾ നിരസിക്കപ്പെടും.

#/$defs/email, #/definitions/email എന്നിവ പോലുള്ള ലോക്കൽ സ്കീമ റഫറൻസുകളും anyOf, oneOf, allOf എന്നിവയും സൈക്കിൾ, ആഴ പരിധികളോടെ പരിശോധിക്കുന്നു. non-local അല്ലെങ്കിൽ പരിഹരിക്കാനാകാത്ത $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-ൽ ലഭ്യമാണ്.

സാധാരണ പിഴവുകൾ#

അടുത്ത ഘട്ടങ്ങൾ#