ਟੂਲ ਇੰਟੀਗ੍ਰੇਸ਼ਨ (API) ਬਣਾਓ

ਆਪਣੇ ਏਜੰਟ ਨੂੰ ਗੱਲਬਾਤ ਦੌਰਾਨ ਤੁਹਾਡੀਆਂ API ਕਾਲ ਕਰਨ ਦਿਓ — ਡੇਟਾਬੇਸ ਖੋਜੋ, ਟਿਕਟ ਬਣਾਓ, ਆਰਡਰ ਲੱਭੋ।

ਇੱਕ ਟੂਲ ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਮੁੜ ਵਰਤਣਯੋਗ HTTP ਐਂਡਪੌਇੰਟ ਹੈ ਜਿਸਨੂੰ ਏਜੰਟ ਕਾਲ ਦੌਰਾਨ ਚਲਾ ਸਕਦਾ ਹੈ। ਤੁਸੀਂ ThunderPhone ਨੂੰ ਟੂਲ ਦਾ JSON-schema ਵੇਰਵਾ ਅਤੇ ਇੱਕ ਐਂਡਪੌਇੰਟ URL ਦਿੰਦੇ ਹੋ; ਏਜੰਟ ਗੱਲਬਾਤ ਦੇ ਆਧਾਰ 'ਤੇ ਇਹ ਤੈਅ ਕਰਦਾ ਹੈ ਕਿ ਇਸਨੂੰ ਕਦੋਂ ਕਾਲ ਕਰਨਾ ਹੈ, ਅਤੇ ThunderPhone ਆਪਣੇ ਸਰਵਰਾਂ ਤੋਂ ਆਊਟਬਾਊਂਡ HTTP ਬੇਨਤੀ ਕਰਦਾ ਹੈ ਅਤੇ ਜਵਾਬ ਏਜੰਟ ਨੂੰ ਵਾਪਸ ਦਿੰਦਾ ਹੈ।

ਇਹ ਗਾਈਡ ਮੌਸਮ ਖੋਜਣ ਵਾਲਾ ਟੂਲ ਸ਼ੁਰੂ ਤੋਂ ਅੰਤ ਤੱਕ ਬਣਾਉਣ ਬਾਰੇ ਦੱਸਦੀ ਹੈ।

ਟੂਲ ਦੀ ਬਣਤਰ#

ਦੋ ਹਿੱਸੇ:

1. ਸਕੀਮਾ — ਇੱਕ OpenAI-ਸ਼ੈਲੀ ਫੰਕਸ਼ਨ ਪਰਿਭਾਸ਼ਾ ({type: "function", function: {name, description, parameters}}) ਜੋ LLM ਨੂੰ ਦੱਸਦੀ ਹੈ ਕਿ ਟੂਲ ਕੀ ਕਰਦਾ ਹੈ ਅਤੇ ਇਹ ਕਿਹੜੀਆਂ ਆਰਗੂਮੈਂਟਾਂ ਲੈਂਦਾ ਹੈ।
2. ਐਂਡਪੌਇੰਟ — ਉਹ URL ਜਿਸਨੂੰ ThunderPhone ਦੇ ਸਰਵਰ ਉਸ ਵੇਲੇ ਕਾਲ ਕਰਦੇ ਹਨ ਜਦੋਂ LLM ਟੂਲ ਵਰਤਣ ਦਾ ਫੈਸਲਾ ਕਰਦਾ ਹੈ। ਬੇਨਤੀ ਇੱਕ JSON POST ਹੁੰਦੀ ਹੈ ਜਿਸਦੀ ਬਾਡੀ ਵਿੱਚ LLM ਵੱਲੋਂ ਚੁਣੀਆਂ ਗਈਆਂ ਆਰਗੂਮੈਂਟਾਂ ਹੁੰਦੀਆਂ ਹਨ।

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 ਮਿਲਦਾ ਹੈ, ਜੋ ਉਸਨੂੰ ਕਾਲਰ ਨਾਲ ਸਪੈਲਿੰਗ ਦੀ ਪੁਸ਼ਟੀ ਕਰਨ ਅਤੇ ਅਸਲ ਐਡਰੈੱਸ ਮੁੜ ਭੇਜਣ ਲਈ ਕਹਿੰਦਾ ਹੈ।

