---
title: "ஒரு கருவி ஒருங்கிணைப்பை உருவாக்குங்கள் (API)"
description: "உரையாடலின் நடுவில் உங்கள் ஏஜென்ட் உங்கள் API-களை அழைக்க அனுமதியுங்கள் — தரவுத்தளத்தில் தேடவும், டிக்கெட்டை உருவாக்கவும், ஆர்டரைப் பார்க்கவும்."
---

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

<Note>
  இந்த API இல்லாமலேயே டாஷ்போர்டு பெரும்பாலான கருவித் தேவைகளைப் பூர்த்தி செய்கிறது: **இணைப்புகள்
  → செயலிகள்** சில OAuth கிளிக்குகளில் Slack, HubSpot, Salesforce, Google Calendar,
  Google Sheets மற்றும் Cal.com-ஐ இணைக்கிறது; **இணைப்புகள் →
  APIகள்** எந்த HTTP API-யையும் ஏஜென்ட் செயலாக மாற்றுகிறது (ஒரு cURL கட்டளையை
  ஒட்டினால், உள்ளமைக்கப்பட்ட சோதனைக் கோரிக்கையுடன் ஒரு AI வழிகாட்டி கருவியை உருவாக்கும்); மேலும்
  **இணைப்புகள் → MCP** MCP சர்வர்களைச் சேர்க்கிறது. பார்க்கவும்
  [இணைப்புகள்](/ta/guides/concepts). இந்த வழிகாட்டி
  APIகள் இடைமுகத்தின் அடிப்படையிலுள்ள மூல API பற்றியது.
</Note>

இந்த வழிகாட்டி, வானிலைத் தேடல் கருவியைத் தொடக்கம் முதல் முடிவு வரை உருவாக்குவதைக் காட்டுகிறது.

## கருவியின் அமைப்பு

இரண்டு பகுதிகள்:

1. **ஸ்கீமா** — OpenAI பாணி செயல்பாட்டு வரையறை
   (`{type: "function", function: {name, description, parameters}}`);
   இது கருவி என்ன செய்கிறது, அது எந்த வாதங்களை ஏற்கிறது என்பதை LLM-க்கு தெரிவிக்கிறது.
2. **எண்ட்பாயிண்ட்** — கருவியைப் பயன்படுத்த LLM தீர்மானிக்கும்போது ThunderPhone-இன் சர்வர்கள் அழைக்கும் URL.
   கோரிக்கை JSON POST ஆகும்; LLM தேர்ந்தெடுத்த வாதங்கள் அதன் உடலாக இருக்கும்.

## 1. எடிட்டரைத் தேர்ந்தெடுக்கவும்

<CardGroup cols={2}>
  <Card title="டாஷ்போர்டு" icon="window-maximize">
    **இணைப்புகள் → APIகள்** என்பதைத் திறந்து, API இணைப்பை உருவாக்கவும் அல்லது திருத்தவும்,
    அளவுரு எடிட்டரை **JSON**-க்கு மாற்றி, அங்கு வடிவத்தைச் சேர்க்கவும்.
  </Card>
  <Card title="ஒருங்கிணைப்புகள் API" icon="plug">
    `POST /v1/integrations` மூலம் விவரக்குறிப்பை உருவாக்கவும் அல்லது
    `PATCH /v1/integrations/{id}` மூலம் அதைப் புதுப்பிக்கவும்.
  </Card>
</CardGroup>

இரண்டு வழிகளும் சேமிக்கப்பட்ட ஒருங்கிணைப்பை உருவாக்கும். சேமித்த பிறகு அந்த ஒருங்கிணைப்பை
ஏஜென்ட்டுடன் இணைக்கவும். ஏஜென்ட்கள் 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`, வெற்று சரம் அல்லது வெற்றிடம் மட்டுமே உள்ள சரமும் மாற்றப்படாது;
தேவையான, nullable அல்லாத மின்னஞ்சலுக்கு அதே மதிப்புகள் நிராகரிக்கப்படும்.

`#/$defs/email` மற்றும் `#/definitions/email` போன்ற உள்ளூர் ஸ்கீமா குறிப்புகளும்,
`anyOf`, `oneOf`, மற்றும் `allOf`-உம் சுழற்சி மற்றும் ஆழ வரம்புகளுடன் ஆய்வு செய்யப்படும்.
உள்ளூர் அல்லாத அல்லது தீர்மானிக்க முடியாத `$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>
  உங்கள் webhook எண்ட்பாயிண்டில் உள்ள அதே `secret` ஐப் பயன்படுத்தி, மூல கோரிக்கை உடலின் மீது கையொப்பம் கணக்கிடப்படுகிறது. **அதைச் சரிபார்க்கவும்** — கருவி எண்ட்பாயிண்டுகள் இணையத்தில் நேரடியாக அணுகக்கூடியவை; அவை webhook களைப் போலவே போலியாக உருவாக்கப்படும் கோரிக்கைகளின் அபாயங்களுக்கு உட்பட்டவை. பார்க்கவும்
  [Webhook கையொப்பங்களைச் சரிபார்க்கவும்](/ta/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="/ta/tools/overview">
    முழுமையான JSON schema இலக்கணமும் கையொப்பமிடப்பட்ட endpoint ஒப்பந்தமும்.
  </Card>
  <Card title="கையொப்பங்களைச் சரிபார்க்கவும்" icon="shield-check" href="/ta/guides/verify-webhook-signatures">
    webhook-கையொப்ப முறையை tool endpoint-களுக்குப் பயன்படுத்தவும்.
  </Card>
  <Card title="உரையாடல் பதிவு + வரலாறு API" icon="phone" href="/api-reference/calls">
    ஒரு tool அழைப்பின் முழு சுற்றுப்பயணத்தை ஆய்வு செய்யவும்.
  </Card>
</CardGroup>