Δημιουργήστε μια ενσωμάτωση εργαλείου (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. Δοκιμάστε το τελικό σημείο σε sandbox

Πριν συνδέσετε την ενσωμάτωση με έναν πράκτορα, στείλτε ένα υπογεγραμμένο αίτημα από τους διακομιστές του 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, ...}"
}

Αυτή η δοκιμή ενισχύει επίσης τις δικλίδες SSRF του ThunderPhone — αιτήματα προς 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-..."]
  }'

Μπορείτε να συνδέσετε πολλές ενσωματώσεις με έναν πράκτορα. Η προτροπή του πράκτορα μπορεί να αναφέρεται σε αυτές με όνομα — «χρησιμοποιήστε το get_weather όταν ο καλών ρωτά για τις συνθήκες» — ή να τις ανακαλύπτει έμμεσα από τις περιγραφές του σχήματος.

5. Υλοποιήστε το endpoint

Όταν ο πράκτορας καλεί το εργαλείο, το ThunderPhone στέλνει ένα υπογεγραμμένο POST στο endpoint_url σας:

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.

Συνήθη προβλήματα

Επόμενα βήματα