ಟೂಲ್ ಏಕೀಕರಣವನ್ನು ನಿರ್ಮಿಸಿ (API)

ಸಂಭಾಷಣೆಯ ಮಧ್ಯೆ ನಿಮ್ಮ ಏಜೆಂಟ್‌ಗೆ ನಿಮ್ಮ APIಗಳನ್ನು ಕರೆಯಲು ಅನುಮತಿಸಿ — ಡೇಟಾಬೇಸ್‌ನಲ್ಲಿ ಹುಡುಕಿ, ಟಿಕೆಟ್ ರಚಿಸಿ, ಆರ್ಡರ್ ಅನ್ನು ಪರಿಶೀಲಿಸಿ.

ಟೂಲ್ ಏಕೀಕರಣವು ಏಜೆಂಟ್ ಕರೆಯ ಸಮಯದಲ್ಲಿ ಕರೆಸಬಹುದಾದ ಮರುಬಳಕೆ ಮಾಡಬಹುದಾದ HTTP ಎಂಡ್‌ಪಾಯಿಂಟ್ ಆಗಿದೆ. ನೀವು ThunderPhoneಗೆ ಟೂಲ್‌ನ JSON-ಸ್ಕೀಮಾ ವಿವರಣೆ ಮತ್ತು ಎಂಡ್‌ಪಾಯಿಂಟ್ URL ಅನ್ನು ನೀಡುತ್ತೀರಿ; ಸಂಭಾಷಣೆಯ ಆಧಾರದ ಮೇಲೆ ಅದನ್ನು ಯಾವಾಗ ಕರೆಯಬೇಕೆಂದು ಏಜೆಂಟ್ ನಿರ್ಧರಿಸುತ್ತದೆ, ಮತ್ತು ThunderPhone ತನ್ನ ಸರ್ವರ್‌ಗಳಿಂದ ಹೊರಹೋಗುವ HTTP ವಿನಂತಿಯನ್ನು ಮಾಡಿ ಪ್ರತಿಕ್ರಿಯೆಯನ್ನು ಏಜೆಂಟ್‌ಗೆ ಹಿಂತಿರುಗಿಸುತ್ತದೆ.

ಈ ಮಾರ್ಗದರ್ಶಿ ಹವಾಮಾನ-ಹುಡುಕಾಟ ಟೂಲ್ ಅನ್ನು ಆರಂಭದಿಂದ ಅಂತ್ಯದವರೆಗೆ ನಿರ್ಮಿಸುವ ವಿಧಾನವನ್ನು ವಿವರಿಸುತ್ತದೆ.

ಟೂಲ್‌ನ ರಚನೆ#

ಎರಡು ಭಾಗಗಳು:

1. ಸ್ಕೀಮಾ — OpenAI-ಶೈಲಿಯ ಕಾರ್ಯ ವ್ಯಾಖ್ಯಾನ ({type: "function", function: {name, description, parameters}}) ಇದು ಟೂಲ್ ಏನು ಮಾಡುತ್ತದೆ ಮತ್ತು ಅದು ಯಾವ ಆರ್ಗ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ಸ್ವೀಕರಿಸುತ್ತದೆ ಎಂಬುದನ್ನು LLMಗೆ ತಿಳಿಸುತ್ತದೆ.
2. ಎಂಡ್‌ಪಾಯಿಂಟ್ — LLM ಟೂಲ್ ಬಳಸಲು ನಿರ್ಧರಿಸಿದಾಗ ThunderPhoneನ ಸರ್ವರ್‌ಗಳು ಕರೆಯುವ URL. ವಿನಂತಿಯು JSON POST ಆಗಿದ್ದು, LLM ಆಯ್ಕೆಮಾಡಿದ ಆರ್ಗ್ಯುಮೆಂಟ್‌ಗಳು ಅದರ ಬಾಡಿಯಾಗಿರುತ್ತವೆ.

1. ಸಂಪಾದಕವನ್ನು ಆಯ್ಕೆಮಾಡಿ#

ಎರಡೂ ಮಾರ್ಗಗಳು ಉಳಿಸಲಾದ ಏಕೀಕರಣವನ್ನು ರಚಿಸುತ್ತವೆ. ಅದನ್ನು ಉಳಿಸಿದ ನಂತರ ಆ ಏಕೀಕರಣವನ್ನು ಏಜೆಂಟ್‌ಗೆ ಜೋಡಿಸಿ. ಏಜೆಂಟ್‌ಗಳ 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, ಖಾಲಿ ಸ್ಟ್ರಿಂಗ್, ಅಥವಾ ಕೇವಲ ಖಾಲಿ ಜಾಗವಿರುವ ಸ್ಟ್ರಿಂಗ್ ಅನ್ನೂ ಬದಲಾಯಿಸುವುದಿಲ್ಲ; ಅಗತ್ಯವಿರುವ, ಶೂನ್ಯಮೌಲ್ಯ-ಅನುಮತಿಸದ ಇಮೇಲ್‌ಗೆ ಇದೇ ಮೌಲ್ಯಗಳನ್ನು ತಿರಸ್ಕರಿಸಲಾಗುತ್ತದೆ.

#/$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 ಬಳಸಿ" — ಅಥವಾ ಸ್ಕೀಮಾ ವಿವರಣೆಗಳಿಂದ ಅವುಗಳನ್ನು ಸೂಚಿತವಾಗಿ ಕಂಡುಹಿಡಿಯಬಹುದು.

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 ನಲ್ಲಿ ಇದೆ.

ಸಾಮಾನ್ಯ ತೊಡಕುಗಳು#

ಮುಂದಿನ ಹಂತಗಳು#