ਛੱਡੀ ਗਈ ਵਿਕਲਪਿਕ ਈਮੇਲ ਨੂੰ ਬਿਨਾਂ ਬਦਲੇ ਰੱਖਿਆ ਜਾਂਦਾ ਹੈ। null, ਖਾਲੀ ਸਟਰਿੰਗ, ਜਾਂ ਸਿਰਫ਼ ਖਾਲੀ ਥਾਂ ਵਾਲੀ ਸਟਰਿੰਗ ਨੂੰ ਵੀ ਬਿਨਾਂ ਬਦਲੇ ਰੱਖਿਆ ਜਾਂਦਾ ਹੈ ਜਦੋਂ ਪ੍ਰਾਪਰਟੀ ਵਿਕਲਪਿਕ ਜਾਂ nullable ਹੋਵੇ; ਲੋੜੀਂਦੀ, non-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 ਵਰਤੋ" — ਜਾਂ ਇਹ schema ਵੇਰਵਿਆਂ ਤੋਂ ਉਹਨਾਂ ਨੂੰ ਅਸਿੱਧੇ ਤੌਰ 'ਤੇ ਪਛਾਣ ਸਕਦਾ ਹੈ।

5. endpoint ਲਾਗੂ ਕਰੋ#

ਜਦੋਂ ਏਜੰਟ ਟੂਲ ਨੂੰ ਚਲਾਉਂਦਾ ਹੈ, 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"}

ਤੁਹਾਡਾ ਸਰਵਰ JSON ਨਾਲ ਜਵਾਬ ਦਿੰਦਾ ਹੈ, ਜੋ LLM ਨੂੰ ਵਾਪਸ ਸੌਂਪਿਆ ਜਾਂਦਾ ਹੈ:

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

LLM ਉਸ ਜਵਾਬ ਨੂੰ ਪ੍ਰੋਸੈਸ ਕਰਦਾ ਹੈ ਅਤੇ ਕਾਲਰ ਨੂੰ ਮਨੁੱਖੀ-ਭਾਸ਼ਾ ਵਿੱਚ ਸੰਖੇਪ ਦੱਸਦਾ ਹੈ।

6. ਲੂਪ ਦੀ ਜਾਂਚ ਕਰੋ#

ਏਜੰਟ ਦੇ ਖ਼ਿਲਾਫ਼ ਇੱਕ mic ਸੈਸ਼ਨ ਚਲਾਓ ਅਤੇ ਉਹ ਸਵਾਲ ਪੁੱਛੋ ਜਿਸਨੂੰ ਤੁਹਾਡਾ ਟੂਲ ਸੰਭਾਲਦਾ ਹੈ ("94110 ਵਿੱਚ ਮੌਸਮ ਕਿਹੋ ਜਿਹਾ ਹੈ?")। ਕਾਲ ਦਾ ਟ੍ਰਾਂਸਕ੍ਰਿਪਟ ਪੂਰਾ round trip ਦਿਖਾਉਂਦਾ ਹੈ:

{
  "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 ਰਾਹੀਂ ਪ੍ਰਾਪਤ ਕਰ ਸਕਦੇ ਹੋ; raw event stream (ਹਰ ਐਂਟਰੀ ਦੀ timing ਅਤੇ audio offsets ਸਮੇਤ) ਇੱਥੇ ਹੈ GET /v1/calls/{call_id}/history।

ਆਮ ਸਮੱਸਿਆਵਾਂ#

ਅਗਲੇ ਕਦਮ#