---
title: "ഒരു ടൂൾ ഇന്റഗ്രേഷൻ (API) നിർമ്മിക്കുക"
description: "സംഭാഷണത്തിനിടയിൽ നിങ്ങളുടെ API-കളെ വിളിക്കാൻ നിങ്ങളുടെ ഏജന്റിനെ അനുവദിക്കുക — ഒരു ഡാറ്റാബേസ് തിരയുക, ഒരു ടിക്കറ്റ് സൃഷ്ടിക്കുക, ഒരു ഓർഡർ പരിശോധിക്കുക."
---

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

<Note>
  ഈ API ഇല്ലാതെയും ഡാഷ്ബോർഡ് മിക്ക ടൂൾ ആവശ്യങ്ങളും കൈകാര്യം ചെയ്യുന്നു:
  **കണക്ഷനുകൾ → ആപ്പുകൾ** ഏതാനും OAuth ക്ലിക്കുകളിലൂടെ Slack, HubSpot,
  Salesforce, Google Calendar, Google Sheets, Cal.com എന്നിവ കണക്റ്റ് ചെയ്യുന്നു;
  **കണക്ഷനുകൾ → APIs** ഏത് HTTP API-യെയും ഒരു ഏജന്റ് ആക്ഷനാക്കി മാറ്റുന്നു
  (ഒരു cURL കമാൻഡ് പേസ്റ്റ് ചെയ്യുക, AI വിസാർഡ് ടൂളിന്റെ ഡ്രാഫ്റ്റ് തയ്യാറാക്കും;
  ബിൽറ്റ്-ഇൻ **ടെസ്റ്റ് റിക്വസ്റ്റ്** ഉൾപ്പെടെ); കൂടാതെ **കണക്ഷനുകൾ → MCP**
  MCP സെർവറുകൾ ചേർക്കുന്നു. [കണക്ഷനുകൾ](/ml/guides/concepts) കാണുക.
  ഈ ഗൈഡ് APIs ഇന്റർഫേസിന് അടിയിലുള്ള അടിസ്ഥാന API ആണ്.
</Note>

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

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

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

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

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

<CardGroup cols={2}>
  <Card title="ഡാഷ്ബോർഡ്" icon="window-maximize">
    **കണക്ഷനുകൾ → APIs** തുറക്കുക, API കണക്ഷൻ സൃഷ്ടിക്കുകയോ എഡിറ്റ് ചെയ്യുകയോ
    ചെയ്യുക, പാരാമീറ്റർ എഡിറ്റർ **JSON**-ലേക്ക് മാറ്റുക, തുടർന്ന് അവിടെ ഫോർമാറ്റ് ചേർക്കുക.
  </Card>
  <Card title="ഇന്റഗ്രേഷനുകൾ API" icon="plug">
    `POST /v1/integrations` ഉപയോഗിച്ച് സ്പെക്ക് സൃഷ്ടിക്കുക, അല്ലെങ്കിൽ
    `PATCH /v1/integrations/{id}` ഉപയോഗിച്ച് അത് അപ്ഡേറ്റ് ചെയ്യുക.
  </Card>
</CardGroup>

രണ്ട് മാർഗങ്ങളും സേവ് ചെയ്ത ഒരു ഇന്റഗ്രേഷൻ സൃഷ്ടിക്കുന്നു. സേവ് ചെയ്ത ശേഷം ആ
ഇന്റഗ്രേഷൻ ഏജന്റിലേക്ക് അറ്റാച്ച് ചെയ്യുക. Agents API-യിൽ എഴുതാവുന്ന ഇൻലൈൻ
`tools` ഫീൽഡ് ഇല്ല. ഈ ഗൈഡ് ഇന്റഗ്രേഷനുകൾ API മാർഗം ഉപയോഗിക്കുന്നു.

## 2. ഇന്റഗ്രേഷൻ സൃഷ്ടിക്കുക

