פתרון תקלות | Talk To My Agent

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

בדיקות ראשונות

תוכנית ההתקנה מוסיפה את הפקודה ninja-talk למכונה של רכיב השיחות. מתחילים באלה:

ninja-talk status          # is the service running
ninja-talk doctor          # quick health checks
ninja-talk version         # install details (on a Mac, the installed version)
curl -s http://127.0.0.1:3335/

לפקודה האחרונה, רכיב שיחות פעיל עונה {"service":"ninja-talk","version":"...","status":"ok"}, וכך קוראים את הגרסה שרצה ב-Linux. פורט 3335 הוא ברירת המחדל; בשרת שמריץ כמה סוכנים, כל סוכן מקבל פורט משלו (NINJA_TALK_PORT בקובץ ה-.env של אותו סוכן).

לקריאת הלוג ב-Linux: ninja-talk logs -n 300 מציג את 300 השורות האחרונות ו-ninja-talk logs -f עוקב אחריו בזמן אמת. ב-Mac, השתמשו ב-ninja-talk logs או ב-ninja-talk logs -f. כל שורה מתויגת לפי רכיב, כמו [ninja-talk:calls], ולכן קל לסנן עם grep:

ninja-talk logs -n 500 | grep "ninja-talk:calls"

שיחות נדחות או לא נענות

כשרכיב השיחות דוחה שיחה, הוא רושם את הסיבה תחת [ninja-talk:calls]:

שורה בלוג	סיבה ופתרון
`Private mode: caller not on whitelist`	הסוכן במצב פרטי ומקבל שיחות רק מהמספר של בעל העסק. העבירו אותו למצב ציבורי בדשבורד, או הגדירו כטלפון של בעל העסק את המספר שממנו אתם מתקשרים, כולל קידומת המדינה.
`Private mode: OWNER_PHONE not configured`	מצב פרטי, בלי טלפון של בעל העסק. הגדירו מספר, או עברו למצב ציבורי.
`At capacity, rejecting call`	הסוכן הגיע למגבלת השיחות המקבילות שלו (2 כברירת מחדל). אם אתם צריכים יותר באופן קבוע, בקשו מאיתנו להעלות אותה.
`per-ANI rate limit hit`	אותו מספר התקשר יותר מ-20 פעמים בשעה (מספרים חסויים חולקים מגבלה משותפת של 5 בשעה). קורה הרבה כשבודקים מטלפון אחד. אפשר לשנות את המגבלה ב-`config.json` (בהמשך).
`deployment is outbound-only`	כיוון השיחות של הסוכן מוגדר ליוצאות בלבד. שנו אותו בדשבורד.
`number is on the blocklist`	המספר של המתקשר חסום אצל הסוכן הזה.
`cloud prompts not ready`	רכיב השיחות עדיין לא טען את ההנחיות שלו מהפלטפורמה. תנו לו דקה אחרי ההפעלה, ודאו שלשרת יש גישה לאינטרנט, ואז הריצו `ninja-talk restart`.
`gateway is draining`	רכיב השיחות היה באמצע הפעלה מחדש או עדכון. השיחות יתקבלו שוב כשיחזור לפעול.

כדי לשנות את המגבלה למתקשר, הגדירו את features.aniRateLimitPerHour ב-config.json של רכיב השיחות והפעילו מחדש. ראו הגדרה ותצורה.

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

שיחות יוצאות נכשלות

בקשת Voice API שנכשלת מחזירה גוף problem+json, ושדה ה-type בו מציין את הסיבה. הטבלה המלאה נמצאת בסקירת ה-Voice API. השגיאות הנפוצות:

תגובה	פתרון
`400 missing-idempotency-key`	הוסיפו כותרת `Idempotency-Key` לכל POST ו-PUT.
`400 validation-failed`	קראו את `detail`: הוא מציין את השדה, למשל מספר שאינו בפורמט E.164, גם `purpose` וגם `task`, תסריט שלא פורסם, או עובדת חובה שחסרה.
`403 insufficient-scope`	המפתח צריך את `voice:call`.
`403 voice-country-blocked`	הוסיפו את מדינת היעד בהגדרה Outbound countries (מדינות לשיחות יוצאות) של הסוכן. כברירת מחדל רשומות בה המדינה של המספר שלכם וארצות הברית.
`404 not-found`	`from` אינו מספר פעיל של סוכן שהמפתח הזה מורשה אליו.
`409 agent-offline`	רכיב השיחות לא מדווח לפלטפורמה. הריצו את הבדיקות הראשונות שלמעלה.
`429 rate-limit-exceeded`	5 שיחות בשעה למספר אחד, 30 בשעה או 100 ביום לכל סוכן. חכו, ואז נסו שוב עם `Idempotency-Key` חדש.

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

