Το ThunderPhone v3 είναι πλέον διαθέσιμο.Ξεκινήστε μόνοι σας, από 2¢/λεπτό.Διαβάστε την ανακοίνωση

Developer cookbook

Δημιουργήστε μια ενσωμάτωση εργαλείου (API)

Επιτρέψτε στον πράκτορά σας να καλεί τα API σας κατά τη διάρκεια της συνομιλίας — να αναζητά σε μια βάση δεδομένων, να δημιουργεί ένα αίτημα υποστήριξης, να εντοπίζει μια παραγγελία.

Μια ενσωμάτωση εργαλείου είναι ένα επαναχρησιμοποιήσιμο τελικό σημείο HTTP που ένας πράκτορας μπορεί να καλέσει κατά τη διάρκεια μιας κλήσης. Παρέχετε στο ThunderPhone μια περιγραφή σχήματος JSON του εργαλείου μαζί με ένα URL τελικού σημείου· ο πράκτορας αποφασίζει πότε να το καλέσει με βάση τη συνομιλία και το ThunderPhone πραγματοποιεί το εξερχόμενο αίτημα HTTP από τους διακομιστές του και επιστρέφει την απάντηση στον πράκτορα.

Αυτός ο οδηγός παρουσιάζει τη δημιουργία ενός εργαλείου αναζήτησης καιρού από άκρο σε άκρο.

Ανατομία ενός εργαλείου

Δύο μέρη:

  1. Το σχήμα — ένας ορισμός συνάρτησης τύπου OpenAI ({type: "function", function: {name, description, parameters}}) που ενημερώνει το LLM για το τι κάνει το εργαλείο και ποια ορίσματα δέχεται.
  2. Το τελικό σημείο — το URL που καλούν οι διακομιστές του ThunderPhone όταν εκτελείται η ενσωμάτωση. Για εργαλεία που ενεργοποιούνται από τον πράκτορα, το αίτημα είναι JSON POST με τα ορίσματα που επέλεξε το LLM ως σώμα.

1. Επιλέξτε επεξεργαστή

Πίνακας ελέγχου

Ανοίξτε τις Συνδέσεις → APIs, δημιουργήστε ή επεξεργαστείτε τη σύνδεση API, αλλάξτε τον επεξεργαστή παραμέτρων σε JSON και προσθέστε εκεί τη μορφή.

API ενσωματώσεων

Δημιουργήστε την προδιαγραφή με POST /v1/integrations ή ενημερώστε την με PATCH /v1/integrations/{id}.

Και οι δύο διαδρομές δημιουργούν μια αποθηκευμένη ενσωμάτωση. Επισυνάψτε αυτή την ενσωμάτωση στον πράκτορα αφού την αποθηκεύσετε. Το API Agents δεν διαθέτει εγγράψιμο ενσωματωμένο πεδίο 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). Οι τιμές κεφαλίδων είναι μόνο για εγγραφή: οι αποκρίσεις παραθέτουν μόνο τα ονόματα κεφαλίδων και ένα μεταγενέστερο PATCH μπορεί να στείλει μια κεφαλίδα χωρίς value ώστε να διατηρηθεί η αποθηκευμένη τιμή.

Δηλώστε format: "email" στις παραμέτρους διεύθυνσης

Μια παράμετρος που δέχεται διεύθυνση email πρέπει να το δηλώνει στο σχήμα της:

"email": { "type": "string", "format": "email", "description": "The caller's email address" }

Το format είναι κάτι περισσότερο από υπόδειξη. Για ένα επιλυμένο σχήμα email, πριν κληθεί το τελικό σας σημείο, το 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, το οποίο του υποδεικνύει να επιβεβαιώσει την ορθογραφία με τον καλούντα και να στείλει ξανά την κυριολεκτική διεύθυνση.

Ένα παραλειπόμενο προαιρετικό email παραμένει ανέπαφο. Το null, μια κενή συμβολοσειρά ή μια συμβολοσειρά μόνο με κενά παραμένουν επίσης ανέπαφα όταν η ιδιότητα είναι προαιρετική ή δέχεται τιμή null· οι ίδιες τιμές απορρίπτονται για ένα υποχρεωτικό email που δεν δέχεται null.

Οι τοπικές αναφορές σχήματος, όπως #/$defs/email και #/definitions/email, καθώς και τα anyOf, oneOf και allOf, ελέγχονται με όρια κύκλων και βάθους. Ένα μη τοπικό ή μη επιλύσιμο $ref αποτελεί γνωστό όριο επιβολής και περνάει αμετάβλητο, όπως και μια κλήση της οποίας το στιγμιότυπο εργαλείου δεν έχει χρησιμοποιήσιμο σχήμα. Διατηρήστε τα σχήματα email τοπικά όταν χρειάζεστε να εφαρμοστεί ο έλεγχος.

Οι παράμετροι χωρίς επιβαλλόμενη μορφή email περνούν ακριβώς όπως τις παρήγαγε το μοντέλο.

Οι υποστηριζόμενες μορφές είναι date-time, time, date, duration, email, hostname, ipv4, ipv6 και uuid· μόνο το email κανονικοποιείται και επιβάλλεται σήμερα.

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" }
  }'
Response
{
  "ok": true,
  "status_code": 200,
  "reason": "OK",
  "latency_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_body_preview": "{\"temperature_f\": 64, ...}",
  "response_truncated": false
}