```bash
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) സംരക്ഷിക്കുക.

<Tip>
  ടൂളിന്റെയും ഓരോ പാരാമീറ്ററിന്റെയും `description` തയ്യാറാക്കുന്നതിൽ യഥാർഥ ശ്രദ്ധ ചെലുത്തുക. ടൂൾ വിളിക്കണമോയെന്നും എങ്ങനെയാണെന്നും തീരുമാനിക്കാൻ LLM പ്രവർത്തനസമയത്ത് ഈ സ്ട്രിംഗുകൾ ഉപയോഗിക്കുന്നു. അവ്യക്തമായ വിവരണങ്ങൾ → അവ്യക്തമായ ടൂൾ കോളുകൾ.
</Tip>

### വിലാസ പാരാമീറ്ററുകളിൽ `format: "email"` പ്രഖ്യാപിക്കുക

ഒരു ഇമെയിൽ വിലാസം സ്വീകരിക്കുന്ന പാരാമീറ്റർ അതിന്റെ സ്കീമയിൽ അങ്ങനെ വ്യക്തമാക്കണം:

```json
"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-ന്റെ സെർവറുകളിൽ നിന്ന് ഒരു സൈൻ ചെയ്ത റിക്വസ്റ്റ് അയയ്ക്കുക:

```bash
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" }
  }'
```

```json Response
{
  "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` വഴി അറ്റാച്ച് ചെയ്യുക:

```bash
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 ഉപയോഗിച്ച് പ്രതികരിക്കുന്നു:

```json
{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}
```

LLM ആ പ്രതികരണം ഉൾക്കൊണ്ട് കോളർക്ക് മനുഷ്യർക്ക് മനസ്സിലാകുന്ന ഒരു സംഗ്രഹം പറയുന്നു.

<Warning>
  നിങ്ങളുടെ വെബ്ഹുക്ക് എൻഡ്പോയിന്റിലേതിന് സമാനമായ `secret` ഉപയോഗിച്ച്
  അസംസ്കൃത അഭ്യർത്ഥന ബോഡിയിലാണ് ഒപ്പ് കണക്കാക്കുന്നത്. **ഇത് സ്ഥിരീകരിക്കുക** —
  ടൂൾ എൻഡ്പോയിന്റുകൾ ഇന്റർനെറ്റിലേക്ക് തുറന്നിട്ടുള്ളവയാണ്, വെബ്ഹുക്കുകൾക്കുള്ളതിന്
  സമാനമായ സ്പൂഫിങ് ആശങ്കകൾ ഇവയ്ക്കും ബാധകമാണ്. കാണുക
  [വെബ്ഹുക്ക് ഒപ്പുകൾ സ്ഥിരീകരിക്കുക](/ml/guides/verify-webhook-signatures).
</Warning>

## 6. ലൂപ്പ് പരീക്ഷിക്കുക

ഏജന്റിനെതിരെ ഒരു [മൈക്ക് സെഷൻ](/api-reference/mic-sessions) പ്രവർത്തിപ്പിച്ച്
നിങ്ങളുടെ ടൂൾ കൈകാര്യം ചെയ്യുന്ന ചോദ്യം ചോദിക്കുക ("94110-ലെ കാലാവസ്ഥ എങ്ങനെയുണ്ട്?").
കോളിന്റെ ട്രാൻസ്ക്രിപ്റ്റ് മുഴുവൻ റൗണ്ട് ട്രിപ്പ് കാണിക്കുന്നു:

```json
{
  "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`](/api-reference/calls#get-transcript) വഴി ലഭ്യമാക്കാം;
ഓരോ എൻട്രിയുടെയും സമയവും ഓഡിയോ ഓഫ്‌സെറ്റുകളും ഉൾപ്പെടുന്ന അസംസ്കൃത ഇവന്റ് സ്ട്രീം
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history)-ൽ ലഭ്യമാണ്.

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

