דלג לתוכן הראשי

title: “עוזר AI” description: “תיעוד עוזר AI של AgentEye.”

לוח המחוונים כולל עוזר AI אופציונלי, פנל צ’אט המעוגן לקצה הימני של לוח המחוונים המענה לשאלות בשפה טבעית לגבי הסוכנים שלך (“איך הטרנד של איכות ב-prod השבוע הזה?”, “אילו סשנים כשלו היום?”, “סכם את הסשן הזה”) ו, כאשר המשתמש מתיר כל פעולה, משרטט וחוסך שאילתות SQL וממשקים על חשבונם. הוא מצטט קישורים הניתנים ללחיצה ישירות לסשנים, שאילתות וממשקים הרלוונטיים, והוא מודע לעמוד: שאל על “סשן זה” בזמן צפייה באחד והוא יודע על מה אתה מדבר. התא מציג מסילה אנכית של 44px בברירת מחדל: גליף הנמודה ›_ בתוספת נקודת בריאות בצבע. לחץ על המסילה (או לחץ על ⌘J / Ctrl+J) כדי להרחיב אותה לפנל הצ’אט המלא. הפנל המורחב הוא ניתן לשינוי גודל בין 320 ל-640 פיקסלים על ידי גרירת הקצה השמאלי שלו; הרוחב המועדף שלך נזכר בתוך טעינות מחדש. הוא רץ כקונטיינר פנימי קטן של agent (ב-Claude Agent SDK) שרק לוח המחוונים יכול להגיע אליו. הוא משבית כברירת מחדל ונשאר מוסתר עד שתשדר נקודת קצה של LLM.

מה הוא יכול ולא יכול לעשות

  • קורא את הנתונים התפעוליים שהמשתמש השואל יכול לראות. אירועים, הערכות, סשנים, תור עבודות הערכה, שאילתות שמורות וממשקים שמורים, מסובבים בכל בקשה להרשאות הקריאה של המשתמש. כלים קריאה מתבצעים באופן מיידי.
  • כתיבה מוערכת בהעדכון לכל פעולה. הוא יכול לחבור שאילתות שמורות (create_saved_query, update_saved_query), להפעיל SQL טיוטה נגד התפקיד קרוא-בלבד כדי לאמת אותה (run_query), וליצור ממשקים מאותן שאילתות (create_dashboard, update_dashboard, add_query_to_dashboard). כל כתיבה עוצרת למייל אשר / דחו / שאל שאלה בצ’אט; ה-SDK לא קורא לכלי עד שהמפעיל לוחץ על אישור. מחיקה לעולם אינה זמינה לעוזר; פעולות הרסניות נשארות עם מפעילים.
  • SQL משוטט עובר דרך אותה sql_guard אימות ותפקידי קרוא-בלבד כמו SQL כתוב על ידי משתמש (SELECT/WITH בלבד, אין רב-הצהרה). הביצוע מנוטב לפי איזה טבלאות שהשאילתה נוגעת בהן: שאילתות המציגות את טבלאות הניתוח (אירועים, הערכות, סשנים) רצות כמשתמש ClickHouse קרוא-בלבד של הארגון (מסובב לאורגון זה על ידי מדיניות שורה, עם כובע ביצוע של 10 שניות וכובע שורה של 100k) בעוד ששאילתות שנוגעות רק בטבלאות יחסיות רצות על תפקיד Postgres קרוא-בלבד (10 שניות, 10k שורות). העוזר לא יכול להרחיב את פני הנתונים; הוא יכול רק להיות מחבר על פני משטח השאילתות שלמפעיל כבר יש.
  • הוא משתמש במפתח עוזר ייעודי (ראה למטה) זרוע עם סט הרשאות קבוע; גם אם המודל מתנהג בצורה לא תקינה, הוא לא יכול לחרוג מהתחומים האלה.
  • כל משתמש לוח מחוונים צריך את הרשאת agent:use כדי לראות ולהשתמש בעוזר. כלים מסוננים לפי בקשה כדי להתאים את הרשאות הנתונים של המשתמש שלו, כך שמשתמש events:read מקבל כלי אירוע אך לא כלים dashboards:write.

