בניית סוכן AI ב-n8n על שרת VPS עצמאי: מדריך מלא

מהו סוכן AI ב־n8n, ובמה הוא שונה משרשרת (chain)

סוכן AI ב־n8n הוא צומת (node) יחיד מסוג AI Agent שאליו מחוברים צמתי משנה: מודל צ'אט אחד, כלי אחד או יותר, וזיכרון אופציונלי. אתם מגדירים מטרה בשפה טבעית, והמודל מחליט באילו כלים להשתמש ובאיזה סדר, עד שהוא מסוגל לספק תשובה. כל מה שמופיע בהמשך הוא התצורה סביב הרעיון הזה.

שרשרת (chain) עובדת בצורה הפוכה. ב־Basic LLM Chain אתם מחליטים על השלבים, והמודל רק ממלא טקסט. בסוכן, המודל הוא שמחליט על השלבים, לכן אותה שאלה עשויה לעלות קריאה אחת למודל היום, ותשע קריאות מחר. ההבדל היחיד הזה מניע את כל ההגדרות במדריך זה. אם הלולאה הזו היא רעיון חדש עבורכם, ולא רק תכונה של n8n, כדאי לכתוב אחת ידנית פעם אחת לפני שמרכיבים אותה מצמתים, כיוון שהצומת מסתיר בדיוק את החלק שעליו תבלו את שארית המדריך בניסיון להבין.

מדריך זה מניח ש־n8n כבר רץ מאחורי HTTPS על מכונה שבשליטתכם. אם לא, התחילו ב־אירוח עצמי של n8n ב־Docker עם תעודה אמיתית, כיוון שמפתח ה־API שאתם עומדים לשמור דורש את הגיבוי של מפתח ההצפנה שהמדריך ההוא מחייב. עבור תבניות שאינן מבוססות סוכנים, כמו מסכמי webhook ומסווגים מתוזמנים, ראו תבניות עבודה של Claude ו־n8n.

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

docker compose exec n8n n8n --version

גרסה 1.82.0 הוציאה משימוש את הגדרת ה-agent-type לטובת ה-Tools Agent. צמתי v1 ישנים עדיין כוללים את ההגדרה; התיעוד של n8n מייעד את הסרת גרסת הצומת הזו ל־n8n 3.0.

שלב 1: בחירת ה-trigger

עבור סוכן שיחתי, הוסיפו צומת Chat Trigger. השאירו את האפשרות Make Chat Publicly Available כבויה בזמן הבנייה, כך שרק לוח הצ'אט של העורך יוכל לגשת אליו. הפעילו אותה לאחר סיום עבודת הסוכן ולאחר שהחלטתם על שיטת האימות.

ה-Chat Trigger מעביר לסוכן שדה בשם chatInput. שם זה חשוב בשלב 3, וטעות בו היא הכשל הנפוץ ביותר בתחילת העבודה.

עבור סוכן הפועל ללא השגחה, השתמשו בצומת Schedule Trigger או Webhook. אף אחד מהם אינו מייצר chatInput, לכן תצטרכו לכתוב את ה-prompt בעצמכם.

שלב 2: הגדרת פרטי הגישה למודל

גררו צומת AI Agent אל משטח העבודה. n8n יציג מיד מחבר Chat Model ריק מתחתיו. חברו אליו תת-צומת מסוג Anthropic Chat Model.

צרו את פרטי הגישה (credential) דרך ה-Claude Console בכתובת platform.claude.com, תחת Settings ולאחר מכן API keys. המפתח מוצג פעם אחת בלבד. ה-Console תבקש מכם לבחור תאריך תפוגה בעת יצירת המפתח; סוכן שפועל ללא השגחה יפסיק לעבוד ביום שבו המפתח יפוג, לכן שמרו את התאריך במקום גלוי. עבור סוכן ללא השגחה, השתמשו במפתח של service account המוגבל ל-workspace מסוים, כך שלא יהיה צורך בכותרת (header) נפרדת עבור ה-workspace.

