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

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

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

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

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

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

docker compose exec n8n n8n --version

השמות במדריך זה תואמים לגרסה היציבה של n8n נכון ליולי 2026. החל מגרסה 1.82.0, כל צומת AI Agent פועל כ־Tools Agent, ולכן התפריט הנפתח לבחירת סוג הסוכן שהיה קיים בעבר אינו קיים עוד.

שלב 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) דרך ה-Anthropic Console בכתובת platform.claude.com, תחת Settings ולאחר מכן API Keys. המפתח מוצג פעם אחת בלבד. השימוש ב-API מחויב לפי טוקן ואינו קשור למנוי Claude.ai, לכן יש להגדיר אמצעי תשלום בחשבון לפני ההרצה הראשונה.

בחרו את המודל בהתאם לסוכן, לא לפי החברה. סוכן בעל כלי אחד שמבצע חיפוש ומדווח עליו יפעל היטב עם Haiku, אשר נכון ליולי 2026 מתומחר ב-$1 למיליון טוקנים של קלט ו-$5 למיליון טוקנים של פלט. ברגע שלסוכן יש כמה כלים והוא נדרש לתכנן את השימוש בהם, עברו ל-Sonnet. הכשל שאתם מנסים למנוע הוא מודל זול שקורא לכלי הלא נכון ארבע פעמים, מה שעולה יותר מאשר מודל יקר שקורא לכלי הנכון פעם אחת.

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

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

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

פתחו את צומת ה-AI Agent. לפרמטר ה-Prompt יש שתי הגדרות.

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

כאשר צומת Webhook נמצא לפניו, גוף ה-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: הענקת כלי אחד לסוכן

צומת AI Agent ללא צומת כלי (tool) מסונף יסרב לפעול. התחילו עם כלי אחד, שכן כלי אחד שעובד מלמד אתכם יותר מארבעה כלים שהוגדרו באופן חלקי.

חברו צומת 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 של הכלי אינו תיעוד עבור עמיתיכם לעבודה. זהו הדבר היחיד שהמודל קורא כאשר הוא מחליט אם הכלי רלוונטי. כתבו אותו כהצהרה פשוטה על מה שמתקבל בחזרה: "Returns the current up or down state and the downtime duration for one monitored service, as 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, כיוון שההיסטוריה נשמרת בנתוני ה-workflow עצמו ולא במאגר משותף. במופע (instance) הפועל במצב 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. הפלט הסופי יכלול אז את קריאות הכלי שביצע הסוכן לאורך הדרך; כך ניתן להבדיל בין מצב שבו "המודל מעולם לא קרא לכלי" לבין מצב שבו "הכלי לא החזיר תוצאה מועילה". כבו אפשרות זו לפני העברה לסביבת ייצור, שכן שלבי הביניים הללו מהווים רעש עבור משתמש הקצה.

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

docker compose logs -f n8n

מניעת צריכת משאבים שקטה על ידי סוכן אוטונומי

לסוכן שמאחורי Chat Trigger יש אדם שמפקח עליו, והוא עוצר אותו כאשר התשובה נראית שגויה. לסוכן שמאחורי Schedule Trigger אין איש שמפקח עליו. כאן אתם עוקבים אחר עלות השימוש במודל ולא אחר עלות הרישוי, משום שהצמתים agent, tool ו־memory פועלים כולם במהדורה החינמית להתקנה עצמית, ו־התכונות שכן דורשות מפתח בתשלום קשורות בעיקר לניהול צוותים ולממשל. ההסבר המלא נמצא ב־בקרת עלויות של סוכן AI ב־VPS שפועל תמיד. ארבע הגדרות ממלאות כאן את עיקר התפקיד.

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

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

FAQ

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

צומת ה-AI Agent מחייב צומת משנה של מודל צ'אט ולפחות צומת משנה אחד של כלי (tool). צומת עם מודל אך ללא כלי נכשל לפני ביצוע כל קריאת API. צרפו כלי אחד, אפילו פשוט, והריצו שוב.

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

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

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

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

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

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