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/new | POST /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 ישירות
@<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, ממשוכן בעצמו, …)
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; סובב אותו על ידי שינוי הערך והפעלת מחדש של השרת. אל תעשה שימוש חוזר במפתח מנהל / לוח מחוונים.
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_PROVIDER | Portkey ספק קלף — אפשרות ניתוב שלישית לצד PORTKEY_VIRTUAL_KEY / PORTKEY_CONFIG (בשימוש רק כאשר אף אחד מאלה לא הוגדר) |
ANTHROPIC_API_KEY | גישה ישירה Anthropic (חלופה לשער / Bedrock / Vertex) |
ANTHROPIC_AUTH_TOKEN | Bearer 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_URL | URL שרת 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_TELEMETRY | 1 כדי להקליט את ריצות העוזר שלו ל-AgentEye |
AGENTEYE_TELEMETRY_API_KEY | מפתח events:add ייעודי בלבד עבור כלי עצמי |
AGENTEYE_AGENT_ENV | תג סביבה הוחל על טלמטריה עצמית של העוזר (ברירת מחדל prod) |
dashboard:
| משתנה | מטרה |
|---|---|
AGENTEYE_AGENT_URL | היכן לוח המחוונים מגיע לשירות הסוכן. המניפסטים המצוברים של Kubernetes וקובץ Compose הגדירו זאת ל-http://agent:9100. השאר לא מוגדר כדי להסתיר את העוזר לחלוטין. |
AGENTEYE_AGENT_TOKEN | חייב להתאים לטוקן של הסוכן |
טלמטריה וראיית מה משתמשים שואלים
תוכן הנושא נשאר בתוך המערכות שלך בלבד כברירת מחדל. שלוש שכבות:- חנות שיחה: כל נושא ותשובה שמורה בבסיס הנתונים AgentEye שלך (לכל משתמש, פרטי), וניתנת לטעינה מחדש מממיר ההיסטוריה של העוזר. זה התיעוד העמיד של מה שמשתמשים שואלים.
- אנליטיקה של מוצר: לוח המחוונים מתעד נתונים בלבד (כמה משתמשים במשתמש העוזר, ספר כלים, זמן השהייה) לאנליטיקה שלך. נושא טקסט לעולם אינו כלול בנתיב זה.
- כלי עצמי (אופציונלי): הגדר
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 מעוקם; קישורים חיצוניים מובוססו.