השימוש ב-API מחויב לפי טוקן, ואופן התשלום תלוי בתוכנית ה-Claude שלכם, נכון ל-31 באוקטובר 2026. תוכניות Max, Ultra ו-Team כוללות קרדיטים חודשיים ל-API: סך של $100 ב-Max, $200 ב-Ultra, ועד $500 במאגר משותף ב-Team. ניתן לממש אותם על ידי קישור ארגון ב-Console לתוכנית דרך Settings > Billing ב-Max או ב-Ultra, או דרך Organization settings > Billing ב-Team; אין צורך להוסיף אמצעי תשלום ב-Console. מנויים חדשים יכולים לממש את הקרדיטים לאחר 7 ימים בתוכנית, וקרדיטים שלא נוצלו פוקעים בסוף כל מחזור חיוב, או מדי חודש בתוכניות שנתיות. כאשר הקרדיטים הכלולים מסתיימים, הבקשות ימשיכו להתבצע מול קרדיטים שנרכשו, ניתן להגדיר טעינה אוטומטית (auto-reload) לרכישת נוספים, וארגונים המשלמים בחשבונית יחויבו על חריגה. בקשות ייעצרו כאשר לארגון שמשלם מראש לא נותרו קרדיטים; השימוש ב-API לעולם אינו מחויב דרך תוכנית ה-Claude שלכם. תוכניות Free, Pro ו-Enterprise אינן כוללות קרדיטים חודשיים ל-API, ולכן בהן ה-API מחויב בנפרד מהמנוי.

בחרו את המודל לפי סוכן, לא לפי חברה. סוכן בעל כלי אחד שמבצע חיפוש ומדווח עליו יפעל היטב על Haiku. הגרסה הנוכחית, Haiku 5.5, מתומחרת ב-$0.10 למיליון טוקנים של קלט ו-$0.50 למיליון טוקנים של פלט נכון ל-12 באוקטובר 2026, ועולה ל-$0.50 ו-$2.50 עבור כל בקשה שה-prompt שלה עובר 100,000 טוקנים – רף שאליו ניתן להגיע עם חלון זיכרון ארוך ותוצאות גדולות של כלים. ברגע שלסוכן יש מספר כלים והוא נדרש לתכנן ביניהם, עברו ל-Sonnet. הכשל שאתם מנסים למנוע הוא מודל זול שקורא לכלי הלא נכון ארבע פעמים, מה שעולה יותר מאשר מודל יקר שקורא לכלי הנכון פעם אחת.

הגדירו את Maximum Number of Tokens באפשרויות של תת-הצומת. הגדרה זו מגבילה את אורך כל תשובה שהמודל מפיק. אם תושאר על ערך ברירת מחדל גבוה, הרצה אחת שגויה עלולה להפיק תשובה ארוכה מאוד ולחייב אתכם בהתאם.

הערה אחת מתוך התיעוד של n8n שתופסת את כולם: ביטויים (expressions) בתוך תת-צומת תמיד מחושבים מול פריט הקלט הראשון, לעולם לא עבור כל פריט בנפרד. הציבו ביטויים ברמת הפריט בשדות ה-prompt של הצומת הראשי.

שלב 3: ה-prompt שהסוכן מקבל

פתחו את ה-node של ה-AI Agent. לפרמטר Source for Prompt (User Message) יש שתי הגדרות.

• Connected Chat Trigger Node מצפה לשדה נכנס בשם chatInput. זו הבחירה הנכונה כאשר ה-node נמצא אחרי Chat Trigger.
• Define below חושף שדה Prompt (User Message) שבו כותבים טקסט סטטי או ביטוי. זו הבחירה הנכונה כאשר ה-node נמצא אחרי Schedule Trigger או Webhook node.

כאשר משתמשים ב-Webhook node לפניו, גוף ה-POST מגיע תחת $json.body, ולכן שדה ה-prompt נראה כך.

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

שלב 4: הענקת כלי אחד לסוכן

התיעוד של n8n מציין כי יש לחבר לפחות תת-צומת (sub-node) אחד של כלי לצומת AI Agent, אף שקוד הצומת הנוכחי (גרסה 3.1) מסרב לפעול רק בהיעדר מודל צ'אט. התחילו עם כלי אחד בכל מקרה, שכן כלי אחד שעובד מלמד אתכם יותר מארבעה כלים שהוגדרו למחצה, וסוכן ללא כלי הוא בסך הכל שרשרת (chain) יקרה יותר.

