--- title: "Δημιουργήστε μια ενσωμάτωση εργαλείου (API)" description: "Επιτρέψτε στον πράκτορά σας να καλεί τα API σας κατά τη διάρκεια της συνομιλίας — να αναζητά σε μια βάση δεδομένων, να δημιουργεί ένα αίτημα υποστήριξης, να εντοπίζει μια παραγγελία." --- Μια **ενσωμάτωση εργαλείου** είναι ένα επαναχρησιμοποιήσιμο τελικό σημείο HTTP που ένας πράκτορας μπορεί να καλέσει κατά τη διάρκεια μιας κλήσης. Παρέχετε στο ThunderPhone μια περιγραφή σχήματος JSON του εργαλείου μαζί με ένα URL τελικού σημείου· ο πράκτορας αποφασίζει πότε να το καλέσει με βάση τη συνομιλία και το ThunderPhone πραγματοποιεί το εξερχόμενο αίτημα HTTP από τους διακομιστές του και επιστρέφει την απάντηση στον πράκτορα. Ο πίνακας ελέγχου καλύπτει τις περισσότερες ανάγκες εργαλείων χωρίς αυτό το API: **Συνδέσεις → Εφαρμογές** συνδέει τα Slack, HubSpot, Salesforce, Google Calendar, Google Sheets και Cal.com με λίγα κλικ OAuth· **Συνδέσεις → APIs** μετατρέπει οποιοδήποτε HTTP API σε ενέργεια πράκτορα (επικολλήστε μια εντολή cURL και ένας οδηγός AI συντάσσει το εργαλείο, με ενσωματωμένο Test Request)· και **Συνδέσεις → MCP** προσθέτει διακομιστές MCP. Δείτε τις [Συνδέσεις](/el/guides/concepts). Αυτός ο οδηγός αφορά το βασικό API που βρίσκεται κάτω από τη διεπαφή APIs. Αυτός ο οδηγός παρουσιάζει τη δημιουργία ενός εργαλείου αναζήτησης καιρού από άκρο σε άκρο. ## Ανατομία ενός εργαλείου Δύο μέρη: 1. **Το σχήμα** — ένας ορισμός συνάρτησης τύπου OpenAI (`{type: "function", function: {name, description, parameters}}`) που ενημερώνει το LLM για το τι κάνει το εργαλείο και ποια ορίσματα δέχεται. 2. **Το τελικό σημείο** — το URL που καλούν οι διακομιστές του ThunderPhone όταν το LLM αποφασίζει να χρησιμοποιήσει το εργαλείο. Το αίτημα είναι JSON POST με τα ορίσματα που επέλεξε το LLM ως σώμα. ## 1. Επιλέξτε επεξεργαστή Ανοίξτε τις **Συνδέσεις → APIs**, δημιουργήστε ή επεξεργαστείτε τη σύνδεση API, αλλάξτε τον επεξεργαστή παραμέτρων σε **JSON** και προσθέστε εκεί τη μορφή. Δημιουργήστε την προδιαγραφή με `POST /v1/integrations` ή ενημερώστε την με `PATCH /v1/integrations/{id}`. Και οι δύο διαδρομές δημιουργούν μια αποθηκευμένη ενσωμάτωση. Επισυνάψτε αυτή την ενσωμάτωση στον πράκτορα αφού την αποθηκεύσετε. Το API Agents δεν διαθέτει εγγράψιμο ενσωματωμένο πεδίο `tools`. Αυτός ο οδηγός χρησιμοποιεί τη διαδρομή του API ενσωματώσεων. ## 2. Δημιουργήστε την ενοποίηση ```bash 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). Αφιερώστε ουσιαστική προσπάθεια στο `description` του εργαλείου και κάθε παραμέτρου. Το LLM χρησιμοποιεί αυτά τα κείμενα κατά τον χρόνο εκτέλεσης για να αποφασίσει αν και πώς θα καλέσει το εργαλείο. Ασαφείς περιγραφές → ασαφείς κλήσεις εργαλείων. ### Δηλώστε `format: "email"` στις παραμέτρους διεύθυνσης Μια παράμετρος που δέχεται διεύθυνση email πρέπει να το δηλώνει στο σχήμα της: ```json "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 για να επιβεβαιώσετε τη συνδεσιμότητα: ```bash 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" } }' ``` ```json Response { "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` όταν δημιουργείτε ή ενημερώνετε έναν πράκτορα: ```bash 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: X-ThunderPhone-Call-ID: 987654321 Content-Type: application/json {"zip": "94110"} ``` Ο διακομιστής σας αποκρίνεται με JSON που επιστρέφεται στο LLM: ```json {"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8} ``` Το LLM επεξεργάζεται αυτή την απόκριση και εκφωνεί μια κατανοητή σύνοψη στον καλούντα. Η υπογραφή υπολογίζεται πάνω στο ακατέργαστο σώμα του αιτήματος, χρησιμοποιώντας το ίδιο `secret` με το τελικό σημείο webhook σας. **Επαληθεύστε την** — τα τελικά σημεία εργαλείων είναι εκτεθειμένα στο διαδίκτυο και υπόκεινται στους ίδιους κινδύνους πλαστογράφησης με τα webhook. Δείτε [Επαλήθευση υπογραφών webhook](/el/guides/verify-webhook-signatures). ## 6. Δοκιμάστε τη ροή Εκτελέστε μια [συνεδρία μικροφώνου](/api-reference/mic-sessions) στον πράκτορα και κάντε την ερώτηση που χειρίζεται το εργαλείο σας («Ποιος είναι ο καιρός στο 94110;»). Η απομαγνητοφώνηση της κλήσης εμφανίζει την πλήρη διαδρομή μετ’ επιστροφής: ```json { "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`](/api-reference/calls#get-transcript); η ακατέργαστη ροή συμβάντων (με χρονισμό ανά καταχώριση και μετατοπίσεις ήχου) βρίσκεται στο [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history). ## Συνήθη προβλήματα Το LLM αποφασίζει με βάση την περιγραφή του εργαλείου. Αν η ερώτηση του καλούντος δεν αντιστοιχεί στην περιγραφή, το μοντέλο δεν θα καλέσει το εργαλείο. Κάντε την περιγραφή πιο συγκεκριμένη (προσθέστε συνήθη συνώνυμα και διατυπώσεις) ή αναφέρετέ το ρητά στην προτροπή του πράκτορα («Όταν ο καλών ρωτά για τον καιρό, χρησιμοποιήστε το `get_weather`.»). Οι αποκρίσεις άνω των 6 kB περικόπτονται στην προεπισκόπηση της απομαγνητοφώνησης. Επιστρέψτε μόνο τα πεδία που χρειάζεται το LLM — όχι ολόκληρη τη γραμμή σας. Τα τελικά σημεία εργαλείων έχουν προεπιλεγμένο χρονικό όριο 10 δευτερολέπτων. Αν χρειάζεστε περισσότερο χρόνο, χειριστείτε το ασύγχρονα: επιστρέψτε `{"status": "pending", "request_id": "..."}` και εμφανίστε το αποτέλεσμα μέσω ξεχωριστής κλήσης εργαλείου. Κάθε `PATCH` ενσωμάτωσης δημιουργεί νέα αναθεώρηση. Ελέγξτε το [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history) για να δείτε ποιος άλλαξε τι. Αν καταστρέψετε το σχήμα ενός εργαλείου, μπορείτε να επαναφέρετε χειροκίνητα μια παλαιότερη κατάσταση στέλνοντάς την ξανά με PATCH. --- ## Επόμενα βήματα CRUD, μεταφορά, ιστορικό εκδόσεων. Πλήρης γραμματική σχήματος JSON και το συμβόλαιο υπογεγραμμένων τελικών σημείων. Εφαρμόστε το πρότυπο υπογραφής webhook σε τελικά σημεία εργαλείων. Ελέγξτε την πλήρη αμφίδρομη ροή μιας κλήσης εργαλείου.