חיבור סוכן AI לכל API באנגלית פשוטה, בלי קוד

API Action builder של Quickchat AI מחבר את סוכן ה-AI שלכם ל-REST API מתוך משפט אחד באנגלית פשוטה. אתם מתארים את ה-API שאליו תרצו לקרוא, למשל “בדוק את סטטוס המשלוח של הזמנה ואמור ללקוח מתי היא תגיע”, ו-LLM עם חיפוש באינטרנט קורא את התיעוד החי של אותו API ומרכיב פעולה מלאה ועובדת, כולל השיטה, ה-URL, הכותרות, הפרמטרים והתיאור שאומר לסוכן שלכם מתי להשתמש בה. הוא מצטט את התיעוד שקרא, וכאשר אינו יכול לאמת endpoint אמיתי, הוא אומר זאת במקום לנחש.

מדריך זה בונה שתי פעולות חיות משני משפטים מוקלדים, בחשבון חינמי, ומוכיח את שתיהן באמצעות קריאות אמיתיות שנרשמו ב-Inbox. לאורך הדרך הוא מסביר מה קריאת API עושה בפועל עבור הסוכן שלכם ומהו “function calling”, המנגנון שעליו היכולת הזו פועלת.

כל מה שלמטה נבנה ונבדק על סוכן אמיתי. כל צילום מסך, שדה שנוצר וקריאת API הם מאותה בנייה, ואפשר לשחזר את כולם.

התוצאה הסופית: מטייל שואל על סוף השבוע, הסוכן קורא ל-API מזג אוויר באמצע השיחה ועונה עם מספרים חיים.

מה תבנו

סוכן תמיכה עבור Wanderlark Tours, מפעילת טיולי הליכה אלפיניים בדיוניים בקבוצות קטנות, שעונה מתוך הידע שלו וקורא לשני APIs אמיתיים באמצע השיחה. בניית שניהם, בדיקתם וצפייה בקריאות החיות אורכות כחמש עשרה דקות:

1. חיפוש תחזית מזג אוויר מול Open-Meteo, שנבנה ממשפט אחד. בלי מפתח, כך שתוכלו להשלים אותו רק עם חשבון Quickchat.
2. תמונת היום באסטרונומיה של NASA מול api.nasa.gov, עבור תוספת הצפייה בכוכבים של Wanderlark. פעולה זו דורשת מפתח API, וזו בדיוק הסיבה שהיא כאן: היא מלמדת את תהליך ה-placeholder מסוג [[secret]], שבו ההפעלה נשארת חסומה עד שתדביקו את המפתח שלכם.

תקלידו גם משפט שהבונה מסרב לבנות, בכוונה, כי הבנת האופן שבו הוא נכשל היא חלק מהידיעה מתי לסמוך עליו.

מה נדרש:

• חשבון Quickchat AI חינמי (הירשמו כאן).
• בלי קוד, בלי שרת. עבור הפעולה השנייה, מפתח API של NASA: NASA מפעילה DEMO_KEY משותף ומוגבל בקצב לבדיקות, שבו משתמשים צילומי המסך, ומנפיקה מפתחות אישיים מיד ב-api.nasa.gov.

מה המשמעות של קריאת API על ידי סוכן AI?

סוכן שיכול לקרוא ל-APIs יכול לשלוף או לשנות דברים במערכות אמיתיות באמצע שיחה, ואז לענות באמצעות התוצאה. chatbot יכול לתאר את העסק שלכם; סוכן שקורא ל-APIs יכול לפעול בו.

מצד משתמש הקצה, שום דבר לא משתנה פרט לתשובה. מטייל שואל “איך יהיה מזג האוויר באינטרלאקן בשבת?” ורואה מחוון הקלדה למשך כמה שניות, ואז תשובה עם טמפרטורות אמיתיות. הוא לא רואה כלי, בקשה או payload של JSON. שתי השניות שבאמצע נראות כך:

המטייל רואה שאלה ותשובה. באמצע, המודל בחר פעולה, מילא את הערכים שלה, ו-Quickchat ביצעה בקשת HTTP אמיתית: 280 ms מתוך כשתי השניות.

אפשר אפילו להגדיר מה המבקר רואה במהלך ההמתנה הזו. לכל פעולה יכולה להיות thinking message, שורה קצרה שהווידג’ט באתר מציג במקום “Thinking…” הכללי בזמן שהקריאה רצה. פעולת התחזית של Wanderlark מגדירה אחת, ולכן זה מה שהמטייל רואה בפועל במהלך אותן שתי שניות:

המבט מצד המטייל, באמצע קריאה: שורת החשיבה המותאמת מנצנצת במקום שבו התשובה עומדת להופיע. תגדירו את השורה הזו בעורך הפעולה בהמשך.

שום דבר מזה אינו ייחודי למזג אוויר. כל מערכת שחושפת HTTP API יכולה להיות בצד השני של פעולה: מסד נתוני הזמנות, מערכת הזמנות, CRM, כלי כרטיסים, פלטפורמת הודעות. חיפושים עונים על שאלות באמצעות נתונים חיים; כתיבות משנות משהו ומשאירות רשומה.

כל אריח הוא בקשת HTTP מתוארת אחת. מדריך זה בונה שניים מהחיפושים; דפוסי הכתיבה מכוסים במדריכים המקושרים בסוף.

הבעיה ההיסטורית היא שחיבור כזה דרש לקרוא תיעוד API ולמלא את הבקשה ידנית. זה החלק שהבונה מסיר.

איך עובד בונה הפעולות באנגלית פשוטה?