חברו צומת HTTP Request למחבר ה-Tool של הסוכן. הגדירו אותו בדיוק כפי שהייתם מגדירים צומת HTTP Request רגיל, ולאחר מכן בדקו את ה-endpoint הזה תחילה מתוך ה-shell.

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

אם פקודת ה-curl הזו מחזירה שגיאה או דף התחברות ב-HTML, גם הסוכן ייכשל. הכשל ייראה כמו בעיה במודל, בעוד שמדובר למעשה בבעיית URL או אימות. תקנו זאת ב-shell, לא בצומת.

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

כדי לאפשר למודל למלא חלק מהבקשה, השתמשו בביטוי $fromAI(). הוא עובד רק בכלים המחוברים לצומת AI Agent, והוא אינו עובד בכלי ה-Code.

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

הארגומנטים הם key, ולאחריהם description אופציונלי, type ו-defaultValue. המפתח חייב להיות באורך של 1 עד 64 תווים, תוך שימוש באותיות, ספרות, קווי תחתון ומקפים. הסוג הוא אחד מ-string, number, boolean או json, וערך ברירת המחדל הוא string. קריאה מלאה יותר נראית כך.

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

המפתח הוא רמז, לא הפניה לנתונים קיימים. $fromAI('service') אינו קורא שדה בשם service משום מקום. הוא אומר למודל "צור ערך וקרא לו service", והמודל מחפש בשיחה, בנתוני הקלט ובתוצאות של כלים אחרים כדי למצוא אחד כזה. בתהליך עבודה של צ'אט, הוא עשוי פשוט לשאול את המשתמש.

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

שלב 5: זיכרון, ומדוע הסוכן שוכח

ללא תת-צומת (sub-node) של זיכרון, כל הודעה מתחילה מאפס. חברו תת-צומת מסוג Simple Memory כדי לשמור את השיחה האחרונה.

לצומת זה שני פרמטרים. Session Key קובע איזו שיחה זו, כך ששני משתמשים עם מפתחות שונים יקבלו היסטוריות נפרדות. Context Window Length הוא מספר האינטראקציות הקודמות שיוזנו חזרה לתוך ה-prompt.

הפרמטר Context Window Length משפיע על העלות לא פחות מאשר על האיכות, כיוון שכל תור שנשמר נשלח מחדש כ-input tokens בכל קריאה עוקבת. חלון של 20 בסוכן פטפטן אומר שתשלמו על אותן הודעות ראשוניות עשרים פעמים.

‏Simple Memory אינו פועל בסביבת production פעילה כאשר n8n רץ במצב queue, מכיוון שהוא מאחסן את ההיסטוריה ב-Map מקומי לתהליך (singleton) המזוהה לפי מזהי workflow ו-session, וה-workers אינם חולקים זיכרון זה. במופע הפועל במצב queue, השתמשו בתת-צומת Postgres Chat Memory והפנו אותו למסד נתונים שגם התהליך הראשי וגם ה-workers יכולים לגשת אליו.

שלב 6: הודעת המערכת (System Message)

פתחו את ה-Options של ה-agent והוסיפו System Message. כאן יש להזין את תיאור התפקיד; זהו הטקסט בעל ההשפעה הרבה ביותר על תהליך העבודה.

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

ההנחיה "Always call the status tool before answering" מבצעת כאן עבודה משמעותית. בלעדיה, מודל שסבור כי הוא כבר יודע את התשובה ידלג על הכלי וישיב מתוך זיכרון, מה שיוביל לתשובה שגויה בביטחון מלא ברגע שהתשתית שלכם תשתנה.

מדוע הסוכן נכנס ללולאה, ומה עוצר אותו

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

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