הסוכן מתעלם מהפלייבוק

הפלייבוק נקרא מסביבת העבודה של הסוכן, כברירת מחדל protocols/dojo-voice-agent-playbook.md. אחרי שיחה, רכיב השיחות רושם בלוג מה הוא טען:

ninja-talk logs -n 300 | grep -E "System instruction built|voice playbook"

"hasPlaybook":true בשורה System instruction built אומר שהפלייבוק נטען.
No voice playbook found אומר שהקובץ לא נמצא במקום שבו רכיב השיחות מחפש. הנתיב של סביבת העבודה מודפס בזמן ההפעלה (Workspace: ...).
Voice playbook rejected (symlink), (not a regular file) או (over size cap): הפלייבוק חייב להיות קובץ אמיתי, לא קישור, ובתוך מגבלת הגודל.
נתיב מותאם שהוגדר ב-config.json (context.voicePlaybook) חייב להיות קובץ .md בתוך סביבת העבודה. אחרת, הלוג מציג Ignoring NINJA_TALK_VOICE_PLAYBOOK ורכיב השיחות משתמש בנתיב ברירת המחדל. הפעילו מחדש אחרי השינוי.

השם והאישיות של הסוכן מגיעים מ-SOUL.md ומ-IDENTITY.md באותה סביבת עבודה, לא מתיקיית ההתקנה של רכיב השיחות. עריכה של עותקים במקום אחר לא תשנה דבר.

רכיב השיחות לא עולה

הריצו ninja-talk status וקראו את השורות האחרונות בלוג. סיבות נפוצות:

שגיאה	פתרון
`EADDRINUSE`	משהו אחר תופס את הפורט. מצאו אותו עם `sudo lsof -i :3335`, עצרו אותו, או הגדירו `NINJA_TALK_PORT` אחר ב-`.env`.
`Voice API key not available`	רכיב השיחות לא מצא את פרטי הגישה שלו לפלטפורמה וגם לא `VOICE_API_KEY`. אם אתם מביאים מפתח מודל משלכם, הוסיפו אותו כ-`VOICE_API_KEY` ב-`.env`; אחרת, פנו אלינו.
`ENOSPC`	הדיסק מלא. בדקו עם `df -h` מה תופס מקום, פנו מקום והפעילו מחדש.

ninja-talk env פותח את קובץ ה-.env (ב-Mac הוא מדפיס איפה הקובץ נמצא). אחרי כל שינוי בו, הפעילו מחדש עם ninja-talk restart.

Webhooks ונתוני שיחה

לא מגיע webhook: בדקו שהוא מוגדר ופעיל עם GET /v1/voice/webhooks?from=.... תגובת 410 מה-endpoint שלכם מכבה אותו. ראו Webhooks ו-n8n.
התמלול הוא null: ההגדרה Ship transcripts (שליחת תמלולים) כבויה בסוכן (Settings, Configuration, Call recording and transcripts).
התוצאה היא null: ההערכה שרצה אחרי השיחה עוד לא הסתיימה. נסו שוב את GET /v1/voice/calls/{id} מאוחר יותר.
ההקלטה מחזירה 404: ההקלטה כבויה, או שהשיחה לא הוקלטה. קישורים מה-endpoint של ההקלטות פגים אחרי 5 דקות, ולכן בקשו קישור חדש בכל פעם.

כלים מותאמים

לתקלות בכלים יש טבלה משלהן בדף כלים מותאמים. התחילו ב-ninja-talk logs -n 300 | grep voice-tools.

עדיין לא נפתר

שלחו לנו את שעת השיחה, את מספר הטלפון של הסוכן, את הפלט של ninja-talk version ואת שורות הלוג סביב השיחה (ninja-talk logs -n 300). בשגיאות API, צרפו את ה-requestId מהתגובה. אפשר לפנות דרך טופס יצירת הקשר.