אתם מתארים את ה-API במשפט אחד, ו-LLM עם חיפוש חי באינטרנט הופך את המשפט הזה לפעולה מלאה. הוא מחפש בתיעוד ה-API בזמן היצירה, מנסח את השיטה, ה-URL, הכותרות, פרמטרי השאילתה והתיאור שאומר לסוכן שלכם מתי לקרוא לה, ומחזיר את התוצאה עם קישורים לדפי התיעוד שקרא. היצירה אורכת כחצי דקה, והתוצאה נפתחת בחלון כשהיא מוכנה.

הבונה משחרר רק מה שאומת בתיעוד. כל דבר שלא ניתן היה לאמת הופך ל-placeholder או לסירוב, לעולם לא לניחוש.

שלוש תכונות הופכות אותו לבטוח לשימוש:

• שום דבר לא רץ עד שאתם מפעילים אותו. כל פעולה שנוצרת מגיעה כבויה, לבדיקה שלכם.
• דברים לא ידועים הופכים ל-placeholders, לא לניחושים. ערכים שהמודל צריך למלא בכל קריאה (תאריך, עיר) הופכים לחסרונות {{param}}; קבועים שרק אתם יודעים (מפתח API) הופכים לחסרונות [[secret]], וההפעלה חסומה עד שתחליפו אותם.
• הוא מראה את העבודה שלו. התוצאה מפרטת את דפי התיעוד שקרא, כל אחד עם הערה על מה שאותו דף אימת, כך שהבדיקה מתחילה מראיות ולא מאמון:

ציטוטים מיצירה שנייה של אותו משפט מזג אוויר שבה משתמשים בהמשך המדריך: דף התיעוד ומקטעי ה-API שלו, כל אחד עם מה שהבונה אימת שם.

שלב 1: צרו את סוכן הנסיעות

צרו קודם את הסוכן כדי שלפעולות יהיה לאן להשתייך. לאחר ההרשמה, תנו שם לסוכן (בבנייה הזו משתמשים ב-Wanderlark) והגדירו את תפקידו בשדה AI Main Prompt תחת Identity בדשבורד:

אתה העוזר של Wanderlark Tours, מפעילת טיולי הליכה אלפיניים בקבוצות קטנות. Wanderlark מפעילה שלושה טיולים מודרכים: Interlaken Classic, Zermatt Highline ו-Dolomites Traverse, וכן את תוספת הצפייה בכוכבים Dark-Sky Nights. עזור למטיילים לבחור טיול, להבין תאריכים, מחירים, דרגת קושי ומה לארוז, וענה על שאלות הזמנה וביטול. היה נעים, מעשי ותמציתי, ושמור על תשובות קצרות.

ענה רק מתוך מה שאתה באמת יודע על Wanderlark. אם אין לך פרט מסוים, אמור שאין לך אותו והצע לחבר אותם עם צוות Wanderlark, במקום לנחש.

לאחר מכן הוסיפו כמה עובדות תחת Knowledge Base כדי שיהיה לו ממה לענות. ההדגמה משתמשת בחמישה מאמרים קצרים (טיולים ומחירים, תוספת Dark-Sky Nights, הזמנה וביטול, אריזה, נקודות מפגש); הטקסט המלא נמצא בבלוק ההעתקה לקראת הסוף. נרחיב את הפרומפט הזה בשתי שורות ספציפיות לפעולות אחרי שהפעולות קיימות. אם תרצו הדרכה מאפס על פרומפטים וידע, פוסט המתכון הראשי המקושר בהמשך עובר על כך שלב אחר שלב.

שלב 2: תארו את ה-API במשפט אחד

בסרגל הצד, פתחו את Actions & MCPs, לחצו על Add Action, ובחרו API Action, הפריט הראשון בתפריט.

פעולות מותאמות נמצאות תחת Actions & MCPs. הפריט API Action פותח את חלון התיאור.

החלון שנפתח מבקש לתאר את ה-API שהפעולה הזו צריכה לקרוא לו, ולציין את ה-endpoint או לקשר את התיעוד שלו. זה המשפט המדויק לפעולת מזג האוויר:

