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

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

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

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

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

Δύο μέρη:

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

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

Και οι δύο διαδρομές δημιουργούν μια αποθηκευμένη ενσωμάτωση. Επισυνάψτε αυτή την ενσωμάτωση στον πράκτορα αφού την αποθηκεύσετε. Το 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).

Δηλώστε 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" }
  }'

{
  "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. Υλοποιήστε το τελικό σημείο#

Όταν ο πράκτορας καλεί το εργαλείο, το 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.

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

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