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

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

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

ടൂളിന്റെ ഘടന

രണ്ട് ഭാഗങ്ങൾ:

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

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-ലുണ്ട്.

സാധാരണ ശ്രദ്ധിക്കേണ്ട കാര്യങ്ങൾ

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