Η δοκιμή περιλαμβάνει τις ίδιες κεφαλίδες ThunderPhone με μια ενεργή κλήση εργαλείου, υπογεγραμμένες με το μυστικό webhook του οργανισμού σας, επομένως ελέγχει επίσης τον έλεγχο υπογραφής σας: X-ThunderPhone-Call-ID: test-request, X-ThunderPhone-Signature-V2 και X-ThunderPhone-Signature. Ένα body αποστέλλεται ως JSON και υπογράφεται όπως αποστέλλεται· με GET, τοποθετήστε τα ορίσματα στο URL. Οι αριθμοί τηλεφώνου της κλήσης δεν αποστέλλονται, καθώς μια δοκιμή δεν έχει κλήση.

Αυτή η δοκιμή ενισχύει επίσης τις προστασίες 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. Υλοποιήστε το τελικό σημείο

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

POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<HMAC-SHA256 hex>
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.

Στο Zeus, οι μεγάλες απομαγνητοφωνήσεις κλήσεων περιλαμβάνουν πλέον την αρχή και το τέλος της κλήσης, με το ενδιάμεσο τμήμα να σελιδοποιείται όταν χρειάζεται, ώστε να μπορείτε να βλέπετε πώς ολοκληρώθηκε η κλήση.

Στις επιφάνειες καταχώρισης κλήσεων και αναλύσεων, το ThunderPhone αναφέρει πλέον τις δοκιμαστικές κλήσεις ξεχωριστά από την πραγματική κίνηση. Οι δοκιμές και οι προσομοιώσεις «Μιλήστε» στο πρόγραμμα περιήγησης μπορούν να επαναχρησιμοποιούν έναν πραγματικό αριθμό τηλεφώνου και ενδέχεται να φαίνονται ως εισερχόμενες, αλλά δεν προσμετρώνται στα σύνολα κλήσεων παραγωγής, στις βαθμολογίες ή στις μετρήσεις ζητημάτων.

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

Ο πράκτορας δεν καλεί ποτέ το εργαλείο

Το LLM αποφασίζει με βάση την περιγραφή του εργαλείου. Αν η ερώτηση του καλούντος δεν αντιστοιχεί στην περιγραφή, το μοντέλο δεν θα καλέσει το εργαλείο. Κάντε την περιγραφή πιο συγκεκριμένη (προσθέστε συνήθη συνώνυμα και διατυπώσεις) ή αναφέρετέ το ρητά στην προτροπή του πράκτορα («Όταν ο καλών ρωτά για τον καιρό, χρησιμοποιήστε το get_weather.»).

Το εργαλείο επιστρέφει υπερβολικά πολλά δεδομένα

Το αποτέλεσμα ενός εργαλείου παραμένει στη συνομιλία και ο πράκτορας το διαβάζει ξανά σε κάθε επόμενο γύρο, επομένως ένα μεγάλο αποτέλεσμα αυξάνει το κόστος και την καθυστέρηση για το υπόλοιπο της κλήσης. Ένα αποτέλεσμα με περισσότερους από 100.000 χαρακτήρες περιορίζεται σε μια προεπισκόπηση και ο πράκτορας ενημερώνεται ότι είναι ελλιπές. Σε μια πολύ μεγάλη κλήση, παλαιότερα αποτελέσματα εργαλείων μπορεί να αφαιρεθούν από τη μνήμη του πράκτορα· μπορεί να καλέσει το εργαλείο ξανά, αν τα χρειάζεται.

Για να διατηρείτε τα αποτελέσματα μικρά:

  • Επιστρέφετε μόνο τα πεδία που χρειάζεται ο πράκτορας, όχι ολόκληρη την εγγραφή σας.
  • Προσθέστε μια παράμετρο ώστε ο πράκτορας να μπορεί να αναζητά ένα στοιχείο ή κατηγορία κάθε φορά, αντί να ανακτά τα πάντα.
  • Τοποθετήστε μεγάλο περιεχόμενο αναφοράς (μενού, καταλόγους, πολιτικές) σε μια βάση γνώσεων.

Η επιλογή Αποστολή δοκιμαστικού αιτήματος στον πίνακα ελέγχου δείχνει πόσο μεγάλο είναι ένα αποτέλεσμα και προειδοποιεί όταν είναι μεγάλο.

Χρονικά όρια

Τα τελικά σημεία εργαλείων έχουν προεπιλεγμένο χρονικό όριο 20 δευτερολέπτων. Ορίστε το spec.timeout ώστε να επιτρέπονται έως 180 δευτερόλεπτα (δείτε τα Εργαλεία). Για ένα εργαλείο που περιμένει ένα άτομο ή μια αργή εργασία, ορίστε το spec.wait_mode σε "hold": ο καλών ακούει μουσική αναμονής αντί για φωνητικές ενημερώσεις και το spec.timeout μπορεί να φτάσει έως 600 δευτερόλεπτα. Το τελικό σημείο σας εξακολουθεί να απαντά εντός 180 δευτερολέπτων· για να περιμένετε περισσότερο, επιστρέψτε {"status": "pending", "request_id": "..."} αμέσως και παραδώστε το αποτέλεσμα αργότερα με POST /v1/calls/{call_id}/tool-results. Δείτε τις Μεγάλες αναμονές.

Διαχείριση εκδόσεων

Κάθε PATCH ενσωμάτωσης δημιουργεί νέα αναθεώρηση. Ελέγξτε το GET /v1/integrations/{id}/versions για να δείτε ποιος άλλαξε τι. Αν καταστρέψετε το σχήμα ενός εργαλείου, μπορείτε να επαναφέρετε χειροκίνητα μια παλαιότερη κατάσταση στέλνοντάς την ξανά με PATCH.


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