כלים מותאמים
כלי ווב־הוק מאפשרים לסוכן הקולי לפנות למערכות שלך במהלך שיחה — לחפש הזמנה, לשלוח שאילתה ל־CRM או להפעיל פעולה צדדית. ההגדרה נעשית בעורך הסוכן; ללא דיפלוי וללא SDK.
למה משמשים כלים מותאמים
הכלים המובנים של הסוכן (סיום שיחה, העברה למספר, זיהוי שפה וכו׳) מכסים את מכניקת השיחה. כשצריך לאחזר נתונים אמיתיים — "מה הסטטוס של הזמנה 1234?", "האם התור עדיין פנוי?" — מחברים כלי ווב־הוק מותאם.
הסוכן מחליט מתי להפעיל את הכלי לפי השיחה. צריך לספק כתובת קצה ו־JSON Schema של הארגומנטים; את השאר הסוכן עושה לבד.
הוספת כלי
בעורך הסוכן גוללים לכלים מותאמים ולוחצים על הוספת כלי. דיאלוג שמלווה שלב־אחר־שלב:
- שם — מזהה קצר ב־snake_case (לדוגמה
lookup_order). - תיאור — מתי הסוכן יפעיל את הכלי? בשפה טבעית. לדוגמה: "להפעיל בכל פעם שהמתקשר מציין מספר הזמנה."
- שיטה וכתובת — POST/GET/PUT/DELETE/PATCH ואז ה־URL (מומלץ HTTPS).
- פרמטרים — JSON Schema אופציונלי שמתאר את גוף הבקשה. הסוכן ממלא את הערכים לפי השיחה.
- כותרות בקשה — כותרות סטטיות אופציונליות (לדוגמה
Authorization: Bearer …).
שמירה — והסוכן יוכל להפעיל את הכלי כבר בשיחה הבאה.
דריסת סאונד רקע
כל כלי יורש את ברירת המחדל של סאונד הרקע של הסוכן — ואפשר לדרוס לכלי בודד. אולי כלי חיפוש ההזמנה ישתמש בהקלדה (קצר וזריז) בזמן שכלי שמירת תור ארוך ישתמש ברקע נעים 2 (לופ אינסטרומנטלי ארוך יותר).
הדריסה נמצאת באותו דיאלוג הוספת כלי, תחת דריסת סאונד רקע. אם משאירים על ברירת מחדל של הסוכן — הכלי יורש את מה שהסוכן מוגדר עליו.
אבטחת נקודת הקצה
הכלים פונים לתשתית שלך. שמירה על אבטחה היא באחריות המפעיל:
- מומלץ להשתמש ב־HTTPS — הדיאלוג מזהיר על HTTP רגיל.
- כדאי להוסיף כותרת
Authorizationכך שרק הסוכן יוכל להפעיל את הכלי. אפשר להחליף בכל עת מהעורך. - לבצע ולידציה לקלט בצד השרת — לעולם לא לסמוך על ולידציה מהסוכן.
- להחזיר הודעת שגיאה בשפה ברורה; הסוכן יסביר אותה למתקשר.
בדיקת האינטגרציה
לאחר שמירה, אפשר ללחוץ על שיחת בדיקה בדשבורד ולומר במפורש את משפט ההפעלה (לדוגמה "רוצה לבדוק הזמנה 1234"). שווה לעקוב שהבקשה מגיעה לנקודת הקצה ולראות שהתגובה חוזרת דרך הסוכן.
אם הכלי לא מופעל — כדאי לבדוק את התיאור שלו. זה מה שהסוכן משתמש בו כדי להחליט מתי לקרוא לכלי. ככל שהתיאור ספציפי וישיר יותר — כך ההפעלה תהיה אמינה יותר.
מקבל קריאה לכלי מותאם
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.post("/agent/lookup-order")
def lookup_order():
payload = request.get_json(silent=True) or {}
order_id = (payload.get("order_id") or "").strip()
if not order_id:
return jsonify({"error": "order_id is required"}), 400
# Replace with your real database lookup.
record = fetch_order_from_db(order_id)
if not record:
return jsonify({"summary": f"No order found for {order_id}."}), 200
return jsonify({
"summary": f"Order {order_id} is currently {record['status']} and ships {record['eta']}.",
"status": record["status"],
"eta": record["eta"],
})
def fetch_order_from_db(order_id: str):
# Stubbed for the docs example.
return {"status": "in transit", "eta": "Friday"}
if __name__ == "__main__":
app.run(host="0.0.0.0", port=8000)
פרמטרים של הכלי (JSON Schema)
{
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "The customer-facing order identifier — usually 6-8 alphanumeric characters."
},
"include_history": {
"type": "boolean",
"description": "When true, also return the full status history.",
"default": false
}
},
"required": ["order_id"]
}
מדריכים קרובים
מסכים נוספים שעוזרים לחבר את הסוכן למערכות שלך.