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

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

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

ਟੂਲ ਦੀ ਬਣਤਰ

ਦੋ ਹਿੱਸੇ:

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

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"}

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

{"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।

ਆਮ ਸਮੱਸਿਆਵਾਂ

ਅਗਲੇ ਕਦਮ