קבל את תחזית מזג האוויר היומית למקום מתוך Open-Meteo API (docs: https://open-meteo.com/en/docs), כך שכאשר מטייל שואל איך יהיה מזג האוויר באחד היעדים שלנו, הסוכן יוכל לענות עם טמפרטורות אמיתיות וסיכויי גשם עבור הימים שעליהם נשאל.

משפט אחד: איזה API, קישור תיעוד, מתי הסוכן צריך להשתמש בו, ומה עליו לעשות עם התוצאה.

המשפט הזה כולל את שלושת הדברים שתיאור טוב צריך:

1. API, endpoint או URL תיעוד קונקרטי. “The Open-Meteo API” וקישור התיעוד נותנים לבונה משהו אמיתי לקרוא. בלעדיו, תקבלו סירוב במקום פעולה.
2. מתי הסוכן צריך להשתמש בו. “כאשר מטייל שואל איך יהיה מזג האוויר” נכנס, כמעט מילה במילה, לתיאור שמפעיל את הפעולה בהמשך.
3. מה לעשות עם התוצאה. “לענות עם טמפרטורות אמיתיות וסיכויי גשם” מעצב את האופן שבו הסוכן משתמש בתגובה.

השדה מקבל עד 500 תווים, יותר מקום ממה שתיאור טוב צריך; כל משפט במדריך הזה נכנס עם מרווח ניכר.

לחצו Submit. החלון נסגר, הודעת toast אומרת שהפעולה בהכנה, וכחצי דקה לאחר מכן חלון התוצאה נפתח מעצמו:

כל התהליך בזמן אמת, עם ההמתנה מקוצרת: תארו, שלחו ובדקו מה חזר.

מה יש בתוך הפעולה שנוצרה?

חלון התוצאה הוא משטח בדיקה. משמאל, כרטיס תצוגה מקדימה של הפעולה החדשה, בדיוק כפי שתופיע בעמוד Actions. מימין, Details: הבונה מסביר מה בנה, אילו ערכים המודל ממלא בזמן ריצה, ומה הוא הניח כשהמשפט שלכם השאיר משהו פתוח. מתחת, Sources: התיעוד שקרא, כקישורים.

הבונה מסביר את עבודתו שדה אחר שדה. בגלילה בחלון, אזור Sources מפרט מה הוא קרא עבור הפעולה הזו: דף התיעוד של Open-Meteo ומפרט OpenAPI של הפרויקט ב-GitHub, כל אחד עם הערה על מה שאימת.

עבור משפט מזג האוויר, הבונה יצר פעולה בשם get_open_meteo_daily_forecast (שמות של הבונה נראים כאילו מהנדס כתב אותם; אפשר לשנות שם בעורך). לחצו Edit Action בתצוגה המקדימה כדי לראות כל שדה שהוא מילא:

כל מה שיש בפעולה שנבנית ידנית, ממולא: השם, טבלת הפרמטרים תחת “What to ask the user first”, וה-endpoint.

קריאה מלמעלה למטה:

• API Action Name: מה שהמודל רואה כשם הכלי.
• What to ask the user first: טבלת הפרמטרים. הבונה הגדיר שבעה פרמטרים, כל אחד עם סוג ותיאור: latitude, longitude, timezone, start_date, end_date, בתוספת יחידות אופציונליות. אלה ערכי {{param}} שהמודל ממלא בכל קריאה. שימו לב מה לא נמצא כאן: אין פרמטר “city”. הבונה חיבר את ה-endpoint כפי ש-Open-Meteo באמת עובד, לפי קואורדינטות, והשאיר את הגאוגרפיה למודל. מיד נראה אותו ממלא את הקואורדינטות האלה נכון.
• API Endpoint: GET https://api.open-meteo.com/v1/forecast, עם פרמטרי השאילתה מחוברים. ערכים קבועים נשארים מילוליים, כמו רשימת משתני התחזית daily שהבונה בחר; ערכים שממולאים על ידי המודל מופיעים כשבבי {{...}} צבעוניים.

חלקים קבועים נשארים קבועים; השבבים הצבעוניים הם החסרונות שהמודל ממלא. השבבים הם המקרא המובנה של ה-UI למה שמגיע מאיפה.

הלשונית הרביעית בעורך ה-endpoint, Test Response, מריצה את הבקשה האמיתית לפני שהפעולה פוגשת מבקר. לכל פרמטר יש שדה “Your test value”; מלאו אותם בערכים סבירים, לחצו על כפתור ההפעלה (“Test the API”), והתגובה האמיתית חוזרת עם קוד הסטטוס שלה. מתג Show cURL חושף, במילים שלו, “the exact HTTP request that would be triggered when this AI Action runs with these parameters”. הנה הבדיקה בבנייה הזו, שוב עם הקואורדינטות של אינטרלאקן:

200 אמיתי מ-Open-Meteo, הופעל מתוך העורך, עם הבקשה שנפתרה מפורטת מתחת. בדקו, נסו, ואז הפעילו.

• API Action Description: המשפט שקובע מתי הסוכן פונה לפעולה הזו. הבונה כתב אותו מתוך סעיף “כאשר מטייל שואל” שלכם. שדה זה עושה את עיקר העבודה בזמן ריצה, והוא הדבר הראשון לכוונון אם הסוכן מפעיל את הפעולה ברגע הלא נכון.
• Thinking message: השורה מצד המטייל מציר הזמן קודם. העורך מתאר אותה כ-”a thinking preloader that will be displayed to the user when this action is invoked”; פעולת התחזית של Wanderlark מגדירה אותה ל-”Checking the live forecast for you…”.

הפעולה הגיעה כבויה. פתחו אותה בעורך ו-Quickchat מציגה באנר שאומר שהפעולה כבויה, עם כפתור Enable; או הפכו את המתג בכרטיס שלה בעמוד Actions. מכיוון שלא היה מה למלא בפעולה הזו, היא מופעלת מיד.

בדקו קודם, ואז הפעילו. שום דבר לא קורא לשום דבר עד שתעשו זאת.

אם אתם מעדיפים לבנות את אותה פעולה ידנית, שדה אחר שדה, ולהבין כל תיבה מהיסודות, זה מדריך היסוד: Build a Free AI Agent That Takes Actions. הבונה והעורך הידני מייצרים אותו סוג פעולה; הפוסט הזה הוא הדרך שנוצרת אוטומטית.

שלב 3: בדקו אותה וצפו בקריאה מתבצעת

שאלו את הסוכן שאלה שאמורה להפעיל את הפעולה. התמלילים כאן הורצו דרך צינור הבדיקה של Quickchat ונרשמו ב-Inbox כמו כל שיחה; בחשבון שלכם, חלונית AI Preview בסרגל הצד נותנת את אותו לופ בדפדפן.

הודעת הבדיקה:

היי! אנחנו עושים את Interlaken Classic בסוף השבוע הבא. איך יהיה מזג האוויר באינטרלאקן בשבת 25 ביולי וביום ראשון 26 ביולי?

הסוכן ענה עם התחזית האמיתית: בערך 27.7°C וכמעט בלי גשם בשבת, קריר יותר עם עד 18 mm גשם סביר ביום ראשון, בתוספת עצות אריזה ששלף מהידע שלו.

הקבלה נמצאת ב-Inbox. מתחת לתשובת הסוכן יש סימון “1 action called”; הרחיבו אותו ותקבלו את הרשומה המלאה של מה שקרה:

רשומת הקריאה: get_open_meteo_daily_forecast, HTTP 200 בתוך 280 ms, וכל ערך שהמודל מילא.

קראו את הפרמטרים שהמודל בחר: latitude: 46.6863, longitude: 7.8632, timezone: Europe/Zurich, start_date: 2026-07-25, end_date: 2026-07-26. אף אחד לא הקליד קואורדינטות. המטייל אמר “אינטרלאקן”, והמודל תרגם זאת לערכים שה-API צריך, בדיוק מספיק כדי להגיע לעיירה. זה חצי השיפוט של המערכת שעושה את עבודתו; החצי הדטרמיניסטי (ה-URL, השיטה, רשימת משתני daily הקבועה) יצא בדיוק כפי שנבדק.

מהו function calling בסוכני AI?

הקבלה למעלה היא תמונה של המנגנון שהתעשייה קוראת לו function calling: מודל שפה, באמצע שיחה, בוחר להפיק קריאה מובנית לכלי מוגדר מראש במקום משפט, הפלטפורמה מפעילה אותה, והמודל ממשיך עם התוצאה ביד.

Function calling בקריאה האמיתית של מדריך זה. המודל מפיק רק את הערכים המובנים; הפלטפורמה מחזיקה את הבקשה; ה-API הוא HTTP רגיל.

כמה מסקנות עולות מהתרשים:

• המודל מחליט, הפלטפורמה מבצעת. המודל לעולם לא שולח bytes ל-Open-Meteo. הוא מפיק {"latitude": 46.6863, ...} ו-Quickchat מכניסה את הערכים האלה לבקשה שבדקתם. החלקים שקיבעתם, ה-URL, השיטה, כל secret, אינם ניתנים לשינוי על ידי המודל.
• “Tool calling” הוא אותו דבר. שני השמות מתארים מנגנון אחד; tool calling הוא המונח החדש והכללי יותר. AI Action היא הגדרת כלי: השם, התיאור וטבלת הפרמטרים שלה הם בדיוק מה שהמודל קורא כשהוא מחליט אם ואיך לקרוא לה. לכן שדה התיאור חשוב כל כך. מבחינה מושגית, כל ההגדרה שהמודל רואה שקולה לזה:

name:        get_open_meteo_daily_forecast
description: השתמש בפעולה זו כאשר מטייל שואל איך יהיה מזג האוויר בימים קרובים ספציפיים ביעד...
parameters:  latitude (number, required), longitude (number, required), timezone (text, required), start_date (text, required), end_date (text, required), temperature_unit (text), precipitation_unit (text)

• צד ה-API רגיל. Open-Meteo לא הוסיף תמיכת AI לשם כך. כל endpoint שמדבר HTTP ומחזיר JSON יכול להיות כלי, ולכן מתכון המשפט האחד מתרחב גם ל-backend שלכם.

כל משפחת מודלים מרכזית תומכת במנגנון הזה. ההבדל בין פלטפורמות הוא מי כותב את הגדרות הכלים. בפלטפורמות למפתחים ובפעולות GPT מותאמות, אתם עושים זאת ידנית, בסכמה. הבונה שבו השתמשתם בשלב 2 הוא function calling בלי כתיבת הסכמה: המשפט שלכם הפך להגדרת הכלי. למבט הנדסי על התחום הזה, מפרוטוקולים כמו MCP ועד endpoints מותאמים, ראו APIs for AI Agents: From MCP to Custom Endpoints.

שלב 4: API שדורש מפתח

רוב ה-APIs האמיתיים דורשים אישור גישה. כאן נכנס סוג ה-placeholder השני של הבונה, ותוספת הצפייה בכוכבים של Wanderlark נותנת לנו סיבה טבעית: אורחי Dark-Sky Nights אוהבים לשאול על תמונת היום באסטרונומיה של NASA.

פתחו שוב את Add Action, בחרו API Action, ותארו אותה, הפעם תוך ציון מראש שתספקו את המפתח:

שלוף את תמונת היום באסטרונומיה של NASA מתוך NASA APOD API (GET https://api.nasa.gov/planetary/apod), כך שאורחים שמתעניינים בתוספת Dark-Sky Nights שלנו יוכלו לשאול על תמונת האסטרונומיה המוצגת הלילה ולשמוע את הכותרת שלה ומה היא מציגה. אני אספק מפתח NASA API משלי.

האמירה “אני אספק מפתח API משלי” אומרת לבונה להשאיר חסר נקי במקום לנחש את האימות.

כחצי דקה לאחר מכן חלון התוצאה נפתח, והוא נראה שונה בדרך חשובה אחת: חלונית ענבר בשם “Replace before activating”, שמפרטת דבר אחד בדיוק: [[nasa_api_key]]. כרטיס התצוגה המקדימה נושא תג אדום Incomplete, ומתג ההפעלה שלו כבוי ונשאר כבוי.

הבונה חיבר את כל הפעולה והשאיר חסר אחד שלא יכול היה למלא: המפתח שלכם. עד שתחליפו אותו, אי אפשר להפעיל את הפעולה.

בעמוד Actions, המתג מושבת לגמרי, עם tooltip שמפרט למה:

ההפעלה חסומה ברמת הפלטפורמה כל עוד נשאר [[secret]]. פעולה עם placeholder במקום שבו אמור להיות מפתח אינה יכולה להיכשל ב-3 לפנות בוקר, כי היא אינה יכולה לרוץ.

לשני סוגי ה-placeholders יש בעלים שונים:

URL אחד, שני הסוגים: {{date}} הוא החסר של המודל, שממולא בכל קריאה מתוך השיחה; [[nasa_api_key]] הוא שלכם, מודבק פעם אחת.

עכשיו מלאו אותו. NASA מנפיקה מפתחות אישיים מיד (שם ואימייל ב-api.nasa.gov, המפתח מגיע במייל), ומתעדת את DEMO_KEY המשותף לבדיקות, שבו משתמשת הבנייה הזו:

1. בכרטיס הפעולה, לחצו Edit Action, ואז פתחו את לשונית Query Params באזור API Endpoint.
2. שורת api_key מכילה את שבב הענבר [[nasa_api_key]]. לחצו בתוך הערך, והחליפו אותו במפתח שלכם.
3. לחצו Save changes.

ה-placeholder הוא ערך רגיל שניתן לעריכה. החליפו אותו ושמרו.

לאחר מכן שימו לב למה שלא הייתם צריכים לעשות: להפוך את המתג. כאשר שמירה הופכת לראשונה פעולת GET לקריאה בלבד למלאה ותקינה, Quickchat מפעילה אותה עבורכם. פעולות שכותבות (POST, PUT, PATCH, DELETE) לעולם לא עושות זאת; הן ממתינות להפעלה מכוונת, ברירת המחדל הנכונה לכל דבר שמשנה נתונים.

הדביקו, שמרו, וחיפוש לקריאה בלבד מפעיל את עצמו. פעולות כתיבה תמיד משאירות את ההחלטה הסופית לכם.

בדקו אותה באותה דרך כמו התחזית:

הוספנו את תוספת Dark-Sky Nights לטיול Zermatt Highline שלנו. על מה תמונת האסטרונומיה של הלילה?

הסוכן שלף את תמונת הלילה, “Shadow and Rainbow”, וסיכם מה היא מציגה.

ושוב הקבלה, ב-Inbox:

HTTP 200 מ-api.nasa.gov. הערך היחיד שמולא על ידי המודל הוא התאריך, שנשאר ריק כך ש-NASA משתמשת כברירת מחדל בהיום. המפתח לא נמצא בשום מקום ברשומה הזו: הוא אינו פרמטר, ולכן לעולם אינו ניתן למילוי או לחשיפה על ידי המודל.

מה קורה כאשר הבונה לא מוצא את ה-API?

הבונה לא תמיד מייצר פעולה, וזה מכוון. הקלידו משפט שמתאר התנהגות אבל לא מציין API:

תן לסוכן שלי לעזור למטיילים לתזמן מחדש את הטיול שלהם כאשר מזג האוויר נראה גרוע.

הבונה מחפש, לא מוצא API יחיד שיוכל לבחור עבורכם באחריות, וחוזר עם חלון אחר: “We need a bit more detail”. לא נוצרת פעולה. חלונית Details מסבירה בדיוק מה חסר (איזה ספק מזג אוויר? איזו מערכת הזמנות?) ומדגימה ניסוח מחדש, עד למשפט לדוגמה עם endpoint קונקרטי.

סירוב עם ערכת תיקון: מה היה עמום, למה ניחוש היה שגוי, ודוגמה למשפט שיעבוד.

יש סוג שני של סירוב. תארו משהו ש-Quickchat כבר עושה באופן מובנה:

העבר את השיחה למדריך אנושי כאשר המטייל נראה מתוסכל או מבקש לדבר עם אדם.

הבונה מזהה שזה תחום מובנה, ובמקום לעטוף API חיצוני סביב בעיה שכבר פתורה, מפנה אתכם ליכולת, עם כפתור Set up Human Handoff ישירות בחלון:

לא כל יכולת צריכה להיות פעולה מותאמת. הסלמה לאדם מובנית, והבונה מנתב אתכם אליה במקום לשכפל אותה.

המשפטים וההגדרות המדויקים להעתקה

כל מה שההדגמה השתמשה בו, במקום אחד. שני המשפטים שיצרו את הפעולות:

קבל את תחזית מזג האוויר היומית למקום מתוך Open-Meteo API (docs: https://open-meteo.com/en/docs), כך שכאשר מטייל שואל איך יהיה מזג האוויר באחד היעדים שלנו, הסוכן יוכל לענות עם טמפרטורות אמיתיות וסיכויי גשם עבור הימים שעליהם נשאל.

שלוף את תמונת היום באסטרונומיה של NASA מתוך NASA APOD API (GET https://api.nasa.gov/planetary/apod), כך שאורחים שמתעניינים בתוספת Dark-Sky Nights שלנו יוכלו לשאול על תמונת האסטרונומיה המוצגת הלילה ולשמוע את הכותרת שלה ומה היא מציגה. אני אספק מפתח NASA API משלי.

ה-AI Main Prompt, כולל שתי שורות הפעולה שנוספו אחרי שהפעולות כבר היו קיימות. ציון שמות הפעולות ורגעי ההפעלה שלהן בפרומפט משפר באופן מורגש את אמינות ההפעלה, ושמות הפעולות לשימוש הם השמות שנוצרו וראיתם בעורך:

אתה העוזר של Wanderlark Tours, מפעילת טיולי הליכה אלפיניים בקבוצות קטנות. Wanderlark מפעילה שלושה טיולים מודרכים: Interlaken Classic, Zermatt Highline ו-Dolomites Traverse, וכן את תוספת הצפייה בכוכבים Dark-Sky Nights. עזור למטיילים לבחור טיול, להבין תאריכים, מחירים, דרגת קושי ומה לארוז, וענה על שאלות הזמנה וביטול. היה נעים, מעשי ותמציתי, ושמור על תשובות קצרות.

כאשר מטייל שואל איך יהיה מזג האוויר ביעד בימים קרובים, קרא ל-get_open_meteo_daily_forecast וענה עם המספרים האמיתיים עבור הימים שעליהם נשאל. כאשר אורח שואל על תמונת האסטרונומיה של הלילה או מה הוא עשוי לראות ב-Dark-Sky Night, קרא ל-get_tonights_nasa_apod ותאר את כותרת התמונה ומה היא מציגה.

ענה רק מתוך מה שאתה באמת יודע על Wanderlark. אם אין לך פרט מסוים, אמור שאין לך אותו והצע לחבר אותם עם צוות Wanderlark, במקום לנחש.

ה-API Action Descriptions שנוצרו, כפי שהבונה כתב אותם (כווננו את אלה, לא את ה-URL, כאשר התנהגות ההפעלה דורשת עבודה):

השתמש בפעולה זו כאשר מטייל שואל איך יהיה מזג האוויר בימים קרובים ספציפיים ביעד, ואתה צריך נתוני תחזית יומית אמיתיים (טמפרטורות גבוהות/נמוכות וסיכוי לגשם) מתוך Open-Meteo API. העוזר צריך לקרוא לפעולה זו עם קו הרוחב/קו האורך של היעד, טווח התאריכים והיחידות המועדפות, ואז להשתמש בתגובת JSON כדי לתאר בשפה טבעית את הטמפרטורות הצפויות והסתברויות המשקעים עבור הימים המבוקשים.

השתמש בפעולה זו כאשר אורח שואל על תמונת היום באסטרונומיה של הלילה הקשורה לתוספת Dark-Sky Nights שלך, כדי שתוכל לשלוף את מטא-דאטה APOD הרשמי של NASA ולתאר את הכותרת ומה התמונה מציגה. הפעולה קוראת ל-APOD API של NASA עבור התאריך שצוין (ברירת מחדל להיום אם לא סופק תאריך) ומחזירה JSON הכולל את URL התמונה או הווידאו, הכותרת, ההסבר וסוג המדיה, שאותם העוזר צריך לסכם באופן שיחתי עבור האורח.

ה-Thinking message שהוגדרה בפעולת התחזית (השורה שהווידג’ט מציג בזמן שהקריאה רצה):

בודק עבורך את התחזית החיה...

חמשת מאמרי Knowledge Base, מקוצרים לעובדות שלהם:

טיולים: Interlaken Classic, 3 ימים, קל עד בינוני, 890 אירו, מקסימום 10 אורחים, מאי עד אוקטובר. Zermatt Highline, 4 ימים, בינוני עד מאתגר, 1,290 אירו, מקסימום 8, יוני עד ספטמבר. Dolomites Traverse, 5 ימים, מאתגר, 1,590 אירו, מקסימום 8, סוף יוני עד אמצע ספטמבר, מבקתה לבקתה. המחירים כוללים מדריך, לינה וארוחות בוקר.

Dark-Sky Nights: תוספת צפייה בכוכבים ב-Zermatt Highline וב-Dolomites Traverse, 120 אירו לאדם, הליכת לילה מודרכת עם טלסקופ, מתוזמנת סביב מולד הירח; מפגשים שמתבטלים בגלל עננות מועברים או מוחזרים.

הזמנה: מקדמה של 200 אירו, היתרה לתשלום 30 יום לפני ההתחלה. ביטול חינם עד 30 יום; החזר של 50 אחוז מ-29 עד 14 יום; בתוך 14 יום אין החזר, אבל שינוי הזמנה אחד בחינם בתוך 12 חודשים.

אריזה: שכבות, מעיל גשם, נעלי הליכה משומשות, תיק יום של 30 ליטר; מקלות הליכה וקרמפונים מסופקים; ערבים קרים גם בקיץ.

נקודות מפגש: תחנת Interlaken Ost; תחנת Zermatt (ללא מכוניות, שאטל מ-Taesch); Cortina d'Ampezzo, העברה משדה התעופה של ונציה 45 אירו לכל כיוון.

איך מתארים API כך שהבונה יעשה זאת נכון?

שלושה כללים מכסים את כל מה שהבנייה הזו נגעה בו, וחלון הכשל מלמד את אותו שיעור מהצד השני:

הדפוס מאחורי כל תוצאה במדריך הזה: API קונקרטי נכנס, פעולה עובדת יוצאת; התנהגות בלבד נכנסת, הנחיה חוזרת.

1. ציינו את ה-API, את ה-endpoint, או הדביקו URL תיעוד. “The Open-Meteo API (docs: …)” יצר פעולה נכונה שמבוססת על שני מקורות מצוטטים. “תזמן מחדש את הטיול שלהם כאשר מזג האוויר נראה גרוע” יצר סירוב, כי הוא מציין משאלה, לא API. הבונה צריך משהו קונקרטי שהוא יכול לקרוא, וזה הכלל שעליו שני האחרים נשענים.
2. אמרו מתי הסוכן צריך להשתמש בו, ומה לומר אחר כך. סעיף הטריגר שלכם הופך כמעט מילה במילה לתיאור הפעולה, והתיאור הוא מה שמפעיל את הפעולה בזמן ריצה. “כאשר מטייל שואל איך יהיה מזג האוויר” הוא אות שהמודל יכול לזהות באמצע שיחה.
3. אמרו איך האישור יעבוד, אם יש כזה. “אני אספק מפתח NASA API משלי” גרם לאימות להיות ממודל כ-[[secret]] נקי. הבונה גם נוטה לכך בעצמו: הוא מעדיף אישורי גישה סטטיים וארוכי חיים כמו מפתחות ו-webhook URLs על פני אסימוני OAuth קצרי חיים, משום שהפעולה רצה כפי שהיא בכל קריאה, בלי מנגנון רענון אסימונים.

וכלל שאינו כלל: אין צורך לציין פרמטרים, פורמטים או שדות תגובה. הבונה קרא את תיעוד Open-Meteo ובחר שבעה פרמטרים, ברירות מחדל סבירות ומשתני daily נכונים בלי שהתבקש. בדקו את מה שבחר בעורך במקום לנסות להכתיב זאת מראש.

האיטרציה עצמה זולה. אין כפתור יצירה מחדש; כאשר טיוטה יוצאת לא נכונה, מחקו אותה ושלחו מחדש משפט חד יותר, כחצי דקה לכל ניסיון. חשבונות מחזיקים עד 15 פעולות שנוצרו, לכן נקו טיוטות תוך כדי עבודה.

מעבר לפרודקשן

ההפעלה כבר עשתה זאת. פעולות שייכות לסוכן, לא לערוץ, לכן שני החיפושים שבניתם מופעלים באותו אופן מהווידג’ט באתר, WhatsApp, Messenger, Slack, Telegram, Discord, או מכל מקום אחר שבו הסוכן פרוס, כאשר כל קריאה נרשמת ב-Inbox. אם הווידג’ט באתר הוא הערוץ הראשי, אפשר להסיר מיתוג מה-AI chatbot בלי לשנות את הפעולה. אותו הדבר נכון לגבי מה שהוא לא יכול לענות עליו: כששואלים על טיולי שלג בחורף, Wanderlark אומרת שהיא לא מפעילה כאלה, במקום לאלתר.

כששואלים משהו מחוץ לידע שלו, הסוכן אומר זאת במקום לאלתר. אותה ריסון חל גם על קריאות ה-API שלו.

שני צעדים טבעיים לאחר שהפעולות הראשונות שלכם חיות:

• הפכו הפעלה לדטרמיניסטית היכן שזה חשוב. תיאורי פעולה קובעים מתי המודל קורא; עבור פעולות שחייבות לרוץ רק בתנאים מסוימים, הוסיפו תנאי ריצה בצד השרת ולכידות זיכרון: How to Make Your AI Agent’s Actions Reliable.
• השתמשו באינטגרציות בלחיצה אחת עבור כלים שיש להם כאלה. אותו תפריט Add Action מכיל את הדרכים האחרות: HubSpot Action, Discord Action ו-Google Sheets מגיעים כגלריות מוכנות, Shopify MCP מחבר קטלוג של חנות, ו-MCP מחבר כל שרת MCP מרוחק, מתוך קטלוג של 240+ או URL מודבק, תוך ייבוא כלי השרת. המדריכים למטה עוברים על הגלריות.

שלוש דרכים לאותו מקום, כלל אצבע אחד:

מדריכים קשורים

• Connect your AI Agent to HubSpot: אנשי קשר, עסקאות וכרטיסים שנכתבים באמצע שיחה, עם דפוס בטיחות לכתיבה בלבד.
• Turn your AI Agent into an MCP server: הצורה ההפוכה, שבה ChatGPT, Claude ו-Cursor קוראים לסוכן שלכם.
• Build an AI Telegram bot to manage your group: שש פעולות Bot API שנבנו ידנית עם שער ניהול.
• AI Discord moderation bot: פעולות מודרציה עם הרשאות ואישור שמבוצעים נכון.
• AI Discord ticket bot: חצי התמיכה של אותה גלריה, עונה מתוך בסיס ידע ופותח threads פרטיים של כרטיסים.
• Connect your AI Agent to Google Sheets: אינטגרציית הדיווח בלחיצה אחת.

שאלות נפוצות

איך מחברים סוכן AI ל-API בלי לכתוב קוד?

ב-Quickchat AI, פתחו את Actions & MCPs, לחצו על Add Action, בחרו API Action, ותארו את ה-API במשפט אחד באנגלית פשוטה. LLM עם חיפוש חי באינטרנט קורא את תיעוד ה-API ומייצר את הפעולה המלאה, עם השיטה, ה-URL, הפרמטרים והתיאור. אתם בודקים אותה, ממלאים ערכי placeholder כגון מפתח API, ומפעילים אותה.

מהו function calling בסוכני AI?

Function calling הוא המנגנון שבו מודל שפה, באמצע שיחה, מפיק בקשה מובנית להרצת כלי מוגדר מראש במקום טקסט רגיל. הפלטפורמה מפעילה את הכלי, במקרה זה בקשת HTTP, ומחזירה את התוצאה למודל, שלאחר מכן כותב את תשובתו באמצעות נתונים אמיתיים. כל קריאת AI Action במדריך זה היא function call אחד.

האם function calling זהה ל-tool calling?

כן. Function calling ו-tool calling הם שמות לאותו מנגנון; tool calling הוא המונח החדש והכללי יותר. AI Action היא אחד מהכלים האלה: בקשת HTTP מתוארת שהמודל יכול לבחור לקרוא לה במהלך שיחה.

איך הבונה יודע איך ה-API נראה?

בזמן היצירה הוא מריץ חיפוש חי באינטרנט על תיעוד ה-API, ומרכיב את הפעולה רק ממה שהצליח לאמת שם. חלון התוצאה מפרט את המקורות שקרא, כך שתוכלו לבדוק אותם לפני הפעלת הפעולה.

מה ההבדל בין placeholders מסוג {{param}} ו-[[secret]]?

ערך {{param}} ממולא על ידי המודל מתוך השיחה בכל קריאה, למשל תאריך או עיר. ערך [[secret]] הוא קבוע שאתם מדביקים פעם אחת לפני ההפעלה, למשל מפתח API. המודל לעולם אינו בוחר או עורך secrets, והם אינם פרמטרים שהוא יכול למלא.

איפה שמים את מפתח ה-API שלי, והאם מבקר יכול לחלץ אותו מהסוכן?

אתם מחליפים את ה-placeholder מסוג [[secret]] בתוך הפעולה, בעורך, לפני ההפעלה. המפתח הופך לחלק מהבקשה הקבועה ש-Quickchat שולחת. הוא אינו פרמטר, לכן המודל אינו יכול לשנות אותו, והוא אינו מופיע ברשומת קריאת הפעולה של השיחה.

האם הבונה יוצר רק חיפושי GET, או שהסוכן יכול גם לכתוב נתונים?

גם וגם. אותו תהליך של משפט אחד מייצר פעולות POST, PUT, PATCH ו-DELETE. פעולות GET לקריאה בלבד מופעלות בעצמן לאחר שהן מלאות ותקינות; פעולות כתיבה תמיד ממתינות שתפעילו אותן במכוון.

האם ניתן להתחבר ל-APIs פרטיים או פנימיים?

כן, כל עוד ה-endpoint נגיש דרך HTTPS מהצד של Quickchat. הבונה מתבסס על תיעוד ציבורי, לכן עבור API פנימי תארו את ה-endpoint במפורש במשפט שלכם, או צרו תבנית קרובה והתאימו את ה-URL והשדות בעורך.

מה קורה אם אני מתאר התנהגות במקום API ספציפי?

הבונה נכשל באופן סגור. במקום להמציא endpoint, הוא מסביר מה חסר ומראה איך לנסח מחדש, בדרך כלל באמצעות ציון ספק, endpoint או URL של תיעוד קונקרטי. אם הבקשה שלכם תואמת יכולת מובנית כגון Human Handoff, הוא מפנה אתכם ליכולת הזו במקום ליצור פעולה מותאמת.

מה קורה אם קריאת ה-API נכשלת במהלך שיחה?

הסוכן רואה את השגיאה ואומר למשתמש שהוא לא הצליח להשלים את החיפוש במקום להמציא תשובה. כל קריאה נרשמת בשיחה ב-Inbox עם הפרמטרים וקוד סטטוס ה-HTTP שלה, כך שתוכלו לראות בדיוק מה נשלח ומה חזר.

האם ChatGPT, Claude או Gemini יכולים להתחבר ל-API כך?

המודלים שלהם כולם תומכים ב-function calling, אבל חיבור שלו הוא עבודת פיתוח: אתם כותבים בעצמכם את סכמת הפונקציה או את מפרט OpenAPI, כמו בפעולות GPT מותאמות. כאן אתם מקלידים משפט אחד והפעולה נוצרת מתיעוד ה-API החי, ואז פועלת בכל ערוצי הסוכן שלכם. אפשר גם לחשוף את סוכן Quickchat המוכן שלכם ל-ChatGPT, Claude ו-Cursor כשרת MCP.

מאילו ערוצים הסוכן יכול לקרוא ל-API?

מכולם. פעולות שייכות לסוכן, לא לערוץ, לכן אותה פעולה מופעלת מהווידג’ט באתר, WhatsApp, Messenger, Slack, Telegram, Discord, ובכל מקום אחר שבו הסוכן שלכם פרוס.

האם בונה הפעולות באנגלית פשוטה הוא חינמי?

כן. יצירה, בדיקה והפעלה של API Actions עובדות במסלול החינמי, ושתי הפעולות במדריך הזה נבנו בחשבון חינמי. מסלולים בתשלום מוסיפים מגבלות שימוש גבוהות יותר ומודלים מתקדמים יותר, לא גישה לבונה.

איך הסוכן בוחר בין כמה פעולות?

הוא קורא את השם והתיאור של כל פעולה ובוחר את זו שמתאימה לרגע בשיחה. לסוכן ההדגמה יש שתיים: שאלת מזג אוויר מנותבת לפעולת התחזית, ושאלת אסטרונומיה מנותבת לפעולת NASA, משום שהתיאורים שלהן מציינים את הטריגרים האלה. תיאורים ברורים ומובחנים הם מה שהופך את הבחירה לאמינה.

כמה השהיה מוסיפה קריאת API לתשובה?

פחות ממה שאפשר לצפות. קריאת התחזית האמיתית במדריך הזה חזרה בתוך 280 ms, כחלק מתשובה שנמשכה כשתי שניות מקצה לקצה. המבקר רואה מחוון חשיבה קצר, שאפשר להחליף בהודעת חשיבה מותאמת, ואז תשובה שנבנתה על נתונים חיים.

סיכום

שני משפטים מוקלדים הפכו לשתי API Actions חיות, מתועדות ובדוקות: חיפוש מזג אוויר ללא מפתח וחיפוש NASA עם מפתח, כל אחת מוכחת באמצעות HTTP 200 שנרשם ב-Inbox ליד הערכים שהמודל מילא. הכללים שהופכים זאת לאמין נכנסים בשלוש שורות. ציינו API אמיתי והבונה מבסס את הפעולה בתיעוד שלו ומצטט אותו. כל דבר שרק אתם יודעים מגיע כ-[[secret]] שחוסם הפעלה עד שתמלאו אותו. כל דבר שהבונה אינו יכול לאמת הופך להסבר ולהצעת ניסוח מחדש, לעולם לא לניחוש.

לרשימת השדות המלאה של API Actions, תנאי ריצה וטיפול בתגובות, השאירו את AI Actions docs בהישג יד בזמן הבנייה.