<AccordionGroup>
  <Accordion title="ഏജന്റ് ഒരിക്കലും ടൂൾ വിളിക്കുന്നില്ല">
    ടൂളിന്റെ വിവരണത്തെ അടിസ്ഥാനമാക്കിയാണ് LLM തീരുമാനിക്കുന്നത്. കോളറുടെ
    ചോദ്യം വിവരണവുമായി പൊരുത്തപ്പെടുന്നില്ലെങ്കിൽ, മോഡൽ ടൂൾ ഇൻവോക്ക് ചെയ്യില്ല.
    വിവരണം കൂടുതൽ കൃത്യമാക്കുക (സാധാരണ പര്യായങ്ങളും പ്രയോഗങ്ങളും ചേർക്കുക)
    അല്ലെങ്കിൽ ഏജന്റിന്റെ prompt-ൽ അത് വ്യക്തമായി പരാമർശിക്കുക ("കോളർ
    കാലാവസ്ഥയെക്കുറിച്ച് ചോദിക്കുമ്പോൾ, `get_weather` ഉപയോഗിക്കുക.").
  </Accordion>

  <Accordion title="ടൂൾ വളരെ അധികം ഡാറ്റ തിരികെ നൽകുന്നു">
    6 kB-ൽ കൂടുതലുള്ള പ്രതികരണങ്ങൾ ട്രാൻസ്ക്രിപ്റ്റ് പ്രിവ്യൂവിൽ വെട്ടിച്ചുരുക്കപ്പെടും.
    നിങ്ങളുടെ മുഴുവൻ വരിയല്ല, LLM-ന് ആവശ്യമായ ഫീൽഡുകൾ മാത്രം തിരികെ നൽകുക.
  </Accordion>

  <Accordion title="ടൈംഔട്ടുകൾ">
    ടൂൾ എൻഡ്പോയിന്റുകൾക്ക് 10 സെക്കൻഡിന്റെ ഡിഫോൾട്ട് ടൈംഔട്ട് ഉണ്ട്. കൂടുതൽ സമയം ആവശ്യമാണെങ്കിൽ,
    അസിങ്ക്രണസായി കൈകാര്യം ചെയ്യുക: `{"status": "pending", "request_id": "..."}`
    തിരികെ നൽകി, വേറൊരു ടൂൾ കോൾ വഴി ഫലം ലഭ്യമാക്കുക.
  </Accordion>

  <Accordion title="വർഷനിംഗ്">
    ഓരോ ഇന്റഗ്രേഷൻ `PATCH`-ഉം പുതിയൊരു റിവിഷൻ സൃഷ്ടിക്കുന്നു.
    ആരാണ് എന്ത് മാറ്റിയതെന്ന് കാണാൻ
    [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history)
    പരിശോധിക്കുക. ഒരു ടൂളിന്റെ സ്കീമ തകരാറിലാക്കിയാൽ, പഴയ ഒരു സ്നാപ്പ്ഷോട്ട് വീണ്ടും PATCH ചെയ്ത്
    നിങ്ങൾക്ക് മാനുവലായി റോൾ ബാക്ക് ചെയ്യാം.
  </Accordion>
</AccordionGroup>

---

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

<CardGroup cols={2}>
  <Card title="ഇന്റഗ്രേഷനുകളുടെ റഫറൻസ്" icon="plug" href="/api-reference/integrations">
    CRUD, ട്രാൻസ്ഫർ, പതിപ്പ് ചരിത്രം.
  </Card>
  <Card title="Function Tools സ്പെസിഫിക്കേഷൻ" icon="screwdriver-wrench" href="/ml/tools/overview">
    പൂർണ്ണ JSON സ്കീമ വ്യാകരണവും സൈൻ ചെയ്ത എൻഡ്‌പോയിന്റ് കരാറും.
  </Card>
  <Card title="സിഗ്നേച്ചറുകൾ പരിശോധിക്കുക" icon="shield-check" href="/ml/guides/verify-webhook-signatures">
    ടൂൾ എൻഡ്‌പോയിന്റുകളിൽ വെബ്ഹുക്ക്-സിഗ്നേച്ചർ പാറ്റേൺ പ്രയോഗിക്കുക.
  </Card>
  <Card title="ട്രാൻസ്ക്രിപ്റ്റ് + ചരിത്ര API" icon="phone" href="/api-reference/calls">
    ഒരു ടൂൾ കോളിന്റെ പൂർണ്ണ റൗണ്ട്-ട്രിപ്പ് പരിശോധിക്കുക.
  </Card>
</CardGroup>