›_ بالإضافة إلى نقطة صحة ملونة. انقر على الشريط (أو اضغط على ⌘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 ثوان وحد صف 100 ألف) بينما الاستعلامات التي تلمس جداول علائقية فقط تعمل على دور Postgres للقراءة فقط (10 ثوان، 10 آلاف صف). لا يمكن للمساعد توسيع سطح البيانات؛ يمكنه فقط التأليف على سطح الاستعلامات الذي يتمتع به المشغل بالفعل. - يستخدم مفتاح مساعد مخصص (انظر أدناه) يحتوي على مجموعة أذونات ثابتة؛ حتى لو تصرف النموذج بشكل سيء فإنه لا يمكنه تجاوز تلك الأنطقة.
- يحتاج كل مستخدم لوحة تحكم إلى أذونة
agent:useلرؤية واستخدام المساعد. يتم تصفية الأدوات لكل طلب لمطابقة أذونات البيانات الخاصة بالمستخدم، لذا يحصل مستخدمevents:readعلى أدوات الأحداث ولكن لا أدواتdashboards:write.
لوحة ذكية الوعي بالصفحة: محرر على /queries، دردشة في مكان آخر
لوحة المساعد على الجانب الأيمن واعية بالصفحة. منتقي النموذج والسجل المحادثة ونقطة صحة النموذج ومدخل الدردشة لا تتغير، لكن شرائح قالب الحالة الفارغة ونص العنصر النائب وأي نقطة نهاية خلفية تصل إليها رسالة المستخدم تتبدل تلقائياً بناءً على المسار الحالي. تصبح الحامل “مساعد AI لأي صفحة تقف عليها”.
نقطتا نهاية خلفية، يتم الاختيار لكل صفحة (مع تجاوزات لكل شريحة).
| المسار | نقطة النهاية الافتراضية للصفحة | السبب |
|---|---|---|
/queries, /queries/new | POST /api/agent/compose-sql (بدون حلقة أداة) | المستخدم يبدأ من جديد؛ ≤1 ثانية SQL أول رمز يُدفق مباشرة إلى المحرر |
/queries/<id> (موجودة) | POST /api/agent/chat (مساعد حلقة أداة كاملة)، افتراضي الصفحة | الرسائل المكتوبة بحرية يجب أن تسمح للمستخدم بأن يسأل أي شيء (“شرح هذا”، “ماذا يفعل هذا؟”)؛ تختار شرائح إعادة البناء العودة إلى compose-sql عبر نوع كل شريحة |
| كل صفحة أخرى | POST /api/agent/chat (مساعد حلقة أداة كاملة) | أدوات القراءة + أدوات كتابة محمية بالموافقة |
/queries/<id> kind صريح حتى تتمكن صفحة واحدة من خلط التدفقين بسلاسة. مجموعة الشريحة الافتراضية هي شريحتا دردشة (شرح الاستعلام على الشاشة, ماذا يفعل هذا الاستعلام؟) بالإضافة إلى خمس شرائح compose-sql (معاملة حسب نطاق التاريخ، إضافة مرشح status='error'، إلخ). تنخفض الرسائل المكتوبة بحرية إلى الافتراضي للصفحة (دردشة)، لذا سؤال مثل “لماذا هذا بطيء جداً؟” يحصل على إجابة نثرية، بينما ينقر على شريحة معاملة حسب نطاق التاريخ عبر نقطة النهاية compose وتحرير SQL.
عندما يعمل المحرر في وضع التعديل (يرى currentSql غير فارغ لأن المستخدم على /queries/<id> أو /queries/new مع SQL المقترح محمل بالفعل)، يتحول موجه النظام من “تكوين استعلام جديد” إلى “تعديل SQL المقدم بأقل حد: الحفاظ على اختيار الجدول وأسماء الأعمدة وبنية الصلة والأسماء والمسافات البادئة”. يُظهر للنموذج مجموعة منفصلة من الأمثلة المعملة قبل وبعد (معاملة، إضافة مرشح، تحويل إلى دلاء بالساعة)، لذا يسفر النقر على شريحة إعادة البناء عن diff أقلي مقابل SQL للمحرر، وليس إعادة كتابة من الصفر.
انقر على شريحة compose (أو اكتب بحرية على /queries/new) → يدفق SQL إلى رسالة المساعد كـ ```sql كتلة مسيجة. في اللحظة التي ينتهي فيها البث، إذا تم تثبيت Monaco على المسار الحالي، يضيء المحرر تلقائياً في عرض diff (الأصلي على اليسار، المقترح على اليمين، تلميح ▾ AI proposed an edit في الأعلى، وحبوب قبول / رفض أدناه). المستخدم لا يحتاج إلى البحث عن أو النقر على زر إدراج في المحرر لرؤية diff. الزر إدراج لا يزال معروضاً تحت كتلة SQL كإعادة تشغيل يدوية (مفيد بعد رفض أو عندما ينقل المستخدم للبعيد والعودة)، وهو يبقى الطريق الوحيد عندما يكون المستخدم على صفحة غير محرر (مثل قائمة الاستعلامات المحفوظة)؛ هناك يخزنها SQL في sessionStorage ويتنقل إلى /queries/new، حيث يقرأ المحرر المثبت حديثاً المخزن المؤقت عند التثبيت ويفتح نفس عرض diff.
إذا كان SQL المقترح متطابقاً بالبايت لما هو موجود بالفعل في المحرر (تحرير بلا تأثير)، يتم تخطي الفتح التلقائي؛ لا نفتح diff فارغاً. زر إدراج في المحرر هو أيضاً بلا تأثير في تلك الحالة.
عندما يقبل المستخدم مقترحاً على /queries/new، تقرأ الإجراء الأساسي للشريط save بدلاً من create؛ تم تسليم SQL إليهم من قبل المساعد؛ النموذج الذهني هو “إكمال هذا”، وليس “كتابة من الصفر”. يتبدل التسمية بمجرد إدراج الحامل SQL ويبقى save حتى الانتقال بين الصفحات. على /queries/<id> كان الزر يقرأ دائماً save؛ لا شيء يتغير هناك.
خارج /queries، تعمل الحامل تماماً كما هي: دردشة كاملة مع بطاقات موافقة الأداة، وعي السياق بالصفحة، والاستشهادات.
الأذونات / البوابات. نقطة النهاية compose بوابة على أذونة 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)، ويرفض طلبات نثرية بحتة (“شرح هذا”، “ماذا يفعل هذا؟”) على مسار compose؛ هذه تنتمي إلى مسار الدردشة وتنتج إجابة نثرية هناك. تعرض الحامل سلسلة الرفض كشريحة خطأ حمراء مضمنة في رسالة المساعد؛ لا شيء يُدرج.
اختيار النموذج. مشترك مع مسار الدردشة. منتقي النموذج في رأس الحامل ينطبق على كلا نقطتي النهاية (استدعاء compose يمرر النموذج المختار عبر resolveModel() على خدمة الوكيل). عندما يسرد AGENTEYE_AGENT_MODELS عدة نماذج، يمكن للمشغلين خلط خيار Haiku-class للمحرر مع خيار Sonnet-class للدردشة؛ يختار المستخدم لكل محادثة.
قوالب لكل صفحة. لكل صفحة قالب خاص بها (العنوان ونص الجسم ونص العنصر النائب وشرائح الاقتراح) حتى تتكيف الحامل مع الصفحة التي تقف عليها. تشير الشرائح المقدمة على مسار معين إلى نفس النوايا التي يُضبط المحرر من أجلها، لذا ينقر على الاقتراح يسفر عن التعديل الذي تتوقعه.
تعطيله. نفس مسار الدردشة: الحامل والمحرر كلاهما بوابة بحاوية agent واتصال LLM الخاص به. إذا كنت تريد سلوك دردشة فقط لمستخدم معين، أزل أذونة queries:run (التي تعطل أيضاً زر Run للمحرر)؛ إذا كنت تريد سلوك محرر فقط، أزل agent:use من أدوار المستخدم، ثم أضف مرة أخرى queries:run بشكل منفصل حتى يتمكنوا من تنفيذ SQL المكتوب من قبل المؤلف.
تفعيله
تشحن خدمةagent في ملف Docker Compose وفي manifests Kubernetes. لتشغيل المساعد، وفّر (1) نقطة نهاية LLM و (2) مفتاح البيانات المخصص للمساعد.
1. اختر اتصال LLM
اختر أحد هذه وعيّن المتغيرات المقابلة على خدمةagent:
a) Anthropic مباشرة
@<slug>/<model> والـ slug يحمل توجيه المزود + الأوراق المالية، لذا لا توجد حاجة لمفتاح افتراضي،
فقط مفتاح Portkey الخاص بك. يرسل الوكيل فقط x-portkey-api-key ويشير إلى بوابة Portkey؛ يحل Portkey الباقي. (اسم نموذج عادي يفشل مع “يُطلب رأس x-portkey-config أو x-portkey-provider header”; بادئة @slug/ هي ما يجعل key-only تعمل.) لبوابة ذاتية الاستضافة اعيّن PORTKEY_BASE_URL.
تفضل التوجيه لكل طلب بدلاً من slug؟ اعيّن PORTKEY_VIRTUAL_KEY=<vk> (أو
PORTKEY_CONFIG=<id>) مع AGENTEYE_AGENT_MODEL عادي.
c) أي بوابة متوافقة مع 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. عيّن رمز لوحة التحكم↔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 | slug مزود Portkey — خيار توجيه ثالث إلى جانب PORTKEY_VIRTUAL_KEY / PORTKEY_CONFIG (يُستخدم فقط عندما لا يتم تعيين أي منهما) |
ANTHROPIC_API_KEY | وصول Anthropic المباشر (بديل لبوابة / Bedrock / Vertex) |
ANTHROPIC_AUTH_TOKEN | رمز Bearer لبوابة تصادق عبر 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 | الحد الأقصى من الدردشات المتزامنة لكل pod (الافتراضي 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 | حيث تصل لوحة التحكم إلى خدمة الوكيل. تعيّن manifests Kubernetes والملف المرفق http://agent:9100. اترك لم يُعيّن لإخفاء المساعد تماماً. |
AGENTEYE_AGENT_TOKEN | يجب أن يطابق رمز الوكيل |
القياس عن بُعد ورؤية ما يسأل المستخدمون
محتوى الموجه يبقى داخل أنظمتك الخاصة بشكل افتراضي. ثلاث طبقات:- مخزن المحادثة: كل موجه وإجابة تُحفظ في قاعدة بيانات AgentEye (لكل مستخدم، خاص)، وقابلة لإعادة التحميل من منتقي السجل للمساعد. هذا هو السجل الدائم لما يسأل المستخدمون.
- تحليلات المنتج: تسجل لوحة التحكم البيانات الوصفية فقط (كم مرة يُستخدم المساعد، عدد الأدوات، الزمن الكامن) إلى التحليلات الخاصة بك. نص الموجه لا يُدرج أبداً على هذا المسار.
- القياس الذاتي (اختياري): عيّن
AGENTEYE_AGENT_SELF_TELEMETRY=1(بالإضافة إلىAGENTEYE_TELEMETRY_API_KEYفقطevents:add) ويسجل المساعد أشغاله الخاصة في AgentEye كوكيلdashboard-assistant. تشاهد بعدها مشاركات المستخدمين وتفكير المساعد في نفس عروض الجلسات/الأحداث التي تستخدمها لكل شيء آخر. ملاحظة: تلك الأحداث مرئية لأي شخص لديهevents:read؛ إذا كان هذا عريضاً جداً، اترك هذا معطلاً.
تعطيله
أي من هذه يعطل المساعد (تختفي حامل الشريط):- ألغِ تعيين
AGENTEYE_AGENT_URLعلى لوحة التحكم، أو - اترك نقطة نهاية LLM لم تُكوَّن على الوكيل (لا
ANTHROPIC_API_KEY/ بوابة / 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، تقيد NetworkPolicy الوكيل إلى الوصول فقط إلى خادم AgentEye ونقطة نهاية LLM.)
- تحديد النطاق لكل مستخدم: فقط مستخدمو
agent:useيحصلون على المساعد، وتُعطى فقط الأدوات المطابقة لأذونات قراءة كل مستخدم. - لا HTML خام / لا تسريب الروابط: تُعرَّض الإجابات كـ markdown معقّم؛ الروابط الخارجية مشطوبة.