תא AI מודע לעמוד: מקם על /queries, צ’אט בכל מקום אחר

תא העוזר בצד ימין הוא מודע לעמוד. בחר המודל, היסטוריית השיחה, נקודת בריאות המודל וקלט הצ’אט נשארים ללא שינוי, אך שבבי תבנית מצב ריק, טקסט ממלא מקום, ואיזו נקודת קצה של backend שאילת משתמש פוגעת הכל משתנה באופן אוטומטי בהתאם לנתיב הנוכחי. התא הופך ל”עוזר AI עבור בכל עמוד שאתה עומד עליו”. שני backends, מובחנים לכל עמוד (עם עריכות לכל שבב).
נתיבbackend ברירת מחדל של דףלמה
/queries, /queries/newPOST /api/agent/compose-sql (לא לולאת כלים)המשתמש מתחיל מחדש; SQL של ≤1s token ראשון זורם ישר לעורך
/queries/<id> (קיים)POST /api/agent/chat (עוזר לולאת כלים מלא), ברירת מחדל של עמודהודעות מקלידות בחופשיות צריכות להתיר למשתמש לשאול הכל (“הסביר את זה”, “מה זה עושה?”); שבבי רפקטור הן בחזרה להרכבה-sql דרך כל סוג של שבב
כל עמוד אחרPOST /api/agent/chat (עוזר לולאת כלים מלא)קרא כלים + כלים כתיבה ברוכי אישור
שבבים על /queries/<id> נושאים kind מפורש כך שעמוד יחיד יכול לערבב את שני הזרימות בצורה חלקה. קבוצת השבב ברירת המחדל היא שני שבבי צ’אט (הסביר את השאילתה על המסך, מה עושה השאילתה הזו?) בתוספת חמישה שבבי compose-sql (parametrize לפי טווח תאריכים, הוסף סטטוס='שגיאה' פילטר, וכו’). הודעות מקלידות בחופשיות נופלות דרך ברירת המחדל של העמוד (צ’אט), כך ששאלה כמו “למה זה כל כך איטי?” מקבלת תשובת פרוזה, בעוד שלחיצה על שבב parametrize לפי טווח תאריכים משוטט דרך נקודת הקצה של הרכבה וערכה את SQL. כאשר המקום פועל במצב עריכה (הוא רואה currentSql שאינו ריק מכיוון שהמשתמש נמצא ב-/queries/<id> או /queries/new עם SQL המוצע שכבר טעון), הנושא שלו משתנה מ”הרכבה שאילתה חדשה” ל”שנה את SQL המסופק מינימלי: שמור בחירת טבלה, שמות עמודה, מבנה צירוף, כינויים, הזחה”. המודל מוצג לקבוצה נפרדת של דוגמאות עובדות לפני/אחרי (parametrize, הוסף סינון, המר לדלי שעתי), כך שרפקטור שנלחץ על שבב מייצר דיפ מינימלי נגד SQL של העורך, לא כתיבה מחדש מאפס. לחץ על שבב הרכבה (או הקלד בחופשיות ב-/queries/new) → SQL זורם לתוך הודעת העוזר כ-```sql בלוק מובקע. ברגע שהזרימה מסתיימת, אם Monaco מעוגן בנתיב הנוכחי, העורך באופן אוטומטי דולק בתצוגת דיפ (המקור בצד שמאל, המוצע בצד ימין, ▾ AI הציע עריכה רמז בחלק העליון, ופתילי קבל / דחו למטה). המשתמש לא צריך למצוא או ללחוץ על כפתור Insert into editor כדי לראות את ההפרש. לחצן ההוספה עדיין מעורך מתחת לבלוק SQL כ-re-trigger ידני (שימושי אחרי דחייה או כאשר המשתמש נסע משם וחזרה), והוא נשאר הנתיב היחיד כאשר המשתמש נמצא בעמוד שאינו עורך (לדוגמה, רשימת השאילתות השמורות); שם היא מטמינה את SQL ב-sessionStorage ופעילות ל-/queries/new, כאשר העורך החדש-מעוגן קורא את הטמון בתקנה וסוגר את אותה תצוגת דיפ. אם SQL המוצע זהה ביתות לגבי מה שכבר בעורך (עריכת no-op), ה-auto-open דולק; אנחנו לא פופ הפרש ריק. כפתור Insert into editor הוא גם no-op במקרה זה. כאשר המשתמש מקבל הצעה על /queries/new, הפעולה הראשונה של סרגל הכלים קורא save במקום create; SQL הופץ להם על ידי העוזר; המודל נפשי הוא “סיימו את זה”, לא “כתוב מאפס”. התווית מתהפכת ברגע שהתא מכניס SQL ונשארת כ-save עד ניווט העמוד. ב-/queries/<id> כפתור הקרא תמיד save; שום דבר לא משתנה שם. מחוץ /queries, התא עובד בדיוק כמו קודם: צ’אט מלא עם כרטיסי אישור כלים, מודעות בהקשר עמוד, ציטוטים. הרשאות / גביע. נקודת הקצה של הרכבה גביע בהרשאת queries:run לכל משתמש (קריאה-שווה ערך; למשתמש עדיין צריך ללחוץ על אישור והפעל, והפעל עובר דרך sql_guard + references_ch_tables הנוכחי על שרת Rust). נקודת הקצה של צ’אט גביע ב-agent:use. שניהם עדיין דורשים חיבור LLM שהוגדר בקונטיינר agent; אם אף אחד לא הוגדר, התא משטח את “העוזר לא הוגדר בהצבה זו” בנר בכל נתיב. סירובים. המקום סיר כל בקשה שהוא לא יכול להשביע עם שאילתת ניתוח קרוא-בלבד וסופר -- REFUSE: <one-sentence reason> בתוך SQL. הוא סיר בקשות שיכתבו נתונים או להגיע לטבלאות מחוץ לתצפיות ניתוח (api_keys, users, dashboards, saved_queries, evaluation_jobs), והוא סיר בקשות פרוזה טהורות (“הסביר את זה”, “מה זה עושה?”) בנתיב הרכבה; אלה שייכות לנתיב הצ’אט והיצרו תשובת פרוזה שם. התא משטח את מחרוזת הסירוב כשבב שגיאה אדום מובקע בהודעת העוזר; שום דבר לא מוכנס. בחירת מודל. משותף עם נתיב הצ’אט. בוחר המודל בראש התא חל על שתי נקודות הקצה (קריאת הרכבה עוברת את המודל הנבחר דרך resolveModel() בשירות הסוכן). כאשר AGENTEYE_AGENT_MODELS רשימות מודלים מרובים, מפעילים יכולים לערבב אפשרות מחלקה Haiku עבור הרכבה עם אפשרות מחלקה Sonnet עבור צ’אט; המשתמש בוחר לכל שיחה. תבניות לכל עמוד. לכל עמוד יש את התבנית שלו (כותרת, גוף העתק, טקסט ממלא מקום, ושבבי הצעה) כך התא מסתגל לעמוד שאתה עומד עליו. השבבים שהוצעו בנתיב נתון ממפים לאותם כוונות שהרכבה מכוונת, כך שלחיצה על הצעה מייצרת את העריכה שאתה מצפה. השבתתו. זהה לנתיב הצ’אט: התא + הרכבה שניהם מוערכים על ידי קונטיינר agent והחיבור LLM שלו. אם אתה רוצה התנהגות צ’אט בלבד למשתמש מסוים, הסר את הרשאת queries:run (המשבית גם את כפתור ה-Run של העורך); אם אתה רוצה התנהגות מקום בלבד, הסר agent:use מתפקידי המשתמש, ואז הוסף מחדש queries:run בנפרד כך שהם עדיין יכולים להפעיל SQL כתוב מחבר.

הפעלתו

שירות agent משונה בקובץ Docker Compose והמניפסטים של Kubernetes. כדי להפעיל את העוזר, ספק (1) נקודת קצה של LLM ו**(2)** מפתח הנתונים המיוחד של העוזר.

1. בחר חיבור LLM

בחר באחד מאלה והגדר את המשתנים התואמים בשירות agent: א) Anthropic ישירות
ב) דרך Portkey (מומלץ; קטלוג מודל slug, מפתח בלבד)
זה הנתיב הפשוט ביותר: ב-Portkey, הגדר אינטגרציית Anthropic (Catalog דגם); הוא מקבל slug. שם את המודל כ-@<slug>/<model> והקליע מוביל את נתיב הספק + יומן, כך לא צריך מפתח וירטואלי, רק המפתח Portkey שלך. הסוכן שולח רק x-portkey-api-key ומצביע על שער Portkey; Portkey פותר את השאר. (שם מודל פשוט כשל עם “x-portkey-config או x-portkey-provider header is required”; הקדומה @slug/ היא מה שעושה קרא בלבד עבודה.) עבור שער שמעוצב בעצמו הגדר PORTKEY_BASE_URL. מעדיפה ניתוב לכל בקשה במקום slug? הגדר PORTKEY_VIRTUAL_KEY=<vk> (או PORTKEY_CONFIG=<id>) עם AGENTEYE_AGENT_MODEL פשוט. ג) שער תואם Anthropic אחר (LiteLLM, ממשוכן בעצמו, …)
ד) Amazon Bedrock / Google Vertex
צפה להשמעה את המודל ברירת המחדל עם AGENTEYE_AGENT_MODEL (ברירת מחדל claude-sonnet-4-6). כדי להתיר למשתמשים לבחור בין מודלים מרובים, הגדר AGENTEYE_AGENT_MODELS לרשימת הרשאות מופרדת בפסיקים (לדוגמה, @anthropic-prod/claude-opus-4-7,@anthropic-prod/claude-sonnet-4-6); בחר מודל מופיע בראש צ’אט, ובחירה של כל משתמש נזכרת. הסוכן קורא לעולם מודל בעצם הרשאה זו.

2. ספק את מפתח העוזר

בחר בכל סוד אקראי והנח אותו לחברת agent כ-AGENTEYE_API_KEY ול-server כ-AGENT_API_KEY (אותו ערך). בהפעלה השרת זורע אותו כמפתח ייעודי בשם dashboard-assistant עם ערכת הרשאה קבועה זו: events:read, evaluations:read, dashboards:read, dashboards:write, queries:read, queries:write, queries:run. הרשאות הכתיבה מעולם מתורגלות רק דרך כלים ברוכי אישור (ראה “מה הוא יכול ולא יכול לעשות” למעלה). אין שום שלב כישוף מפתח ידני ואין מפתח יועץ מעורב. ערכת ההרשאה קבועה בשרת, והמפתח הזרוע הוא מוגן: אי אפשר להשבית או להחליף דור דרך מפתחות API; סובב אותו על ידי שינוי הערך והפעלת מחדש של השרת. אל תעשה שימוש חוזר במפתח מנהל / לוח מחוונים.
על Kubernetes זה חווט בשבילך: שים AGENTEYE_API_KEY בסוד agenteye-agent והשרת Deployment כבר קורא את אותו ערך כ-AGENT_API_KEY.

3. הגדר את הטוקן המשותף של dashboard↔agent

הגדר את אותו AGENTEYE_AGENT_TOKEN על שתי שירותי dashboard ו-agent. לוח המחוונים משתנה אותו כאשר קורא לשירות הסוכן הפנימי; הסוכן דוחה קריאות ללא זה.

4. הנח גישה למשתמשים

תן למפעילי לוח המחוונים הרלוונטיים את הרשאת agent:use (ראה enterprise-docs/api-keys.md). משתמשים ללא זה לעולם לא רואים את העוזר. ברגע שנקודת קצה של LLM ומפתח קרוא-בלבד מוגדרים, הפעלת מחדש את server (כדי לזרוע את מפתח קרוא-בלבד) ושירות agent. תא העוזר מופיע בקצה הימני לכל משתמש agent:use, מכובה כברירת מחדל; לחץ על המסילה או לחץ על ⌘J / Ctrl+J כדי להרחיב.

הפניה למשתנה סביבה

הגדר בשירות agent:
משתנהמטרה
PORTKEY_API_KEYניתוב דרך Portkey (הסוכן בונה את חיבור השער מזה)
PORTKEY_VIRTUAL_KEYמפתח וירטואלי Portkey עבור יומן Anthropic שלך (אופציונלי אם למפתח קונפ ברירת מחדל)
PORTKEY_CONFIG / PORTKEY_BASE_URLתצורת Portkey שם / URL שער Portkey ממשוכן בעצמו (אופציונלי)
PORTKEY_PROVIDERPortkey ספק קלף — אפשרות ניתוב שלישית לצד PORTKEY_VIRTUAL_KEY / PORTKEY_CONFIG (בשימוש רק כאשר אף אחד מאלה לא הוגדר)
ANTHROPIC_API_KEYגישה ישירה Anthropic (חלופה לשער / Bedrock / Vertex)
ANTHROPIC_AUTH_TOKENBearer token עבור שער שמעמיד את זה דרך Authorization: Bearer במקום x-api-key (אופציונלי)
ANTHROPIC_BASE_URLנקודת קצה עבור שער שאינו Portkey
ANTHROPIC_CUSTOM_HEADERSכותרות נוספות עבור שער שאינו Portkey: Name: Value שורות מופרדות בשורה חדשה (לא JSON)
CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEXניתוב דרך Bedrock / Vertex
AGENTEYE_AGENT_MODELמזהה דגם ברירת מחדל (ברירת מחדל claude-sonnet-4-6)
AGENTEYE_AGENT_MODELSרשימת הרשאות מופרדת בפסיקים של מודלים שהמשתמש יכול לבחור בראש צ’אט. השאר לא מוגדר עבור דגם יחיד קבוע. ברירת המחדל למעלה חייבת להיות אחד מאלה (אחרת היא מתווספת).
AGENTEYE_AGENT_MAX_CONCURRENCYשיחות מקבילות מרביות לכל תרכובת (ברירת מחדל 4); בקשות עודפות מקבלות 429
AGENTEYE_API_KEYמפתח נתונים של העוזר. הגדר את אותו ערך כ-AGENT_API_KEY של השרת, שזורע אותו עם ערכת הרשאה מסובבת קבועה בהפעלה (ראה שלב 2).
AGENTEYE_AGENT_TOKENסוד משותף עם לוח המחוונים
AGENTEYE_SERVER_URLURL שרת AgentEye (ברירת מחדל http://server:8080)
AGENTEYE_AGENT_ALLOW_NO_ORGריבוי דיירים. כבוי כברירת מחדל (סגור כושל): העוזר דוחה בקשת /chat שאינה נושאת הקשר ארגון עם 400, מכיוון שכל כלי שהוא מפעיל מוסדר לארגון אחד. לוח המחוונים תמיד שולח הקשר זה ברגע שהוא מודע לארגון, ולכן אתה בדרך כלל משאיר זה לא מוגדר. הגדר ל-1 רק במהלך צבא מעבר שבו לוח מחוונים שלא-עדיין-מודע-לארגון מדבר לסוכן מודע לארגון, כך העוזר חוזר לארגון default במקום להסרב. נקה אותו ברגע שהשדרוג של לוח המחוונים נוחת.
AGENTEYE_AGENT_MAX_STEPSשלבי כלים מרביים לכל תשובה (ברירת מחדל 8)
AGENTEYE_AGENT_TIMEOUT_MSפג תוקף בקשת /chat הכללי (כל סיבובי דגם + שלבי כלים), במילישניות (ברירת מחדל 90000); לכלי SQL יש תאריך משלו של 10 שניות
AGENTEYE_AGENT_SELF_TELEMETRY1 כדי להקליט את ריצות העוזר שלו ל-AgentEye
AGENTEYE_TELEMETRY_API_KEYמפתח events:add ייעודי בלבד עבור כלי עצמי
AGENTEYE_AGENT_ENVתג סביבה הוחל על טלמטריה עצמית של העוזר (ברירת מחדל prod)
הגדר על שירות dashboard:
משתנהמטרה
AGENTEYE_AGENT_URLהיכן לוח המחוונים מגיע לשירות הסוכן. המניפסטים המצוברים של Kubernetes וקובץ Compose הגדירו זאת ל-http://agent:9100. השאר לא מוגדר כדי להסתיר את העוזר לחלוטין.
AGENTEYE_AGENT_TOKENחייב להתאים לטוקן של הסוכן

טלמטריה וראיית מה משתמשים שואלים

תוכן הנושא נשאר בתוך המערכות שלך בלבד כברירת מחדל. שלוש שכבות:
  1. חנות שיחה: כל נושא ותשובה שמורה בבסיס הנתונים AgentEye שלך (לכל משתמש, פרטי), וניתנת לטעינה מחדש מממיר ההיסטוריה של העוזר. זה התיעוד העמיד של מה שמשתמשים שואלים.
  2. אנליטיקה של מוצר: לוח המחוונים מתעד נתונים בלבד (כמה משתמשים במשתמש העוזר, ספר כלים, זמן השהייה) לאנליטיקה שלך. נושא טקסט לעולם אינו כלול בנתיב זה.
  3. כלי עצמי (אופציונלי): הגדר AGENTEYE_AGENT_SELF_TELEMETRY=1 (בתוספת events:add-בלבד AGENTEYE_TELEMETRY_API_KEY) והעוזר מתעד ריצות משלו ל-AgentEye כסוכן dashboard-assistant. אתה אז צופה בנושאים של משתמשים והנמקת העוזר בדיוק באותה תצפיות/אירועים שאתה משתמש בהם לכל השאר. הערה: אירועים אלה נראים לכל מי שיש events:read; אם זה רחב מדי, השאר זה כבוי.

השבתתו

כל אחד מאלה משבית את העוזר (התא מסילה נעלם):
  • בטל הגדרה AGENTEYE_AGENT_URL בלוח המחוונים, או
  • השאר את נקודת הקצה של LLM לא מוגדרת על הסוכן (לא ANTHROPIC_API_KEY / gateway / Bedrock / Vertex), או
  • אל תפרוס את שירות agent בכלל.

סיכום אבטחה

  • ללא כתיבה שקטה: כלי הכתיבה של העוזר (create_saved_query, update_saved_query, create_dashboard, update_dashboard, add_query_to_dashboard) לא יכולים להתבצע ללא לחיצת מפעיל מפורשת על כפתור אישור בצ’אט; שער הקדם-קריאה של ה-SDK חוסם את הכלי עד שהאישור מגיע לסוכן דרך תעלה משנית. אין הגדרה המשבית שער זה.
  • טווח נתונים קבוע וצר: העוזר משנה את עצמו לשרת עם מפתח ייעודי שערכת ההרשאה שלו קבועה בשרת (events:read, evaluations:read, dashboards:read, dashboards:write, queries:read, queries:write, queries:run). הכתיבות היחידות שהוא יכול לחבור הן שאילתות שמורות וממשקים; השרת דוחה קום שהוא מחוץ להיקף זה ללא קשר לכל מה שהמודל מנסה.
  • פני מחיקה: המפתח אינו נושא הרשאה מחיקה ולא כלי מחיקה חשוף. מפעילים מוחקים דרך הממשק של לוח המחוונים, לעולם לא העוזר.
  • פנימית בלבד: לסוכן אין נתיב ציבורי; רק לוח המחוונים יכול להתקשר אליו, ורק עם הטוקן המשותף. (ב-Kubernetes, מדיניות רשת מגביל את הסוכן להשגת רק שרת AgentEye ונקודת קצה של LLM.)
  • סקופ לכל משתמש: רק משתמשי agent:use מקבלים את העוזר, והם ניתנים רק הכלים התואמים לכל הרשאות הקריאה של המשתמש.
  • ללא HTML גולמי / ללא פליטת קישור: תשובות משתנות כמו markdown מעוקם; קישורים חיצוניים מובוססו.
ראה enterprise-docs/troubleshooting.md לבעיות נפוצות.