בזמן ניפוי שגיאות (debugging), הפעילו את Return Intermediate Steps. הפלט הסופי יכלול אז את קריאות הכלי שהסוכן ביצע לאורך הדרך; כך ניתן להבדיל בין מצב שבו "המודל מעולם לא קרא לכלי" לבין מצב שבו "הכלי לא החזיר דבר מועיל". כבו אפשרות זו לפני העלייה לאוויר (production), כיוון ששלבים אלו מהווים רעש עבור משתמש הקצה.

עקבו אחר הרצה בזמן אמת מתוך ה-shell.

docker compose logs -f n8n

מניעת צריכת משאבים חריגה מסוכן הפועל ללא השגחה

סוכן המופעל באמצעות Chat Trigger כולל מעורבות אנושית, והמשתמש עוצר אותו כאשר התשובה נראית שגויה. לעומת זאת, סוכן המופעל באמצעות Schedule Trigger פועל ללא השגחה. במקרה זה, הדאגה העיקרית היא צריכת המשאבים של המודל ולא עלות הרישוי, שכן הסוכן, הכלים וצמתי הזיכרון פועלים בגרסת ה-self-hosted החינמית, ו-התכונות הדורשות מפתח בתשלום הן בעיקר תכונות ניהול צוות וממשל. הפירוט המלא מופיע ב-בקרת עלויות של סוכני AI בשרת VPS הפועל ללא הפסקה. ארבע הגדרות מבצעות את עיקר העבודה כאן:

• הגבילו את Maximum Number of Tokens בתת-צומת המודל, כדי למנוע מתגובה בודדת להתארך יתר על המידה.
• הגדירו את Max Iterations למספר הקטן ביותר שעדיין מאפשר להשלים את המשימה.
• שמרו על תגובות הכלים קטנות. כלי שמחזיר אובייקט JSON בן 4,000 שורות מכניס את כולו לקריאת המודל הבאה, ולאחר מכן לכל קריאה נוספת באותה הרצה.
• בדקו האם הסוכן באמת זקוק ללוח זמנים. משימה שרצה כל חמש דקות מופעלת 288 פעמים ביום. העלות של הרצה בודדת היא הנתון שיש להכפיל.

בטלו את פרסום ה-workflow בזמן ביצוע שינויים, או לפחות זכרו איזו גרסה פעילה כרגע. workflow שפורסם עם Schedule Trigger ממשיך להריץ את הגרסה האחרונה שפורסמה, ולא את הטיוטה שמוצגת על המסך, כיוון ש-n8n שומרת את העריכות בטיוטה עד לפרסום הבא.

FAQ

מדוע צומת ה-AI Agent שלי מסרב לפעול?

בדקו תחילה את המחברים. צומת ה-AI Agent דורש צומת משנה מסוג Chat Model; ללא צומת כזה, הוא עוצר עם השגיאה "Please connect a model to the Chat Model input" עוד לפני ביצוע קריאת API כלשהי. התיעוד של n8n מציין כי נדרש גם לפחות צומת משנה אחד מסוג Tool. אם המודל מחובר והצומת עדיין מסרב לפעול, חברו כלי אחד, אפילו פשוט ביותר, והריצו שוב.

הסוכן עונה, אך הוא לעולם לא מפעיל את הכלי שלי. מה הבעיה?

כמעט תמיד מדובר בשדה ה-Description של הכלי. המודל בוחר כלים על ידי קריאת התיאורים הללו; תיאור כמו "HTTP Request" אינו מספק לו מידע על מתי יש להשתמש בכלי. נסחו מחדש את התיאור כך שיציין איזה מידע חוזר ובאילו מצבים הוא שימושי, ולאחר מכן הוסיפו שורה ב-System Message המורה לסוכן להפעיל את הכלי לפני מתן תשובה.

מדוע אותה שאלה עולה סכום שונה בכל הרצה?

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

הזיכרון עובד בעורך אך לא בסביבת הייצור. מה השתנה?

בדקו אם המופע (instance) רץ במצב queue mode. ה-Simple Memory שומר היסטוריה ב-Map מקומי לתהליך, המזוהה לפי מזהי workflow ו-session, ותהליכי worker נפרדים אינם משתפים אותו. החליפו אותו בצומת המשנה Postgres Chat Memory, השומר את ההיסטוריה בבסיס הנתונים המשותף לכל ה-workers.