diff --git a/docs/ar/agenteye/audits.mdx b/docs/ar/agenteye/audits.mdx index 3730df81..ddcb3b16 100644 --- a/docs/ar/agenteye/audits.mdx +++ b/docs/ar/agenteye/audits.mdx @@ -1,108 +1,105 @@ --- +title: "التدقيقات — كشف تحسينات موجهة بالوكيل" +description: "توثيق AgentEye Audits — كشف تحسينات موجهة بالوكيل." --- -title: "التدقيقات — كشف التحسينات الموكلة" -description: "توثيق تدقيقات AgentEye — كشف التحسينات الموكلة." ---- - -التدقيقات هي وظائف متكررة تفحص سجلات الوكيل الخاص بك **عبر الجلسات** للعثور على أشياء تستحق التحسين. بينما ينظر التنبيه إلى مقياس واحد تعرفه بالفعل في الوقت الفعلي تقريباً، يقوم التدقيق *بالتحقيق*: وفقاً لجدول زمني تحدده، يقوم بتشغيل مسار سياسة حتمي على النافذة، ثم يطلق **وكيل موثوقية مدعوماً بالذكاء الاصطناعي** على الجلسات — يقوم الوكيل باستعلام البيانات بنفسه، وقراءة النصوص المريبة، و(عند الحاجة) تشغيل سكريبتات تحليل صغيرة، ثم يكتب **توصيات تحسين** مع الأدلة وراء كل واحدة. +التدقيقات عبارة عن مهام متكررة تستخرج من سجلات الوكيل الخاص بك **عبر الجلسات** للعثور على أشياء تستحق التحسين. بينما تراقب التنبيهات مقياساً واحداً تعرفه بالفعل في الوقت الفعلي تقريباً، يقوم التدقيق *بالتحقيق*: وفقاً لجدول زمني تحدده، يقوم بتنفيذ نقطة سياسة حتمية عبر النافذة، ثم يحرر **وكيل موثوقية موجه بالذكاء الاصطناعي** على جلساتك — يستعلم الوكيل عن البيانات بنفسه، ويقرأ النسخ المريبة، وعند الحاجة يقوم بتشغيل نصوص تحليل صغيرة، ثم يكتب **توصيات تحسين** مع الأدلة وراء كل منها. -استخدم التدقيقات للإجابة على "ما الذي يجب أن أصلحه أو أحسنه في الوكلاء الخاصين بي؟" — واستخدم التنبيهات للحصول على إخطار فوري عند تجاوز عتبة محددة. يرتبط كل تحسين بالجلسات والاستعلامات الدقيقة وراءه، وينشئ نقرة واحدة تنبيهاً مملوءاً مسبقاً لالتقاط التكرارات. +استخدم التدقيقات للإجابة على "ما الذي يجب أن أصلحه أو أحسنه في الوكلاء الخاصين بي؟" — واستخدم التنبيهات ليتم إخطارك في اللحظة التي يتم فيها تجاوز حد معين. يرتبط كل تحسين بالجلسات والاستعلامات الدقيقة وراءه، وبنقرة واحدة يتم إنشاء تنبيه معبأ مسبقاً للتقاط التكرارات. -سطح لوحة التحكم هو **`//audits`** (الشريط الجانبي → *تحليل* → *التدقيقات*)، محمي بأذونات `audits:read` / `audits:write`. +سطح لوحة المعلومات هو **`//audits`** (الشريط الجانبي → *تحليل* → *التدقيقات*)، محمي بصلاحيات `audits:read` / `audits:write`. --- -## كيف يعمل التشغيل +## كيفية عمل التشغيل -لكل تشغيل طبقتان — قاعدة حتمية وتحقيق موكل. +لكل تشغيل طبقتان — حد أدنى حتمي وتحقيق موجه بالوكيل. -### 1. مسار السياسة (حتمي) +### 1. نقطة السياسة (حتمية) -قبل تشغيل أي نموذج، يقوم التدقيق بتنفيذ فهرس صغير من **فحوصات السياسة SQL** على النافذة: استعلامات تجميع محدودة تحدد الأنماط السيئة المعروفة وتقرير *كم عدد* الأحداث / *أي* الجلسات المطابقة — لا تطابق النص نفسه. يتضمن الفهرس: +قبل تشغيل أي نموذج، ينفذ التدقيق كتالوغ صغير من **فحوصات سياسة SQL** عبر النافذة: استعلامات إجمالية محدودة تضع علامة على الأنماط السيئة المعروفة وتبلغ عن *عدد* الأحداث / *أي* الجلسات المطابقة — لا تبلغ أبداً عن النص المطابق نفسه. يتضمن الكتالوغ: -- **تسرب السرية/بيانات الاعتماد** في حمولات الأحداث — مفاتح الوصول AWS، مفاتيح API من نوع `sk-…`، مفاتيح PEM الخاصة، رموز JWT / Bearer، وتعيينات بيانات الاعتماد `KEY=…`. -- **علامات حقن المطالب** — "تجاهل التعليمات السابقة"، "كشف نظام المطالبات الخاص بك"، وما شابه ذلك. -- **معلومات تعريف شخصية** — أرقام على شكل SSN (استدلالي). -- **رفض أذونات الأدوات** و**حلقات استدعاء الأدوات الجامحة**. +- **تسريب السرية / بيانات الاعتماد** في حمولات الأحداث — مفاتيح وصول AWS، مفاتيح API `sk-…`، مفاتيح خاصة PEM، رموز JWT / Bearer، وتعيينات بيانات الاعتماد `KEY=…`. +- **علامات حقن الموجه** — "تجاهل الإرشادات السابقة"، "اكشف عن موجه النظام الخاص بك"، وما شابه. +- **معلومات شخصية قابلة للتحديد** — أرقام على شكل SSN (استكشافي). +- **رفض أذونات الأداة** و**حلقات استدعاء الأداة الجامحة**. -يتم الاحتفاظ بنتائج السياسة كنتائج بحث (نوع `policy`) التي **تظهر دائماً** (لا يتم قصها أبداً بواسطة الحد الأقصى لكل تشغيل)، وتُسلم إلى وكيل الذكاء الاصطناعي كتلميحات البداية. لأن هذه الطبقة لا تحتاج إلى نموذج، فإن التدقيق ينتج عنه أهم الإشارات الأمنية حتى لو كان وكيل الذكاء الاصطناعي غير متاح. +يتم الاحتفاظ بضربات السياسة كنتائج (نوع `policy`) و**تظهر دائماً** (لا تتم إزالتها أبداً بواسطة الحد الأقصى لكل تشغيل)، وتُسلّم إلى وكيل الذكاء الاصطناعي كخيوط بداية. لأن هذه الطبقة لا تحتاج إلى نموذج، فإن التدقيق لا يزال ينتج عن أهم إشارات الأمان الخاصة به حتى لو كان وكيل الذكاء الاصطناعي غير متاح. -### 2. التحقيق الموكل (الذكاء الاصطناعي) +### 2. التحقيق الموجه بالوكيل (الذكاء الاصطناعي) -ثم يقوم التدقيق بتشغيل **وكيل موثوقية مستقل** (نفس خدمة Agents SDK التي تشغل مساعد لوحة التحكم، مع موجهة خاصة بالتدقيق). يُعطى **نطاق** التدقيق (الوكلاء المحددين × البيئات) و**النافذة الزمنية**، يقوم الوكيل بـ: +ثم ينفذ التدقيق **وكيل موثوقية مستقل** (نفس خدمة Claude Agent SDK التي تشغل مساعد لوحة المعلومات، مع موجه خاص بالتدقيق). بالنظر إلى **نطاق** التدقيق (الوكلاء المختارون × البيئات) و**نافذة زمنية**، يقوم الوكيل بـ: -- تشغيل استعلامات SQL للقراءة فقط مقابل جداول التحليلات الخاصة بك، -- قراءة حفنة من نصوص الجلسات التمثيلية، -- كتابة وتشغيل سكريبتات Python قصيرة اختياراً في صندوق فراغ مقفل داخل القرص (بدون شبكة، بدون وصول نظام الملفات، أسرار مخفوفة) للتحليل الذي لا تستطيع SQL التعبير عنه — تجميع الأخطاء، حساب التوزيعات، تنظيف الحمولات التي حصلت عليها بالفعل، -- وتسجيل كل **تحسين** موثق جيداً تجده. +- تشغيل استعلامات SQL للقراءة فقط على جداول التحليلات الخاصة بك، +- قراءة حفنة من نسخ جلسة ممثلة، +- كتابة وتشغيل **نصوص Python قصيرة في برنامج sandbox مقفول داخل القرن** (بدون شبكة، بدون وصول نظام الملفات، بيانات سرية محظاة) للتحليل الذي لا يمكن لـ SQL التعبير عنه — تجميع الأخطاء، حساب التوزيعات، كنس الحمولات التي استرجعها بالفعل، +- وتسجيل كل **تحسين** موثق بشكل جيد يجده. -تعمل من خلال عدة أسطر تحقيق — تجميع الأخطاء، الانجراف مقابل أساس البداية، فشل الهدف في النصوص، إساءة استخدام الأداة، مقايضات الجودة/التكلفة، وفجوات التغطية — على **حساسية** التدقيق (منخفضة / متوسطة / عالية). كل تحسين **يجب أن يستشهد بالأدلة**: معرّفات الجلسة التي فحصها الوكيل فعلاً و/أو SQL الذي قام به. يتحقق الخادم من أن الجلسات المستشهد بها موجودة و**يرفض أي تحسين بدون أدلة باقية**، لذلك يحقق الوكيل ولكن لا يختلق أبداً. +يعمل من خلال عدة خطوط تحقيق — تجميع الأخطاء، الانجراف مقابل خط الأساس، فشل الهدف في النسخ، سوء استخدام الأداة، مقايضات الجودة/التكلفة، وفجوات التغطية — عند **حساسية** التدقيق (منخفضة / متوسطة / عالية). يجب أن يستشهد كل تحسين **بالأدلة**: معرفات الجلسة التي فحصها الوكيل بالفعل و/أو SQL الذي قام بتشغيله. يتحقق الخادم من أن الجلسات المستشهد بها موجودة و**يتخلص من أي تحسين بدون دليل باقٍ**، لذا يحقق الوكيل لكن لا يبتكر أبداً. يحمل كل تحسين: -- **توصية** (التغيير المحدد الذي يجب إجراؤه — تعديل المطالب، إصلاح مخطط الأداة، سياسة إعادة محاولة، حراسة، تغطية تقييم أكثر)، +- **توصية** (التغيير الملموس المراد إجراؤه — تعديل موجه، إصلاح مخطط أداة، سياسة إعادة محاولة، حاجز، تغطية تقييم أكثر)، - **تأثير متوقع** و**تقدير جهد** (منخفض / متوسط / عالي)، -- **حجم** — `big` (يجب استدعاء المشغل)، `medium` (ينتمي إلى تقرير التشغيل)، أو `small` (سياق لوحة التحكم)، -- **بصمة** مستقرة (من فئة المشكلة + النطاق، *ليس* جلسات هذا التشغيل) بحيث يتم تتبع نفس المشكلة من تشغيل إلى تشغيل حتى مع تغير الأدلة، -- وحيث يمكن لمراقب حتمي بسيط أن يلتقط التكرار، **تنبيه مقترح** يمكنك إنشاؤه بنقرة واحدة. +- **حجم** — `big` (يجب إخطار المشغل)، `medium` (ينتمي إلى تقرير التشغيل)، أو `small` (سياق لوحة المعلومات)، +- **بصمة** مستقرة (من فئة المشكلة + النطاق، *ليس* جلسات هذا التشغيل) بحيث يتم تتبع نفس المشكلة من تشغيل إلى تشغيل حتى عندما تتغير الأدلة، +- وعند الحاجة، حيث يمكن لمراقب حتمي بسيط أن يلتقط التكرار، **تنبيه مقترح** يمكنك إنشاؤه بنقرة واحدة. -> **طبقة الذكاء الاصطناعي اختيارية ولكنها موصى بها.** إذا لم يتم تكوين وكيل ذكاء اصطناعي لخط أنابيب التدقيق، فإن التشغيلات تعمل بشكل عام، تحتفظ بنتائج السياسة، وتقرر بصراحة "التحليل غير متاح" للطبقة الموكلة بدلاً من الإمرار صامتاً. +> **طبقة الذكاء الاصطناعي اختيارية لكن موصى بها.** إذا لم يتم تكوين وكيل ذكاء اصطناعي لخط أنابيب التدقيق، فإن التشغيلات لا تزال تُنفذ، وتحتفظ بنتائج السياسة، وتُبلغ بصراحة عن "التحليل غير متاح" للطبقة الموجهة بالوكيل بدلاً من السكوت. -### أنماط الفشل +### أوضاع الفشل -تصنيف التحسينات إلى **فهرس أنماط الفشل** الدائم في منظمتك (أو اقتراح وضع جديد). تعطي الأنماط الأنماط هوية مستقرة عبر التشغيلات وتتبع التكرار طويل الأفق. +تصنف التحسينات إلى **كتالوغ وضع فشل** دائم في المؤسسة (أو تقترح وضعاً جديداً). تعطي الأوضاع الأنماط هوية مستقرة عبر التشغيلات وتتبع التكرار على الأفق الطويل. -## دورة حياة الفحص +## دورة حياة الفرز على صفحة البحث (`/audits//findings/`): | الإجراء | التأثير | |---|---| -| **acknowledge** | يحافظ على البحث مرئياً لكن يقلل أولويته إلى النصف. | -| **resolve** | يحدده كمثبت. إذا عاد النمط فعلاً لاحقاً، يعيد فتحه كـ **new** — لذا يكون الانحدار مرتفع الصوت، وليس مطوياً صامتاً في التاريخ. | -| **mute** / **dismiss** | قمع دائم: يتم تذكر بصمة النمط ولا تظهر أبداً، حتى عبر التشغيلات. استخدم mute لـ "معروف، مقبول"؛ dismiss لـ "ليس مفيداً". | -| **reopen** | يمسح القمع / الدقة ويعيد ترتيب النمط. | -| **assign** | يوجه البحث إلى مشغل (عضو منظمة) لتولي الملكية. الأولوية وحالة القمع بدون تغيير. | +| **acknowledge** | يحافظ على ظهور البحث لكن يخفض أولويته إلى النصف. | +| **resolve** | يضع علامة عليه كمصحح. إذا عادت النمط فعلاً لاحقاً، فإنه **يُعاد فتحه كـ** جديد — لذا يكون الانحدار بصوت مرتفع، وليس مطوياً صامتاً في السجل. | +| **mute** / **dismiss** | قمع دائم: يتم تذكر بصمة النمط ولا تظهر أبداً مجدداً، حتى عبر التشغيلات. استخدم mute لـ "معروف، مقبول"؛ dismiss لـ "غير مفيد". | +| **reopen** | يمسح القمع / الحل ويصنف النمط مرة أخرى. | -يتم التحكم في الضوضاء منخفضة الإشارة لكل تدقيق مع حد أقصى للنتائج لكل تشغيل (`top_k`) على التحسينات الموكلة. تتجاوز نتائج السياسة الحد الأقصى (أنها ذات صلة أمنية وتظهر دائماً). يتم عد أي شيء يقطعه الحد الأقصى في إحصائيات التشغيل — لا يتم إسقاط أي شيء صامتاً. +يتم التحكم في ضوضاء الإشارة المنخفضة لكل تدقيق بحد أقصى من البحث لكل تشغيل (`top_k`) على التحسينات الموجهة بالوكيل. تتجاوز نتائج السياسة الحد الأقصى (فهي ذات صلة بالأمان وتُظهر دائماً). أي شيء يتم قطعه بواسطة الحد الأقصى يتم عده في إحصائيات التشغيل — لا يتم إسقاط أي شيء صامتاً. ## الجدولة -- **Cadence** (`schedule_interval_secs`): كل ساعة إلى أسبوعياً؛ **يومياً هو الافتراضي**. التدقيقات متعمدة أغلظ من التنبيهات — يفحص التحقيق الموكل النوافذ الكاملة ويعمل لدقائق. -- **النافذة**: إما بحث متجدد ثابت (مثل "كل تشغيل يفحص آخر 7 أيام") أو **منذ آخر تشغيل** (الافتراضي) — يلتقط كل تشغيل من حيث انتهى التشغيل السابق الناجح، مع تداخل صغير بحيث لا تُفقد أحداث الحدود أبداً. -- يتم جدولة التشغيل التالي فترة زمنية كاملة بعد انتهاء التشغيل السابق **يكمل**، لذا فإن التشغيل البطيء لا يكدس أبداً تشغيل ثانٍ متزامن لنفس التدقيق. -- **تشغيل الآن** على صفحة التدقيق يجعله مستحقاً فوراً. +- **التكرار** (`schedule_interval_secs`): بالساعة إلى أسبوعي؛ **يومي هو الافتراضي**. التدقيقات أكثر خشونة بقصد من التنبيهات — يفحص التحقيق الموجه بالوكيل النوافذ الكاملة ويعمل لدقائق. +- **النافذة**: إما نظرة خلفية دوارة ثابتة (مثل "كل تشغيل يفحص آخر 7 أيام") أو **منذ آخر تشغيل** (الافتراضي) — يختار كل تشغيل من حيث انتهى التشغيل الناجح السابق، مع تداخل صغير حتى لا تُفتقد أحداث الحدود. +- يتم جدولة التشغيل التالي فترة زمنية كاملة بعد انتهاء التشغيل السابق **يكتمل**، لذا فإن التشغيل البطيء لن يكدس أبداً تشغيل ثانٍ متزامن من نفس التدقيق. +- **تشغيل الآن** على صفحة التدقيق يجعله مستحقاً على الفور. ## اختيار النموذج -عند إنشاء تدقيق، يمكنك اختيار النموذج الذي يستخدمه التحقيق، من **قائمة النماذج التي قام المشغل بتكوينها** لخدمة الوكيل. مع نموذج واحد مكون، يعرض المنتقى كتسمية توضيحية؛ مع عدة، تختار. تركه بدون تعيين يستخدم الافتراضي المكون. +عند إنشاء تدقيق، يمكنك اختيار النموذج الذي يستخدمه التحقيق، من **قائمة النماذج التي قام المشغل بتكوينها** لخدمة الوكيل. مع تكوين نموذج واحد، يُظهر المنتقي اسمه كعنوان; مع عدة، تختار. عدم تعيينه يستخدم الافتراضي المكون. ## الإخطارات -عندما يكتشف التشغيل **نتائج جديدة**، يقوم التدقيق بإخطار قنوات المنظمة المكونة — نفس بوابة `alerts.enabled_channels` والإعدادات التي يستخدمها خط أنابيب التنبيهات: +عندما يظهر التشغيل **نتائج جديدة**، يخطر التدقيق قنوات المؤسسة المكونة — نفس بوابة `alerts.enabled_channels` والإعدادات التي يستخدمها خط أنابيب التنبيهات: -- **Slack** — ملخص البنود الكبيرة الجديدة ذات الصلة مع ارتباط عميق. -- **البريد الإلكتروني** — **تقرير تدقيق** مصمم يسرد التحسينات الجديدة (أعلى شدة، توصيات لكل عنصر، ارتباط عميق)، مرسل عندما يكون للتدقيق قناة **بريد إلكتروني** مرفقة وهناك نتيجة بحث جديدة واحدة على الأقل. +- **Slack** — ملخص للعناصر الجديدة الهامة (`big`) مع رابط عميق. +- **البريد الإلكتروني** — **تقرير تدقيق** مصمم يسرد التحسينات الجديدة (أعلى خطورة، توصيات لكل عنصر، رابط عميق)، مرسل عندما يكون لديه التدقيق قناة **بريد إلكتروني** مرفقة وهناك نتيجة واحدة على الأقل جديدة. -لا تعاود إخطار النتائج المتكررة لكن المعروفة. +لا تعيد الإخطار للنتائج المتكررة المعروفة. ## مرجع التكوين -يتم إدارة تعريفات التدقيق في لوحة التحكم (`/audits/new`) أو عبر API. تتضمن الإعدادات لكل تدقيق جدول التشغيل والنافذة والنطاق (`{"environments": [...], "agent_ids": [...]}`)، والحساسية (`low` / `medium` / `high`)، والقنوات الإخطارية، والحد الأقصى للنتائج لكل تشغيل (`top_k`)، والنموذج (عبر `llm_budget.model`). يتم توثيق إعدادات خادم مستوى المشغل (المهل الزمنية، الصندوق الفراغ، عنوان URL لخدمة الوكيل) في [deployment.md](/ar/agenteye/deployment). +يتم إدارة تعريفات التدقيق في لوحة المعلومات (`/audits/new`) أو عبر واجهة برمجية التطبيقات. تتضمن الإعدادات لكل تدقيق جدول التكرار والنافذة والنطاق (`{"environments": [...], "agent_ids": [...]}`)، والحساسية (`low` / `medium` / `high`)، وقنوات الإخطار، وحد البحث لكل تشغيل (`top_k`)، والنموذج (عبر `llm_budget.model`). يتم توثيق إعدادات الخادم على مستوى المشغل (المهل الزمنية، sandbox، URL خدمة الوكيل) في [deployment.md](/ar/agenteye/deployment). -## API +## واجهة برمجية التطبيقات -جميع النقاط النهائية ذات نطاق منظمة وتتبع مصادقة مفتاح المتحمل القياسية (انظر [api-keys.md](/ar/agenteye/api-keys)). +جميع نقاط النهاية محدودة بالمؤسسة وتتبع المصادقة القياسية للمفتاح الحامل (انظر [api-keys.md](/ar/agenteye/api-keys)). -| النقطة النهائية | الإذن | الغرض | +| نقطة النهاية | الصلاحية | الغرض | |---|---|---| -| `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | سرد / إنشاء تعريفات التدقيق. | -| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | فحص، تحرير، حذف تدقيق. | -| `POST /audits/:id/run` | `audits:write` | جعل التدقيق مستحقاً فوراً. | -| `GET /audits/:id/runs` | `audits:read` | سجل التشغيل (النافذة، الحالة، الإحصائيات، عدد النتائج). | -| `GET /audits/findings` | `audits:read` | النتائج على مستوى المنظمة، قابلة للتصفية حسب `audit_id`، `status`؛ مرتبة حسب الأولوية. | -| `GET /audits/findings/:fid` | `audits:read` | تفاصيل البحث الكاملة (التوصية، الأدلة، الأولوية). | -| `POST /audits/findings/:fid/status` | `audits:write` | الفحص: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | - -للاطلاع على "التدقيق قيد التشغيل لكن لم يجد شيئاً"، "صندوق الأكواد معطل"، و"بريد التدقيق الإلكتروني لم يتم تسليمه"، انظر [troubleshooting.md](/ar/agenteye/troubleshooting#audits). \ No newline at end of file +| `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | قائمة / إنشاء تعريفات التدقيق. | +| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | فحص، تعديل، حذف تدقيق. | +| `POST /audits/:id/run` | `audits:write` | اجعل التدقيق مستحقاً على الفور. | +| `GET /audits/:id/runs` | `audits:read` | سجل التشغيل (النافذة، الحالة، الإحصائيات، عدد البحث). | +| `GET /audits/findings` | `audits:read` | البحث على مستوى المؤسسة، قابل للتصفية حسب `audit_id`، `status`؛ مرتب حسب الأولوية. | +| `GET /audits/findings/:fid` | `audits:read` | تفاصيل البحث الكاملة (توصية، أدلة، أولوية). | +| `POST /audits/findings/:fid/status` | `audits:write` | الفرز: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | + +لـ "تم تشغيل التدقيق لكن لم يجد شيئاً"، "sandbox الكود معطل"، و"بريد التدقيق الإلكتروني لم يتم تسليمه"، انظر [troubleshooting.md](/ar/agenteye/troubleshooting#audits). \ No newline at end of file diff --git a/docs/ar/agenteye/cli-recipes.mdx b/docs/ar/agenteye/cli-recipes.mdx index b4905661..584a17cc 100644 --- a/docs/ar/agenteye/cli-recipes.mdx +++ b/docs/ar/agenteye/cli-recipes.mdx @@ -1,29 +1,29 @@ --- title: "وصفات CLI للوكلاء" -description: "وثائق وصفات AgentEye CLI للوكلاء." +description: "وثائق وصفات CLI للوكلاء في AgentEye." --- -اسحب بيانات الجلسة والحدث والتقييم (وشغّل إعادة التقييمات) مباشرة من سكريبت أو وكيل ترميز، مع JSON نظيف على stdout يمكن توجيهه مباشرة إلى `jq`. تحول هذه الوصفات بيانات القابلية للملاحظة في AgentEye إلى شيء يمكن لمستخدم المحطة الطرفية أو وكيل ترميز ذكي (Claude Code، Cursor) الاستعلام عنه وأتمتته، دون الحاجة للنقر عبر لوحة التحكم. +اسحب بيانات الجلسة والحدث والتقييم (وشغّل إعادة التقييمات) مباشرة من سكريبت أو وكيل ترميز، مع JSON نظيف على stdout يتم توجيهه مباشرة إلى `jq`. تحول هذه الوصفات بيانات المراقبة في AgentEye إلى شيء يمكن لمستخدم الطرفية أو وكيل ترميز AI (Claude Code، Cursor) أن يستعلم عنه ويأتمتته، دون الحاجة للنقر عبر لوحة التحكم. -الأنماط أدناه جاهزة للنسخ واللصق في AgentEye CLI (`agenteye`). للتثبيت والمصادقة وقائمة الخيارات الكاملة، انظر [CLI](/ar/agenteye/cli)؛ شغّل `agenteye -h` أو `agenteye -h` للحصول على المساعدة المدمجة. +الأنماط أدناه جاهزة للنسخ واللصق لـ AgentEye CLI (`agenteye`). للتثبيت والمصادقة وقائمة الخيارات الكاملة، انظر [CLI](/ar/agenteye/cli)؛ شغّل `agenteye -h` أو `agenteye -h` للمساعدة المدمجة. ## القواعد الذهبية -1. **تأتي الخيارات العامة *قبل* الأمر.** `agenteye --json sessions` صحيح؛ `agenteye sessions --json` ليس كذلك. الخيارات العامة هي `--json`، `--base-url`، `--org`، `--token`، `--insecure`/`--secure`، `--timeout`، `--quiet`، `--no-color`. -2. **مرّر `--json` كلما حللت المخرجات.** تذهب البيانات إلى **stdout** بصيغة JSON؛ حالة المستخدم والأخطاء تذهب إلى **stderr**، لذا يبقى stdout نظيفاً للتوجيه إلى `jq`. -3. **افرع بناءً على رمز الخروج**، وليس على نص stderr: `0` موافق · `2` حجج سيئة · `3` لا يمكن الوصول إلى لوحة التحكم · `4` لم تسجل الدخول أو انتهت صلاحية الجلسة · `5` صلاحية مفقودة. -4. **اكتشف باستخدام `-h`.** كل أمر يوثق مرشحاته وتنسيقات القيم وشكل JSON. +1. **الخيارات العامة تأتي *قبل* الأمر.** `agenteye --json sessions` صحيح؛ `agenteye sessions --json` غير صحيح. الخيارات العامة هي `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **مرّر `--json` كلما قمت بتحليل الإخراج.** تذهب البيانات إلى **stdout** كـ JSON؛ رسائل الحالة والأخطاء البشرية تذهب إلى **stderr**، لذا يبقى stdout نظيفًا للتوجيه إلى `jq`. +3. **تفرع بناءً على رمز الخروج**، وليس على نص stderr: `0` حسنًا · `2` وسائط سيئة · `3` لا يمكن الوصول إلى لوحة التحكم · `4` لم تقم بتسجيل الدخول أو انتهت الجلسة · `5` إذن مفقود. +4. **اكتشف مع `-h`.** كل أمر يوثّق مرشحاته وتنسيقات القيمة وشكل JSON. ## إعداد لمرة واحدة ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # لتتجنب تكرار --base-url +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # حتى لا تكرر --base-url agenteye login --email you@example.com # الصق الرمز المرسل بالبريد؛ صالح ~24h ``` ## تأكد من المصادقة قبل القيام بالعمل -`whoami` لا يرمي أخطاء على جلسة مفقودة أو منتهية الصلاحية؛ بدلاً من ذلك تقارير `logged_in:false`، لذا يمكن للوكيل اختبار حالة المصادقة بأمان. (لا يزال يمكن أن يخرج بقيمة غير صفرية إذا لم تكن هناك عنوان URL أساسي محدد أو كانت لوحة التحكم غير قابلة للوصول.) +`whoami` لا يخطئ أبدًا على جلسة مفقودة أو منتهية الصلاحية؛ بدلاً من ذلك يبلّغ عن `logged_in:false`، لذا يمكن للوكيل أن يفحص حالة المصادقة بأمان. (لا يزال يمكنه الخروج برمز غير صفري إذا لم يتم تعيين عنوان URL أساسي أو كانت لوحة التحكم غير قابلة للوصول.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -31,105 +31,105 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## ابحث عن الجلسات الفاشلة أو منخفضة الدرجات +## ابحث عن الجلسات التي تفشل أو ذات الدرجات المنخفضة ```bash -# جلسات في آخر 24 ساعة حيث فشل التقييم +# الجلسات في آخر 24h التي فشل تقييمها agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# تقييمات بدرجة <= 0.5 في المساعدة، لوكيل واحد +# التقييمات التي تسجل ≤ 0.5 على المساعدة، لوكيل واحد agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -تصفية الدرجات موجودة في **`evals`**، وليس `sessions`. `--score KEY:MIN..MAX` قابلة للتكرار ويتم دمجها بـ AND؛ أي حد اختياري (`..0.5` يعني ≤ 0.5، `0.9..` يعني ≥ 0.9). يمكنك تمرير ما يصل إلى 20 مرشح درجة لكل طلب؛ المزيد يرجع HTTP 400. يشارك `sessions` المرشحات `--env`، `--status`، `--agent-id`، `--session-id`، ونطاق الوقت مع `evals`، لكن لا يوجد `--score`. +يعيش تصفية الدرجات على **`evals`**، وليس `sessions`. `--score KEY:MIN..MAX` قابل للتكرار ويتم دمجه مع AND؛ كلا الحدين اختياري (`..0.5` يعني ≤ 0.5، `0.9..` يعني ≥ 0.9). يمكنك تمرير ما يصل إلى 20 مرشح درجة لكل طلب؛ المزيد يعيد HTTP 400. `sessions` يشارك مرشحات `--env`, `--status`, `--agent-id`, `--session-id` ونطاق الوقت مع `evals`، لكنه لا يحتوي على `--score`. -## اقرأ جلسة واحدة من البداية إلى النهاية +## اقرأ جلسة واحدة من البداية للنهاية -لا يوجد أمر `session show` واحد — ادمج مسار الحدث مع التقييم الخاص بالجلسة: +لا يوجد أمر واحد `session show` — ادمج مسار الحدث مع تقييم الجلسة: ```bash -# آخر تقييم للجلسة (الحالة والدرجات) +# أحدث تقييم للجلسة (الحالة + الدرجات) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# كل حدث في التشغيل (ارفع --limit لقائمة شاملة) +# كل حدث في المشغل (ارفع --limit للفحص الكامل) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# فقط استدعاءات الأداة في جلسة +# فقط استدعاءات الأدوات في جلسة agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -## جلب كل شيء (الترقيم) +## احصل على كل شيء (الترقيم) -النتائج هي الأحدث أولاً ومرقمة بالمؤشر. +النتائج هي الأحدث أولاً والترقيم بواسطة المؤشر. ```bash -# طلقة واحدة: جلب ما يصل إلى 500 صف في صفحات 200 صف +# لقطة واحدة: احصل على ما يصل إلى 500 صف في صفحات بـ 200 صف agenteye --json events --session-id run-001 --limit 500 --all > events.json -# الترقيم اليدوي: أرجع next_cursor +# الترقيم اليدوي: مرّر next_cursor للخلف page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## قلّل المخرجات باستخدام --fields +## اختصر الإخراج مع --fields -قيّد المفاتيح (في الجدول و `--json`) لتقليل ما يجب على الوكيل قراءته. +قيّد المفاتيح (في الجدول و`--json`) لتقليل ما يجب على الوكيل قراءته. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -أسماء الحقول غير المعروفة يتم رفضها (خروج `2`) مع القائمة الصحيحة، طريقة رخيصة لاكتشاف أسماء الحقول. +أسماء الحقول غير المعروفة يتم رفضها (خروج `2`) مع القائمة الصحيحة، وهي طريقة رخيصة لاكتشاف أسماء الحقول. ## اكتشف قيم المرشح الصحيحة ```bash agenteye --json list envs | jq -r '.values[]' # قيم --env -agenteye --json list tools | jq -r '.values[]' # أسماء الأدوات؛ أيضاً agents، models، event_types، ... +agenteye --json list tools | jq -r '.values[]' # أسماء الأدوات؛ أيضًا وكلاء، نماذج، event_types، إلخ agenteye --json list score_filters | jq -r '.values[]' # KEY الصحيح لـ --score KEY:MIN..MAX ``` ## اختر منظمتك (متعدد المستأجرين) -إذا كنت تنتمي إلى أكثر من منظمة واحدة، اختر المستأجر النشط عند تسجيل الدخول (يتم حفظه): +إذا كنت تنتمي إلى أكثر من منظمة واحدة، اختر المستأجر النشط عند تسجيل الدخول (سيتم حفظه): ```bash agenteye login --org acme --email you@corp.com # عيّن المستأجر في نفس خطوة تسجيل الدخول agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # استبدل لأمر واحد +agenteye --org globex --json sessions --since 24h # اجعله قيد السريان لأمر واحد ``` -تسجيل دخول متعدد المنظمات بدون `--org` يخرج بقيمة غير صفرية ويطبع المنظمات للاختيار منها. +تسجيل دخول متعدد المنظمات بدون `--org` يخرج برمز غير صفري ويطبع المنظمات للاختيار من بينها. -## وفّر مفتاح API لـ SDK/collector +## توفير مفتاح API لـ SDK/المجمِّع ```bash # يتم طباعة السر مرة واحدة فقط — مع --json إنه حقل .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # تدوير؛ agenteye keys disable ci-bot --yes للإلغاء +agenteye keys regenerate ci-bot --yes # دوّر؛ agenteye keys disable ci-bot --yes للإلغاء ``` -## قم بتشغيل استعلام محفوظ أو مخصص +## شغّل استعلامًا محفوظًا أو مخصصًا ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # استعلام محفوظ + موضعي $1 +agenteye --json query run errs --arg prod | jq '.rows' # استعلام محفوظ + وسيط موضعي $1 ``` -## قم بفحص الحادث بشكل غير تفاعلي +## فرز حادثة طارئة بدون تفاعل ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> الطفرات تتجاوز تلقائياً موجز التأكيد الخاص بهم تحت `--json` أو عندما لا يكون stdin TTY، لذا لا يعلق الوكلاء أبداً؛ مرّر `--yes`/`-y` لتجاوزه بشكل صريح في مكان آخر. +> التغييرات تخطي تلقائيًا مطالبة التأكيد الخاصة بها تحت `--json` أو عندما لا تكون stdin TTY، لذا لا تتعلق الوكلاء؛ مرّر `--yes`/`-y` لتخطيها صراحة في مكان آخر. ## معالجة رمز الخروج في سكريبت @@ -144,7 +144,7 @@ case "${code:-0}" in esac ``` -## أشكال مخرجات JSON +## أشكال إخراج JSON | الأمر | stdout JSON (مع `--json`) | |---|---| @@ -155,15 +155,15 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (يتم عرض `key` مرة واحدة) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (يظهر `key` مرة واحدة) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (أي) | كائن المورد، أو `{"deleted": true, "id"}` للحذف | +| إنشاء/تحديث/حذف (أي) | كائن المورد، أو `{"deleted": true, "id"}` للحذف | | فشل (أي، مع `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` على stdout | - كل عنصر **حدث** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. - كل عنصر **تقييم** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. - كل عنصر **جلسة** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -يقبل `--fields` لكل أمر بدقة أسماء حقول عنصره الخاص — تختلف المجموعة بين `sessions` و `evals`، لذا قد يكون الاسم الصحيح لأحدهما مرفوضاً من الآخر. \ No newline at end of file +يقبل `--fields` لكل أمر بالضبط أسماء حقول عنصره الخاص — تختلف المجموعة بين `sessions` و`evals`، لذا قد يتم رفض الاسم الصحيح لأحدهما من قبل الآخر. \ No newline at end of file diff --git a/docs/ar/agenteye/deployment.mdx b/docs/ar/agenteye/deployment.mdx index 3ff58389..585afb96 100644 --- a/docs/ar/agenteye/deployment.mdx +++ b/docs/ar/agenteye/deployment.mdx @@ -1,16 +1,18 @@ --- +--- title: "النشر" -description: "توثيق نشر AgentEye." +description: "وثائق نشر AgentEye." --- -يغطي هذا الدليل نشر خادم AgentEye وعرض لوحة المعلومات في الإنتاج. + +يغطي هذا الدليل نشر خادم AgentEye والقائمة الأمامية في الإنتاج. --- ## نظرة عامة على العمارة ``` - [ AI agent machines ] [ Your infrastructure ] + [ آلات وكيل AI ] [ البنية التحتية الخاصة بك ] Python SDK | writes JSONL +----------------------+ @@ -29,135 +31,134 @@ description: "توثيق نشر AgentEye." +-----------+ ``` -- **Server**: خدمة HTTP بلغة Rust؛ تستقبل دفعات الأحداث، وتكتبها إلى ClickHouse، وتحافظ على الحالة العلائقية في PostgreSQL. -- **Dashboard**: تطبيق Next.js؛ يقرأ ويكتب حصراً عبر API الخادم. -- **agenteye-collector**: مُنتشر على آلات الوكيل، وليس على مضيف الخادم. -- **Postgres 15+**: مطلوب. (تم رفعه من 14 في إصدار متعدد المستأجرين؛ يستخدم مخطط العضوية في المنظمة مفتاح خارجي `ON DELETE SET NULL` بقائمة الأعمدة، وهذا يتطلب Postgres 15+. قم بترقية Postgres قبل نشر هذا الإصدار.) يخزن حالة OLTP: `api_keys`، `users`، `sessions`، `evaluation_jobs` (الطابور)، `dashboards`، `saved_queries`، `otp_codes`، بالإضافة إلى جداول متعددة المستأجرين `orgs`، `org_memberships`، `org_settings`. -- **ClickHouse 24+**: مطلوب. متجر التحليلات لكل حدث مُستقبل. المحرك: `ReplacingMergeTree`، مقسم حسب الشهر، مرتب حسب `(session_id, ts, dedup_key)`. يتصل الخادم عبر `CLICKHOUSE_URL`؛ التكوين الموزع في `deploy/base/clickhouse/` يشحن إعدادات محسنة للأداء لعقدة واحدة. **متطلب متعدد المستأجرين:** يفعّل التكوين الموزع إدارة وصول SQL + `users_without_row_policies_can_read_rows=false` حتى يتمكن الخادم من إنشاء مستخدم ClickHouse واحد للقراءة فقط + سياسة صف واحدة لكل منظمة (حدود العزل المفروضة بواسطة المحرك لمحرر SQL والوكيل الذكي). إذا كنت توفر إعدادات ClickHouse الخاصة بك، فانقل هذه الإعدادات (انظر `deploy/base/clickhouse/configmap.yaml`). -- **Redis 7+**: *اختياري* ذاكرة تخزين مؤقتة مشتركة + خلفية تحديد السعر. يتصل كل من الخادم ولوحة المعلومات عبر `REDIS_URL`. إذا كانت غير موجودة، كلاهما ينحط بأناقة إلى مسارات Postgres فقط. انظر **Redis (ذاكرة تخزين مؤقتة اختيارية)** أدناه. +- **الخادم**: خدمة HTTP بلغة Rust؛ تستقبل دفعات الأحداث وتكتبها إلى ClickHouse وتحافظ على الحالة العلائقية في PostgreSQL. +- **القائمة الأمامية**: تطبيق Next.js؛ تقرأ وتكتب حصريًا من خلال API الخادم. +- **agenteye-collector**: تُنشر على آلات الوكيل وليس على مضيف الخادم. +- **Postgres 15+**: مطلوب. (تم رفعه من 14 في الإصدار متعدد المستأجرين؛ مخطط العضوية في المنظمة يستخدم مفتاحًا أجنبيًا `ON DELETE SET NULL` قائمًا على قائمة الأعمدة، وهو مطلوب في Postgres 15+. قم بترقية Postgres قبل نشر هذا الإصدار.) يخزن حالة OLTP: `api_keys`، `users`، `sessions`، `evaluation_jobs` (الطابور)، `dashboards`، `saved_queries`، `otp_codes`، بالإضافة إلى جداول متعددة المستأجرين `orgs`، `org_memberships`، `org_settings`. +- **ClickHouse 24+**: مطلوب. مخزن التحليلات لكل حدث مُدخَل. محرك: `ReplacingMergeTree`، مقسم حسب الشهر، مرتب حسب `(session_id, ts, dedup_key)`. يتصل الخادم عبر `CLICKHOUSE_URL`؛ تتضمن الحزمة المجمعة `deploy/base/clickhouse/` تكوينًا أحادي العقدة محسّنًا للأداء. **متطلب متعدد المستأجرين:** يفعّل التكوين المجمع إدارة الوصول إلى SQL + `users_without_row_policies_can_read_rows=false` بحيث يمكن للخادم إنشاء مستخدم ClickHouse للقراءة فقط + سياسة صف واحدة لكل منظمة (حد العزل الذي يفرضه المحرك للمحرر الخاص بـ SQL والوكيل الذكي). إذا قدمت تكوين ClickHouse الخاص بك، فنقل هذه الإعدادات (انظر `deploy/base/clickhouse/configmap.yaml`). +- **Redis 7+**: *اختياري* ذاكرة تخزين مؤقت مشتركة + خادم حد المعدل. يتصل الخادم والقائمة الأمامية عبر `REDIS_URL`. إذا كان غير موجود، يتدهور كلاهما برفق إلى مسارات Postgres فقط. انظر **Redis (ذاكرة تخزين مؤقت اختيارية)** أدناه. --- ## الخادم -### استحضار الصورة +### سحب الصورة ```bash echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> الإصدارات الحالية تنشر تحت `beta-latest`؛ `latest` يُسند فقط للإصدارات المستقرة. للإنتاج، ثبّت وسم `:v` محدد؛ انظر [علامات الصور المتاحة](#available-image-tags). +> الإصدارات الحالية تُنشر تحت `beta-latest`؛ يتم تعيين `latest` فقط للإصدارات المستقرة. للإنتاج، ثبّت علامة إصدار محددة `:v`؛ انظر [علامات الصور المتاحة](#available-image-tags). ### متغيرات البيئة -| المتغير | مطلوب | الافتراضي | الوصف | +| المتغير | مطلوب | القيمة الافتراضية | الوصف | |---|---|---|---| -| `DATABASE_URL` | نعم | لا شيء | Postgres DSN. سلسلة اتصال libpq قياسية بصيغة `postgres://`. تدعم `?sslmode=require` ومعاملات libpq الأخرى. يجب ألا تحتوي كلمة المرور على `/`، `+`، أو `=`؛ استخدم `openssl rand -hex` لإنشاء كلمات مرور آمنة للـ URL. | -| `ADMIN_KEY` | لا | لا شيء | مفتاح API للإدارة التمهيدي. تم إدراجه مع جميع الأذونات عند كل بدء تشغيل. قم بالتدوير بتغيير القيمة وإعادة التشغيل. | +| `DATABASE_URL` | نعم | بلا | DSN خاص بـ Postgres. سلسلة اتصال libpq قياسية بصيغة `postgres://`. يدعم `?sslmode=require` ومعاملات libpq الأخرى. لا يجب أن تحتوي كلمة المرور على `/` أو `+` أو `=`؛ استخدم `openssl rand -hex` لإنشاء كلمات مرور آمنة للعناوين. | +| `ADMIN_KEY` | لا | بلا | مفتاح API الإدارة التمهيدي. يتم الترقية أو الإدراج مع جميع الأذونات عند كل بدء تشغيل. أدر دوريًا بتغيير القيمة وإعادة التشغيل. | | `LISTEN_ADDR` | لا | `0.0.0.0:8080` | عنوان TCP للربط | -| `MAX_BODY_BYTES` | لا | `134217728` (128 MB) | حد أقصى لحجم جسم الطلب | -| `ADMIN_EMAIL` | لا | لا شيء | بريد المسؤول التمهيدي. تم إدراجه مع جميع الأذونات عند كل بدء تشغيل وتم وضع علامة محمية: لا يمكن تعطيله أو تعديل أذوناته عبر لوحة المعلومات/API. لتدوير المسؤول التمهيدي، غيّر `ADMIN_EMAIL` وأعد التشغيل؛ يتم إدراج البريد الجديد كمحمي، والبريد السابق يحتفظ بحمايته حتى يتم حذفها يدويًا في قاعدة البيانات. | -| `ALLOWED_EMAILS` | لا | لا شيء (الكل محظور) | قائمة مفصولة بفواصل من رسائل البريد الإلكتروني المسموحة لإنشاء المستخدمين والدخول. يدعم عناوين دقيقة (`user@example.com`) والنطاقات الموسعة (`*@example.com`). إذا لم يتم التعيين، لا يمكن لأي مستخدمين الإنشاء أو تسجيل الدخول. **بذرة الإقلاع الأولى فقط**: تزرع قائمة منع النطاق الافتراضي للمنظمة عند الإقلاع الأول؛ بعد ذلك تكون صفحة [`//settings`](#operational-settings) لكل منظمة هي مصدر الحقيقة وتغيير متغير env هذا لا يترتب عليه تأثير. | -| `SMTP_HOST` | لا | لا شيء | اسم مضيف خادم SMTP لإرسال رسائل بريد OTP. إذا لم يتم التعيين، يتم تسجيل رموز OTP إلى stdout بدلاً من ذلك. | +| `MAX_BODY_BYTES` | لا | `134217728` (128 MB) | حد أقصى لحجم طلب الجسم | +| `ADMIN_EMAIL` | لا | بلا | البريد الإلكتروني لمستخدم الإدارة التمهيدي. يتم الترقية أو الإدراج مع جميع الأذونات عند كل بدء تشغيل ويتم وضع علامة محمية: لا يمكن تعطيله أو تعديل أذوناته عبر لوحة التحكم/API. لتدوير إدارة التمهيد، غيّر `ADMIN_EMAIL` وأعد التشغيل؛ يتم ترقية البريد الإلكتروني الجديد كمحمي، والبريد الإلكتروني السابق يحتفظ بحمايته حتى يتم مسحه يدويًا في قاعدة البيانات. | +| `ALLOWED_EMAILS` | لا | بلا (الكل محظور) | قائمة بفواصل منفصلة بالبريد الإلكتروني المسموح به لإنشاء المستخدم وتسجيل الدخول. يدعم العناوين الدقيقة (`user@example.com`) ومتغيرات النطاق (`*@example.com`). إذا لم يتم التعيين، لا يمكن لأي مستخدم أن ينشئ حسابًا أو يسجل دخول. **بذر التمهيد الأول فقط**: يبذر قائمة المنظمة الافتراضية المسموح بها عند التمهيد الأول؛ بعد ذلك صفحة `//settings` الخاصة بكل منظمة هي مصدر الحقيقة وتغيير متغير البيئة هذا ليس له تأثير. | +| `SMTP_HOST` | لا | بلا | اسم مضيف خادم SMTP لإرسال رسائل بريد إلكتروني OTP. إذا لم يتم التعيين، يتم تسجيل رموز OTP في stdout بدلاً من ذلك. | | `SMTP_PORT` | لا | `587` | منفذ خادم SMTP | -| `SMTP_USERNAME` | لا | لا شيء | اسم المستخدم للمصادقة على SMTP | -| `SMTP_PASSWORD` | لا | لا شيء | كلمة مرور المصادقة على SMTP | -| `SMTP_FROM` | لا | لا شيء | عنوان البريد الإلكتروني للمرسل لرسائل OTP | -| `SMTP_TLS` | لا | STARTTLS | يُستخدم STARTTLS إلا إذا قمت بإيقافه صراحة: `false` أو `0` يرسل نص عادي (بدون TLS)؛ أي قيمة أخرى — بما في ذلك الإيقاف — تفعّل STARTTLS. | -| `DASHBOARD_URL` | لا | افتراضي مدمج | أصل لوحة المعلومات المستخدم لإنشاء كل من رابط الرسالة السحري للـ OTP وروابط الحوادث السحرية في إخطارات التنبيهات. إذا لم يتم التعيين، يعود إلى افتراضي مدمج (وللـ OTP فقط، إلى أصل مشتق من لوحة المعلومات أولاً). عيّن هذا للإعدادات المقسمة بين النطاقات بحيث تشير كل من رسائل البريد وروابط Slack/الحادث إلى لوحة المعلومات الخاصة بك. انظر **URL رابط البريد السحري** أدناه؛ معظم المشغلين لا يحتاجون إلى تعيين هذا. | -| `SESSION_TTL_SECS` | لا | `86400` (24 h) | مدة جلسة لوحة المعلومات بالثواني. **بذرة الإقلاع الأولى فقط**: عدّل لكل منظمة عبر [`//settings`](#operational-settings) بعد النشر الأول. | -| `OTP_TTL_SECS` | لا | `600` (10 min) | فترة صلاحية رمز OTP بالثواني. **بذرة الإقلاع الأولى فقط**: عدّل لكل منظمة عبر [`//settings`](#operational-settings) بعد النشر الأول. | -| `REDIS_URL` | لا | لا شيء | خلفية اختيارية لذاكرة التخزين المؤقتة المشتركة + تحديد السعر، مثل `redis://redis:6379/0`. عند التعيين، يخزن الخادم عمليات البحث عن المفاتيح المصادقة، و`/models` الكلي لوحة المعلومات، قائمة الجلسات، وجوانب قائمة env؛ كما يحرك حد معدل طلب OTP من PostgreSQL COUNT وإلى Redis INCR. إذا لم يتم التعيين أو غير قابل للوصول، يعمل الخادم بدون الذاكرة المؤقتة (ينخفض حد OTP إلى Postgres، كل نداء ذاكرة تخزين مؤقتة أخرى ينخفض إلى مصدر الحقيقة). انظر **Redis (ذاكرة تخزين مؤقتة اختيارية)** أدناه. | -| `CLICKHOUSE_URL` | **نعم** | لا شيء | URL الأساسي لمثيل ClickHouse، مثل `http://clickhouse:8123`. يطبق الخادم مخطط الأحداث الخاص به على هذه قاعدة البيانات عند كل بدء تشغيل ويرفض الإقلاع إذا لم يتمكن من الوصول إلى ClickHouse. انظر **ClickHouse (متجر التحليلات المطلوب)** أدناه. | -| `CLICKHOUSE_DATABASE` | لا | `agenteye` | اسم قاعدة بيانات ClickHouse (المخطط). ينشئه الخادم عند بدء التشغيل إذا لم يكن موجوداً. | -| `ORG_CH_SECRET` | لا (أحادي المستأجر) / **نعم (متعدد المنظمات)** | افتراضي تطوير | مفتاح HMAC الذي يُستخرج منه كلمة مرور ClickHouse الفريدة لكل منظمة لكل مستأجر. يقوم محرر SQL والوكيل الذكي `run_query` بالتنفيذ كمستخدم ClickHouse الخاص بالمنظمة وقراءة فقط، حيث تفرض سياسة الصف عزل المستأجرين في المحرك. تُقلع عمليات النشر أحادية المستأجر بشكل جيد على الافتراضي المدمج للتطوير؛ **قبل حالة الحصول على منظمة ثانية يجب عليك تعيين قيمة قوية وثابتة**، لأن CLI `agenteye-orgctl org create` يرفض التشغيل على الافتراضي المدمج للتطوير. يؤدي تدويره إلى دون نسب كل مستخدم ClickHouse للمنظمة حتى إعادة التشغيل التالية تعيدها (تشفي المصالحة في وقت الإقلاع هذا تلقائياً). احفظه سراً وبدون تغيير عبر النسخ. يتم الحصول على المنظمات نفسها من قِبل المشغل فقط؛ انظر **المنظمات (تعدد المستأجرين)** أدناه. | -| `DEFAULT_ORG_NAME` | لا | `Default` | اسم العرض المزروع للمنظمة الافتراضية المدمجة. **بذرة الإقلاع الأولى فقط**، وفقط أثناء احتفاظ المنظمة بهويتها العامة المنقولة حديثاً، يتم تطبيقها عند بدء التشغيل، ثم تُتجاهل. بمجرد إعادة تسمية المنظمة (`agenteye-orgctl org rename`) تصبح إعادة التسمية موثوقة وهذا متغير env لا يترتب عليه تأثير آخر. | -| `DEFAULT_ORG_SLUG` | لا | `default` | عنوان URL للمنظمة الافتراضية المدمجة، مسار لوحة المعلومات التي تعيش فيه (`//…`). نفس بذرة الإقلاع الأولى فقط / بكر فقط الدلالات كما `DEFAULT_ORG_NAME`. يجب أن يكون 1-40 أبجديات صغيرة مع شرطات داخلية واحدة وليس [كلمة محفوظة](#organizations-multi-tenancy)؛ يتم تجاهل القيمة غير الصالحة (تحتفظ المنظمة بـ `default`). يسمح لتثبيت أحادي المستأجر بالعرض كـ `/acme` بدلاً من `/default` بدون أي خطوة CLI بعد النشر. | -| `RUST_LOG` | لا | `info` | طراز السجلات (`debug`, `warn`, `error`, `agenteye_server=trace`) | -| `EVALUATOR_ENDPOINT` | لا | لا شيء | URL الأساسي لخدمة المُقيّم الخاصة بك (مثل `http://evaluator:9000`). عند الإيقاف، يكون خط أنابيب التقييم بالكامل بدون عملية؛ لا يتم كتابة صفوف الطابور، لا يتم تشغيل العمال. انظر [أداة التقييم](/ar/agenteye/evaluation-suite). | -| `EVALUATOR_TOKEN` | لا | لا شيء | يُرسل كـ `Authorization: Bearer ` إلى المُقيّم. **يجب أن يساوي نفس القيمة التي يتم تكوين خدمة المُقيّم بها.** اختياري فقط إذا تم تكوين المُقيّم بدون رمز. | -| `EVALUATOR_WORKERS` | لا | `2` | التزامن: عدد مهام العمال لكل مثيل خادم تُرسل التقييمات. آمن للتشغيل عبر عدة خوادم مقسمة بشكل أفقي. | -| `EVALUATOR_CLAIM_BATCH` | لا | `4` | الحد الأقصى لعدد التقييمات التي يطالب بها عامل واحد لكل علامة. يتم إرسال الدفعات **بشكل متزامن**، لذا فإن التزامن الكلي على نقطة نهاية المُقيّم الخاصة بك هو `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | لا | `2` | المدة التي ينام فيها العامل بين محاولات الإرسال عندما لا يكون هناك شيء مستحق. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | لا | `10` | آخر خط احتياطي لـ (ثواني) لـ `GET /evaluate/{id}` استطلاعات عندما لا يُرجع المُقيّم `next_poll_secs` لكل استجابة ولا يعلن `default_poll_interval_secs` من `GET /config`. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | لا | `30000` | حد انتظار لكل طلب HTTP ضد المُقيّم (ميلي ثانية). | -| `EVALUATOR_MAX_ATTEMPTS` | لا | `5` | بعد هذا العدد من محاولات الفشل يتم تسجيل التقييم كنهاية `error` (أو `timeout` إذا كانت الأعطال استجابات انتظار). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | لا | `300` (5 min) | عدد مرات إعادة جلب `GET /config` الخادم من المُقيّم. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | لا | `3600` (1 h) | الحد الأقصى لوقت ساعة الحائط قد تبقى الجلسة في طابور الاستطلاع قبل أن تنهيها AgentEye كـ `timeout`. الحراسة ضد مُقيّم يعود `pending` إلى الأبد. | -| `ALERT_WORKERS` | لا | `1` | التزامن: عدد مهام العمال لكل مثيل خادم التي تقيّم قواعد التنبيهات. انظر [التنبيهات](/ar/agenteye/alerts). | -| `ALERT_CLAIM_BATCH` | لا | `16` | الحد الأقصى لعدد التنبيهات التي يطالب بها عامل واحد لكل علامة. | -| `ALERT_POLL_IDLE_SECS` | لا | `5` | المدة التي ينام فيها عامل التنبيهات عندما يكون الطابور فارغاً. | -| `ALERT_REQUEST_TIMEOUT_MS` | لا | `15000` | مهلة قيمة تقييم لكل زناد (استعلامات ClickHouse + HTTP المسار الخارجي). | -| `ALERT_MAX_ATTEMPTS` | لا | `5` | أعطال عابرة متتالية قبل إعادة جدولة التنبيه في خطته العادية بدلاً من التراجع الأسي. | -| `AUDIT_WORKERS` | لا | `1` | التزامن: عدد مهام العمال لكل مثيل خادم التي تنفذ المراجعات. انظر [المراجعات](/ar/agenteye/audits). | -| `AUDIT_CLAIM_BATCH` | لا | `1` | الحد الأقصى لعدد المراجعات المستحقة التي يطالب بها عامل واحد لكل علامة. التحقيق الوكالي هو حلقة طويلة واحدة، لذا الافتراضي هو 1. | -| `AUDIT_POLL_IDLE_SECS` | لا | `30` | المدة التي ينام فيها عامل المراجعات عندما لا تكون هناك مراجعة مستحقة. | -| `AUDIT_REQUEST_TIMEOUT_MS` | لا | `30000` | مهلة الاستعلام لكل سياسة ضد ClickHouse (ميلي ثانية). | -| `AUDIT_LLM_TIMEOUT_MS` | لا | `1440000` | انتظر استدعاء التحقيق الوكالي لخدمة المساعد الذكي. حلقة عامل كاملة تعمل لدقائق؛ احفظها فوق خاص الوكيل `AGENTEYE_AUDIT_TIMEOUT_MS` بحيث يعود الوكيل بنتائجه الجزئية قبل استسلام الخادم. | -| `AUDIT_MAX_ATTEMPTS` | لا | `5` | أعطال عابرة متتالية قبل إعادة جدولة المراجعة في خطتها العادية بدلاً من التراجع الأسي. | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | لا | — | يستدعي التحقيق الوكالي للمراجعة خدمة المساعد الذكي `agent`، **إعادة استخدام نفس الاتصال مثل المساعد** — لذا عيّن هذان أيضاً على **الخادم** (يفعل البيانات الموزعة/compose). كلاهما يُعيّن ⇒ تُجري المراجعات التحقيق الذكي؛ إما إيقاف ⇒ تُجري المراجعات **سياسة فقط** (يعمل اجتياز السياسة SQL الحتمية)، بغض النظر عن علم العزل `llm_enabled` لكل مراجعة. يجب أن يحتوي الوكيل أيضاً على LLM محكمة — انظر [assistant.md](/ar/agenteye/assistant). | - -**خدمة المساعد الذكي — تدقيق + إعدادات الحماية.** التحقيق الوكالي وحماية Python في الكبسولة محكمة على **خدمة الوكيل** (وليس الخادم)، جميعها على بادئة `AGENTEYE_AUDIT_*` وكلها اختيارية: +| `SMTP_USERNAME` | لا | بلا | اسم مستخدم مصادقة SMTP | +| `SMTP_PASSWORD` | لا | بلا | كلمة مرور مصادقة SMTP | +| `SMTP_FROM` | لا | بلا | عنوان البريد الإلكتروني للمرسل لرسائل بريد إلكتروني OTP | +| `SMTP_TLS` | لا | STARTTLS | يتم استخدام STARTTLS ما لم تقم بإيقافه بشكل صريح: `false` أو `0` يرسل نصًا عاديًا (بدون TLS)؛ أي قيمة أخرى — بما في ذلك عدم التعيين — تفعّل STARTTLS. | +| `DASHBOARD_URL` | لا | القيمة الافتراضية المدمجة | أصل القائمة الأمامية المستخدم لإنشاء كل من ارتباط السحر في رسالة البريد الإلكتروني OTP وارتباطات السحر للحادث في إخطارات التنبيه. إذا لم يتم التعيين، فسيعود إلى قيمة افتراضية مدمجة (وبالنسبة إلى OTP فقط، إلى أصل الطلب المشتق من لوحة التحكم أولاً). اضبط هذا للإعدادات المقسومة حسب النطاق بحيث يشير كل من البريد الإلكتروني وارتباطات Slack/الحادث إلى لوحة التحكم الخاصة بك. انظر **عنوان URL لارتباط السحر في البريد الإلكتروني** أدناه؛ معظم المشغلين لا يحتاجون إلى تعيين هذا. | +| `SESSION_TTL_SECS` | لا | `86400` (24 ساعة) | مدة جلسة لوحة التحكم بالثواني. **بذر التمهيد الأول فقط**: عدّل لكل منظمة عبر [`//settings`](#operational-settings) بعد النشر الأول. | +| `OTP_TTL_SECS` | لا | `600` (10 دقائق) | فترة صلاحية رمز OTP بالثواني. **بذر التمهيد الأول فقط**: عدّل لكل منظمة عبر [`//settings`](#operational-settings) بعد النشر الأول. | +| `REDIS_URL` | لا | بلا | ذاكرة تخزين مؤقت مشتركة اختيارية + خادم حد معدل، مثل `redis://redis:6379/0`. عند التعيين، يخزن الخادم عمليات البحث عن مفتاح API المصرح، وإجمالي `/models` القائمة الأمامية، وقائمة الجلسات، وجوانب قائمة البيئة؛ كما أنه ينقل حد معدل طلب OTP من Postgres COUNT إلى Redis INCR. إذا لم يتم التعيين أو لم يكن قابلاً للوصول إليه، يعمل الخادم بدون ذاكرة التخزين المؤقت (حد OTP ينخفض إلى Postgres، وكل نداء ذاكرة تخزين مؤقت آخر ينخفض إلى مصدر الحقيقة). انظر **Redis (ذاكرة تخزين مؤقت اختيارية)** أدناه. | +| `CLICKHOUSE_URL` | **نعم** | بلا | عنوان URL الأساسي لمثيل ClickHouse، مثل `http://clickhouse:8123`. يطبق الخادم مخطط الأحداث الخاص به على قاعدة البيانات هذه عند كل بدء تشغيل ويرفض التمهيد إذا لم يتمكن من الوصول إلى ClickHouse. انظر **ClickHouse (مخزن التحليلات المطلوب)** أدناه. | +| `CLICKHOUSE_DATABASE` | لا | `agenteye` | اسم قاعدة بيانات ClickHouse (المخطط). ينشئها الخادم عند بدء التشغيل إذا لم تكن موجودة. | +| `ORG_CH_SECRET` | لا (أحادي المستأجر) / **نعم (متعدد المنظمات)** | افتراضي للتطوير | مفتاح HMAC الذي يشتق منه كلمة مرور ClickHouse الخاصة بكل منظمة. يقوم محرر SQL والوكيل الذكي `run_query` بالتنفيذ كمستخدم ClickHouse للقراءة فقط الخاص بالمنظمة، وتفرض سياسة الصف الخاصة به عزل المستأجرين في المحرك. تعمل النشرات أحادية المستأجر بشكل جيد على الافتراضي المدمج للتطوير؛ **قبل توفير منظمة ثانية يجب عليك تعيين قيمة قوية ومستقرة**، لأن CLI `agenteye-orgctl org create` يرفض الركض على الافتراضي المدمج للتطوير. يؤدي تدويره إلى حذف مستخدم ClickHouse الخاص بكل منظمة حتى إعادة المزامنة التالية عند بدء التشغيل (يشفي المصالحة في وقت التمهيد هذا تلقائيًا). ابقِ محافظًا على سريته وبدون تغيير عبر النسخ المتماثلة. توفير المنظمات نفسه خاص بالمشغل فقط؛ انظر **المنظمات (تعدد المستأجرين)** أدناه. | +| `DEFAULT_ORG_NAME` | لا | `Default` | اسم العرض المبذور للمنظمة الافتراضية المدمجة. **بذر التمهيد الأول فقط** و**فقط بينما تحمل المنظمة هويتها العامة المنقولة حديثًا**، تم التطبيق عند بدء التشغيل، ثم يتم تجاهله. بمجرد إعادة تسمية المنظمة (`agenteye-orgctl org rename`) تصبح إعادة التسمية موثوقة ولا يكون لمتغير البيئة هذا تأثير آخر. | +| `DEFAULT_ORG_SLUG` | لا | `default` | عنوان URL slug للمنظمة الافتراضية المدمجة، مسار لوحة التحكم الذي تعيش فيه (`//…`). نفس دلالات بذر التمهيد الأول / البذور فقط كما هو الحال مع `DEFAULT_ORG_NAME`. يجب أن يكون 1-40 أحرفًا صغيرة وأرقامًا مع واصلات داخلية واحدة وليس كلمة [محجوزة](#organizations-multi-tenancy)؛ تُتجاهل القيمة غير الصالحة (تحتفظ المنظمة بـ `default`). يسمح لتثبيت أحادي المستأجر بالعرض بـ `/acme` بدلاً من `/default` دون أي خطوة CLI بعد النشر. | +| `RUST_LOG` | لا | `info` | تفاصيل السجل (`debug`، `warn`، `error`، `agenteye_server=trace`) | +| `EVALUATOR_ENDPOINT` | لا | بلا | عنوان URL الأساسي لخدمة المقيّم الخاصة بك (مثل `http://evaluator:9000`). عند عدم التعيين، تكون خط أنابيب التقييم بأكمله نو-أوب؛ لا يتم كتابة صفوف الطابور، ولا يعمل أي عمال. انظر [مجموعة التقييم](/ar/agenteye/evaluation-suite). | +| `EVALUATOR_TOKEN` | لا | بلا | مرسل كـ `Authorization: Bearer ` إلى المقيّم. **يجب أن يساوي نفس القيمة التي تم تكوين خدمة المقيّم بها.** اختياري فقط إذا تم تكوين المقيّم الخاص بك بدون توكن. | +| `EVALUATOR_WORKERS` | لا | `2` | التزامن: عدد مهام العمل لكل مثيل خادم تُرسل التقييمات. آمن للتشغيل عبر عدة خوادم مدرجة أفقيًا. | +| `EVALUATOR_CLAIM_BATCH` | لا | `4` | الحد الأقصى لعدد التقييمات التي يطالب بها عامل واحد لكل تكة. يتم إرسال الدفعات **بشكل متزامن**، لذا فإن إجمالي التزامن على نقطة نهاية المقيّم الخاصة بك هو `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | لا | `2` | مدة نوم العامل بين محاولات الإرسال عندما لا يكون شيء مستحقًا. | +| `EVALUATOR_POLLING_INTERVAL_SECS` | لا | `10` | آلية الاستقصاء النهائية (الثواني) لـ `GET /evaluate/{id}` عندما لا يُرجع المقيّم `next_poll_secs` لكل استجابة ولا يعلن `default_poll_interval_secs` من `GET /config`. | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | لا | `30000` | انتظار HTTP لكل طلب ضد المقيّم (بالميلي ثانية). | +| `EVALUATOR_MAX_ATTEMPTS` | لا | `5` | بعد هذا العدد من المحاولات الفاشلة يتم تسجيل التقييم كخطأ نهائي `error` (أو `timeout` إذا كانت الإخفاقات طلبات المهلة الزمنية). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | لا | `300` (5 دقائق) | بأي تكرار يعيد الخادم جلب `GET /config` من المقيّم. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | لا | `3600` (ساعة واحدة) | الحد الأقصى لوقت الجدار الذي قد تبقى فيه جلسة واحدة في طابور الاستقصاء قبل أن ينهيها AgentEye كـ `timeout`. حماية ضد مقيّم يعود `pending` للأبد. | +| `ALERT_WORKERS` | لا | `1` | التزامن: عدد مهام العمل لكل مثيل خادم التي تقيّم قواعد التنبيه. انظر [التنبيهات](/ar/agenteye/alerts). | +| `ALERT_CLAIM_BATCH` | لا | `16` | الحد الأقصى لعدد التنبيهات التي يطالب بها عامل واحد لكل تكة. | +| `ALERT_POLL_IDLE_SECS` | لا | `5` | مدة نوم عامل التنبيهات عندما يكون الطابور فارغًا. | +| `ALERT_REQUEST_TIMEOUT_MS` | لا | `15000` | انتظار لكل تقييم محفز (استعلامات ClickHouse + HTTP قنوات صادرة). | +| `ALERT_MAX_ATTEMPTS` | لا | `5` | إخفاقات عابرة متتالية قبل أن يُعاد جدولة التنبيه بالتكرار الطبيعي بدلاً من التراجع الأسي. | +| `AUDIT_WORKERS` | لا | `1` | التزامن: عدد مهام العمل لكل مثيل خادم التي تنفذ التدقيقات. انظر [التدقيقات](/ar/agenteye/audits). | +| `AUDIT_CLAIM_BATCH` | لا | `1` | الحد الأقصى لعدد التدقيقات المستحقة التي يطالب بها عامل واحد لكل تكة. التحقيق الاستشعاري الواحد هو حلقة طويلة واحدة، لذا الافتراضي هو 1. | +| `AUDIT_POLL_IDLE_SECS` | لا | `30` | مدة نوم عامل التدقيق عندما لا يكون أي تدقيق مستحقًا. | +| `AUDIT_REQUEST_TIMEOUT_MS` | لا | `30000` | انتظار لكل استعلام سياسة ضد ClickHouse (بالميلي ثانية). | +| `AUDIT_LLM_TIMEOUT_MS` | لا | `1440000` | المهلة الزمنية لاستدعاء التحقيق الاستشعاري لخدمة مساعد AI. تعمل حلقة عميل كاملة لعدة دقائق؛ ابقِ هذا فوق `AGENTEYE_AUDIT_TIMEOUT_MS` الخاص بالعميل بحيث يعود العميل بنتائجه الجزئية قبل أن يستسلم الخادم. | +| `AUDIT_MAX_ATTEMPTS` | لا | `5` | إخفاقات عابرة متتالية قبل أن يُعاد جدولة التدقيق بالتكرار الطبيعي بدلاً من التراجع الأسي. | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | لا | — | يستدعي التحقيق الاستشعاري خدمة المساعد الذكي `agent`، **معاد استخدام نفس الاتصال مع المساعد** — لذا اضبط هذين على **الخادم** أيضًا (تفعل المظاهر/الحزم المجمعة). كلاهما مضبوط ⇒ تعمل التدقيقات على التحقيق الذكي؛ أي واحد غير مضبوط ⇒ تعمل التدقيقات **سياسة فقط** (تمر السياسة SQL الحتمية لا تزال تعمل)، بغض النظر عن علم `llm_enabled` لكل تدقيق. يجب أن يكون لدى العميل أيضًا نموذج لغة مُعد — انظر [assistant.md](/ar/agenteye/assistant). | + +**خدمة مساعد AI — إعدادات التدقيق والصندوق الرملي.** يتم ضبط التحقيق الاستشعاري والصندوق الرملي الخاص به داخل القرية على **خدمة العميل** (وليس الخادم)، الكل على بادئة `AGENTEYE_AUDIT_*` وكل اختياري: | المتغير | الافتراضي | المعنى | |---|---|---| -| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | الحد الأقصى لأدوار الوكيل لكل تحقيق. | -| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | الوقت الفعلي لتحقيق واحد (20 دقيقة). يجب أن يبقى **أقل من** `AUDIT_LLM_TIMEOUT_MS` الخادم. | -| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | تحقيقات متزامنة لكل كبسولة وكيل (منفصلة عن ميزانية مساعد الدردشة). | -| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | حدود لكل سكريبت لسجن bubblewrap. | +| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | أقصى أدوار عميل لكل تحقيق. | +| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | جدار الساعة لتحقيق واحد (20 دقيقة). يجب أن يبقى **تحت** `AUDIT_LLM_TIMEOUT_MS` الخاص بالخادم. | +| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | تحقيقات متزامنة لكل وحدة عميل (منفصلة عن ميزانية مساعد الدردشة). | +| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | حدود لكل برنامج نصي للصندوق الرملي bubblewrap. | -**متطلب منصة الحماية.** يقوم رمز حماية المراجعة بتشغيل Python النموذج داخل سجن bubblewrap، والذي يحتاج إلى **مساحات أسماء مستخدمين بلا امتيازات**. يجب أن تسمح كبسولة الوكيل بأعلام `clone()` — عيّن `seccompProfile: Unconfined` (k8s) أو `security_opt: [seccomp:unconfined]` (compose) على الوكيل. حيث يعطّل نواة العقدة مساحات الأسماء غير المتمتعة بامتيازات (مثل بعض صور GKE COS)، فشل الفحص المسبق للحماية **والمدقق ينحط إلى SQL فقط تلقائياً** — لا خطأ، فقط `sandbox_available: false` على صحة الوكيل `/health`. +**متطلب منصة الصندوق الرملي.** يعمل صندوق الرملي الخاص بتدقيق الكود من خلال Python النموذج داخل سجن bubblewrap، والذي يحتاج إلى **مسافات أسماء المستخدم غير المتميزة**. يجب أن تسمح وحدة العميل بعلامات `clone()` — اضبط `seccompProfile: Unconfined` (k8s) أو `security_opt: [seccomp:unconfined]` (compose) على العميل. حيث يعطّل نواة العقدة مسافات الأسماء غير المتميزة (مثل بعض صور COS في GKE)، فإن **الفحص المسبق للصندوق الرملي يفشل والمدقّق ينحط إلى SQL فقط تلقائيًا** — لا خطأ، فقط `sandbox_available: false` على `/health` الخاص بالعميل. -### تشغيل +### التشغيل -عيّن `DATABASE_URL` و `CLICKHOUSE_URL` في بيئتك (يرفض الخادم الإقلاع بدون ClickHouse)، ثم مررها إلى الكنتاينر: +اضبط `DATABASE_URL` في بيئتك، ثم مرره عبر الحاوية: ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest ``` -يقوم الخادم بتشغيل هجرات قاعدة البيانات تلقائياً عند بدء التشغيل؛ لا حاجة لخطوة هجرة منفصلة. +يقوم الخادم بتشغيل هجرات قاعدة البيانات تلقائيًا عند بدء التشغيل؛ لا توجد خطوة هجرة منفصلة مطلوبة. ### فحص الصحة ``` -GET /health # liveness - always {"status":"ok"} once the process is up -GET /ready # readiness - 200 when Postgres + ClickHouse are reachable, else 503 +GET /health # liveness - دائمًا {"status":"ok"} بمجرد أن تكون العملية مرفوعة +GET /ready # readiness - 200 عندما يكون Postgres + ClickHouse قابلين للوصول، وإلا 503 ``` -لا توثيق مطلوب. استخدم `/health` لمسابير **liveness** و `/ready` لمسابير **readiness** / load-balancer. `/ready` تفحص المتطلبات الثابتة التي لا يمكن للخادم الخدمة بدونها (Postgres + ClickHouse)، لذا خادم يعمل لكن لا يمكنه الوصول إلى قاعدة بيانته يُؤخذ من الدوران ويظهر كـ `NotReady`؛ يتم الإبلاغ عن Redis لكنه لا يفشل القابلية للجاهزية أبداً. على بيانات Kubernetes الموزعة مسبار الجاهزية موجود بالفعل عند `/ready` ويبقى liveness في `/health`. انظر [enterprise-docs/health-monitoring.md](/ar/agenteye/health-monitoring) للصورة الكاملة، بما في ذلك التنبيهات الاختيارية المدمجة بـ Kubernetes لفشل الكبسولة إلى Slack. +لا يوجد مصادقة مطلوبة. استخدم `/health` لمسابر **liveness** و `/ready` لمسابر **readiness** / موازن التحميل. يتحقق `/ready` من التبعيات الصعبة التي لا يستطيع الخادم العمل بدونها (Postgres + ClickHouse)، لذا فإن الخادم الذي يعمل لكن لا يستطيع الوصول إلى قاعدة بيانات يتم إخراجه من التدوير ويظهر كـ `NotReady`؛ يتم الإبلاغ عن Redis لكنه لا يفشل في الاستعداد أبدًا. على المظاهر Kubernetes المجمعة، تشير مسبار الاستعداد بالفعل إلى `/ready` ويبقى liveness على `/health`. انظر [enterprise-docs/health-monitoring.md](/ar/agenteye/health-monitoring) للصورة الكاملة، بما في ذلك تنبيهات فشل القرية الأصلية Kubernetes المدمجة إلى Slack. -### رابط البريد السحري +### عنوان URL لارتباط السحر في البريد الإلكتروني -رسائل بريد تسجيل OTP تحتوي على زر **افتح لوحة المعلومات** بنقرة واحدة. النقر عليه يهبط المستخدم على `/login?token=&email=
`؛ تبادل لوحة المعلومات هذا الزوج لجلسة وإعادة توجيه إلى التطبيق، بدون إعادة إدخال رمز يدوية. يحل الخادم أصل لوحة المعلومات المستخدم لبناء الرابط في ثلاث طبقات: +رسائل البريد الإلكتروني OTP تتضمن زر **افتح لوحة التحكم** على نقرة واحدة. سيؤدي النقر عليه إلى هبوط المستخدم على `/login?token=&email=
`؛ تتبادل لوحة التحكم هذا الزوج لجلسة وتعيد التوجيه إلى التطبيق، بدون إعادة إدخال يدوية للرمز. يحل الخادم أصل لوحة التحكم المستخدم لإنشاء الارتباط في ثلاث طبقات: -1. **رأس `X-AgentEye-Dashboard-Url`**: يُعيّن تلقائياً بواسطة وكيل `/api/auth/otp/request` لوحة المعلومات من أصلها العام. في نشر نفس الأصل (الخادم ولوحة المعلومات يشاركان المضيف خلف ingress واحد يرسل رؤوس الوكيل)، **لا توجد حاجة لأي تكوين**. -2. **متغير بيئة `DASHBOARD_URL`**: عيّن هذا إذا كانت لوحة المعلومات الخاصة بك قابلة للوصول على أصل مختلف عن الذي يراه نقطة نهاية طلب OTP الخادم (تقسيم `api.example.com` / `app.example.com`)، أو إذا كان ingress الخاص بك لا ينتشر المضيف العام إلى كبسولة لوحة المعلومات (بحيث `request.nextUrl.origin` سيحل إلى ربط موسّع مثل `0.0.0.0:3000`). مثال: `DASHBOARD_URL=https://app.example.com`. -3. **الافتراضي**: `https://app.befailproof.ai`، يُستخدم فقط إذا لم يكن أي من الخيارات أعلاه موجوداً. +1. **رأس `X-AgentEye-Dashboard-Url`**: يتم تعيينه تلقائيًا بواسطة وكيل `/api/auth/otp/request` الخاص بالقائمة الأمامية من أصله العام الخاص. في نشر نفس الأصل (الخادم والقائمة الأمامية يشتركان في مضيف خلف ingress واحد يعيد توجيه رؤوس الوكيل)، **لا يلزم أي تكوين**. +2. **متغير البيئة `DASHBOARD_URL`**: اضبط هذا إذا كانت لوحة التحكم الخاصة بك قابلة للوصول على أصل مختلف عن الذي يراه نقطة نهاية طلب OTP الخاصة بالخادم (انقسام `api.example.com` / `app.example.com`)، أو إذا لم يقم ingress الخاص بك بنشر المضيف العام في وحدة القائمة الأمامية (بحيث `request.nextUrl.origin` سيحل بطريقة أخرى إلى ربط بدل مثل `0.0.0.0:3000`). مثال: `DASHBOARD_URL=https://app.example.com`. +3. **الافتراضي**: `https://app.befailproof.ai`، مستخدم فقط إذا لم يكن أي من الأعلى موجودًا. -يتم التحقق من قيمة الرأس: فقط `https://*` و loopback (`http://localhost*`, `http://127.0.0.1*`) الأصول مقبولة، وعناوين الربط الموسّعة (`0.0.0.0`, `[::]`) مرفوضة حتى مع مخطط `https://`. أي شيء آخر ينسحب إلى الطبقة 2. +يتم التحقق من قيمة الرأس: فقط أصول `https://*` و loopback (`http://localhost*`، `http://127.0.0.1*`) مقبول، ويتم رفض عناوين ربط البدل (`0.0.0.0`، `[::]`) حتى مع مخطط `https://`. أي شيء آخر ينخفض عبر الطبقة 2. -عيّن على مجموعة قيد التشغيل بسطر واحد؛ لا ملف، لا إعادة بناء kustomize: +اضبطه على مجموعة تشغيل باستخدام أمر سطر واحد؛ بدون ملف، بدون إعادة بناء kustomize: ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -هذا يُطلق عملية إعادة تشغيل؛ تلتقط الكبسولات الجديدة القيمة عند أول طلب. لاحظ أن الكبس يعيش فقط على الانتشار؛ `kustomize build | kubectl apply` اللاحقة ضد التراكب ستحذفها إلا إذا أضفت متغير البيئة نفسه إلى رقعة `server-env.yaml` للتراكب الخاص بك. +هذا ينجز تطوير؛ تختار الوحدات الجديدة القيمة عند أول طلب. لاحظ أن الإلغاء يعيش فقط على النشر؛ `kustomize build | kubectl apply` لاحقة ضد الإضافة الخاصة بك ستمسحها ما لم تضف نفس متغير البيئة إلى `server-env.yaml` الخاص بك. --- -## لوحة المعلومات +## القائمة الأمامية -### استحضار الصورة +### سحب الصورة ```bash docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest @@ -165,18 +166,18 @@ docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest ### متغيرات البيئة -| المتغير | مطلوب | الافتراضي | الوصف | +| المتغير | مطلوب | القيمة الافتراضية | الوصف | |---|---|---|---| -| `AGENTEYE_SERVER_URL` | نعم | لا شيء | URL الأساسي للخادم، مثل `http://localhost:8080` | -| `AGENTEYE_API_KEY` | نعم | لا شيء | مفتاح API تستخدمه لوحة المعلومات للمصادقة على الخادم. يحتاج إلى جميع الأذونات (يوصى بمفتاح المسؤول). | -| `AE_LOG_LEVEL` | لا | `info` | طراز السجلات من جانب الخادم: `debug`, `info`, `warn`, `error`. عيّن على `debug` لرؤية سطور الطلب/الاستجابة الأعلى وآثار التحقق من الجلسة عند تشخيص المشاكل. | -| `AE_LOG_JSON` | لا | تلقائي | `1` يفرض JSON-per-line output؛ `0` يفرض إخراج قابل للقراءة البشرية. عند الإيقاف، يتم تفعيل JSON تلقائياً إذا كان `NODE_ENV=production`. يوصى بـ JSON في الإنتاج بحيث تحلل السجلات بشكل نظيف مع `jq` أو محمّع السجل. | -| `AE_ANALYTICS_DISABLED` | لا | لا شيء | عيّن على `1`/`true` لتعطيل بيانات وصول المنتج المجهولة لوحة المعلومات. انظر [بيانات التلميح والخصوصية](#telemetry--privacy) أدناه. | -| `REDIS_URL` | لا | لا شيء | خلفية ذاكرة التخزين المؤقتة المشتركة الاختيارية، مثل `redis://redis:6379/0`. عند التعيين، تخزن لوحة المعلومات نتائج `validateSession()` عبر النسخ المتماثلة وتشاركها في ذاكرة التخزين المؤقتة fetch الجديدة لمسارات وكيل التجميع اللطيف / قائمة env. حدود معدل طلب OTP والتحقق من جانب الحافة أيضاً تستخدم Redis عند الوجود (تفشل مفتوحة إذا كانت Redis غير قابلة للوصول؛ حد الخادم الجانبي هو backstop الأمان). انظر **Redis (ذاكرة تخزين مؤقتة اختيارية)** أدناه. | -| `AGENTEYE_AGENT_URL` | لا | لا شيء | URL الأساسي للخدمة اختيارية للمساعد الذكي `agent`، مثل `http://agent:9100`. **اتركها غير معيّنة لإخفاء المساعد بالكامل**: لا فقاعة مساعد تظهر في لوحة المعلومات. انظر [enterprise-docs/assistant.md](/ar/agenteye/assistant). | -| `AGENTEYE_AGENT_TOKEN` | لا | لا شيء | سر مشترك تعرضه لوحة المعلومات لخدمة `agent`. يجب أن يطابق `AGENTEYE_AGENT_TOKEN` محكمة على الوكيل. انظر [enterprise-docs/assistant.md](/ar/agenteye/assistant). | +| `AGENTEYE_SERVER_URL` | نعم | بلا | عنوان URL الأساسي للخادم، مثل `http://localhost:8080` | +| `AGENTEYE_API_KEY` | نعم | بلا | مفتاح API الذي تستخدمه لوحة التحكم للمصادقة مع الخادم. يحتاج إلى جميع الأذونات (مفتاح الإدارة موصى به). | +| `AE_LOG_LEVEL` | لا | `info` | تفاصيل السجل من جانب الخادم: `debug`، `info`، `warn`، `error`. اضبط على `debug` لرؤية أسطر الطلب/الرد المرسل والتتبع ضمن التحقق من صحة الجلسة عند تشخيص المشاكل. | +| `AE_LOG_JSON` | لا | auto | `1` يفرض إخراج JSON لكل سطر؛ `0` يفرض إخراج قابل للقراءة من قبل البشر. عند عدم التعيين، يتم تفعيل JSON تلقائيًا إذا كان `NODE_ENV=production`. يُنصح به JSON في الإنتاج بحيث تُحلل السجلات بشكل نظيف مع `jq` أو محمع سجلات. | +| `AE_ANALYTICS_DISABLED` | لا | بلا | اضبط على `1`/`true` لتعطيل قياس الاستخدام المجهول للمنتج الخاص بالقائمة الأمامية. انظر [البيانات الوصفية والخصوصية](#telemetry--privacy) أدناه. | +| `REDIS_URL` | لا | بلا | خادم ذاكرة تخزين مؤقت مشترك اختياري، مثل `redis://redis:6379/0`. عند التعيين، تخزن لوحة التحكم نتائج `validateSession()` عبر النسخ المتماثلة وتشارك ذاكرة التخزين المؤقت جلب Next.js لطرق وكيل الإجمالي الكامن / البيئة قائمة. حدود معدل طلب OTP والتحقق من OTP على الحافة تستخدم أيضًا Redis عند وجودها (الفشل المفتوح إذا كان Redis غير قابل للوصول؛ حد الخادم من الجانب الآمن هو backstop الأمان). انظر **Redis (ذاكرة تخزين مؤقت اختيارية)** أدناه. | +| `AGENTEYE_AGENT_URL` | لا | بلا | عنوان URL الأساسي لخدمة المساعد الذكي `agent` الاختيارية، مثل `http://agent:9100`. **تركه بدون تعيين لإخفاء المساعد بالكامل**: لا يظهر فقاعة مساعد في لوحة التحكم. انظر [enterprise-docs/assistant.md](/ar/agenteye/assistant). | +| `AGENTEYE_AGENT_TOKEN` | لا | بلا | السر المشترك الذي تعرضه لوحة التحكم لخدمة `agent`. يجب أن يتطابق مع `AGENTEYE_AGENT_TOKEN` المُعد على العميل. انظر [enterprise-docs/assistant.md](/ar/agenteye/assistant). | -### تشغيل +### التشغيل ```bash docker run -d --restart unless-stopped \ @@ -187,91 +188,91 @@ docker run -d --restart unless-stopped \ ghcr.io/agenteye-enterprise/dashboard:beta-latest ``` -### بيانات التلميح والخصوصية +### البيانات الوصفية والخصوصية -تُرسل لوحة المعلومات **بيانات وصول المنتج المجهولة** إلى خدمة بيانات Exosphere (PostHog): أي صفحات لوحة المعلومات يتم عرضها وحفنة من الإجراءات UI مثل إنشاء مفتاح API أو إعادة تقييم جلسة. تُخبر هذه إشارة الاستخدام أي الميزات ذات الأولوية. +تُرسل لوحة التحكم **قياس الاستخدام المجهول للمنتج** إلى خدمة تحليل Exosphere (PostHog): صفحات لوحة التحكم التي يتم عرضها وحفنة من إجراءات واجهة المستخدم مثل إنشاء مفتاح API أو إعادة تقييم جلسة. تُخبر إشارة الاستخدام هذه ميزات الأولويات التي يتم تحديدها. -- **لا توثيق الوكيل أو الجلسة أو الحدث يترك البنية الأساسية الخاصة بك أبداً.** يتم الإبلاغ عن استخدام واجهة مستخدم لوحة المعلومات فقط. يتم تجريد عناوين URL للصفحة من المعرّفات قبل الإرسال، والمشغلون يتم التعريف بهم فقط برقم داخلي معتم، أبداً بالبريد الإلكتروني. -- بيانات التلميح **ممكّنة بشكل افتراضي**. لتعطيلها بالكامل، عيّن `AE_ANALYTICS_DISABLED=1` على كنتاينر لوحة المعلومات وأعد التشغيل. -- تُرسل بيانات التحليلات إلى المسار `/ingest` الخاص بلوحة المعلومات، والتي تعكس لوحة المعلومات إلى PostHog (`https://us.i.posthog.com`). إبقاء الطلبات من الطرف الأول يعني أن مانعات الإعلانات في المتصفح لا تسقطها. **كنتاينر لوحة المعلومات** يحتاج إلى وصول خارج PostHog؛ إذا تم حظره، تفعل بيانات التلميح شيء صامت ولا تتأثر لوحة المعلومات. +- **لا تغادر بيانات الوكيل أو الجلسة أو الحدث البنية التحتية الخاصة بك أبدًا.** يتم الإبلاغ عن استخدام واجهة مستخدم لوحة التحكم فقط. يتم تجريد عناوين URL للصفحة من المعرفات قبل الإرسال، ويتم تحديد هويات المشغلين فقط بمعرّف داخلي معتم، وليس عبر البريد الإلكتروني. +- البيانات الوصفية **مفعّلة افتراضيًا**. لإيقافها تمامًا، اضبط `AE_ANALYTICS_DISABLED=1` على حاوية القائمة الأمامية وأعد التشغيل. +- يتم إرسال البيانات الوصفية إلى مسار `/ingest` الخاص بلوحة التحكم الخاصة، الذي تعيد توجيهه لوحة التحكم إلى PostHog (`https://us.i.posthog.com`). إن إبقاء الطلبات من الطرف الأول يعني أن حاجبات الإعلانات الخاصة بمتصفح لن تسقطها. **حاوية القائمة الأمامية** تحتاج إلى وصول صادر إلى PostHog؛ إذا تم حظره، لا تفعل البيانات الوصفية شيئًا بصمت وتبقى لوحة التحكم غير متأثرة. --- -## المساعد الذكي (اختياري) +## مساعد AI (اختياري) -يسمح مساعد ذكي في لوحة المعلومات لفريقك بطرح أسئلة حول بيانات الوكيل الخاصة بهم باللغة الطبيعية (تلخيص الجلسات، صياغة SQL لمحرر `/queries`، وتحويل الاستعلامات المحفوظة إلى بلاط لوحة المعلومات) دون مغادرة لوحة المعلومات. يعمل كـ كنتاينر `agent` داخلي منفصل (على Agents SDK Claude) الذي تستطيع لوحة المعلومات فقط الوصول إليه، ويبقى **معطّل حتى تحكم نقطة نهاية LLM**. +يسمح مساعد AI داخل لوحة التحكم لفريقك بطرح أسئلة حول بيانات وكيلهم باللغة الطبيعية (تلخيص الجلسات، وصياغة SQL لمحرر `/queries`، وتحويل الاستعلامات المحفوظة إلى بلاطات لوحة التحكم) دون ترك لوحة التحكم. يعمل كحاوية `agent` داخلية منفصلة (على Agents SDK) التي يمكن فقط للقائمة الأمامية الوصول إليها، ويبقى **معطلاً حتى تقوم بتكوين نقطة نهاية LLM**. -لتفعيله تعيّن، على خدمة `agent`، اتصال LLM (**Portkey** عبر `PORTKEY_API_KEY` + سلج فهرس نموذج `AGENTEYE_AGENT_MODEL=@/`، Anthropic مباشر عبر `ANTHROPIC_API_KEY`، بوابة أخرى عبر `ANTHROPIC_BASE_URL`، أو Bedrock/Vertex)، مفتاح بيانات **مخصص**، و`AGENTEYE_AGENT_TOKEN` مشترك يطابق لوحة المعلومات. يحتاج مستخدمو لوحة المعلومات بالإضافة إلى أذن `agent:use`. +لتفعيله تضبط، على خدمة `agent`، اتصال LLM (**Portkey** عبر `PORTKEY_API_KEY` + slug كتالوج النموذج `AGENTEYE_AGENT_MODEL=@/`، Anthropic مباشر عبر `ANTHROPIC_API_KEY`، بوابة أخرى عبر `ANTHROPIC_BASE_URL`، أو Bedrock/Vertex)، مفتاح بيانات **مخصص**، و `AGENTEYE_AGENT_TOKEN` مشترك يطابق لوحة التحكم. يحتاج مستخدمو لوحة التحكم أيضًا إلى إذن `agent:use`. -لمفتاح بيانات المساعد لا تحك أي شيء بالفعل: اختر سر عشوائي، عيّنه كـ `AGENTEYE_API_KEY` على `agent` **و** كـ `AGENT_API_KEY` على `server`، والخادم يزرعه عند بدء التشغيل بمجموعة أذن ثابتة. دخوله هو قراءة فقط (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`)، والإضافة يحتوي على نطاقات المصادقة الموافقة (`dashboards:write`, `queries:write`, `queries:run`) حتى يتمكن من صياغة والتحقق من الاستعلامات المحفوظة وبناء بلاط لوحة المعلومات نيابة عن المستخدم؛ كل SQL يعمل عبر دور ClickHouse قراءة فقط للمنظمة، لذا يوسع هذا ما يستطيع المساعد صياغته، وليس ما البيانات التي يمكنه الوصول إليها. النطاقات ثابتة في الكود ولا يمكن توسيعها بالتكوين. هذا المفتاح محمي؛ لا يمكن تعطيله أو إعادة توليده عبر API، فقط تدويره بتغيير القيمة وإعادة التشغيل. لا تعيد استخدام مفتاح المسؤول/لوحة المعلومات لهذا. +بالنسبة لمفتاح بيانات المساعد، لا تُصنع أي شيء يدويًا: اختر سرًا عشوائيًا، اضبطه كـ `AGENTEYE_API_KEY` على `agent` **و** كـ `AGENT_API_KEY` على `server`، وينشئ الخادم ميزة مجموعة أذونات ثابتة عند بدء التشغيل. وصول البيانات الخاص به يكون للقراءة فقط (`events:read`، `evaluations:read`، `dashboards:read`، `queries:read`)، وبالإضافة إلى ذلك يحمل نطاقات تأليف بوابة موافقة (`dashboards:write`، `queries:write`، `queries:run`) بحيث يمكنه صياغة والتحقق من صحة الاستعلامات المحفوظة وبناء بلاطات لوحة التحكم نيابة عن المستخدم؛ لا يزال كل SQL يعمل من خلال دور ClickHouse للقراءة فقط الخاص بالمنظمة، لذا يوسع هذا ما يمكن للمساعد تأليفه، وليس البيانات التي يمكنه الوصول إليها. يتم إصلاح النطاقات في الكود ولا يمكن توسيعها بواسطة التكوين. هذا المفتاح محمي؛ لا يمكن تعطيله أو إعادة توليده عبر API، فقط إعادة تدويره بتغيير القيمة وإعادة التشغيل. لا تعيد استخدام مفتاح الإدارة/لوحة التحكم لهذا. -الإعداد الكامل، والمرجع الكامل لمتغير البيئة، وخيارات بيانات التلميح، والنموذج الأمني في **[enterprise-docs/assistant.md](/ar/agenteye/assistant)**. +الإعداد الكامل، ومرجع متغير البيئة الكامل، وخيارات البيانات الوصفية، والنموذج الأمني موجود في **[enterprise-docs/assistant.md](/ar/agenteye/assistant)**. --- -## ClickHouse (متجر التحليلات المطلوب) +## ClickHouse (مخزن التحليلات المطلوب) -يحافظ ClickHouse على لوحات معلوماتك سريعة في مجلدات الأحداث العالية ويسمح محرر SQL `/queries` بالانضمام عبر الأحداث والتقييمات والجلسات في متجر واحد. إنه متجر القانوني المطلوب لكل حدث مستقبل، وكل نتيجة تقييم نهائية، والمجاميع المشتقة لكل جلسة. يحتوي PostgreSQL على جداول الحالة العلائقية / القابلة للتغيير (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries)؛ توجد السطح التحليلي في ClickHouse لذا استعلامات لوحة المعلومات التجميعية والاستعلامات SQL الخاصة بك يمكن أن تفحص وتنضم إليها بشكل أصلي، بدون رحلات قاعدة بيانات متقاطعة. يرفض الخادم الإقلاع بدون `CLICKHOUSE_URL`. +يحافظ ClickHouse على استجابة لوحات التحكم الخاصة بك عند مجلدات الأحداث العالية ويسمح لمحرر SQL `/queries` بالانضمام عبر الأحداث والتقييمات والجلسات في متجر واحد. إنه متجر قانوني مطلوب لكل حدث مُدخَل، وكل نتيجة تقييم نهائية، والمجاميع المشتقة لكل جلسة. يحتفظ PostgreSQL بجداول الحالة القابلة للتغيير (api_keys، users، otp_codes، evaluation_jobs، dashboards، saved_queries)؛ السطح التحليلي يعيش في ClickHouse بحيث يمكن لتجميعات لوحة التحكم والاستعلامات الخاصة بك الفحص والانضمام بشكل أصلي، بدون round-trips قاعدة بيانات متقاطعة. يرفض الخادم التمهيد بدون `CLICKHOUSE_URL`. ### المخطط -ثلاثة كائنات ClickHouse يتم إنشاؤها عند بدء تشغيل الخادم، كلها idempotent (`CREATE IF NOT EXISTS`): +يتم إنشاء ثلاثة كائنات ClickHouse عند بدء تشغيل الخادم، الكل idempotent (`CREATE IF NOT EXISTS`): -- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, مقسم بواسطة `toYYYYMM(ts)`, مرتب حسب `(session_id, ts, dedup_key)`. تُسقط إدراجات مكررة (محاولات المجمع) إلى صف واحد في وقت الدمج؛ يحسب الخادم SHA-256 `dedup_key` حتمية لكل حدث بحيث تكون المحاولات الإعادة آمنة. -- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, مقسم بواسطة `toYYYYMM(finished_at)`, مرتب حسب `(session_id, finished_at, dedup_key)`. كُتب مرة واحدة لكل نتيجة تقييم نهائية من قبل خط أنابيب المُقيّم. نفس نموذج dedup-key كما `events`. -- **`agenteye.agent_sessions`**: **VIEW** أعلى `agenteye.events`، وليس جدول فعلي. كل عمود مشتق (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, إلخ.). لا إدراج لكل حدث ولا تعبئة خلفية منفصلة؛ يعكس العرض تلقائياً مهما كان في `events`. +- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`، مقسم حسب `toYYYYMM(ts)`، مرتب حسب `(session_id, ts, dedup_key)`. تسقط الإدراجات المكررة (إعادة محاولات المجمع) إلى صف واحد في وقت الدمج؛ يحسب الخادم `dedup_key` SHA-256 حتمي لكل حدث بحيث تكون إعادة المحاولات آمنة. +- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`، مقسم حسب `toYYYYMM(finished_at)`، مرتب حسب `(session_id, finished_at, dedup_key)`. كتب مرة واحدة لكل نتيجة تقييم نهائية بواسطة خط أنابيب المقيّم. نموذج dedup-key نفسه كما هو الحال في `events`. +- **`agenteye.agent_sessions`**: **VIEW** عبر `agenteye.events`، وليس جدول مادي. كل عمود مشتق (`started_at = min(ts)`، `last_event_at = max(ts)`، `ended_at = max(if event_type='agent_end', ts, NULL)`، `event_count = count()`، إلخ). لا upsert لكل حدث ولا ملء منفصل؛ يعكس العرض تلقائيًا كل ما هو في `events`. -لـ backwards-compat مع الاستعلامات المحفوظة التي تُرجع `analytics.evaluations` / `analytics.sessions`، ينشئ الخادم أيضاً قاعدة بيانات `analytics` ClickHouse برؤى أعلى جداول `agenteye.*`؛ `analytics.events`، `analytics.evaluations`، `analytics.agent_sessions`، `analytics.sessions` جميعها تُحل بشكل صحيح. +من أجل التوافقية للخلف مع الاستعلامات المحفوظة التي تشير إلى `analytics.evaluations` / `analytics.sessions`، ينشئ الخادم أيضًا قاعدة بيانات `analytics` ClickHouse مع عروض عبر جداول `agenteye.*`؛ `analytics.events`، `analytics.evaluations`، `analytics.agent_sessions`، `analytics.sessions` جميعها تحل بشكل صحيح. ### التكوين -توزع البيانات docker-compose والـ `deploy/base/clickhouse/` خدمة ClickHouse محكمة لحمل عمل AgentEye الخاص بك: +توفير docker-compose المجمع و `deploy/base/clickhouse/` خدمة ClickHouse محسّنة لعبء عمل AgentEye: -- 2 GiB طُلب / 4 GiB حد الذاكرة في التراكب الأساسي المشحون (الحجم لملاءمة عُقد POC/staging الصغيرة)؛ يجب على عملاء الإنتاج تراكب الأعلى — الحد الموصى به هو 2c / 4Gi طلب، 6c / 8Gi حد. `max_server_memory_usage_to_ram_ratio=0.9` -- ذاكرة 5 GiB + ذاكرة غير مضغوطة 8 GiB -- `background_pool_size=16`, `background_merges_mutations_concurrency_ratio=2` -- MergeTree: `parts_to_throw_insert=3000`, `parts_to_delay_insert=1500`, `non_replicated_deduplication_window=1000` -- `local_io_method=auto` (io_uring على kernels المدعومة) -- `fsync_metadata=0`: مقبول لأن هناك على الأقل مرة واحدة ingest + ReplacingMergeTree dedup -- `query_log` ممكّن مع TTL 30 يوم؛ `query_thread_log` محذوف (باهظ عند QPS عالي) -- `max_execution_time=30` لاستعلامات جانب المستخدم -- 100 GiB PVC على قالب StatefulSet (يجب أن تعطّل تراكبات العملاء على فئة تخزين SSD سريع للإنتاج) +- 2 GiB مطلوب / 4 GiB حد الذاكرة في الإضافة الأساسية المشحونة (بحجم تناسب عقد POC/staging الصغيرة)؛ يجب على عملاء الإنتاج ترقية الإضافة — الأرضية الموصى بها هي 2c / 4Gi الطلب، 6c / 8Gi الحد. `max_server_memory_usage_to_ram_ratio=0.9` +- ذاكرة تخزين مؤقت 5 GiB علامة + 8 GiB ذاكرة غير مضغوطة +- `background_pool_size=16`، `background_merges_mutations_concurrency_ratio=2` +- MergeTree: `parts_to_throw_insert=3000`، `parts_to_delay_insert=1500`، `non_replicated_deduplication_window=1000` +- `local_io_method=auto` (io_uring على النوى المدعومة) +- `fsync_metadata=0`: قابل للقبول بسبب ضمان على الأقل مرة واحدة ingest + ReplacingMergeTree dedup +- `query_log` مفعّل مع TTL 30 يوم؛ تم إزالة `query_thread_log` (مكلفة عند QPS عالي) +- `max_execution_time=30` للاستعلامات من جانب المستخدم +- PVC 100 GiB في قالب StatefulSet (يجب على الإضافات الخاصة بالعميل تجاوز فئة التخزين SSD السريع للإنتاج) ### النسخ الاحتياطية -يتم التقاط مجموعة البيانات الكاملة الخاصة بك ليلاً في ملف واحد قابل للاستعادة، لذا فقدان مجموعة أو التخزين قابل للاسترجاع. يتم نسخ ClickHouse احتياطياً تلقائياً بواسطة `agenteye-backup` CronJob اليومي، الذي يُلقي كل من PostgreSQL و ClickHouse في مسار واحد. يُقرأ ClickHouse عبر HTTP API الخاصة به: `agenteye.events` و `agenteye.evaluations` يتم إلقاؤها بصيغة ClickHouse الأصلية (تُعاد إنشاء العروض وسياسات الصفوف من قبل الخادم عند بدء التشغيل، لذا فإن بيانات الجدول هي الصورة الكاملة) ومضمن مع Postgres dump في ملف واحد مضغوط يُرفع إلى التخزين الموضوعي الخاص بك. +يتم التقاط المجموعة البيانات الكاملة الخاصة بك كل ليلة في أرشيف استعادة واحد، لذا فإن فقدان المجموعة أو التخزين قابل للاسترجاع. يتم عمل نسخة احتياطية من ClickHouse تلقائيًا بواسطة CronJob `agenteye-backup` اليومي، الذي يُفرغ PostgreSQL و ClickHouse في مسار واحد. يتم قراءة ClickHouse عبر HTTP API الخاص به: يتم تفريغ `agenteye.events` و `agenteye.evaluations` بتنسيق ClickHouse الأصلي (يتم إعادة إنشاء العروض وسياسات الصفوف بواسطة الخادم عند بدء التشغيل، لذا بيانات الجدول هي الصورة الكاملة) وتجميعها مع تفريغ Postgres في أرشيف مضغوط واحد تم تحميله إلى التخزين الموضوعي الخاص بك. -يتم تكوين دلو الوجهة وبيانات اعتماد السحابة لكل تراكب. انظر قسم **النسخ الاحتياطية** من [enterprise-docs/kubernetes-deployment.md](/ar/agenteye/kubernetes-deployment) لتكوين المرفع وخطوات الاستعادة. +يتم تكوين الدلو الوجهة وبيانات اعتماد السحابة لكل إضافة. انظر قسم **النسخ الاحتياطية** من [enterprise-docs/kubernetes-deployment.md](/ar/agenteye/kubernetes-deployment) لتكوين التحميل وخطوات الاستعادة. --- -## Redis (ذاكرة تخزين مؤقتة اختيارية) +## Redis (ذاكرة تخزين مؤقت اختيارية) -Redis هي **اختيارية** ذاكرة تخزين مؤقتة مشتركة + خلفية تحديد السعر المستخدمة من قبل الخادم ولوحة المعلومات. مع نشر Redis و`REDIS_URL` عيّن على كلا الخدمات: +Redis هي ذاكرة تخزين مؤقت مشتركة **اختيارية** + خادم حد معدل يستخدمه الخادم والقائمة الأمامية. مع Redis المنشرة و `REDIS_URL` المضبوط على كلا الخدمتين: -- **الخادم** يخزن عمليات البحث عن المفاتيح المصادقة، قائمة `/events/environments` + `/evaluations/environments`، لفافة `/events/latency_aggregate` (أثقل استعلام تسأل عنه لوحة المعلومات)، قائمة `/sessions`، وينقل حد معدل طلب OTP من Postgres `COUNT(*)` إلى Redis `INCR + EXPIRE`. -- **لوحة المعلومات** تخزن نتائج `validateSession()` بحيث تُشاركه 10-20 جرعة API المصادقة التي تصدرها حمولة صفحة نموذجية تفحص جلسة واحدة فقط. كما تُحدد معدل طلب OTP والتحقق عند حافة لوحة المعلومات. +- **الخادم** يخزن بحثًا مفتاح API مصرح، قوائم `/events/environments` + `/evaluations/environments`، إجمالي `/events/latency_aggregate` (الاستعلام الأثقل الذي تستقصيه لوحة التحكم)، قائمة `/sessions`، وينقل معدل حد طلب OTP من `COUNT(*)` Postgres إلى Redis `INCR + EXPIRE`. +- **القائمة الأمامية** تخزن نتائج `validateSession()` بحيث تشارك مكالمات API المصرحة 10-20 لتحميل صفحة نموذجية فحص جلسة رفع واحد. كما تعدّل معدل طلب OTP والتحقق من OTP في حافة لوحة التحكم. -**كل الخدمات تنحط بأناقة إذا كانت Redis غير قابلة للوصول.** كل نداء ذاكرة تخزين مؤقتة يعود `Err` ضمن انتظار مقيد والمتصل ينسحب إلى مصدر الحقيقة (Postgres على الخادم، خادم Rust الأعلى على لوحة المعلومات). حد معدل OTP ينسحب إلى مسار Postgres `COUNT(*)` على الخادم (يُحافظ على خاصية الأمان)؛ حد OTP للحافة لوحة المعلومات يفشل مفتوح أثناء حد الخادم الجانبي لا يزال يحمل. Redis كونه نزولاً يُنحط الزمن الكامن، وليس الصحة. +**كلا الخدمتين يتدهوران برفق إذا كان Redis غير قابل للوصول إليه.** كل نداء ذاكرة تخزين مؤقت يعود `Err` في انتظار محدود والمستدعي ينخفض إلى مصدر الحقيقة (Postgres على الخادم، الخادم Rust الرفع على لوحة التحكم). يسقط معدل حد OTP إلى مسار `COUNT(*)` Postgres على الخادم (الخاصية الأمان تُحفظ)؛ حد حافة OTP الخاص بلوحة التحكم ينفتح بينما حد من الجانب الخادم لا يزال ثابتًا. Redis كونه معطلاً يتدهور الكمون، وليس الصحة. ### التكوين -بيانات docker-compose تتضمن بالفعل خدمة Redis ويسيّر `REDIS_URL=redis://redis:6379/0` في الخادم ولوحة المعلومات. لاستخدام Redis خارجي، عيّن `REDIS_URL` إلى نقطة النهاية الخاصة بك وأزل الخدمة `redis` من ملف compose. +حزمة docker-compose بالفعل تتضمن خدمة Redis وتسلك `REDIS_URL=redis://redis:6379/0` في الخادم والقائمة الأمامية. لاستخدام Redis خارجي، اضبط `REDIS_URL` على نقطة النهاية الخاصة بك وأزل خدمة `redis` من ملف الإنشاء. -### الذاكرة + الثبات +### الذاكرة والمثابرة -صورة Redis الموزعة تعمل مع `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. يعني AOF persistence أن الذاكرة المؤقتة تبقى عبر إعادة تشغيل الكنتاينر؛ `everysec` هو توازن الثبات/الأداء الصحيح لأن فقدان آخر ثانية من كتابات الذاكرة المؤقتة غير مؤذي. يُغطي إجلاء LRU نمو الذاكرة. +تعمل صورة Redis المجمعة مع `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. إن AOF المثابرة تعني أن ذاكرة التخزين المؤقت تنجو من إعادة تشغيل الحاوية؛ `everysec` هي الموازنة الصحيحة بين المتانة والأداء لأن فقدان كتابات ذاكرة التخزين المؤقت الثانية الأخيرة بلا ضرر. سقط الإزالة يحد من نمو الذاكرة. -### عندما لا تنشر Redis +### عندما لا يتم نشر Redis -- واحد-instance dev/QA. الذاكرات المؤقتة داخل العملية على الخادم وحده توفر معظم الفائدة لكل نسخة متماثلة؛ Redis يضيف المشاركة عبر النسخ المتماثلة التي لا تحتاجها الإعدادات أحادية-instance. -- تثبيتات هواء-فراغ حيث التكلفة التشغيلية لتشغيل خدمة واحدة أخرى تفوق كسب الزمن الكامن. +- تطوير/QA مثيل واحد. ذاكرات التخزين المؤقت داخل العملية على الخادم وحده توفر معظم الفائدة لكل نسخة؛ تضيف Redis المشاركة عبر النسخ المتماثلة التي لا تحتاج إليها إعدادات المثيل الواحد. +- التثبيتات المنقطعة عن الشبكة حيث تفوق التكلفة التشغيلية لتشغيل خدمة أخرى فائدة الكمون. --- ## Docker Compose (موصى به) -ملف `docker-compose.yml` متاح في مستودع `agenteye-enterprise/releases`. يجلب Postgres وClickHouse و Redis والخادم ولوحة المعلومات مع أمر واحد. +`docker-compose.yml` متاح في `agenteye-enterprise/releases` repo. يحضر Postgres والخادم والقائمة الأمامية بأمر واحد. ```bash GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ @@ -284,16 +285,16 @@ cd agenteye **تجاوز الافتراضيات عبر `.env`:** ``` -# Use URL-safe passwords (no /, +, or = characters). -# Generate with: openssl rand -hex 24 +# استخدم كلمات مرور آمنة للعناوين (لا /, +, أو =). +# توليد باستخدام: openssl rand -hex 24 POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret -# Dashboard authentication +# مصادقة لوحة التحكم ADMIN_EMAIL=admin@yourcompany.com ALLOWED_EMAILS=*@yourcompany.com -# SMTP for OTP emails (omit to log OTP codes to stdout) +# SMTP لرسائل بريد إلكترونية OTP (حذف لتسجيل رموز OTP في stdout) # SMTP_HOST=smtp.yourprovider.com # SMTP_PORT=587 # SMTP_USERNAME=your-smtp-user @@ -307,13 +308,13 @@ RUST_LOG=info docker compose up -d ``` -**التوقف (يحتفظ بمجلد البيانات):** +**التوقف (يحافظ على حجم البيانات):** ```bash docker compose down ``` -**التوقف ومسح جميع البيانات:** +**التوقف والمسح النظيف لجميع البيانات:** ```bash docker compose down -v @@ -323,12 +324,9 @@ docker compose down -v ## الإعدادات التشغيلية -مجموعة صغيرة من المقابض التشغيلية التي اعتادت تثبيتها بواسطة متغيرات env قابلة الآن للتحرير لكل منظمة من صفحة **`//settings`** الخاصة بلوحة المعلومات؛ تُنسّق كل منظمة الخاصة بها. التغييرات تسري مفعول ضمن ثواني، بدون إعادة تشغيل وبدون إعادة نشر. +مجموعة صغيرة من مقابض التشغيل التي كانت مثبتة بواسطة متغيرات البيئة يمكن الآن تحريرها لكل منظمة من صفحة **`//settings`** الخاصة بلوحة التحكم؛ تكوّن كل منظمة ملكها. تُصبح التغييرات ساري المفعول خلال ثوانٍ، بدون إعادة تشغيل وبدون إعادة نشر. -| الإعداد | متغير env التمهيد | ما تتحكم فيه | +| الإعداد | متغير البيئة التمهيدي | ما الذي يتحكم | |---|---|---| -| عمليات تسجيل الدخول المسموحة | `ALLOWED_EMAILS` | رسائل البريد الإلكتروني (أو بدلات `*@domain.com`) مسموح بها تلقي OTP وإضافة كمستخدمين | -| أذونات المستخدم الافتراضية | `DEFAULT_USER_PERMISSIONS` | رموز الأذونات المفصولة بفواصل محددة مسبقاً عندما يفتح المسؤول **+ مستخدم جديد**. يجب أن يكون كل رمز أحد السلاسل المدرجة تحت [أذونات مفتاح API](/ar/agenteye/api-keys). يُفقد للإعداد المسبق `standard`: وصول قراءة فقط بالإضافة إلى الإجراءات اليومية في on-call (إعادة تقييم الزناد، تشغيل الاستعلامات، ack الحوادث، استخدام المساعد). | -| عمر الجلسة | `SESSION_TTL_SECS` | مدى اعتبار تسجيل دخول لوحة المعلومات صالح قبل إعادة المصادقة. تُعيد لوحة المعلومات فحص الجلسة الأعلى كل 5 ثواني، بحيث تأخذ تحديث الأذن على `//users` تأثيره على الطلب التالي للمستخدم المتأثر، بدون إعادة تسجيل. | -| عمر أحادي الاستخدام | `OTP_TTL_SECS` | مدى صلاح رابط OTP / سحري | -| قنوات إخطار التنبيهات | `ALERTS_ENABLED_CHANNELS` | قائمة مفصولة بفواصل من أنواع القنوات موزّع التنبيهات مسموح باستخدامها: `email`, `slack`, `webhook`. التكوين لكل تنبيه مصادقٌ على `//alerts/`، لكن موزّع يفلتر كل تسليم خارج من خلال هذه المجموعة؛ قناة معطّلة هنا short-circuits مع `skipped_disabled` audit row. القناة `dashboard` (الإدراج المحلي للمراجعة) دائماً مسموحة. يُفقد لجميع ال \ No newline at end of file +| السماح بعمليات تسجيل الدخول | `ALLOWED_EMAILS` | رسائل بريد إلكترونية (أو `*@domain.com` من الأحرف الكبيرة) مسموح بها لاستقبال OTP وإضافة كمستخدمين | +| أذونات المستخدم الافتراضية | `DEFAULT_USER_PERMISSIONS` | رموز الأذونات المفصولة بفاصلة محددة مسبقًا عند فتح إدارة **+ مستخدم جديد**. يجب أن يكون كل رمز واحدًا من السلاسل المدرجة تحت [أذونات مفتاح API](/ar/agenteye/api-keys). الافتراضي هو معيار `standard`: وصول للقراءة فقط بالإضافة إلى إجراءات يومية في الخدمة (تقييمات إعادة التشغيل، استعلامات مسموح، حوادث ack، استخد \ No newline at end of file diff --git a/docs/ar/agenteye/getting-started.mdx b/docs/ar/agenteye/getting-started.mdx index 2ae34b19..63870acc 100644 --- a/docs/ar/agenteye/getting-started.mdx +++ b/docs/ar/agenteye/getting-started.mdx @@ -5,32 +5,32 @@ description: "وثائق البدء مع AgentEye." --- -يرشدك هذا الدليل خلال إعداد AgentEye كامل: نشر الخادم والشاشة الرئيسية، وتثبيت جامع البيانات على جهاز الوكيل، وتجهيز كود وكيل Python الخاص بك. +يرشدك هذا الدليل خلال إعداد AgentEye الكامل: نشر الخادم واللوحة، وتثبيت جامع البيانات على جهاز الوكيل، وتجهيز كود وكيل Python الخاص بك. --- ## ما هو AgentEye؟ -AgentEye هي **منصة قابلة للاستضافة ذاتياً للمراقبة والتقييم لوكلاء الذكاء الاصطناعي**. تسجل ما يفعله وكلاؤك — في كل خطوة من خطوات التشغيل — وتقيّم تلقائياً جودة كل تشغيل مكتمل، حتى تتمكن من رؤية كيف يتصرف وكلاؤك في الإنتاج واكتشاف التراجعات قبل أن يكتشفها مستخدموك. +AgentEye هي **منصة مراقبة وتقييم ذاتية الاستضافة لوكلاء AI**. تسجل ما يفعله وكلاؤك — في كل خطوة من الدورة — وتقيّم تلقائياً جودة كل دورة مكتملة، حتى تتمكن من معرفة كيف يتصرف وكلاؤك في الإنتاج واكتشاف الانحدار قبل أن يكتشفه المستخدمون. -تتدفق البيانات في اتجاه واحد: ينبعث كود الوكيل **الأحداث** عبر **Python SDK** → محل جمع بيانات خفيف الوزن يجمع البيانات وينقلها إلى **الخادم** → يتم تخزين الأحداث والتحليلات في **ClickHouse** (الحالة التشغيلية مثل المؤسسات والمستخدمين ومفاتيح API والشاشات والاستعلامات المحفوظة تعيش في **Postgres**) → تستكشف كل شيء في **الشاشة الرئيسية**. +تتدفق البيانات في اتجاه واحد: يصدر كود الوكيل **أحداثاً** عبر **Python SDK** → تجميع **جامع** خفيف الوزن وشحن الأحداث إلى **الخادم** → تخزين الأحداث والتحليلات في **ClickHouse** (الحالة التشغيلية مثل المنظمات والمستخدمين ومفاتيح API والمجلات والاستعلامات المحفوظة توجد في **Postgres**) → استكشاف كل شيء في **لوحة المعلومات**. -ما ستحصل عليه: +ما تحصل عليه: -- **الأحداث** — سجل خام لكل خطوة من كل تشغيل وكيل (استدعاءات الأدوات، استدعاءات النموذج، الخطافات، الأخطاء). -- **الجلسات** — تلك الأحداث مدمجة في صف واحد لكل تشغيل، يتم **تقييم كل منها تلقائياً** وتسجيله. -- **التقييمات** — درجات الجودة التي تنتجها خدمات المقيّم الخاصة بك، بحيث يظهر انخفاض الجودة بدون مراجعة يدوية. -- **الاستعلامات والشاشات** — استعلامات ClickHouse SQL المحفوظة على بيانتك، مرسومة في شاشات مشتركة في نطاق المؤسسة. -- **التنبيهات والحوادث** — قواعد العتبة التي تخطرك (بريد إلكتروني، Slack، webhook، في الشاشة) بالإضافة إلى سير عمل الحوادث لفرزها. -- **CLI والمساعد الذكي** — عميل طرفي (`agenteye`) ومساعد في الشاشة للإجابة على الأسئلة باللغة الطبيعية. +- **الأحداث** — مسار خام مفصل لكل دورة وكيل (استدعاءات الأدوات، استدعاءات النموذج، الخطافات، الأخطاء). +- **الجلسات** — تلك الأحداث مدمجة في صف واحد لكل دورة، كل منها **تقيّم تلقائياً** وتسجيل. +- **التقييمات** — درجات الجودة التي تنتجها خدمات المقيّم الخاصة بك، حتى تظهر انخفاضات الجودة بدون مراجعة يدوية. +- **الاستعلامات والمجلات** — استعلامات ClickHouse SQL المحفوظة على بيانات الخاص بك، مرسومة في مجلات مشتركة محدودة بالمنظمة. +- **التنبيهات والحوادث** — قواعد العتبة التي تخطرك (بريد إلكتروني، Slack، webhook، لوحة المعلومات) بالإضافة إلى سير عمل الحادث لفحصها. +- **واجهة سطر الأوامر ومساعد AI** — عميل محطة (`agenteye`) ومساعد لوحة المعلومات للإجابة على الأسئلة بلغة إنجليزية بسيطة. -تقوم بتشغيل كل هذا في البنية التحتية الخاصة بك، كمكدس Docker Compose واحد (هذا الدليل) أو تثبيت Kubernetes للإنتاج أو وحدة واحدة في نفس المكان. يعد الجزء المتبقي من هذا الدليل مكدس Compose من النهاية إلى النهاية. +تشغّل كل شيء في البنية التحتية الخاصة بك، كمكدس Docker Compose واحد (هذا الدليل)، تثبيت Kubernetes للإنتاج، أو وحدة واحدة موضوعة بشكل مشترك. يقوم باقي هذا الدليل بإعداد مكدس Compose من البداية إلى النهاية. --- ## الخطوة 1: المصادقة -يتم توزيع جميع عناصر AgentEye من منظمة `agenteye-enterprise` على GitHub. بصفتك مطوراً في المؤسسة، يمكنك إنشاء رمز وصول شخصي لـ GitHub الخاص بك. اتبع [enterprise-docs/github-token.md](/ar/agenteye/github-token) للحصول على الخطوات الدقيقة والأذونات المطلوبة. +يتم توزيع جميع تقنيات AgentEye من منظمة GitHub `agenteye-enterprise`. كمطور مؤسسة، يمكنك إنشاء رمز PAT خاص بـ GitHub الخاص بك. اتبع [enterprise-docs/github-token.md](/ar/agenteye/github-token) للحصول على الخطوات الدقيقة والأذونات المطلوبة. ```bash export AGENTEYE_TOKEN= @@ -41,11 +41,11 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin --- -## الخطوة 2: نشر الخادم والشاشة الرئيسية +## الخطوة 2: نشر الخادم ولوحة المعلومات -يستقبل الخادم الأحداث من جامعي البيانات ويجعلها قابلة للاستعلام عنها؛ الشاشة الرئيسية هي المكان الذي تستكشف فيه الأحداث. تعيش الأحداث المدخلة والتحليلات في ClickHouse (متجر التحليلات المطلوب)، بينما يحتفظ Postgres بالحالة التشغيلية مثل المؤسسات والمستخدمين ومفاتيح API والشاشات والاستعلامات المحفوظة. +يستقبل الخادم الأحداث من جامعي البيانات ويجعلها قابلة للاستعلام؛ لوحة المعلومات هي المكان الذي تستكشف فيه الأحداث. الأحداث المدخولة والتحليلات موجودة في ClickHouse (متجر التحليلات المطلوب)، بينما يحتفظ Postgres بالحالة التشغيلية مثل المنظمات والمستخدمين ومفاتيح API والمجلات والاستعلامات المحفوظة. -**تحميل ملف compose المنشور:** +**قم بتحميل ملف compose المنشور:** ```bash mkdir -p ./agenteye @@ -56,38 +56,32 @@ curl -fsSL \ cd agenteye ``` -**اضبط أسرارك:** +**عيّن أسرارك:** -أنشئ ملف `.env` حتى لا ينبغي للنشر أن يعمل على بيانات اعتماد `admin` الافتراضية. على الأقل اضبط `ADMIN_KEY` و `POSTGRES_PASSWORD`: +أنشئ ملف `.env` حتى لا يعمل النشر على بيانات اعتماد `admin` الافتراضية. عيّن كحد أدنى `ADMIN_KEY` و `POSTGRES_PASSWORD`: ```bash POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -قم أيضاً بتصدير `ADMIN_KEY` في الجلسة الحالية حتى تتمكن الخطوات اللاحقة (مثل `curl` في الخطوة 3) من الإشارة إليه مباشرة: - -```bash -export ADMIN_KEY=your-admin-secret -``` - -**ابدأ المكدس:** +**بدء المكدس:** ```bash docker compose up -d ``` -يضع هذا المكدس الكامل، بما في ذلك متجر تحليلات ClickHouse المطلوب وذاكرة تخزين مؤقت Redis اختيارية، جنباً إلى جنب مع الخادم والشاشة الرئيسية. يجب أن يكون ClickHouse صحياً لبدء الخادم. +يؤدي هذا إلى إطلاق المكدس الكامل، بما في ذلك متجر تحليلات ClickHouse المطلوب وذاكرة تخزين مؤقت Redis اختيارية، إلى جانب الخادم ولوحة المعلومات. يجب أن يكون ClickHouse صحياً حتى يبدأ الخادم. -الخادم يستمع الآن على `http://localhost:8080` والشاشة الرئيسية على `http://localhost:3000`. +الخادم يستمع الآن في `http://localhost:8080` ولوحة المعلومات في `http://localhost:3000`. -لنشر الإنتاج (Postgres مخصص، TLS، proxy عكسي)، انظر [enterprise-docs/deployment.md](/ar/agenteye/deployment). +بالنسبة للنشرات الإنتاجية (Postgres مخصص، TLS، reverse proxy)، انظر [enterprise-docs/deployment.md](/ar/agenteye/deployment). --- ## الخطوة 3: إنشاء مفتاح API لجامع البيانات -يقوم كل جامع بيانات بالمصادقة باستخدام مفتاح API محدود النطاق. استخدم `ADMIN_KEY` الذي قمت بتعيينه في الخطوة 2 لإنشاء واحد: +يتم مصادقة كل جامع بمفتاح API محدود النطاق. استخدم `ADMIN_KEY` الذي عينته في الخطوة 2 لإنشاء واحد: ```bash curl -s -X POST http://localhost:8080/keys \ @@ -96,15 +90,15 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -تقدم قيمة `key` بنفسك؛ استخدمها في تكوين جامع البيانات في الخطوة 4. انظر [enterprise-docs/api-keys.md](/ar/agenteye/api-keys) لإدارة المفاتيح الكاملة. +أنت توفر قيمة `key` بنفسك؛ استخدمها في تكوين جامع البيانات في الخطوة 4. راجع [enterprise-docs/api-keys.md](/ar/agenteye/api-keys) لإدارة المفاتيح الكاملة. --- ## الخطوة 4: تثبيت جامع البيانات -على كل جهاز يقوم بتشغيل وكلاء الذكاء الاصطناعي الخاصة بك، قم بتثبيت خدمة جامع البيانات. +على كل جهاز يشغّل وكلاء AI الخاص بك، ثبّت جامع البيانات daemon. -**تحميل الملف الثنائي (Linux x86_64):** +**قم بتحميل البرنامج الثنائي (Linux x86_64):** ```bash VERSION=0.0.1-beta.13 @@ -115,9 +109,9 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> يحمل هذا الملف الثنائي **Linux x86_64**. لـ macOS (Apple Silicon أو Intel) أو Linux arm64 أو إعداد Docker / systemd / launchd، انظر [collector-installation.md](/ar/agenteye/collector-installation)، والذي يسرد التحميل لكل منصة — الأمر أعلاه يثبت ملف ثنائي Linux لن يعمل في أي مكان آخر. +> يقوم هذا بتحميل **Linux x86_64** البناء. بالنسبة إلى macOS (Apple Silicon أو Intel)، Linux arm64، أو Docker/systemd/launchd setup، انظر [collector-installation.md](/ar/agenteye/collector-installation)، التي تسرد التحميل لكل منصة — الأمر أعلاه يثبت ملف ثنائي Linux لن يعمل في مكان آخر. -**التكوين:** +**تكوين:** ```bash mkdir -p ~/.agenteye @@ -129,25 +123,25 @@ cat > ~/.agenteye/config.json </…`). +مع تدفق الأحداث، تحول صفحات **التحليل** النشاط الخام إلى إجابات، حتى تتمكن من قياس سلوك الوكيل ومشاركة النتائج عبر الفريق والحصول على صفحة اللحظة التي يحدث فيها انحدار ما. صفحات لوحة المعلومات محدودة النطاق بالمنظمة، لذا فإن عناوين URL التي تراها في شريط العناوين مع بادئة slug المؤسسة الخاصة بك (`//…`). -- **الاستعلامات** (`//queries`): ابدأ من مكتبة استعلامات محفوظة وقابلة لإعادة الاستخدام على أحداثك والتقييمات (إعدادات مدمجة مسبقاً بالإضافة إلى إعداداتك الخاصة)… +- **الاستعلامات** (`//queries`): ابدأ من مكتبة الاستعلامات المحفوظة وقابلة لإعادة الاستخدام على الأحداث والتقييمات الخاصة بك (الإعدادات المدمجة بالإضافة إلى الخاصة بك)… -![مكتبة الاستعلامات المحفوظة: شبكة استعلامات قابلة لإعادة الاستخدام، كل من الإعدادات المسبقة والاستعلامات المخصصة](/agenteye/images/queries.png) +![مكتبة الاستعلامات المحفوظة: شبكة من الاستعلامات القابلة لإعادة الاستخدام، سواء الإعدادات المدمجة أو الاستعلامات المخصصة](/agenteye/images/queries.png) - …ثم افتح واحد في منشئ SQL لتعديله وتشغيله مع النتائج المباشرة: + …ثم افتح واحداً في منشئ SQL لتعديله وتشغيله مع النتائج المباشرة: -![منشئ استعلام SQL يقوم بتشغيل استعلام محفوظ، مع شريط الجانب للمخطط ونبكة النتائج المباشرة](/agenteye/images/query-lab.png) +![منشئ استعلام SQL يقوم بتشغيل استعلام محفوظ، مع شريط جانبي للمخطط وشبكة نتائج مباشرة](/agenteye/images/query-lab.png) -- **الشاشات** (`//dashboards`): حدّد الاستعلامات كبلاط خطية أو شريطية أو منطقة أو دائرية في شاشات مشتركة في جميع أنحاء المؤسسة. +- **لوحات المعلومات** (`//dashboards`): اضبط الاستعلامات كخط أو شريط أو منطقة أو بلاط دائري في لوحات معلومات مشتركة في جميع أنحاء المنظمة. -![شاشة مدمجة من الاستعلامات المحفوظة: خط أحداث لكل ساعة وشريط أخطاء حسب النوع ومخطط منطقة زمن انتظار والرموز حسب النموذج](/agenteye/images/dashboard-fleet.png) +![لوحة معلومات مبنية من الاستعلامات المحفوظة: خط أحداث في الساعة، شريط أخطاء حسب النوع، مخطط منطقة الكمون، والرموز حسب النموذج](/agenteye/images/dashboard-fleet.png) -- **التنبيهات** (`//alerts`): ارفع أي عتبة إلى قاعدة الصفحة التي تخطرك بالبريد الإلكتروني أو Slack أو webhook أو في الشاشة. انظر [enterprise-docs/alerts.md](/ar/agenteye/alerts). +- **التنبيهات** (`//alerts`): ارفع أي عتبة إلى قاعدة تصفية تخطر عبر البريد الإلكتروني أو Slack أو webhook أو لوحة المعلومات. انظر [enterprise-docs/alerts.md](/ar/agenteye/alerts). --- ## الخطوات التالية -- [النشر](/ar/agenteye/deployment): تعزيز للإنتاج +- [النشر](/ar/agenteye/deployment): تصلب للإنتاج - [مفاتيح API](/ar/agenteye/api-keys): إدارة الوصول -- [استكشاف الأخطاء](/ar/agenteye/troubleshooting): تشخيص المشاكل \ No newline at end of file +- [استكشاف الأخطاء والإصلاح](/ar/agenteye/troubleshooting): تشخيص المشاكل \ No newline at end of file diff --git a/docs/ar/agenteye/managed-deployment.mdx b/docs/ar/agenteye/managed-deployment.mdx index 5153bbff..51bf1db2 100644 --- a/docs/ar/agenteye/managed-deployment.mdx +++ b/docs/ar/agenteye/managed-deployment.mdx @@ -1,158 +1,158 @@ --- +--- title: "النشر المُدار على مجموعة Kubernetes الخاصة بك" description: "توثيق النشر المُدار لـ AgentEye على مجموعة Kubernetes الخاصة بك." --- +AgentEye هي منصة قابلة للاستضافة الذاتية لقابلية الملاحظة والتقييم لوكلاء الذكاء الاصطناعي وأنماط اللغة الكبيرة. تلتقط جلسات الوكيل واستدعاءات الأدوات وطلبات النموذج والأخطاء، وتحولها إلى تحليلات وتقييمات قابلة للبحث، وتعرض النتائج في لوحة معلومات مع مساعد ذكاء اصطناعي اختياري للقراءة فقط. -AgentEye هي منصة قابلة للاستضافة الذاتية للملاحظة والتقييم للوكلاء الذكيين وأنماط اللغات الكبيرة. تلتقط جلسات الوكيل واستدعاءات الأدوات وطلبات النموذج والأخطاء، وتحولها إلى تحليلات وتقييمات قابلة للبحث، وتعرض النتائج في لوحة معلومات مع مساعد ذكي قراءة فقط اختياري. - -في نموذج النشر المُدار، تقدم مجموعة Kubernetes مخصصة و Exosphere تقوم بتشغيل المنصة الكاملة بداخلها، وتنشر وتكوّن وتشغّل وتنسخ احتياطياً وتحدّث كل مكون بالنيابة عنك. يحصل فريقك على قيمة المنصة (رؤية الوكيل والتحليلات والتقييم والمساعد الاختياري) دون تشغيل قواعد البيانات أو الشهادات أو الترقيات. تبقى جميع البيانات ضمن حسابك السحابي. +في نموذج النشر المُدار، توفر مجموعة Kubernetes مخصصة ويقوم Exosphere بتشغيل المنصة الكاملة داخلها، ونشر وتكوين وتشغيل وعمل نسخ احتياطية وترقية كل مكون نيابة عنك. يحصل فريقك على قيمة المنصة (رؤية الوكيل والتحليلات والتقييم والمساعد الاختياري) دون الاضطرار إلى تشغيل قواعد البيانات أو الشهادات أو الترقيات. تبقى جميع البيانات ضمن حسابك السحابي. --- ## المتطلبات الأساسية -- **رمز GitHub PAT** لسحب صور الحاويات وتحميل القطع الأثرية (راجع [إعداد رمز GitHub](/ar/agenteye/github-token)) -- **مجموعة Kubernetes مخصصة** (راجع المتطلبات أدناه) -- **حاوية تخزين** للنسخ الاحتياطية من قاعدة البيانات -- **الاتصال بالشبكة**: المنفذ 443 بالداخل إلى موازن حمل المجموعة +- **GitHub PAT** لسحب صور الحاويات وتنزيل الكائنات (انظر [enterprise-docs/github-token.md](/ar/agenteye/github-token)) +- **مجموعة Kubernetes مخصصة** (انظر المتطلبات أدناه) +- **دلو التخزين** لنسخ احتياطية لقاعدة البيانات +- **الاتصال بالشبكة**: المنفذ 443 الوارد إلى موازن الحمل للمجموعة --- -## الخطوة 1: تجهيز مجموعة Kubernetes مخصصة +## الخطوة 1: توفير مجموعة Kubernetes مخصصة -أنشئ مجموعة Kubernetes مخصصة لـ AgentEye. يجب ألا تُشارك مع أحمال عمل أخرى، بحيث تعمل المنصة الكاملة (خدمات التطبيق وقواعس البيانات والتحليلات والتخزين المؤقت) بعزلة دون التأثير على البنية التحتية الموجودة لديك. +قم بإنشاء مجموعة Kubernetes مخصصة لـ AgentEye. يجب ألا تكون مشتركة مع أعباء عمل أخرى، بحيث تعمل المنصة الكاملة (خدمات التطبيقات وقواعس البيانات والتحليلات والتخزين المؤقت) بعزلة دون التأثير على البنية الحالية الموجودة لديك. | المتطلب | التفاصيل | |---|---| -| **التوزيع** | أي Kubernetes متوافق: EKS أو GKE أو AKS أو إدارة ذاتية | -| **الإصدار** | 1.27 أو أحدث | -| **مجموعة العُقد** | الحد الأدنى: **3 عُقد، 4 vCPU / 8 GB RAM لكل منها** (نوى الأغراض العامة القياسية) | -| **التخزين** | StorageClass افتراضي يوفر أحجام الكتل (على سبيل المثال `gp3` على AWS أو `pd-ssd` على GCP) | +| **التوزيع** | أي توزيع Kubernetes متوافق: EKS أو GKE أو AKS أو إدارة ذاتية | +| **الإصدار** | 1.27 أو إصدار أحدث | +| **مجموعة العقد** | الحد الأدنى: **3 عقد، 4 vCPU / 8 GB RAM لكل منها** (نماذج الأغراض العامة القياسية) | +| **التخزين** | StorageClass افتراضي ينشئ وحدات تخزين كتلة (مثل `gp3` على AWS أو `pd-ssd` على GCP) | | **موازن الحمل** | يجب أن تكون المجموعة قادرة على توفير خدمات LoadBalancer السحابية (افتراضي على EKS و GKE و AKS) | -> Exosphere تقوم بتثبيت وإدارة كل شيء آخر بداخل المجموعة: متحكمات الدخول وشهادات TLS وقواعد البيانات والتخزين المؤقت والمراقبة ونشر جميع التطبيقات. +> يقوم Exosphere بتثبيت وإدارة كل شيء آخر داخل المجموعة: متحكمات الدخول وشهادات TLS وقواعس البيانات والتخزين المؤقت والمراقبة وجميع نشرات التطبيقات. --- -## الخطوة 2: منح الوصول لفريق AgentEye +## الخطوة 2: منح الوصول إلى فريق AgentEye -تحتاج Exosphere إلى وصول cluster-admin (أو ما يعادله من RBAC واسع) لإدارة المساحات والتعريفات المورد المخصصة ومتحكمات الدخول وموفري التخزين. +يحتاج Exosphere إلى وصول cluster-admin (أو RBAC عريض مكافئ) لإدارة مساحات الأسماء وتعريفات الموارد المخصصة ومتحكمات الدخول ومجهزي التخزين. | المتطلب | التفاصيل | |---|---| | **طريقة الوصول** | دور IAM (مفضل لـ EKS/GKE) أو kubeconfig أو وصول قائم على SSO | -| **VPN / bastion** | إذا كان خادم واجهة برمجة تطبيقات Kubernetes خاصاً، قدم بيانات اعتماد VPN أو وصول bastion لفريق عمليات Exosphere | +| **VPN / bastion** | إذا كان خادم Kubernetes API خاصًا، وفر بيانات اعتماد VPN أو وصول bastion لفريق عمليات Exosphere | --- ## الخطوة 3: تكوين الاتصال بالشبكة -يحتاج فريق الشبكة الخاص بك إلى السماح بحركة المرور الواردة على **المنفذ 443** إلى موازنات حمل المجموعة. يقوم النشر بتشغيل اثنين من موازنات الحمل المنفصلة: واحد لاستقبال الأحداث (محمي بـ mTLS) وواحد للوحة المعلومات: +يحتاج فريق الشبكة لديك إلى السماح بحركة المرور الواردة على **المنفذ 443** إلى موازنات حمل المجموعة. يقوم النشر بتشغيل موازني حمل منفصلين: أحدهما لاستقبال الأحداث (محمي بـ mTLS) وواحد للوحة المعلومات: | حركة المرور | المصدر | الوجهة | الأمان | |---|---|---|---| -| **استقبال الأحداث** | حاويات المجمِّع في مجموعتك | موازن حمل الاستقبال، المنفذ 443 | mTLS (شهادة العميل) + مفتاح API | -| **لوحة المعلومات** | متصفحات المطورين | موازن حمل لوحة المعلومات، المنفذ 443 | HTTPS على مجالك، تسجيل الدخول بكلمة مرور لمرة واحدة عبر البريد الإلكتروني | +| **استقبال الأحداث** | حاويات Collector في مجموعاتك | موازن حمل الاستقبال، المنفذ 443 | mTLS (شهادة العميل) + مفتاح API | +| **لوحة المعلومات** | متصفحات المطورين | موازن حمل لوحة المعلومات، المنفذ 443 | HTTPS على نطاقك، تسجيل دخول OTP خالي من كلمة المرور عبر البريد الإلكتروني | -نقطة الاستقبال محمية بـ TLS المتبادل؛ يجب على المجمِّعات تقديم شهادة عميل صالحة **و** مفتاح API صالح في كل طلب. تعمل لوحة المعلومات على موازن حمل واسم مضيف خاصين بها، مع تقييد تسجيل الدخول إلى عناوين البريد الإلكتروني والنطاقات المسموحة بها. +تتم حماية نقطة الاستقبال بواسطة TLS المتبادل؛ يجب أن يقدم المجمعون شهادة عميل صحيحة **و** مفتاح API صحيح في كل طلب. تعمل لوحة المعلومات على موازن حمل واسم مضيف منفصل، مع تقييد تسجيل الدخول إلى عناوين البريد الإلكتروني/النطاقات المسموح بها لديك. -**سجلات DNS (مرة واحدة):** يمكنك إنشاء سجلي CNAME ضمن مجال تتحكم فيه — واحد لنقطة الاستقبال وواحد لوحة المعلومات (على سبيل المثال `agenteye.your-company.example`) — موجهاً إلى أسماء مضيفي موازن الحمل الذي توفره Exosphere. ثم تقوم Exosphere بتوفير شهادات TLS الموثوقة علناً لكلا أسماء المضيفين تلقائياً، بما في ذلك التجديدات. +**سجلات DNS (مرة واحدة):** يمكنك إنشاء سجلي CNAME ضمن نطاق تتحكم به — أحدهما لنقطة الاستقبال والآخر للوحة المعلومات (مثل `agenteye.your-company.example`) — يشير إلى أسماء مضيفات موازن الحمل التي يوفرها Exosphere. بعد ذلك، يقوم Exosphere بتوفير شهادات TLS الموثوقة علنًا لكلا اسمي المضيف تلقائيًا، بما في ذلك التجديدات. -> **ملاحظة المنفذ 80:** يتحقق إصدار الشهادات الآلي والتجديد على HTTP على المنفذ 80 من كل موازن حمل. إذا كان موقف الأمان الخاص بك يتطلب تقييد موازن حمل لوحة المعلومات على نطاقات IP الشركة، أخبر Exosphere أولاً — نحن نبدل التحقق من الشهادة إلى طريقة قائمة على DNS (سجل DNS إضافي واحد على جانبك) بحيث تستمر التجديدات في العمل خلف التقييد. +> **ملاحظة المنفذ 80:** يتم التحقق من إصدار الشهادة التلقائي والتجديد عبر HTTP على المنفذ 80 لكل موازن حمل. إذا كان وضع الأمان لديك يتطلب تقييد موازن حمل لوحة المعلومات على نطاقات IP الشركة، أخبر Exosphere أولاً — نحن ننتقل إلى طريقة التحقق القائمة على DNS (سجل DNS إضافي واحد من جانبك) بحيث تستمر التجديدات في العمل خلف القيد. -> **الصادرة:** يحتاج عُقد المجموعة إلى الوصول إلى الإنترنت لسحب صور الحاويات من `ghcr.io`. إذا كانت الشبكة الخاصة بك تقيد حركة المرور الصادرة، أدرج في القائمة البيضاء `ghcr.io` أو نسخ الصور احتياطياً إلى السجل الداخلي. +> **الصادر:** تحتاج عقد المجموعة إلى الوصول إلى الإنترنت لسحب صور الحاويات من `ghcr.io`. إذا كانت شبكتك تقيد حركة المرور الصادرة، أدرج `ghcr.io` في القائمة البيضاء أو انسخ الصور إلى السجل الداخلي لديك. --- -## الخطوة 4: توفير حاوية تخزين النسخ الاحتياطية +## الخطوة 4: توفير دلو تخزين النسخة الاحتياطية -يتم تخزين النسخ الاحتياطية من قاعدة البيانات في حاوية تخزين سحابية تمتلكها. +يتم تخزين النسخ الاحتياطية لقاعدة البيانات في دلو التخزين السحابي الذي تملكه. | المتطلب | التفاصيل | |---|---| | **الخدمة** | S3 (AWS) أو GCS (GCP) أو Azure Blob Storage | -| **الوصول** | منح الوصول للكتابة إلى عُقد المجموعة عبر دور IAM لحسابات الخدمات (IRSA على EKS أو Workload Identity على GKE) أو توفير بيانات الاعتماد | -| **الاحتفاظ** | أنت تتحكم في سياسة دورة حياة الحاوية (فترة الاحتفاظ وقواعد الأرشفة). تكتب Exosphere النسخ الاحتياطية؛ تقرر أنت المدة التي تريد الاحتفاظ بها | +| **الوصول** | امنح إذن الكتابة إلى عقد المجموعة عبر دور IAM لحسابات الخدمة (IRSA على EKS أو Workload Identity على GKE) أو وفر بيانات الاعتماد | +| **الاحتفاظ** | أنت تتحكم في سياسة دورة حياة دلو التخزين (فترة الاحتفاظ وقواعد الأرشفة). يكتب Exosphere النسخ الاحتياطية؛ أنت تقرر المدة التي تريد الاحتفاظ بها | -يقوم نسخة احتياطية واحدة يومية بتفريغ PostgreSQL (الحالة العلائقية) و ClickHouse (الأحداث والتقييمات) في أرشيف مضغوط واحد وتحميله إلى حاويتك. تعمل النسخ الاحتياطية أيضاً قبل كل ترقية. +تقوم نسخة احتياطية واحدة يومية بتفريغ كل من PostgreSQL (الحالة العلائقية) و ClickHouse (الأحداث والتقييمات) في أرشيف مضغوط واحد وتحميله إلى دلو التخزين الخاص بك. تعمل النسخ الاحتياطية أيضًا قبل كل ترقية. --- -## الخطوة 5: تعيين جهة اتصال +## الخطوة 5: تحديد جهة اتصال -وفِّر شخص واحد أو قناة Slack/Teams على جانبك لمشاكل مستوى المجموعة: صحة العُقدة وحدود حساب السحابة والتغييرات على الشبكة. العمليات اليومية لا تتضمن هذه الجهة الاتصال. +وفر شخصًا واحدًا أو قناة Slack/Teams من جانبك لمشاكل مستوى المجموعة: صحة العقدة وحدود حسابات السحابة والتغييرات في الشبكة. لا تتطلب عمليات يومية تدخل هذا الاتصال. --- ## ما ننشره -بمجرد حصول Exosphere على وصول المجموعة، يتم نشر المكونات التالية وإدارتها نيابة عنك: +بمجرد أن يحصل Exosphere على وصول المجموعة، يتم نشر المكونات التالية وإدارتها لك: | المكون | الدور | |---|---| -| **خادم AgentEye** | واجهة برمجة تطبيقات HTTP تستقبل الأحداث من المجمِّعات وتشغّل التحليلات وتوفر البيانات للوحة المعلومات | -| **لوحة المعلومات** | واجهة ويب لعرض جلسات الوكيل واستدعاءات الأدوات وطلبات النموذج والأخطاء؛ تستضيف المساعد الذكي القراءة فقط الاختياري | -| **ClickHouse** | المتجر القانوني المطلوب للأحداث المستقبلة والتحليلات والتقييمات | -| **PostgreSQL** | المتجر العلائقي للمؤسسات ومفاتيح API والمستخدمين لوحات المعلومات والاستعلامات المحفوظة | -| **Redis** | ذاكرة التخزين المؤقت المشتركة الاختيارية وخلفية حد المعدل؛ تتدهور المنصة بأمان إذا كانت غير متاحة | -| **المساعد الذكي (اختياري)** | حاوية مساعد قراءة فقط داخلية؛ تبقى معطلة حتى يتم تكوين نقطة نهاية LLM | -| **متحكمات الدخول** | اثنان من موازنات الحمل (واحد لاستقبال محمي بـ mTLS وواحد لوحة المعلومات) ينهيان TLS بشهادات موثوقة علناً وذاتية التجديد ويفرضان mTLS على نقطة الاستقبال | +| **خادم AgentEye** | واجهة برمجية HTTP تستقبل الأحداث من المجمعين وتشغل التحليلات وتقدم البيانات لوحة المعلومات | +| **لوحة المعلومات** | واجهة ويب لعرض جلسات الوكيل واستدعاءات الأدوات وطلبات النموذج والأخطاء؛ تستضيف مساعد الذكاء الاصطناعي الاختياري للقراءة فقط | +| **ClickHouse** | مخزن قانوني مطلوب للأحداث والتحليلات والتقييمات المستقبلة | +| **PostgreSQL** | مخزن العلائقي للمنظمات ومفاتيح API والمستخدمين ولوحات المعلومات والاستعلامات المحفوظة | +| **Redis** | ذاكرة تخزين مؤقت مشتركة اختيارية وخلفية حد معدل؛ تتدهور المنصة بأناقة إذا كانت غير متاحة | +| **مساعد الذكاء الاصطناعي (اختياري)** | حاوية مساعد داخلية للقراءة فقط؛ تبقى معطلة حتى يتم تكوين نقطة نهاية LLM | +| **متحكمات الدخول** | موازنا حمل منفصلين (أحدهما لاستقبال محمي بـ mTLS والآخر للوحة المعلومات) يكملان TLS بشهادات موثوقة علنًا وقابلة للتجديد التلقائي وتطبق mTLS على نقطة الاستقبال | | **cert-manager** | يؤتمت توفير شهادات TLS وإصدار شهادات عميل mTLS | -| **مراقبة الشهادات** | تفحص مهمة مجدولة انقضاء الشهادة وتُرسل تنبيهات (على سبيل المثال إلى Slack) عندما تقترب الشهادات من التجديد | +| **مراقبة الشهادة** | تتحقق وظيفة مجدولة من انتهاء صحة الشهادة وترسل تنبيهات (مثل إلى Slack) عندما تقترب الشهادات من التجديد | -يقوم العرض المُدار أيضاً بتشغيل خط أنابيب التقييم الخاص بالمنصة، والذي يسجل نشاط الوكيل مقابل معايير التقييم الخاصة بك. راجع [المساعد](/ar/agenteye/assistant) و [مجموعة التقييم](/ar/agenteye/evaluation-suite) لمعرفة ما تقدمه هذه القدرات. +تعمل الخدمة المُدارة أيضًا على خط أنابيب التقييم الخاص بالمنصة، والذي يسجل نشاط الوكيل مقابل معايير التقييم الخاصة بك. انظر [enterprise-docs/assistant.md](/ar/agenteye/assistant) و [enterprise-docs/evaluation-suite.md](/ar/agenteye/evaluation-suite) لتعرف على ما توفره هذه الإمكانيات. --- ## ما نوفره لك -بعد اكتمال النشر، تتلقى: +بعد انتهاء النشر، تتلقى: -| العنصر | التفاصيل | +| البند | التفاصيل | |---|---| -| **عنوان URL لوحة المعلومات** | اسم مضيف ضمن مجالك (على سبيل المثال `https://agenteye.your-company.example`)، موفر بشهادة TLS موثوقة علناً وذاتية التجديد. أنت تنشئ CNAME واحد لاسم مضيف موازن الحمل الذي توفره؛ تسجيل الدخول هو بكلمة مرور لمرة واحدة عبر البريد الإلكتروني | -| **نقطة نهاية المجمِّع** | مسار `/events` لاسم المضيف الخاص بالاستقبال (على سبيل المثال `https://ingest.your-company.example/events`)، محمي بـ mTLS | -| **حزمة شهادة العميل** | لكل مجموعة: شهادة عميل ومفتاح خاص وشهادة CA يتم تسليمها كبيان Secret من Kubernetes. طبِّقها مرة واحدة لكل مجموعة | -| **رمز GitHub** | لتحميل ثنائيات المجمِّع وحزم Python SDK | -| **مفاتيح API للمجمِّع** | مفاتيح مجالها بـ `events:add`، واحد لكل نشر مجمِّع | -| **أدلة التثبيت** | أدوات خطوة بخطوة لتثبيت المجمِّع و Python SDK | +| **عنوان URL لوحة المعلومات** | اسم مضيف ضمن نطاقك (مثل `https://agenteye.your-company.example`)، مقدم مع شهادة TLS موثوقة علنًا وقابلة للتجديد التلقائي. يمكنك إنشاء CNAME واحد لاسم مضيف موازن الحمل الذي نوفره؛ تسجيل الدخول هو بريد إلكتروني OTP خالي من كلمة المرور | +| **نقطة نهاية Collector** | مسار `/events` لاسم مضيف الاستقبال (مثل `https://ingest.your-company.example/events`)، محمي بـ mTLS | +| **حزمة شهادة العميل** | لكل مجموعة: شهادة عميل ومفتاح خاص وشهادة CA يتم تسليمها كبيان Secret في Kubernetes. طبقها مرة واحدة لكل مجموعة | +| **GitHub PAT** | لتنزيل ملفات Collector الثنائية وحزم Python SDK | +| **مفاتيح API Collector** | مفاتيح محدودة النطاق بإذن `events:add`، واحد لكل نشر Collector | +| **أدلة التثبيت** | مستندات خطوة بخطوة لـ Collector و Python SDK | --- ## ما تفعله بعد الإعداد -يقتصر العمل الجاري الوحيد على أجهزة الوكيل الخاصة بك، وليس مجموعة AgentEye: +العمل الوحيد المستمر لديك هو على آلات الوكيل الخاصة بك، وليس على مجموعة AgentEye: -1. **ثبت المجمِّع** في كل مجموعة Kubernetes التي تشغّل وكلاء ذكيين: اربط شهادة العميل وكوِّن عنوان URL لنقطة النهاية ومفتاح API. راجع [تثبيت المجمِّع](/ar/agenteye/collector-installation). -2. **دمِّج Python SDK** في رمز الوكيل الخاص بك. راجع [Python SDK](/ar/agenteye/python-sdk). -3. **افتح لوحة المعلومات** في متصفحك لعرض نشاط الوكيل. +1. **ثبت Collector** في كل مجموعة Kubernetes التي تقوم بتشغيل وكلاء الذكاء الاصطناعي: ركب شهادة العميل وكوّن عنوان نقطة النهاية ومفتاح API. انظر [enterprise-docs/collector-installation.md](/ar/agenteye/collector-installation). +2. **دمج Python SDK** في كود الوكيل الخاص بك. انظر [enterprise-docs/python-sdk.md](/ar/agenteye/python-sdk). +3. **افتح لوحة المعلومات** في المتصفح الخاص بك لعرض نشاط الوكيل. -لا عمليات مجموعة ولا إدارة قاعدة بيانات ولا تجديدات شهادات ولا ترقيات. +لا توجد عمليات مجموعة ولا إدارة قاعدة بيانات ولا تجديدات شهادات ولا ترقيات. --- ## الأمان -- **البيانات تبقى في حسابك السحابي.** تعمل المجموعة والتخزين وقواعد البيانات في بيئتك. لا توجد بيانات تتجاوز حدودك. -- **أنت تتحكم في الوصول.** المجموعة في حسابك. يمكنك تدقيق أو مراقبة أو سحب وصول Exosphere في أي وقت. تمر جميع العمليات عبر سجل التدقيق السحابي (CloudTrail و GCP Audit Logs وما إلى ذلك). -- **mTLS على استقبال الأحداث.** يتطلب كل طلب مجمِّع شهادة عميل صالحة ومفتاح API. مفتاح مُسرب بلا فائدة بدون الشهادة؛ شهادة مسروقة بلا فائدة بدون مفتاح صالح. -- **التحكم بالوصول إلى لوحة المعلومات.** تعمل لوحة المعلومات على موازن حمل منفصل، منفصل عن استقبال الأحداث، وتسجيل الدخول هو بكلمة مرور لمرة واحدة عبر البريد الإلكتروني مقيدة بعناوين البريد الإلكتروني/النطاقات المسموحة بها. قائمة السماح بنطاق مصدر IP على موازن الحمل متاحة عند الطلب؛ لأن تجديد الشهادات الآلي يجب أن يصل إلى موازن الحمل، Exosphere يقيّد التقييد بالتحقق من الشهادة القائم على DNS بحيث تستمر التجديدات في العمل. -- **شهادات لكل مجموعة.** تتلقى كل مجموعة من مجموعاتك شهادة عميل خاصة بها. إذا تم اختراق مجموعة واحدة، يتم سحب تلك الشهادة بشكل مستقل دون التأثير على الآخرين. +- **البيانات تبقى في حسابك السحابي.** المجموعة والتخزين وقواعس البيانات كلها تعمل في بيئتك. لا تترك أي بيانات حدودك. +- **أنت تتحكم في الوصول.** المجموعة في حسابك. يمكنك تدقيق أو مراقبة أو إلغاء وصول Exosphere في أي وقت. تمر جميع العمليات عبر سجل المراجعة السحابي (CloudTrail و GCP Audit Logs وما إلى ذلك). +- **mTLS على استقبال الأحداث.** يتطلب كل طلب Collector شهادة عميل صحيحة **و** مفتاح API. مفتاح مسرّب بلا فائدة بدون الشهادة؛ شهادة مسروقة بلا فائدة بدون مفتاح صحيح. +- **التحكم في وصول لوحة المعلومات.** تعمل لوحة المعلومات على موازن حمل منفصل، منفصلة عن استقبال الأحداث، وتسجيل الدخول هو بريد إلكتروني OTP خالي من كلمة المرور مقيد بعناوين البريد الإلكتروني/النطاقات المسموح بها. قائمة بيضاء بنطاق IP المصدر على موازن الحمل متاحة عند الطلب؛ لأن تجديد الشهادة التلقائي يجب أن يصل إلى موازن الحمل، يقترن Exosphere القيد بالتحقق من الشهادة القائم على DNS بحيث تستمر التجديدات في العمل. +- **شهادات لكل مجموعة.** تتلقى كل مجموعة من مجموعاتك شهادة عميل خاصة بها. إذا تم اختراق مجموعة واحدة، يتم إلغاء تلك الشهادة بشكل مستقل دون التأثير على الآخرين. --- -## الجدول الزمني للنشر +## مخطط النشر الزمني | المرحلة | المدة | مشاركتك | |---|---|---| -| **تجهيز المجموعة** | 1-2 يوم | جهِّز المجموعة ومنح Exosphere الوصول | -| **إعداد المنصة** | 1 يوم | بلا؛ Exosphere تثبت جميع مكونات البنية التحتية | -| **نشر التطبيق** | 1 يوم | بلا؛ Exosphere تنشر الخادم ولوحة المعلومات وتنشئ مفاتيح API | -| **طرح المجمِّع** | 1-3 يوم | ثبت المجمِّعات في مجموعاتك (بتوجيه من Exosphere) | -| **حرق الإنتاج** | 1 أسبوع | بلا؛ Exosphere تراقب وتضبط | +| **توفير المجموعة** | 1-2 يوم | وفر المجموعة ومنح وصول Exosphere | +| **إعداد المنصة** | 1 يوم | بلا؛ يقوم Exosphere بتثبيت جميع مكونات البنية الأساسية | +| **نشر التطبيق** | 1 يوم | بلا؛ يقوم Exosphere بنشر الخادم ولوحة المعلومات وإنشاء مفاتيح API | +| **طرح Collector** | 1-3 أيام | ثبت المجمعات في مجموعاتك (بإرشادات من Exosphere) | +| **فترة الاحتراق الإنتاجية** | 1 أسبوع | بلا؛ يراقب Exosphere وينقح | -الإجمالي المعتاد: **~أسبوعين** من البداية إلى جاهزية الإنتاج. +الإجمالي النموذجي: **~أسبوعين** من البداية إلى جاهزية الإنتاج. --- @@ -164,8 +164,8 @@ AgentEye هي منصة قابلة للاستضافة الذاتية للملاح ## الخطوات التالية -- [البدء السريع](/ar/agenteye/getting-started): شرح شامل من النهاية إلى النهاية -- [تثبيت المجمِّع](/ar/agenteye/collector-installation): ثبت وكوِّن المجمِّع -- [Python SDK](/ar/agenteye/python-sdk): شغِّل رمز الوكيل الخاص بك -- [مفاتيح API](/ar/agenteye/api-keys): إدارة الوصول والأذونات -- [استكشاف الأخطاء](/ar/agenteye/troubleshooting): المشاكل الشائعة والإصلاحات \ No newline at end of file +- [Getting Started](/ar/agenteye/getting-started): شرح شامل من البداية إلى النهاية +- [Collector Installation](/ar/agenteye/collector-installation): ثبت وكوّن Collector +- [Python SDK](/ar/agenteye/python-sdk): أداة كود الوكيل الخاص بك +- [API Keys](/ar/agenteye/api-keys): إدارة الوصول والأذونات +- [Troubleshooting](/ar/agenteye/troubleshooting): المشاكل الشائعة والحلول \ No newline at end of file diff --git a/docs/de/agenteye/audits.mdx b/docs/de/agenteye/audits.mdx index 6f49fb55..f3c4ff3e 100644 --- a/docs/de/agenteye/audits.mdx +++ b/docs/de/agenteye/audits.mdx @@ -4,104 +4,103 @@ description: "AgentEye Audits — Dokumentation zur agentischen Verbesserungserk --- -Audits sind wiederkehrende Jobs, die Ihre Agent-Logs **sitzungsübergreifend** durchsuchen, um verbesserungswürdige Stellen zu finden. Während ein Alert eine einzelne, bereits bekannte Kennzahl nahezu in Echtzeit überwacht, *untersucht* ein Audit: Nach einem von Ihnen festgelegten Zeitplan führt er einen deterministischen Policy-Durchlauf über das Zeitfenster aus und setzt anschließend einen **KI-Zuverlässigkeits-Agenten** auf Ihre Sitzungen an — der Agent fragt die Daten selbst ab, liest verdächtige Transkripte und führt (wenn hilfreich) kleine Analyseskripte aus, bevor er **Verbesserungsempfehlungen** mit den jeweiligen Belegen verfasst. +Audits sind wiederkehrende Jobs, die Ihre Agent-Logs **sitzungsübergreifend** durchsuchen, um verbesserungswürdige Aspekte zu finden. Während ein Alert eine bestimmte Kennzahl in nahezu Echtzeit überwacht, *untersucht* ein Audit: Nach einem von Ihnen festgelegten Zeitplan führt er einen deterministischen Policy-Durchlauf über das Zeitfenster aus, setzt dann einen **KI-Zuverlässigkeitsagenten** auf Ihre Sitzungen an — der Agent fragt die Daten selbst ab, liest verdächtige Transkripte und führt (wo hilfreich) kleine Analyseskripte aus. Anschließend erstellt er **Verbesserungsempfehlungen** mit den jeweiligen Belegen. -Nutzen Sie Audits, um die Frage „Was sollte ich in meinen Agents beheben oder verbessern?" zu beantworten — und Alerts, um sofort benachrichtigt zu werden, sobald ein bestimmter Schwellenwert überschritten wird. Jede Verbesserung verweist auf die genauen Sitzungen und Abfragen, die ihr zugrunde liegen, und ein einziger Klick erstellt einen vorbefüllten Alert, um Wiederholungen abzufangen. +Nutzen Sie Audits, um die Frage zu beantworten „Was sollte ich an meinen Agenten beheben oder verbessern?" — und Alerts, um sofort benachrichtigt zu werden, wenn ein bestimmter Schwellenwert überschritten wird. Jede Verbesserung verweist auf die genauen Sitzungen und Abfragen, auf denen sie basiert, und mit einem Klick lässt sich ein vorbefüllter Alert erstellen, um erneutes Auftreten zu erkennen. -Die Dashboard-Oberfläche befindet sich unter **`//audits`** (Seitenleiste → *analyze* → *audits*) und ist durch die Berechtigungen `audits:read` / `audits:write` geschützt. +Die Dashboard-Oberfläche ist **`//audits`** (Seitenleiste → *analyze* → *audits*), geschützt durch die Berechtigungen `audits:read` / `audits:write`. --- -## Ablauf eines Durchlaufs +## Ablauf eines Runs -Jeder Durchlauf besteht aus zwei Schichten — einem deterministischen Fundament und einer agentischen Untersuchung. +Jeder Run besteht aus zwei Schichten — einer deterministischen Grundlage und einer agentischen Untersuchung. ### 1. Der Policy-Durchlauf (deterministisch) -Bevor ein Modell ausgeführt wird, führt der Audit einen kleinen Katalog von **SQL-Policy-Prüfungen** über das Zeitfenster aus: begrenzte Aggregatabfragen, die bekannte Fehlermuster kennzeichnen und melden, *wie viele* Ereignisse / *welche* Sitzungen übereinstimmen — niemals den übereinstimmenden Text selbst. Der Katalog umfasst: +Bevor ein Modell ausgeführt wird, führt das Audit einen kleinen Katalog von **SQL-Policy-Prüfungen** über das Zeitfenster aus: begrenzte Aggregatabfragen, die bekannte Fehlermuster erkennen und melden, *wie viele* Ereignisse / *welche* Sitzungen übereinstimmten — niemals den übereinstimmenden Text selbst. Der Katalog umfasst: -- **Geheimnis-/Zugangsdaten-Lecks** in Event-Payloads — AWS-Zugriffsschlüssel, `sk-…`-API-Schlüssel, PEM-Privatschlüssel, JWT-/Bearer-Tokens und `KEY=…`-Zugangsdatenzuweisungen. +- **Geheimnis-/Credential-Leaks** in Event-Payloads — AWS Access Keys, `sk-…` API-Keys, PEM-Private-Keys, JWT-/Bearer-Tokens und `KEY=…`-Credential-Zuweisungen. - **Prompt-Injection-Marker** — „ignore previous instructions", „reveal your system prompt" und Ähnliches. -- **PII** — SSN-artige Nummern (heuristisch). -- **Werkzeugberechtigungs-Ablehnungen** und **unkontrollierte Werkzeugaufruf-Schleifen**. +- **PII** — SSN-förmige Zahlen (heuristisch). +- **Tool-Berechtigungsablehnungen** und **außer Kontrolle geratene Tool-Call-Schleifen**. -Policy-Treffer werden als Findings (Art `policy`) gespeichert, die **immer angezeigt werden** (sie werden nie durch das Durchlaufs-Limit gekürzt) und dem KI-Agenten als erste Anhaltspunkte übergeben. Da diese Schicht kein Modell benötigt, liefert ein Audit seine wichtigsten Sicherheitssignale auch dann, wenn der KI-Agent nicht verfügbar ist. +Policy-Treffer werden als Findings (Typ `policy`) gespeichert, die **immer angezeigt werden** (sie werden nie durch das pro-Run-Limit beschnitten), und sie werden dem KI-Agenten als Ausgangspunkte übergeben. Da diese Schicht kein Modell benötigt, liefert ein Audit seine wichtigsten Sicherheitssignale auch dann, wenn der KI-Agent nicht verfügbar ist. ### 2. Die agentische Untersuchung (KI) -Der Audit führt anschließend einen **autonomen Zuverlässigkeits-Agenten** aus (denselben Claude Agent SDK-Dienst, der den Dashboard-Assistenten antreibt, mit einem audit-spezifischen Prompt). Basierend auf dem **Scope** des Audits (ausgewählte Agents × Umgebungen) und dem **Zeitfenster** führt der Agent folgende Schritte durch: +Das Audit führt dann einen **autonomen Zuverlässigkeitsagenten** aus (denselben Claude Agent SDK-Dienst, der auch den Dashboard-Assistenten antreibt, mit einem auditspezifischen Prompt). Gegeben den **Scope** des Audits (ausgewählte Agenten × Umgebungen) und das **Zeitfenster** führt der Agent folgende Schritte aus: - Er führt schreibgeschützte SQL-Abfragen gegen Ihre Analytics-Tabellen aus, - liest eine Handvoll repräsentativer Sitzungstranskripte, -- schreibt und führt optional kurze **Python-Skripte in einer abgesicherten In-Pod-Sandbox** aus (kein Netzwerkzugriff, kein Dateisystemzugriff, Geheimnisse werden entfernt), um Analysen durchzuführen, die SQL nicht ausdrücken kann — Fehler-Clustering, Verteilungsberechnungen, Durchsuchen bereits abgerufener Payloads, -- und dokumentiert jede gut belegte **Verbesserung**, die er findet. +- schreibt und führt optional kurze **Python-Skripte in einer abgesicherten In-Pod-Sandbox** aus (kein Netzwerk, kein Dateisystemzugriff, Secrets entfernt) für Analysen, die SQL nicht ausdrücken kann — Fehler-Clustering, Berechnung von Verteilungen, Durchsuchen bereits abgerufener Payloads, +- und zeichnet jede gut belegte **Verbesserung** auf, die er findet. -Er arbeitet sich durch mehrere Untersuchungslinien — Fehler-Clustering, Drift gegenüber einer Basislinie, Zielverfehlung in Transkripten, Werkzeugmissbrauch, Qualitäts-/Kosten-Kompromisse und Abdeckungslücken — entsprechend der **Sensitivität** des Audits (niedrig / mittel / hoch). Jede Verbesserung **muss Belege zitieren**: die Sitzungs-IDs, die der Agent tatsächlich inspiziert hat, und/oder das ausgeführte SQL. Der Server überprüft, ob die zitierten Sitzungen existieren, und **verwirft jede Verbesserung ohne überlebenden Beleg** — der Agent untersucht also, erfindet aber nichts. +Er arbeitet mehrere Untersuchungslinien durch — Fehler-Clustering, Drift gegenüber einer Baseline, Zielverfehlung in Transkripten, Tool-Missbrauch, Qualitäts-/Kosten-Abwägungen und Abdeckungslücken — entsprechend der **Sensitivität** des Audits (niedrig / mittel / hoch). Jede Verbesserung **muss Belege anführen**: die tatsächlich untersuchten Sitzungs-IDs und/oder das ausgeführte SQL. Der Server überprüft, ob die angeführten Sitzungen existieren, und **verwirft jede Verbesserung ohne verbleibende Belege** — der Agent untersucht also, erfindet aber nie. Jede Verbesserung enthält: -- eine **Empfehlung** (die konkrete Maßnahme — eine Prompt-Anpassung, eine Werkzeugschema-Korrektur, eine Retry-Richtlinie, eine Schutzmaßnahme, mehr Eval-Abdeckung), -- eine **erwartete Wirkung** und eine **Aufwandsschätzung** (niedrig / mittel / hoch), -- eine **Schwere** — `big` (ein Operator sollte benachrichtigt werden), `medium` (gehört in den Durchlaufsbericht) oder `small` (Dashboard-Kontext), -- einen stabilen **Fingerabdruck** (aus der Kategorie + dem Scope des Problems, *nicht* den Sitzungen dieses Durchlaufs), sodass dasselbe Problem von Durchlauf zu Durchlauf verfolgt wird, auch wenn sich die Belege ändern, -- und, falls ein einfacher deterministischer Watcher das Wiederauftreten erkennen könnte, einen **vorgeschlagenen Alert**, den Sie mit einem Klick erstellen können. +- eine **Empfehlung** (die konkrete Änderung — eine Prompt-Anpassung, eine Tool-Schema-Korrektur, eine Retry-Policy, ein Guardrail, mehr Eval-Abdeckung), +- einen **erwarteten Impact** und eine **Aufwandsschätzung** (niedrig / mittel / hoch), +- eine **Größenordnung** — `big` (ein Operator sollte benachrichtigt werden), `medium` (gehört in den Run-Bericht) oder `small` (Dashboard-Kontext), +- einen stabilen **Fingerprint** (aus der Kategorie + dem Scope des Problems, *nicht* aus den Sitzungen dieses Runs), damit dasselbe Problem run-übergreifend verfolgt wird, auch wenn sich die Belege ändern, +- und, wo ein einfacher deterministischer Watcher das erneute Auftreten erkennen könnte, einen **vorgeschlagenen Alert**, den Sie mit einem Klick erstellen können. -> **Die KI-Schicht ist optional, aber empfohlen.** Wenn kein KI-Agent für die Audit-Pipeline konfiguriert ist, werden Durchläufe trotzdem ausgeführt, die Policy-Findings gespeichert, und für die agentische Schicht wird ehrlich „Analyse nicht verfügbar" gemeldet, anstatt stillschweigend zu bestehen. +> **Die KI-Schicht ist optional, wird aber empfohlen.** Wenn kein KI-Agent für die Audit-Pipeline konfiguriert ist, werden Runs trotzdem ausgeführt, die Policy-Findings gespeichert und für die agentische Schicht ehrlich „Analyse nicht verfügbar" gemeldet, anstatt stillschweigend zu bestehen. ### Fehlermodi -Verbesserungen werden in den dauerhaften **Fehlermodus-Katalog** Ihrer Organisation eingeordnet (oder schlagen einen neuen Modus vor). Modi geben Mustern eine stabile Identität über Durchläufe hinweg und ermöglichen eine langfristige Wiederauftritts-Verfolgung. +Verbesserungen werden in den dauerhaften **Fehlermodus-Katalog** Ihrer Organisation eingeordnet (oder schlagen einen neuen Modus vor). Modi geben Mustern eine stabile Identität über Runs hinweg und ermöglichen die Nachverfolgung von Wiederauftreten über längere Zeiträume. ## Triage-Lebenszyklus Auf einer Finding-Seite (`/audits//findings/`): -| Aktion | Wirkung | +| Aktion | Effekt | |---|---| -| **acknowledge** | Hält das Finding sichtbar, halbiert aber seine Priorität. | -| **resolve** | Markiert es als behoben. Wenn das Muster später tatsächlich wieder auftritt, wird es als **neu** wieder geöffnet — eine Regression ist also deutlich sichtbar und wird nicht stillschweigend in die Historie eingefaltet. | -| **mute** / **dismiss** | Dauerhafte Unterdrückung: Der Fingerabdruck des Musters wird gespeichert und taucht nie wieder auf, auch nicht über Durchläufe hinweg. Verwenden Sie mute für „bekannt, akzeptiert"; dismiss für „nicht nützlich". | -| **reopen** | Hebt die Unterdrückung/Auflösung auf und stuft das Muster wieder ein. | -| **assign** | Weist das Finding einem Operator (einem Organisationsmitglied) zur Verantwortung zu. Priorität und Unterdrückungsstatus bleiben unverändert. | +| **acknowledge** | Behält das Finding sichtbar, halbiert aber seine Priorität. | +| **resolve** | Markiert es als behoben. Tritt das Muster später tatsächlich erneut auf, wird es als **neu** wieder geöffnet — eine Regression ist also auffällig, wird nicht stillschweigend in die Geschichte eingefügt. | +| **mute** / **dismiss** | Dauerhafte Unterdrückung: Der Fingerprint des Musters wird gespeichert und taucht nie wieder auf, auch nicht über Runs hinweg. Verwenden Sie mute für „bekannt, akzeptiert"; dismiss für „nicht nützlich". | +| **reopen** | Hebt die Unterdrückung/Lösung auf und stuft das Muster erneut ein. | -Rauschen mit geringem Signalgehalt wird pro Audit mit einem Finding-Limit pro Durchlauf (`top_k`) für die agentischen Verbesserungen gesteuert. Policy-Findings umgehen das Limit (sie sind sicherheitsrelevant und werden immer angezeigt). Alles, was durch das Limit abgeschnitten wird, zählt in den Statistiken des Durchlaufs — nichts wird stillschweigend verworfen. +Rauschen mit geringem Signalwert wird pro Audit mit einem pro-Run-Finding-Limit (`top_k`) für agentische Verbesserungen kontrolliert. Policy-Findings umgehen das Limit (sie sind sicherheitsrelevant und werden immer angezeigt). Alles, was durch das Limit herausfällt, wird in den Run-Statistiken gezählt — nichts wird stillschweigend verworfen. ## Zeitplanung -- **Takt** (`schedule_interval_secs`): stündlich bis wöchentlich; **täglich ist der Standard**. Audits sind bewusst grobkörniger als Alerts — eine agentische Untersuchung scannt ganze Zeitfenster und läuft minutenlang. -- **Fenster**: entweder ein fester rollierender Rückblickzeitraum (z. B. „jeder Durchlauf scannt die letzten 7 Tage") oder **since-last-run** (der Standard) — jeder Durchlauf setzt dort fort, wo der vorherige erfolgreiche endete, mit einer kleinen Überschneidung, damit Grenz-Ereignisse nie verpasst werden. -- Der nächste Durchlauf wird einen vollständigen Intervall nach **Abschluss** des vorherigen geplant, sodass ein langsamer Durchlauf nie einen zweiten gleichzeitigen Durchlauf desselben Audits auslöst. +- **Kadenz** (`schedule_interval_secs`): stündlich bis wöchentlich; **täglich ist der Standard**. Audits sind bewusst grobkörniger als Alerts — eine agentische Untersuchung scannt ganze Zeitfenster und läuft minutenlang. +- **Fenster**: entweder ein fester rollierender Lookback (z. B. „jeder Run scannt die letzten 7 Tage") oder **since-last-run** (der Standard) — jeder Run setzt dort an, wo der vorherige erfolgreiche endete, mit einer kleinen Überlappung, damit Grenzereignisse nie verpasst werden. +- Der nächste Run wird ein volles Intervall nach dem **Abschluss** des vorherigen geplant, sodass ein langsamer Run nie einen zweiten gleichzeitigen Run desselben Audits auslöst. - **Run now** auf der Audit-Seite macht ihn sofort fällig. ## Modellauswahl -Beim Erstellen eines Audits können Sie auswählen, welches Modell die Untersuchung verwendet — aus der **Liste der Modelle, die Ihr Operator für den Agent-Dienst konfiguriert hat**. Bei einem einzigen konfigurierten Modell zeigt die Auswahl es als Beschriftung an; bei mehreren wählen Sie selbst. Ohne Auswahl wird das konfigurierte Standardmodell verwendet. +Bei der Erstellung eines Audits können Sie auswählen, welches Modell die Untersuchung verwendet — aus der **Liste der Modelle, die Ihr Operator für den Agentendienst konfiguriert hat**. Bei einem einzigen konfigurierten Modell zeigt die Auswahl es als Beschriftung an; bei mehreren wählen Sie aus. Ohne Auswahl wird das konfigurierte Standardmodell verwendet. ## Benachrichtigungen -Wenn ein Durchlauf **neue** Findings aufdeckt, benachrichtigt der Audit die konfigurierten Kanäle Ihrer Organisation — dieselbe `alerts.enabled_channels`-Steuerung und Einstellungen, die auch die Alert-Pipeline verwendet: +Wenn ein Run **neue** Findings ergibt, benachrichtigt das Audit die konfigurierten Kanäle Ihrer Organisation — dasselbe `alerts.enabled_channels`-Gate und dieselben Einstellungen, die auch die Alerts-Pipeline verwendet: -- **Slack** — eine Zusammenfassung der bedeutenden (`big`) neuen Einträge mit einem Deep-Link. -- **E-Mail** — ein gestalteter **Auditbericht** mit den neuen Verbesserungen (höchste Schwere, Empfehlungen pro Eintrag, Deep-Link), der versendet wird, wenn der Audit einen **E-Mail**-Kanal angehängt hat und mindestens ein neues Finding vorliegt. +- **Slack** — eine Zusammenfassung der bedeutsamen (`big`) neuen Einträge mit einem Deep Link. +- **E-Mail** — ein gestalteter **Audit-Bericht** mit den neuen Verbesserungen (höchster Schweregrad, Empfehlungen pro Eintrag, Deep Link), der gesendet wird, wenn das Audit einen **E-Mail**-Kanal hat und mindestens ein neues Finding vorliegt. Wiederkehrende, aber bekannte Findings lösen keine erneute Benachrichtigung aus. ## Konfigurationsreferenz -Audit-Definitionen werden im Dashboard (`/audits/new`) oder über die API verwaltet. Audit-spezifische Einstellungen umfassen den Zeitplan-Takt und das Fenster, den Scope (`{"environments": [...], "agent_ids": [...]}`), die Sensitivität (`low` / `medium` / `high`), die Benachrichtigungskanäle, das Finding-Limit pro Durchlauf (`top_k`) und das Modell (über `llm_budget.model`). Operator-seitige Servereinstellungen (Timeouts, Sandbox, die Agent-Dienst-URL) sind in [deployment.md](/de/agenteye/deployment) dokumentiert. +Audit-Definitionen werden im Dashboard (`/audits/new`) oder über die API verwaltet. Pro-Audit-Einstellungen umfassen die Zeitplan-Kadenz und das Fenster, den Scope (`{"environments": [...], "agent_ids": [...]}`), die Sensitivität (`low` / `medium` / `high`), die Benachrichtigungskanäle, das pro-Run-Finding-Limit (`top_k`) und das Modell (über `llm_budget.model`). Einstellungen auf Operator-Ebene (Timeouts, Sandbox, die Agent-Service-URL) sind in [deployment.md](/de/agenteye/deployment) dokumentiert. ## API -Alle Endpunkte sind organisations-begrenzt und folgen der Standard-Bearer-Key-Authentifizierung (siehe [api-keys.md](/de/agenteye/api-keys)). +Alle Endpunkte sind org-bezogen und verwenden die Standard-Bearer-Key-Authentifizierung (siehe [api-keys.md](/de/agenteye/api-keys)). | Endpunkt | Berechtigung | Zweck | |---|---|---| | `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | Audit-Definitionen auflisten / erstellen. | -| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Einen Audit inspizieren, bearbeiten, löschen. | -| `POST /audits/:id/run` | `audits:write` | Den Audit sofort fällig machen. | -| `GET /audits/:id/runs` | `audits:read` | Durchlaufshistorie (Fenster, Status, Statistiken, Finding-Anzahl). | +| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Ein Audit einsehen, bearbeiten, löschen. | +| `POST /audits/:id/run` | `audits:write` | Das Audit sofort fällig machen. | +| `GET /audits/:id/runs` | `audits:read` | Run-Verlauf (Fenster, Status, Statistiken, Finding-Anzahl). | | `GET /audits/findings` | `audits:read` | Organisationsweite Findings, filterbar nach `audit_id`, `status`; nach Priorität sortiert. | -| `GET /audits/findings/:fid` | `audits:read` | Vollständige Finding-Details (Empfehlung, Belege, Priorität). | +| `GET /audits/findings/:fid` | `audits:read` | Vollständiges Finding-Detail (Empfehlung, Belege, Priorität). | | `POST /audits/findings/:fid/status` | `audits:write` | Triage: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | Für „Audit wurde ausgeführt, hat aber nichts gefunden", „die Code-Sandbox ist deaktiviert" und „Audit-E-Mail wurde nicht zugestellt" siehe [troubleshooting.md](/de/agenteye/troubleshooting#audits). \ No newline at end of file diff --git a/docs/de/agenteye/cli-recipes.mdx b/docs/de/agenteye/cli-recipes.mdx index 21af03b2..ef421618 100644 --- a/docs/de/agenteye/cli-recipes.mdx +++ b/docs/de/agenteye/cli-recipes.mdx @@ -3,113 +3,112 @@ title: "CLI-Rezepte für Agenten" description: "AgentEye CLI-Rezepte für die Agenten-Dokumentation." --- +Sitzungs-, Ereignis- und Evaluierungsdaten direkt aus einem Skript oder Coding-Agenten abrufen (und Neubewertungen auslösen) – mit sauberem JSON auf stdout, das sich direkt in `jq` pipen lässt. Diese Rezepte machen AgentEyes Observability-Daten für Terminal-Nutzer oder KI-Coding-Agenten (Claude Code, Cursor) abfragbar und automatisierbar, ohne durch das Dashboard zu klicken. -Sitzungs-, Ereignis- und Auswertungsdaten direkt aus einem Skript oder Coding-Agenten abrufen (und erneute Auswertungen auslösen) – mit sauberem JSON auf stdout, das sich direkt in `jq` einleiten lässt. Diese Rezepte machen AgentEyes Observability-Daten für Terminal-Nutzer oder KI-Coding-Agenten (Claude Code, Cursor) abfragbar und automatisierbar, ohne durch das Dashboard klicken zu müssen. - -Die folgenden Muster sind kopierfertig für die AgentEye CLI (`agenteye`). Installation, Authentifizierung und die vollständige Optionsliste finden Sie unter [CLI](/de/agenteye/cli); `agenteye -h` oder `agenteye -h` zeigt die eingebaute Hilfe. +Die folgenden Muster sind kopierbereit für die AgentEye CLI (`agenteye`). Informationen zur Installation, Authentifizierung und der vollständigen Optionsliste findest du unter [CLI](/de/agenteye/cli); führe `agenteye -h` oder `agenteye -h` für die eingebaute Hilfe aus. ## Grundregeln 1. **Globale Optionen kommen *vor* dem Befehl.** `agenteye --json sessions` ist korrekt; `agenteye sessions --json` ist es nicht. Die globalen Optionen sind `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **`--json` angeben, wenn die Ausgabe geparst wird.** Daten gehen als JSON an **stdout**; menschlesbare Status- und Fehlermeldungen gehen an **stderr**, sodass stdout sauber in `jq` weitergeleitet werden kann. -3. **Auf den Exit-Code verzweigen**, nicht auf stderr-Text: `0` OK · `2` ungültige Argumente · `3` Dashboard nicht erreichbar · `4` nicht eingeloggt oder abgelaufen · `5` fehlende Berechtigung. -4. **Mit `-h` erkunden.** Jeder Befehl dokumentiert seine Filter, Werteformate und JSON-Struktur. +2. **`--json` übergeben, wenn du die Ausgabe parst.** Daten gehen als JSON an **stdout**; menschenlesbare Status- und Fehlermeldungen gehen an **stderr**, sodass stdout sauber in `jq` gepipet werden kann. +3. **Verzweige anhand des Exit-Codes**, nicht anhand des stderr-Texts: `0` ok · `2` ungültige Argumente · `3` Dashboard nicht erreichbar · `4` nicht eingeloggt oder abgelaufen · `5` fehlende Berechtigung. +4. **Mit `-h` erkunden.** Jeder Befehl dokumentiert seine Filter, Wertformate und die JSON-Struktur. ## Einmalige Einrichtung ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # damit --base-url nicht wiederholt werden muss -agenteye login --email you@example.com # per E-Mail zugesandten Code eingeben; gültig ~24h +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # damit du --base-url nicht wiederholen musst +agenteye login --email you@example.com # per E-Mail gesendeten Code einfügen; gültig ~24h ``` -## Authentifizierung prüfen, bevor gearbeitet wird +## Auth prüfen, bevor Arbeit erledigt wird -`whoami` gibt keinen Fehler bei fehlender oder abgelaufener Sitzung zurück; stattdessen wird `logged_in:false` gemeldet, sodass ein Agent den Auth-Status gefahrlos abfragen kann. (Ein Fehler mit Nicht-Null-Exit ist dennoch möglich, wenn keine Basis-URL gesetzt ist oder das Dashboard nicht erreichbar ist.) +`whoami` gibt bei einer fehlenden oder abgelaufenen Sitzung keinen Fehler aus; stattdessen meldet es `logged_in:false`, sodass ein Agent den Auth-Status sicher abfragen kann. (Es kann trotzdem mit einem Exit-Code ungleich null enden, wenn keine Basis-URL gesetzt oder das Dashboard nicht erreichbar ist.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then - echo "Nicht authentifiziert. Ausführen: agenteye login" >&2; exit 1 + echo "Not authenticated. Run: agenteye login" >&2; exit 1 fi ``` ## Fehlgeschlagene oder niedrig bewertete Sitzungen finden ```bash -# Sitzungen der letzten 24h, deren Auswertung fehlgeschlagen ist +# Sitzungen der letzten 24h, deren Evaluierung fehlgeschlagen ist agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# Auswertungen mit Helpfulness-Score <= 0.5 für einen Agenten +# Evaluierungen mit <= 0.5 bei Hilfsbereitschaft, für einen Agenten agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -Die Score-Filterung liegt bei **`evals`**, nicht bei `sessions`. `--score KEY:MIN..MAX` ist wiederholbar und wird UND-verknüpft; jede Grenze ist optional (`..0.5` bedeutet ≤ 0.5, `0.9..` bedeutet ≥ 0.9). Pro Anfrage können bis zu 20 Score-Filter übergeben werden; mehr ergibt HTTP 400. `sessions` teilt die Filter `--env`, `--status`, `--agent-id`, `--session-id` und den Zeitbereichsfilter mit `evals`, hat aber kein `--score`. +Score-Filterung liegt bei **`evals`**, nicht bei `sessions`. `--score KEY:MIN..MAX` ist wiederholbar und wird mit UND verknüpft; beide Grenzen sind optional (`..0.5` bedeutet ≤ 0,5; `0.9..` bedeutet ≥ 0,9). Pro Anfrage können bis zu 20 Score-Filter übergeben werden; mehr ergibt HTTP 400. `sessions` teilt die Filter `--env`, `--status`, `--agent-id`, `--session-id` und Zeitbereich mit `evals`, hat aber kein `--score`. -## Eine Sitzung vollständig lesen +## Eine Sitzung von Anfang bis Ende lesen -Es gibt keinen einzelnen `session show`-Befehl – die Ereignishistorie und die Auswertung der Sitzung werden kombiniert: +Es gibt keinen einzelnen Befehl `session show` – kombiniere den Ereignisverlauf mit der Evaluierung der Sitzung: ```bash -# die neueste Auswertung der Sitzung (Status + Scores) +# die neueste Evaluierung der Sitzung (Status + Scores) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# alle Ereignisse des Durchlaufs (--limit für vollständigen Durchlauf erhöhen) +# alle Ereignisse im Durchlauf (--limit für einen vollständigen Sweep erhöhen) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# nur die Tool-Aufrufe einer Sitzung +# nur die Tool-Aufrufe in einer Sitzung agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` ## Alles abrufen (Paginierung) -Ergebnisse sind nach Datum absteigend sortiert und cursor-paginiert. +Ergebnisse sind neueste zuerst und cursor-paginiert. ```bash -# in einem Schritt: bis zu 500 Zeilen in 200-Zeilen-Seiten abrufen +# Einmalig: bis zu 500 Zeilen in 200-Zeilen-Seiten abrufen agenteye --json events --session-id run-001 --limit 500 --all > events.json -# manuelles Paging: next_cursor zurückspeisen +# Manuelles Blättern: next_cursor zurückführen page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## Ausgabe mit --fields verkleinern +## Ausgabe mit --fields einschränken -Die Schlüssel (sowohl in der Tabelle als auch bei `--json`) einschränken, um zu reduzieren, was ein Agent lesen muss. +Schlüssel (sowohl in der Tabelle als auch bei `--json`) einschränken, um zu reduzieren, was ein Agent lesen muss. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Unbekannte Feldnamen werden abgelehnt (Exit `2`) und die gültige Liste wird ausgegeben – eine einfache Methode, um Feldnamen zu entdecken. +Unbekannte Feldnamen werden abgelehnt (Exit `2`) und die gültige Liste wird ausgegeben – eine einfache Methode, um Feldnamen zu erkunden. -## Gültige Filterwerte erkunden +## Gültige Filterwerte entdecken ```bash agenteye --json list envs | jq -r '.values[]' # Werte für --env agenteye --json list tools | jq -r '.values[]' # Tool-Namen; auch agents, models, event_types, … -agenteye --json list score_filters | jq -r '.values[]' # gültige KEY-Werte für --score KEY:MIN..MAX +agenteye --json list score_filters | jq -r '.values[]' # gültiger KEY für --score KEY:MIN..MAX ``` -## Organisation auswählen (Mandantenfähigkeit) +## Organisation auswählen (Multi-Tenant) -Wenn Sie mehr als einer Organisation angehören, wählen Sie den aktiven Mandanten beim Login (wird gespeichert): +Wenn du mehr als einer Organisation angehörst, wähle den aktiven Mandanten beim Login (er wird gespeichert): ```bash -agenteye login --org acme --email you@corp.com # Mandanten im selben Schritt wie den Login setzen +agenteye login --org acme --email you@corp.com # Mandant im selben Schritt wie Login setzen agenteye --json orgs list | jq -r '.orgs[].org_slug' agenteye --org globex --json sessions --since 24h # für einen Befehl überschreiben ``` -Ein Multi-Org-Login ohne `--org` endet mit einem Nicht-Null-Exit und gibt die auswählbaren Organisationen aus. +Ein Multi-Org-Login ohne `--org` endet mit einem Exit-Code ungleich null und gibt die zur Auswahl stehenden Organisationen aus. -## Einen API-Key für das SDK/den Collector anlegen +## API-Schlüssel für das SDK/den Collector bereitstellen ```bash -# Das Secret wird EINMAL ausgegeben – bei --json ist es das Feld .key +# Das Secret wird EINMALIG ausgegeben — mit --json ist es das .key-Feld key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # rotieren; agenteye keys disable ci-bot --yes zum Widerrufen ``` @@ -118,7 +117,7 @@ agenteye keys regenerate ci-bot --yes # rotieren; agenteye keys disable ci-bo ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # eine gespeicherte Abfrage + ein positionaler $1-Parameter +agenteye --json query run errs --arg prod | jq '.rows' # eine gespeicherte Abfrage + ein positionaler $1 ``` ## Einen Vorfall nicht-interaktiv triagieren @@ -126,11 +125,11 @@ agenteye --json query run errs --arg prod | jq '.rows' # eine gespeicherte Abf ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> Mutationen überspringen ihre Bestätigungsaufforderung automatisch bei `--json` oder wenn stdin kein TTY ist, sodass Agenten nie hängen bleiben; `--yes`/`-y` übergeben, um sie an anderen Stellen explizit zu überspringen. +> Mutationen überspringen ihre Bestätigungsabfrage automatisch bei `--json` oder wenn stdin kein TTY ist, sodass Agenten nie hängen bleiben; übergib `--yes`/`-y`, um sie anderswo explizit zu überspringen. ## Exit-Code-Behandlung in einem Skript @@ -138,14 +137,14 @@ agenteye incidents resolve "$id" --yes out=$(agenteye --json sessions --since 1h) || code=$? case "${code:-0}" in 0) echo "$out" | jq '.sessions | length' ;; - 4) echo "Sitzung abgelaufen - 'agenteye login' ausführen." >&2 ;; - 5) echo "Fehlende Berechtigung (Admin nach evaluations:read fragen)." >&2 ;; - 3) echo "Dashboard nicht erreichbar - URL prüfen." >&2 ;; - *) echo "Unerwarteter Fehler (Exit ${code})." >&2 ;; + 4) echo "Session expired - run 'agenteye login'." >&2 ;; + 5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;; + 3) echo "Dashboard unreachable - check the URL." >&2 ;; + *) echo "Unexpected error (exit ${code})." >&2 ;; esac ``` -## JSON-Ausgabeformate +## JSON-Ausgabestrukturen | Befehl | stdout JSON (mit `--json`) | |---|---| @@ -160,11 +159,11 @@ esac | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (beliebig) | das Ressourcenobjekt, oder `{"deleted": true, "id"}` bei Löschvorgängen | +| create/update/delete (beliebig) | das Ressourcenobjekt oder `{"deleted": true, "id"}` bei Löschvorgängen | | Fehler (beliebig, mit `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` auf stdout | -- Jedes **Ereignis**-Element (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. -- Jedes **Auswertungs**-Element (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. -- Jedes **Sitzungs**-Element (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. +- Jedes **event**-Element (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. +- Jedes **evaluation**-Element (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. +- Jedes **session**-Element (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -Das `--fields`-Argument eines Befehls akzeptiert genau die Feldnamen seines eigenen Elements – die Menge unterscheidet sich zwischen `sessions` und `evals`, sodass ein für eines gültiger Name vom anderen abgelehnt werden kann. \ No newline at end of file +Das `--fields`-Argument jedes Befehls akzeptiert genau die Feldnamen des jeweiligen Elements – der Satz unterscheidet sich zwischen `sessions` und `evals`, sodass ein für eines gültiger Name vom anderen abgelehnt werden kann. \ No newline at end of file diff --git a/docs/de/agenteye/deployment.mdx b/docs/de/agenteye/deployment.mdx index cc2e2b7c..8d806ac7 100644 --- a/docs/de/agenteye/deployment.mdx +++ b/docs/de/agenteye/deployment.mdx @@ -3,7 +3,7 @@ title: "Deployment" description: "AgentEye Deployment-Dokumentation." --- -Dieser Leitfaden behandelt das Deployment des AgentEye-Servers und -Dashboards in der Produktionsumgebung. +Diese Anleitung beschreibt das Deployment des AgentEye-Servers und Dashboards in der Produktion. --- @@ -15,7 +15,7 @@ Dieser Leitfaden behandelt das Deployment des AgentEye-Servers und -Dashboards i Python SDK | schreibt JSONL +----------------------+ v +--->| PostgreSQL 15+ | - agenteye-collector --HTTP--+ | | (relationale DB) | + agenteye-collector --HTTP--+ | | (relationale Ablage) | | | +----------------------+ v | +--------+ | +----------------------+ @@ -29,135 +29,134 @@ Dieser Leitfaden behandelt das Deployment des AgentEye-Servers und -Dashboards i +-----------+ ``` -- **Server**: Rust-HTTP-Dienst; empfängt Event-Batches, schreibt sie nach ClickHouse und pflegt den relationalen Zustand in PostgreSQL. +- **Server**: Rust-HTTP-Dienst; empfängt Event-Batches, schreibt sie in ClickHouse und verwaltet den relationalen Zustand in PostgreSQL. - **Dashboard**: Next.js-Webanwendung; liest und schreibt ausschließlich über die Server-API. -- **agenteye-collector**: wird auf Agent-Maschinen deployed, nicht auf dem Server-Host. -- **Postgres 15+**: ERFORDERLICH. (In der Multi-Tenant-Version von 14 auf 15 angehoben; das Org-Membership-Schema verwendet einen spaltenbasierten `ON DELETE SET NULL`-Fremdschlüssel, der Postgres 15+ erfordert. Postgres vor dem Deployment dieser Version aktualisieren.) Speichert OLTP-Zustand: `api_keys`, `users`, `sessions`, `evaluation_jobs` (Warteschlange), `dashboards`, `saved_queries`, `otp_codes` sowie die Multi-Tenant-Tabellen `orgs`, `org_memberships`, `org_settings`. -- **ClickHouse 24+**: ERFORDERLICH. Der Analyse-Datenspeicher für jeden ingested Event. Engine: `ReplacingMergeTree`, nach Monat partitioniert, sortiert nach `(session_id, ts, dedup_key)`. Der Server verbindet sich über `CLICKHOUSE_URL`; die mitgelieferte `deploy/base/clickhouse/` enthält eine leistungsoptimierte Single-Node-Konfiguration. **Multi-Tenant-Anforderung:** Die mitgelieferte Konfiguration aktiviert SQL-Zugriffsverwaltung + `users_without_row_policies_can_read_rows=false`, damit der Server pro Organisation einen schreibgeschützten ClickHouse-Benutzer + eine Row Policy anlegen kann (die engine-seitig erzwungene Isolationsgrenze für den SQL-Editor und den KI-Agenten). Wenn Sie eine eigene ClickHouse-Konfiguration verwenden, übernehmen Sie diese Einstellungen (siehe `deploy/base/clickhouse/configmap.yaml`). -- **Redis 7+**: *optional* gemeinsamer Cache + Rate-Limit-Backend. Server und Dashboard verbinden sich beide über `REDIS_URL`. Fehlt Redis, degradieren beide graceful auf Postgres-only-Pfade. Siehe **Redis (optionaler Cache)** weiter unten. +- **agenteye-collector**: wird auf Agent-Maschinen eingesetzt, nicht auf dem Server-Host. +- **Postgres 15+**: ERFORDERLICH. (Ab Version 14 in der Multi-Tenant-Version angehoben; das Org-Mitgliedschaftsschema verwendet einen `ON DELETE SET NULL`-Fremdschlüssel mit Spaltenliste, der Postgres 15+ erfordert. Postgres vor der Bereitstellung dieser Version aktualisieren.) Speichert den OLTP-Zustand: `api_keys`, `users`, `sessions`, `evaluation_jobs` (Warteschlange), `dashboards`, `saved_queries`, `otp_codes` sowie die Multi-Tenant-Tabellen `orgs`, `org_memberships`, `org_settings`. +- **ClickHouse 24+**: ERFORDERLICH. Der Analyse-Store für alle eingehenden Events. Engine: `ReplacingMergeTree`, nach Monat partitioniert, geordnet nach `(session_id, ts, dedup_key)`. Der Server verbindet sich über `CLICKHOUSE_URL`; die mitgelieferte `deploy/base/clickhouse/` enthält eine leistungsoptimierte Einzelknoten-Konfiguration. **Multi-Tenant-Anforderung:** Die mitgelieferte Konfiguration aktiviert SQL-Zugriffsverwaltung + `users_without_row_policies_can_read_rows=false`, damit der Server pro Organisation einen schreibgeschützten ClickHouse-Benutzer und eine Zeilenrichtlinie erstellen kann (die engine-seitig erzwungene Isolationsgrenze für den SQL-Editor und den KI-Agenten). Wenn Sie eine eigene ClickHouse-Konfiguration verwenden, übernehmen Sie diese Einstellungen (siehe `deploy/base/clickhouse/configmap.yaml`). +- **Redis 7+**: *optional* als gemeinsamer Cache- und Rate-Limit-Backend. Server und Dashboard verbinden sich beide über `REDIS_URL`. Ist Redis nicht vorhanden, fallen beide auf Postgres-only-Pfade zurück. Siehe **Redis (optionaler Cache)** weiter unten. --- ## Server -### Image pullen +### Image herunterladen ```bash echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> Aktuelle Builds werden unter `beta-latest` veröffentlicht; `latest` wird nur stabilen Releases zugewiesen. Für die Produktion empfiehlt sich ein konkreter `:v`-Tag; siehe [Verfügbare Image-Tags](#available-image-tags). +> Aktuelle Builds werden unter `beta-latest` veröffentlicht; `latest` wird nur stabilen Releases zugewiesen. Für die Produktion sollten Sie einen konkreten `:v`-Tag festlegen; siehe [Verfügbare Image-Tags](#available-image-tags). ### Umgebungsvariablen -| Variable | Erforderlich | Standard | Beschreibung | +| Variable | Erforderlich | Standardwert | Beschreibung | |---|---|---|---| -| `DATABASE_URL` | Ja | keiner | Postgres-DSN. Standard-libpq-Verbindungsstring mit Schema `postgres://`. Unterstützt `?sslmode=require` und andere libpq-Parameter. Das Passwort darf kein `/`, `+` oder `=` enthalten; zum Generieren URL-sicherer Passwörter `openssl rand -hex` verwenden. | -| `ADMIN_KEY` | Nein | keiner | Bootstrap-Admin-API-Schlüssel. Wird bei jedem Start mit allen Berechtigungen upsertet. Rotieren durch Ändern des Werts und Neustart. | +| `DATABASE_URL` | Ja | keiner | Postgres-DSN. Standard-libpq-Verbindungszeichenfolge mit Schema `postgres://`. Unterstützt `?sslmode=require` und andere libpq-Parameter. Das Passwort darf keine `/`, `+` oder `=` enthalten; verwenden Sie `openssl rand -hex` zum Generieren URL-sicherer Passwörter. | +| `ADMIN_KEY` | Nein | keiner | Bootstrap-Admin-API-Schlüssel. Wird bei jedem Start mit allen Berechtigungen per Upsert gesetzt. Rotation durch Ändern des Werts und Neustart. | | `LISTEN_ADDR` | Nein | `0.0.0.0:8080` | TCP-Adresse zum Binden | -| `MAX_BODY_BYTES` | Nein | `134217728` (128 MB) | Maximale Request-Body-Größe | -| `ADMIN_EMAIL` | Nein | keiner | E-Mail des Bootstrap-Admin-Benutzers. Wird bei jedem Start mit allen Berechtigungen upsertet und als geschützt markiert: kann nicht deaktiviert oder in der Berechtigung über Dashboard/API geändert werden. Zum Rotieren des Bootstrap-Admins `ADMIN_EMAIL` ändern und neu starten; die neue E-Mail wird als geschützt upsertet, die bisherige behält ihren Schutz bis zur manuellen Bereinigung in der Datenbank. | -| `ALLOWED_EMAILS` | Nein | keiner (alle gesperrt) | Kommagetrennte Liste erlaubter E-Mails für die Benutzererstellung und den Login. Unterstützt exakte Adressen (`user@example.com`) und Domain-Wildcards (`*@example.com`). Wenn nicht gesetzt, können keine Benutzer erstellt werden oder sich anmelden. **Nur beim ersten Start**: Befüllt die Zulassungsliste der Standard-Org beim ersten Start; danach ist die Seite [`//settings`](#operational-settings) jeder Org die maßgebliche Quelle, und Änderungen dieser Umgebungsvariable haben keine Wirkung mehr. | -| `SMTP_HOST` | Nein | keiner | SMTP-Server-Hostname für den Versand von OTP-E-Mails. Wenn nicht gesetzt, werden OTP-Codes stattdessen auf stdout geloggt. | -| `SMTP_PORT` | Nein | `587` | SMTP-Server-Port | +| `MAX_BODY_BYTES` | Nein | `134217728` (128 MB) | Maximale Anfrage-Body-Größe | +| `ADMIN_EMAIL` | Nein | keiner | Bootstrap-Admin-Benutzer-E-Mail. Wird bei jedem Start per Upsert mit allen Berechtigungen gesetzt und als geschützt markiert: kann weder deaktiviert noch über Dashboard/API in seinen Berechtigungen geändert werden. Um den Bootstrap-Admin zu wechseln, ändern Sie `ADMIN_EMAIL` und starten neu; die neue E-Mail-Adresse wird als geschützt per Upsert gesetzt, die vorherige behält ihren Schutz, bis er manuell in der Datenbank aufgehoben wird. | +| `ALLOWED_EMAILS` | Nein | keiner (alle blockiert) | Kommagetrennte Liste erlaubter E-Mail-Adressen für Benutzererstellung und Anmeldung. Unterstützt exakte Adressen (`user@example.com`) und Domain-Wildcards (`*@example.com`). Wenn nicht gesetzt, können keine Benutzer erstellt werden oder sich anmelden. **Nur beim ersten Start:** Befüllt die Zulassungsliste der Standard-Org beim ersten Start; danach ist die Seite [`//settings`](#operational-settings) jeder Org die maßgebliche Quelle, und Änderungen dieser Umgebungsvariablen haben keine Wirkung mehr. | +| `SMTP_HOST` | Nein | keiner | SMTP-Serverhostname für den Versand von OTP-E-Mails. Wenn nicht gesetzt, werden OTP-Codes stattdessen nach stdout geloggt. | +| `SMTP_PORT` | Nein | `587` | SMTP-Serverport | | `SMTP_USERNAME` | Nein | keiner | SMTP-Authentifizierungs-Benutzername | -| `SMTP_PASSWORD` | Nein | keiner | SMTP-Authentifizierungs-Passwort | +| `SMTP_PASSWORD` | Nein | keiner | SMTP-Authentifizierungspasswort | | `SMTP_FROM` | Nein | keiner | Absender-E-Mail-Adresse für OTP-E-Mails | -| `SMTP_TLS` | Nein | STARTTLS | STARTTLS wird verwendet, sofern nicht explizit deaktiviert: `false` oder `0` sendet Klartext (kein TLS); jeder andere Wert – auch nicht gesetzt – aktiviert STARTTLS. | -| `DASHBOARD_URL` | Nein | interner Standard | Dashboard-Origin zum Aufbauen des OTP-E-Mail-Magic-Links und der Incident-Magic-Links in Alert-Benachrichtigungen. Wenn nicht gesetzt, wird auf einen internen Standard zurückgegriffen (und bei OTP auch auf den vom Dashboard abgeleiteten Request-Origin). Bei Split-Domain-Setups setzen, damit sowohl E-Mail- als auch Slack-/Incident-Links auf Ihr Dashboard zeigen. Siehe **E-Mail-Magic-Link-URL** weiter unten; die meisten Betreiber müssen dies nicht setzen. | -| `SESSION_TTL_SECS` | Nein | `86400` (24 Std.) | Dashboard-Sitzungsdauer in Sekunden. **Nur beim ersten Start**: Nach dem ersten Deployment pro Org über [`//settings`](#operational-settings) bearbeiten. | -| `OTP_TTL_SECS` | Nein | `600` (10 Min.) | OTP-Code-Gültigkeitsdauer in Sekunden. **Nur beim ersten Start**: Nach dem ersten Deployment pro Org über [`//settings`](#operational-settings) bearbeiten. | -| `REDIS_URL` | Nein | keiner | Optionales gemeinsames Cache- + Rate-Limit-Backend, z. B. `redis://redis:6379/0`. Wenn gesetzt, cached der Server authentifizierte API-Key-Lookups, das `/models`-Aggregat des Dashboards, die Sessions-Liste und das Env-List-Facet; außerdem wird das OTP-Request-Rate-Limiting von Postgres COUNT auf Redis INCR umgestellt. Wenn nicht gesetzt oder nicht erreichbar, läuft der Server ohne Cache (das OTP-Limit fällt auf Postgres zurück, alle anderen Cache-Aufrufe fallen auf die primäre Datenquelle zurück). Siehe **Redis (optionaler Cache)** weiter unten. | -| `CLICKHOUSE_URL` | **Ja** | keiner | Basis-URL der ClickHouse-Instanz, z. B. `http://clickhouse:8123`. Der Server wendet sein Events-Schema bei jedem Start auf diese Datenbank an und verweigert den Start, wenn ClickHouse nicht erreichbar ist. Siehe **ClickHouse (erforderlicher Analyse-Datenspeicher)** weiter unten. | -| `CLICKHOUSE_DATABASE` | Nein | `agenteye` | ClickHouse-Datenbankname (Schema). Der Server legt sie beim Start an, falls sie noch nicht existiert. | -| `ORG_CH_SECRET` | Nein (Single-Tenant) / **Ja (Multi-Org)** | Dev-Standard | HMAC-Schlüssel, aus dem das pro-Tenant ClickHouse-Passwort jeder Organisation abgeleitet wird. SQL-Editor und `run_query` des KI-Agenten werden als eigener schreibgeschützter ClickHouse-Benutzer der Org ausgeführt, dessen Row Policy die Tenant-Isolation in der Engine erzwingt. Single-Tenant-Deployments starten problemlos mit dem eingebauten Dev-Standard; **bevor eine zweite Org angelegt wird, MUSS ein starker, stabiler Wert gesetzt werden**, da das `agenteye-orgctl org create`-CLI die Ausführung auf dem eingebauten Dev-Standard verweigert. Ein Rotieren verwaist alle ClickHouse-Benutzer der Orgs bis zum nächsten Start, der sie automatisch neu provisioniert. Geheim halten und über alle Replikas hinweg unverändert lassen. Die Org-Provisionierung selbst ist Operator-only; siehe **Organisationen (Multi-Tenancy)** weiter unten. | -| `DEFAULT_ORG_NAME` | Nein | `Default` | Anzeigename, der für die eingebaute Standard-Org gesetzt wird. **Nur beim ersten Start**, und nur solange die Org noch ihre frisch migrierte generische Identität trägt; wird beim Start angewendet und danach ignoriert. Sobald Sie die Org umbenennen (`agenteye-orgctl org rename`), ist die Umbenennung maßgeblich und diese Umgebungsvariable hat keine weitere Wirkung. | -| `DEFAULT_ORG_SLUG` | Nein | `default` | URL-Slug für die eingebaute Standard-Org, der Dashboard-Pfad, unter dem sie erreichbar ist (`//…`). Gleiche Erststart-only-/Pristine-only-Semantik wie `DEFAULT_ORG_NAME`. Muss 1–40 Kleinbuchstaben und Ziffern mit einzelnen internen Bindestrichen sein und kein [reserviertes Wort](#organizations-multi-tenancy); ein ungültiger Wert wird ignoriert (die Org behält `default`). Ermöglicht einem Single-Tenant-Install, z. B. als `/acme` statt `/default` zu erscheinen, ohne einen Post-Deploy-CLI-Schritt. | +| `SMTP_TLS` | Nein | STARTTLS | STARTTLS wird verwendet, sofern nicht explizit deaktiviert: `false` oder `0` sendet Klartext (kein TLS); jeder andere Wert — einschließlich nicht gesetzt — aktiviert STARTTLS. | +| `DASHBOARD_URL` | Nein | integrierter Standard | Dashboard-Ursprung zum Erstellen des OTP-E-Mail-Magic-Links sowie der Incident-Magic-Links in Alert-Benachrichtigungen. Wenn nicht gesetzt, fällt er auf einen integrierten Standard zurück (und bei OTP zuerst auf den vom Dashboard abgeleiteten Request-Ursprung). Setzen Sie dies für Split-Domain-Setups, damit E-Mail- und Slack/Incident-Links auf Ihr Dashboard zeigen. Siehe **E-Mail-Magic-Link-URL** weiter unten; die meisten Betreiber müssen dies nicht setzen. | +| `SESSION_TTL_SECS` | Nein | `86400` (24 h) | Dashboard-Sitzungsdauer in Sekunden. **Nur beim ersten Start:** Nach dem ersten Deployment per Org über [`//settings`](#operational-settings) bearbeitbar. | +| `OTP_TTL_SECS` | Nein | `600` (10 min) | OTP-Code-Gültigkeitsdauer in Sekunden. **Nur beim ersten Start:** Nach dem ersten Deployment per Org über [`//settings`](#operational-settings) bearbeitbar. | +| `REDIS_URL` | Nein | keiner | Optionales gemeinsames Cache- und Rate-Limit-Backend, z. B. `redis://redis:6379/0`. Wenn gesetzt, cacht der Server authentifizierte API-Key-Lookups, das `/models`-Aggregat des Dashboards, die Session-Liste und die Env-List-Facette; außerdem wird das OTP-Request-Rate-Limiting von Postgres COUNT auf Redis INCR umgestellt. Wenn nicht gesetzt oder nicht erreichbar, läuft der Server ohne Cache (das OTP-Limit fällt auf Postgres zurück, alle anderen Cache-Aufrufe fallen auf die Quelle zurück). Siehe **Redis (optionaler Cache)** weiter unten. | +| `CLICKHOUSE_URL` | **Ja** | keiner | Basis-URL der ClickHouse-Instanz, z. B. `http://clickhouse:8123`. Der Server wendet sein Events-Schema bei jedem Start auf diese Datenbank an und verweigert den Start, wenn ClickHouse nicht erreichbar ist. Siehe **ClickHouse (erforderlicher Analyse-Store)** weiter unten. | +| `CLICKHOUSE_DATABASE` | Nein | `agenteye` | ClickHouse-Datenbankname (Schema). Der Server erstellt ihn beim Start, falls er nicht existiert. | +| `ORG_CH_SECRET` | Nein (single-tenant) / **Ja (multi-org)** | Entwicklungsstandard | HMAC-Schlüssel, aus dem das ClickHouse-Passwort jedes Tenants pro Organisation abgeleitet wird. Der SQL-Editor und das `run_query` des KI-Agenten werden als schreibgeschützter ClickHouse-Benutzer der Org ausgeführt, dessen Zeilenrichtlinie die Tenant-Isolation in der Engine erzwingt. Single-Tenant-Deployments starten problemlos mit dem integrierten Entwicklungsstandard; **bevor Sie eine zweite Org anlegen, MÜSSEN Sie einen starken, stabilen Wert setzen**, da der CLI `agenteye-orgctl org create` die Ausführung mit dem integrierten Entwicklungsstandard verweigert. Eine Rotation führt dazu, dass alle ClickHouse-Benutzer der Org verwaisen, bis beim nächsten Start eine erneute Provisionierung erfolgt (der Boot-Zeit-Abgleich heilt dies automatisch). Halten Sie den Wert geheim und über alle Replikate hinweg unverändert. Die Org-Provisionierung selbst ist nur für Betreiber; siehe **Organisationen (Multi-Tenancy)** weiter unten. | +| `DEFAULT_ORG_NAME` | Nein | `Default` | Anzeigename, der für die integrierte Standard-Org gesetzt wird. **Nur beim ersten Start** und nur solange die Org noch ihre frisch migrierte generische Identität trägt, wird er beim Start angewendet und danach ignoriert. Sobald Sie die Org umbenennen (`agenteye-orgctl org rename`), ist die Umbenennung maßgeblich und diese Umgebungsvariable hat keine weitere Wirkung. | +| `DEFAULT_ORG_SLUG` | Nein | `default` | URL-Slug für die integrierte Standard-Org, der Dashboard-Pfad, unter dem sie erreichbar ist (`//…`). Gleiche Nur-beim-ersten-Start/nur-unberührt-Semantik wie `DEFAULT_ORG_NAME`. Muss 1–40 Kleinbuchstaben und Ziffern mit einzelnen internen Bindestrichen sein und darf kein [reserviertes Wort](#organizations-multi-tenancy) sein; ein ungültiger Wert wird ignoriert (die Org behält `default`). Ermöglicht es einem Single-Tenant-Install, z. B. unter `/acme` statt `/default` erreichbar zu sein, ohne einen Post-Deploy-CLI-Schritt. | | `RUST_LOG` | Nein | `info` | Log-Ausführlichkeit (`debug`, `warn`, `error`, `agenteye_server=trace`) | -| `EVALUATOR_ENDPOINT` | Nein | keiner | Basis-URL Ihres Evaluator-Dienstes (z. B. `http://evaluator:9000`). Wenn nicht gesetzt, ist die gesamte Evaluation-Pipeline ein No-op; es werden keine Queue-Zeilen geschrieben und keine Worker gestartet. Siehe [Evaluation Suite](/de/agenteye/evaluation-suite). | -| `EVALUATOR_TOKEN` | Nein | keiner | Wird als `Authorization: Bearer ` an den Evaluator gesendet. **Muss dem gleichen Wert entsprechen, mit dem der Evaluator-Dienst konfiguriert ist.** Nur optional, wenn Ihr Evaluator ohne Token konfiguriert ist. | -| `EVALUATOR_WORKERS` | Nein | `2` | Parallelität: Anzahl der Worker-Tasks pro Server-Instanz, die Evaluierungen dispatchen. Kann sicher über mehrere horizontal skalierte Server hinweg betrieben werden. | +| `EVALUATOR_ENDPOINT` | Nein | keiner | Basis-URL Ihres Evaluator-Dienstes (z. B. `http://evaluator:9000`). Wenn nicht gesetzt, ist die gesamte Evaluierungspipeline ein No-op; es werden keine Queue-Zeilen geschrieben, keine Worker laufen. Siehe [Evaluation Suite](/de/agenteye/evaluation-suite). | +| `EVALUATOR_TOKEN` | Nein | keiner | Wird als `Authorization: Bearer ` an den Evaluator gesendet. **Muss mit dem Wert übereinstimmen, mit dem der Evaluator-Dienst konfiguriert ist.** Nur optional, wenn Ihr Evaluator ohne Token konfiguriert ist. | +| `EVALUATOR_WORKERS` | Nein | `2` | Parallelität: Anzahl der Worker-Tasks pro Server-Instanz, die Evaluierungen dispatchen. Kann sicher über mehrere horizontal skalierte Server ausgeführt werden. | | `EVALUATOR_CLAIM_BATCH` | Nein | `4` | Maximale Anzahl von Evaluierungen, die ein einzelner Worker pro Tick beansprucht. Batches werden **gleichzeitig** dispatcht, sodass die Gesamtparallelität an Ihrem Evaluator-Endpunkt `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` beträgt. | -| `EVALUATOR_POLL_IDLE_SECS` | Nein | `2` | Wie lange ein Worker zwischen Dispatch-Versuchen schläft, wenn nichts ansteht. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | Nein | `10` | Letzter Fallback-Takt (Sekunden) für `GET /evaluate/{id}`-Polls, wenn der Evaluator weder `next_poll_secs` pro Antwort noch `default_poll_interval_secs` über `GET /config` zurückgibt. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | Nein | `30000` | Timeout pro HTTP-Request gegen den Evaluator (Millisekunden). | -| `EVALUATOR_MAX_ATTEMPTS` | Nein | `5` | Nach so vielen fehlgeschlagenen Versuchen wird eine Evaluierung als terminaler `error` (oder `timeout`, wenn die Fehler Request-Timeouts waren) aufgezeichnet. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | Nein | `300` (5 Min.) | Wie oft der Server `GET /config` vom Evaluator neu abruft. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Nein | `3600` (1 Std.) | Maximale Wanduhrzeittdauer, die eine Sitzung in der Polling-Queue verbleiben kann, bevor AgentEye sie als `timeout` beendet. Schützt vor einem Evaluator, der dauerhaft `pending` zurückgibt. | +| `EVALUATOR_POLL_IDLE_SECS` | Nein | `2` | Wie lange ein Worker zwischen Dispatch-Versuchen schläft, wenn nichts fällig ist. | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Nein | `10` | Endgültiger Fallback-Takt (Sekunden) für `GET /evaluate/{id}`-Polls, wenn der Evaluator weder ein `next_poll_secs` pro Response noch ein `default_poll_interval_secs` von `GET /config` zurückgibt. | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | Nein | `30000` | Pro-HTTP-Request-Timeout gegenüber dem Evaluator (Millisekunden). | +| `EVALUATOR_MAX_ATTEMPTS` | Nein | `5` | Nach dieser Anzahl fehlgeschlagener Versuche wird eine Evaluierung als terminaler `error` (oder `timeout`, wenn die Fehler Request-Timeouts waren) erfasst. | +| `EVALUATOR_CONFIG_REFRESH_SECS` | Nein | `300` (5 min) | Wie oft der Server `GET /config` vom Evaluator neu abruft. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Nein | `3600` (1 h) | Maximale Wall-Clock-Zeit, während der eine Session in der Poll-Warteschlange verbleiben darf, bevor AgentEye sie als `timeout` beendet. Schützt vor einem Evaluator, der dauerhaft `pending` zurückgibt. | | `ALERT_WORKERS` | Nein | `1` | Parallelität: Anzahl der Worker-Tasks pro Server-Instanz, die Alert-Regeln auswerten. Siehe [Alerts](/de/agenteye/alerts). | | `ALERT_CLAIM_BATCH` | Nein | `16` | Maximale Anzahl von Alerts, die ein einzelner Worker pro Tick beansprucht. | -| `ALERT_POLL_IDLE_SECS` | Nein | `5` | Wie lange ein Alert-Worker schläft, wenn die Queue leer ist. | -| `ALERT_REQUEST_TIMEOUT_MS` | Nein | `15000` | Timeout pro Trigger-Evaluierung (ClickHouse-Abfragen + ausgehende Channel-HTTP-Anfragen). | -| `ALERT_MAX_ATTEMPTS` | Nein | `5` | Aufeinanderfolgende transiente Fehler, bevor ein Alert gemäß seinem normalen Takt statt mit exponentiellem Backoff neu eingeplant wird. | +| `ALERT_POLL_IDLE_SECS` | Nein | `5` | Wie lange ein Alerts-Worker schläft, wenn die Warteschlange leer ist. | +| `ALERT_REQUEST_TIMEOUT_MS` | Nein | `15000` | Pro-Trigger-Auswertungs-Timeout (ClickHouse-Abfragen + ausgehende Kanal-HTTP). | +| `ALERT_MAX_ATTEMPTS` | Nein | `5` | Aufeinanderfolgende transiente Fehler, bevor ein Alert nach normalem Takt statt exponentiellem Backoff neu geplant wird. | | `AUDIT_WORKERS` | Nein | `1` | Parallelität: Anzahl der Worker-Tasks pro Server-Instanz, die Audits ausführen. Siehe [Audits](/de/agenteye/audits). | | `AUDIT_CLAIM_BATCH` | Nein | `1` | Maximale Anzahl fälliger Audits, die ein einzelner Worker pro Tick beansprucht. Eine agentische Untersuchung ist eine lange Schleife, daher ist der Standard 1. | -| `AUDIT_POLL_IDLE_SECS` | Nein | `30` | Wie lange ein Audit-Worker schläft, wenn kein Audit fällig ist. | -| `AUDIT_REQUEST_TIMEOUT_MS` | Nein | `30000` | Timeout pro Policy-Abfrage gegen ClickHouse (Millisekunden). | -| `AUDIT_LLM_TIMEOUT_MS` | Nein | `1440000` | Timeout für den agentischen Untersuchungsaufruf an den KI-Assistenten-Dienst. Ein vollständiger Agent-Loop läuft mehrere Minuten; diesen Wert ÜBER dem eigenen `AGENTEYE_AUDIT_TIMEOUT_MS` des Agenten halten, damit der Agent seine Teilergebnisse zurückgibt, bevor der Server aufgibt. | -| `AUDIT_MAX_ATTEMPTS` | Nein | `5` | Aufeinanderfolgende transiente Fehler, bevor ein Audit gemäß seinem normalen Takt statt mit exponentiellem Backoff neu eingeplant wird. | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | Nein | — | Die agentische Untersuchung des Audits ruft den KI-Assistenten-`agent`-Dienst auf und **nutzt dabei dieselbe Verbindung wie der Assistent** — daher müssen diese beiden Variablen auch auf dem **Server** gesetzt sein (die mitgelieferten Manifests/Compose tun dies). Beide gesetzt ⇒ Audits führen die KI-Untersuchung durch; eine davon nicht gesetzt ⇒ Audits laufen **nur mit Policy** (der deterministische SQL-Policy-Pass läuft trotzdem), unabhängig vom `llm_enabled`-Flag des einzelnen Audits. Der Agent muss außerdem ein LLM konfiguriert haben – siehe [assistant.md](/de/agenteye/assistant). | +| `AUDIT_POLL_IDLE_SECS` | Nein | `30` | Wie lange ein Audits-Worker schläft, wenn kein Audit fällig ist. | +| `AUDIT_REQUEST_TIMEOUT_MS` | Nein | `30000` | Pro-Policy-Query-Timeout gegenüber ClickHouse (Millisekunden). | +| `AUDIT_LLM_TIMEOUT_MS` | Nein | `1440000` | Timeout für den agentischen Untersuchungsaufruf an den KI-Assistenten-Dienst. Ein vollständiger Agent-Loop läuft mehrere Minuten; halten Sie diesen Wert ÜBER dem eigenen `AGENTEYE_AUDIT_TIMEOUT_MS` des Agenten, damit der Agent seine Teilergebnisse zurückgibt, bevor der Server aufgibt. | +| `AUDIT_MAX_ATTEMPTS` | Nein | `5` | Aufeinanderfolgende transiente Fehler, bevor ein Audit nach normalem Takt statt exponentiellem Backoff neu geplant wird. | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | Nein | — | Die agentische Untersuchung des Audits ruft den KI-Assistenten-`agent`-Dienst auf und **nutzt dabei dieselbe Verbindung wie der Assistent** — setzen Sie diese beiden also auch auf dem **Server** (die mitgelieferten Manifeste/Compose tun das). Beide gesetzt ⇒ Audits führen die KI-Untersuchung durch; eines fehlt ⇒ Audits laufen **nur mit Policy** (der deterministische SQL-Policy-Pass läuft trotzdem), unabhängig vom `llm_enabled`-Flag des Audits. Der Agent muss außerdem ein LLM konfiguriert haben — siehe [assistant.md](/de/agenteye/assistant). | **KI-Assistenten-Dienst — Audit- und Sandbox-Einstellungen.** Die agentische Untersuchung und ihre In-Pod-Python-Sandbox werden auf dem **Agent-Dienst** (nicht dem Server) konfiguriert, alle mit dem Präfix `AGENTEYE_AUDIT_*` und alle optional: | Variable | Standard | Bedeutung | |---|---|---| -| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Maximale Agent-Turns pro Untersuchung. | -| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Wanduhrzeit für eine Untersuchung (20 Min.). Muss **unter** dem `AUDIT_LLM_TIMEOUT_MS` des Servers bleiben. | +| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Maximale Agenten-Turns pro Untersuchung. | +| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Wall-Clock für eine Untersuchung (20 Min.). Muss **unter** dem `AUDIT_LLM_TIMEOUT_MS` des Servers bleiben. | | `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Gleichzeitige Untersuchungen pro Agent-Pod (getrennt vom Budget des Chat-Assistenten). | -| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Limits pro Script für die Bubblewrap-Sandbox. | +| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Pro-Skript-Limits für die Bubblewrap-Sandbox. | -**Sandbox-Plattformanforderung.** Die Audit-Code-Sandbox führt das Python des Modells in einem Bubblewrap-Jail aus, das **unprivilegierte User-Namespaces** benötigt. Der Agent-Pod muss die `clone()`-Flags erlauben — `seccompProfile: Unconfined` (k8s) oder `security_opt: [seccomp:unconfined]` (Compose) am Agenten setzen. Wenn der Node-Kernel unprivilegierte User-Namespaces deaktiviert (z. B. bei manchen GKE-COS-Images), **schlägt der Sandbox-Preflight fehl und der Auditor degradiert automatisch auf SQL-only** — kein Fehler, nur ein `sandbox_available: false` am `/health`-Endpunkt des Agenten. +**Sandbox-Plattformanforderung.** Die Audit-Code-Sandbox führt das Python des Modells in einem Bubblewrap-Jail aus, das **unprivilegierte User-Namespaces** benötigt. Der Agent-Pod muss die `clone()`-Flags erlauben — setzen Sie `seccompProfile: Unconfined` (k8s) oder `security_opt: [seccomp:unconfined]` (compose) auf dem Agenten. Wenn der Node-Kernel unprivilegierte User-Namespaces deaktiviert (z. B. bei einigen GKE-COS-Images), **schlägt der Sandbox-Preflight fehl und der Auditor degradiert automatisch auf SQL-only** — kein Fehler, nur `sandbox_available: false` im `/health` des Agenten. ### Starten -`DATABASE_URL` und `CLICKHOUSE_URL` in Ihrer Umgebung setzen (der Server verweigert den Start ohne ClickHouse), dann in den Container übergeben: +Setzen Sie `DATABASE_URL` in Ihrer Umgebung und übergeben Sie es dann an den Container: ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest ``` -Der Server führt Datenbank-Migrationen beim Start automatisch durch; kein separater Migrationsschritt nötig. +Der Server führt Datenbankmigrationen automatisch beim Start durch; kein separater Migrationsschritt erforderlich. ### Health-Check ``` -GET /health # Liveness - gibt immer {"status":"ok"} zurück, sobald der Prozess läuft +GET /health # Liveness - immer {"status":"ok"} sobald der Prozess läuft GET /ready # Readiness - 200 wenn Postgres + ClickHouse erreichbar, sonst 503 ``` -Keine Authentifizierung erforderlich. `/health` für **Liveness**-Probes und `/ready` für **Readiness**-/Load-Balancer-Probes verwenden. `/ready` prüft die Hard-Dependencies, ohne die der Server nicht funktioniert (Postgres + ClickHouse): Ein Server, der läuft aber seine Datenbank nicht erreichen kann, wird aus der Rotation genommen und als `NotReady` angezeigt; Redis wird gemeldet, schlägt aber nie die Readiness fehl. In den mitgelieferten Kubernetes-Manifests zeigt die Readiness-Probe bereits auf `/ready`, Liveness bleibt auf `/health`. Die vollständige Übersicht einschließlich optionalem Kubernetes-nativem Pod-Fehler-Alerting an Slack findet sich unter [enterprise-docs/health-monitoring.md](/de/agenteye/health-monitoring). +Keine Authentifizierung erforderlich. Verwenden Sie `/health` für **Liveness**-Probes und `/ready` für **Readiness**-/Load-Balancer-Probes. `/ready` prüft die harten Abhängigkeiten, ohne die der Server nicht bedienen kann (Postgres + ClickHouse), sodass ein laufender Server, der seine Datenbank nicht erreicht, aus der Rotation genommen und als `NotReady` angezeigt wird; Redis wird gemeldet, schlägt aber nie bei der Readiness-Prüfung fehl. In den mitgelieferten Kubernetes-Manifesten zeigt die Readiness-Probe bereits auf `/ready`, während Liveness auf `/health` bleibt. Siehe [enterprise-docs/health-monitoring.md](/de/agenteye/health-monitoring) für das vollständige Bild, einschließlich optionalem Kubernetes-nativen Pod-Fehler-Alerting an Slack. ### E-Mail-Magic-Link-URL -OTP-Login-E-Mails enthalten einen **Dashboard öffnen**-Button mit einem einzigen Klick. Ein Klick darauf landet den Benutzer auf `/login?token=&email=
`; das Dashboard tauscht dieses Paar gegen eine Sitzung ein und leitet in die App weiter, ohne manuelle Code-Eingabe. Der Server ermittelt den Dashboard-Origin für den Link in drei Stufen: +OTP-Login-E-Mails enthalten eine Ein-Tap-Schaltfläche **Dashboard öffnen**. Ein Klick darauf bringt den Benutzer auf `/login?token=&email=
`; das Dashboard tauscht dieses Paar gegen eine Session aus und leitet zur App weiter, ohne manuelle Code-Eingabe. Der Server löst den Dashboard-Ursprung für den Link-Aufbau in drei Ebenen auf: -1. **`X-AgentEye-Dashboard-Url`-Header**: Wird automatisch vom `/api/auth/otp/request`-Proxy des Dashboards aus dessen eigenem öffentlichen Origin gesetzt. Bei einem Same-Origin-Deployment (Server und Dashboard teilen sich einen Host hinter einem Ingress, der Proxy-Header weiterleitet) **ist keine Konfiguration erforderlich**. -2. **`DASHBOARD_URL`-Umgebungsvariable**: Setzen, wenn Ihr Dashboard auf einem anderen Origin als dem erreichbar ist, den der OTP-Request-Endpunkt des Servers sieht (geteilte `api.example.com` / `app.example.com`), oder wenn Ihr Ingress den öffentlichen Host nicht in den Dashboard-Pod propagiert (sodass `request.nextUrl.origin` sonst auf eine Wildcard-Bind-Adresse wie `0.0.0.0:3000` auflösen würde). Beispiel: `DASHBOARD_URL=https://app.example.com`. +1. **`X-AgentEye-Dashboard-Url`-Header**: Wird automatisch vom `/api/auth/otp/request`-Proxy des Dashboards aus seinem eigenen öffentlichen Ursprung gesetzt. In einem Same-Origin-Deployment (Server und Dashboard teilen sich einen Host hinter einem Ingress, der Proxy-Header weiterleitet) **ist keine Konfiguration erforderlich**. +2. **`DASHBOARD_URL`-Umgebungsvariable**: Setzen Sie diese, wenn Ihr Dashboard auf einem anderen Ursprung erreichbar ist als dem, den der OTP-Request-Endpunkt des Servers sieht (getrennte `api.example.com` / `app.example.com`), oder wenn Ihr Ingress den öffentlichen Host nicht in den Dashboard-Pod weiterleitet (sodass `request.nextUrl.origin` sonst auf eine Wildcard-Bind-Adresse wie `0.0.0.0:3000` aufgelöst würde). Beispiel: `DASHBOARD_URL=https://app.example.com`. 3. **Standard**: `https://app.befailproof.ai`, wird nur verwendet, wenn keines der oben genannten vorhanden ist. -Der Header-Wert wird validiert: Nur `https://*`- und Loopback-Origins (`http://localhost*`, `http://127.0.0.1*`) werden akzeptiert; Wildcard-Bind-Adressen (`0.0.0.0`, `[::]`) werden auch mit `https://`-Schema abgelehnt. Alles andere fällt auf Stufe 2 zurück. +Der Header-Wert wird validiert: Nur `https://*`- und Loopback-(`http://localhost*`, `http://127.0.0.1*`)-Ursprünge werden akzeptiert, und Wildcard-Bind-Adressen (`0.0.0.0`, `[::]`) werden auch mit dem `https://`-Schema abgelehnt. Alles andere fällt auf Ebene 2 zurück. -Auf einem laufenden Cluster mit einem einzeiligen Befehl setzen; keine Datei, kein Kustomize-Rebuild nötig: +Setzen Sie es auf einem laufenden Cluster mit einem Einzeiler; keine Datei, kein Kustomize-Rebuild: ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -Dies löst ein Rollout aus; die neuen Pods übernehmen den Wert beim ersten Request. Beachten Sie, dass der Override nur auf dem Deployment liegt; ein nachfolgendes `kustomize build | kubectl apply` gegen das Overlay überschreibt ihn, sofern Sie nicht dieselbe Umgebungsvariable in Ihren `server-env.yaml`-Patch des Overlays aufnehmen. +Dies löst ein Rollout aus; die neuen Pods übernehmen den Wert beim ersten Request. Beachten Sie, dass das Override nur im Deployment lebt; ein nachfolgendes `kustomize build | kubectl apply` gegen den Overlay löscht es, sofern Sie dieselbe Umgebungsvariable nicht in den `server-env.yaml`-Patch Ihres Overlays aufnehmen. --- ## Dashboard -### Image pullen +### Image herunterladen ```bash docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest @@ -165,16 +164,16 @@ docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest ### Umgebungsvariablen -| Variable | Erforderlich | Standard | Beschreibung | +| Variable | Erforderlich | Standardwert | Beschreibung | |---|---|---|---| | `AGENTEYE_SERVER_URL` | Ja | keiner | Basis-URL des Servers, z. B. `http://localhost:8080` | -| `AGENTEYE_API_KEY` | Ja | keiner | API-Schlüssel, mit dem sich das Dashboard beim Server authentifiziert. Benötigt alle Berechtigungen (Admin-Schlüssel empfohlen). | -| `AE_LOG_LEVEL` | Nein | `info` | Serverseitige Log-Ausführlichkeit: `debug`, `info`, `warn`, `error`. Auf `debug` setzen, um Upstream-Request-/Response-Zeilen und Session-Validierungs-Traces bei der Fehlersuche zu sehen. | -| `AE_LOG_JSON` | Nein | auto | `1` erzwingt JSON-per-Line-Ausgabe; `0` erzwingt menschenlesbare Ausgabe. Wenn nicht gesetzt, wird JSON automatisch aktiviert, wenn `NODE_ENV=production`. JSON wird in der Produktion empfohlen, damit Logs sauber mit `jq` oder einem Log-Aggregator geparst werden können. | -| `AE_ANALYTICS_DISABLED` | Nein | keiner | Auf `1`/`true` setzen, um die anonyme Produkt-Nutzungstelemetrie des Dashboards zu deaktivieren. Siehe [Telemetrie & Datenschutz](#telemetry--privacy) weiter unten. | -| `REDIS_URL` | Nein | keiner | Optionales gemeinsames Cache-Backend, z. B. `redis://redis:6379/0`. Wenn gesetzt, cached das Dashboard `validateSession()`-Ergebnisse über Replikas hinweg und teilt den Next.js-Fetch-Cache für Latenz-Aggregat-/Env-List-Proxy-Routen. Edge-seitige OTP-Request- und Verify-Rate-Limits nutzen Redis ebenfalls, wenn vorhanden (fail open bei Unerreichbarkeit; das serverseitige Limit ist der Sicherheits-Backstop). Siehe **Redis (optionaler Cache)** weiter unten. | -| `AGENTEYE_AGENT_URL` | Nein | keiner | Basis-URL des optionalen KI-Assistenten-`agent`-Dienstes, z. B. `http://agent:9100`. **Nicht gesetzt lassen, um den Assistenten vollständig auszublenden**: Im Dashboard erscheint dann keine Assistenten-Blase. Siehe [enterprise-docs/assistant.md](/de/agenteye/assistant). | -| `AGENTEYE_AGENT_TOKEN` | Nein | keiner | Gemeinsames Geheimnis, das das Dashboard dem `agent`-Dienst präsentiert. Muss dem auf dem Agenten konfigurierten `AGENTEYE_AGENT_TOKEN` entsprechen. Siehe [enterprise-docs/assistant.md](/de/agenteye/assistant). | +| `AGENTEYE_API_KEY` | Ja | keiner | API-Schlüssel, den das Dashboard zur Authentifizierung gegenüber dem Server verwendet. Benötigt alle Berechtigungen (Admin-Schlüssel empfohlen). | +| `AE_LOG_LEVEL` | Nein | `info` | Server-seitige Log-Ausführlichkeit: `debug`, `info`, `warn`, `error`. Auf `debug` setzen, um Upstream-Request/Response-Zeilen und Session-Validierungs-Traces bei der Diagnose zu sehen. | +| `AE_LOG_JSON` | Nein | auto | `1` erzwingt JSON-per-Zeile-Ausgabe; `0` erzwingt menschenlesbare Ausgabe. Wenn nicht gesetzt, wird JSON automatisch aktiviert, wenn `NODE_ENV=production`. JSON wird in der Produktion empfohlen, damit Logs mit `jq` oder einem Log-Aggregator sauber geparst werden können. | +| `AE_ANALYTICS_DISABLED` | Nein | keiner | Auf `1`/`true` setzen, um die anonyme Produktnutzungs-Telemetrie des Dashboards zu deaktivieren. Siehe [Telemetrie & Datenschutz](#telemetry--privacy) weiter unten. | +| `REDIS_URL` | Nein | keiner | Optionales gemeinsames Cache-Backend, z. B. `redis://redis:6379/0`. Wenn gesetzt, cacht das Dashboard `validateSession()`-Ergebnisse über Replikate hinweg und teilt den Next.js-Fetch-Cache für die Latenz-Aggregat-/Env-List-Proxy-Routen. Edge-seitige OTP-Request- und Verify-Rate-Limits verwenden ebenfalls Redis, wenn vorhanden (offen fallend, wenn Redis nicht erreichbar; das serverseitige Limit ist der Sicherheits-Backstop). Siehe **Redis (optionaler Cache)** weiter unten. | +| `AGENTEYE_AGENT_URL` | Nein | keiner | Basis-URL des optionalen KI-Assistenten-`agent`-Dienstes, z. B. `http://agent:9100`. **Nicht setzen, um den Assistenten vollständig auszublenden**: Im Dashboard erscheint keine Assistent-Blase. Siehe [enterprise-docs/assistant.md](/de/agenteye/assistant). | +| `AGENTEYE_AGENT_TOKEN` | Nein | keiner | Gemeinsames Geheimnis, das das Dashboard dem `agent`-Dienst präsentiert. Muss mit dem auf dem Agenten konfigurierten `AGENTEYE_AGENT_TOKEN` übereinstimmen. Siehe [enterprise-docs/assistant.md](/de/agenteye/assistant). | ### Starten @@ -189,89 +188,89 @@ docker run -d --restart unless-stopped \ ### Telemetrie & Datenschutz -Das Dashboard sendet **anonyme Produkt-Nutzungsanalysen** an den Analysedienst von Exosphere (PostHog): welche Dashboard-Seiten aufgerufen werden und einige UI-Aktionen wie das Erstellen eines API-Schlüssels oder das erneute Auswerten einer Sitzung. Dieses Nutzungssignal beeinflusst, welche Funktionen priorisiert werden. +Das Dashboard sendet **anonyme Produktnutzungs-Analytics** an den Analytics-Dienst von Exosphere (PostHog): welche Dashboard-Seiten aufgerufen werden und eine Handvoll UI-Aktionen wie das Erstellen eines API-Schlüssels oder das Neubewerten einer Session. Dieses Nutzungssignal gibt Aufschluss darüber, welche Features priorisiert werden. -- **Es verlassen niemals Agent-, Sitzungs- oder Event-Daten Ihre Infrastruktur.** Nur die Dashboard-UI-Nutzung wird gemeldet. Seiten-URLs werden vor dem Senden von Kennungen bereinigt, und Betreiber werden nur durch eine opake interne ID identifiziert, niemals per E-Mail. -- Telemetrie ist **standardmäßig aktiviert**. Um sie vollständig zu deaktivieren, `AE_ANALYTICS_DISABLED=1` am Dashboard-Container setzen und neu starten. -- Analytics werden an den eigenen `/ingest`-Pfad des Dashboards gesendet, den das Dashboard als Reverse Proxy zu PostHog (`https://us.i.posthog.com`) weiterleitet. Durch First-Party-Requests werden diese nicht von Browser-Werbeblockern blockiert. Der **Dashboard-Container** benötigt ausgehenden Zugang zu PostHog; ist dieser blockiert, passiert bei der Telemetrie stillschweigend nichts, und das Dashboard ist nicht beeinträchtigt. +- **Keine Agenten-, Session- oder Event-Daten verlassen je Ihre Infrastruktur.** Nur die Dashboard-UI-Nutzung wird gemeldet. Seiten-URLs werden vor dem Senden von Identifikatoren bereinigt, und Betreiber werden nur durch eine undurchsichtige interne ID identifiziert, niemals per E-Mail. +- Telemetrie ist **standardmäßig aktiviert**. Um sie vollständig zu deaktivieren, setzen Sie `AE_ANALYTICS_DISABLED=1` auf dem Dashboard-Container und starten neu. +- Analytics werden an den eigenen `/ingest`-Pfad des Dashboards gesendet, den das Dashboard als Reverse-Proxy an PostHog (`https://us.i.posthog.com`) weiterleitet. Anfragen zunächst first-party zu halten bedeutet, dass Browser-Werbeblocker sie nicht blockieren. Der **Dashboard-Container** benötigt ausgehenden Zugriff auf PostHog; wenn dieser blockiert ist, funktioniert die Telemetrie still nicht und das Dashboard ist nicht beeinträchtigt. --- ## KI-Assistent (optional) -Ein im Dashboard integrierter KI-Assistent ermöglicht es Ihrem Team, Fragen zu den Agentendaten in natürlicher Sprache zu stellen (Sitzungen zusammenfassen, SQL für den `/queries`-Editor entwerfen und gespeicherte Abfragen in Dashboard-Kacheln verwandeln), ohne das Dashboard zu verlassen. Er läuft als separater interner `agent`-Container (auf dem Claude Agents SDK), der nur vom Dashboard erreichbar ist, und bleibt **deaktiviert, bis Sie einen LLM-Endpunkt konfigurieren**. +Ein im Dashboard integrierter KI-Assistent ermöglicht es Ihrem Team, Fragen zu ihren Agent-Daten in natürlicher Sprache zu stellen (Sessions zusammenfassen, SQL für den `/queries`-Editor entwerfen und gespeicherte Abfragen in Dashboard-Kacheln umwandeln), ohne das Dashboard zu verlassen. Er läuft als separater interner `agent`-Container (auf dem Claude Agents SDK), der nur vom Dashboard erreichbar ist, und bleibt **deaktiviert, bis Sie einen LLM-Endpunkt konfigurieren**. -Um ihn zu aktivieren, setzen Sie auf dem `agent`-Dienst eine LLM-Verbindung (**Portkey** über `PORTKEY_API_KEY` + einen Model-Catalog-Slug `AGENTEYE_AGENT_MODEL=@/`, direktes Anthropic über `ANTHROPIC_API_KEY`, ein anderes Gateway über `ANTHROPIC_BASE_URL` oder Bedrock/Vertex), einen **dedizierten** Datenschlüssel und ein gemeinsames `AGENTEYE_AGENT_TOKEN`, das mit dem Dashboard übereinstimmt. Dashboard-Benutzer benötigen zusätzlich die Berechtigung `agent:use`. +Um ihn zu aktivieren, setzen Sie auf dem `agent`-Dienst eine LLM-Verbindung (**Portkey** über `PORTKEY_API_KEY` + einen Modell-Katalog-Slug `AGENTEYE_AGENT_MODEL=@/`, direktes Anthropic über `ANTHROPIC_API_KEY`, ein anderes Gateway über `ANTHROPIC_BASE_URL`, oder Bedrock/Vertex), einen **dedizierten** Datenschlüssel und ein gemeinsames `AGENTEYE_AGENT_TOKEN`, das mit dem Dashboard übereinstimmt. Dashboard-Benutzer benötigen außerdem die `agent:use`-Berechtigung. -Den Datenschlüssel für den Assistenten müssen Sie nicht manuell erstellen: Wählen Sie ein zufälliges Geheimnis, setzen Sie es als `AGENTEYE_API_KEY` auf dem `agent` **und** als `AGENT_API_KEY` auf dem `server`, und der Server befüllt es beim Start mit einem festen Berechtigungssatz. Der Datenzugriff ist schreibgeschützt (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), und er hält zusätzlich genehmigungspflichtige Authoring-Scopes (`dashboards:write`, `queries:write`, `queries:run`), damit er gespeicherte Abfragen entwerfen und validieren sowie Dashboard-Kacheln im Auftrag des Benutzers erstellen kann; der gesamte SQL-Zugriff läuft weiterhin über die schreibgeschützte ClickHouse-Rolle der Org, sodass dies erweitert, was der Assistent erstellen kann, nicht auf welche Daten er zugreifen kann. Die Scopes sind im Code festgelegt und können nicht durch Konfiguration erweitert werden. Dieser Schlüssel ist geschützt; er kann nicht über die API deaktiviert oder neu generiert werden, sondern nur durch Ändern des Werts und Neustart rotiert werden. Den Admin-/Dashboard-Schlüssel niemals dafür wiederverwenden. +Für den Datenschlüssel des Assistenten müssen Sie nichts manuell anlegen: Wählen Sie ein zufälliges Geheimnis, setzen Sie es als `AGENTEYE_API_KEY` auf dem `agent` **und** als `AGENT_API_KEY` auf dem `server`, und der Server befüllt es beim Start mit einem festen Berechtigungssatz. Sein Datenzugriff ist schreibgeschützt (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), und er besitzt zusätzlich genehmigungsgepflegte Authoring-Scopes (`dashboards:write`, `queries:write`, `queries:run`), damit er gespeicherte Abfragen entwerfen und validieren sowie Dashboard-Kacheln im Auftrag des Benutzers erstellen kann; alle SQL-Abfragen laufen weiterhin über die schreibgeschützte ClickHouse-Rolle der Org, sodass dies erweitert, was der Assistent erstellen kann, nicht welche Daten er erreichen kann. Die Scopes sind im Code festgelegt und können nicht durch Konfiguration erweitert werden. Dieser Schlüssel ist geschützt; er kann nicht über die API deaktiviert oder regeneriert werden, nur durch Ändern des Werts und Neustart rotiert werden. Verwenden Sie niemals den Admin-/Dashboard-Schlüssel dafür. -Die vollständige Einrichtung, die komplette Umgebungsvariablenreferenz, Telemetrie-Optionen und das Sicherheitsmodell finden sich in **[enterprise-docs/assistant.md](/de/agenteye/assistant)**. +Vollständige Einrichtung, die vollständige Umgebungsvariablen-Referenz, Telemetrie-Optionen und das Sicherheitsmodell finden Sie in **[enterprise-docs/assistant.md](/de/agenteye/assistant)**. --- -## ClickHouse (erforderlicher Analyse-Datenspeicher) +## ClickHouse (erforderlicher Analyse-Store) -ClickHouse hält Ihre Dashboards auch bei hohem Event-Volumen reaktionsschnell und ermöglicht es dem `/queries`-SQL-Editor, Events, Evaluierungen und Sitzungen in einem einzigen Datenspeicher zu verknüpfen. Es ist der erforderliche kanonische Speicher für jeden ingestierten Event, jedes terminale Evaluierungsergebnis und die abgeleiteten Per-Session-Aggregate. PostgreSQL hält die relationalen/mutablen Zustandstabellen (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); die Analyse-Oberfläche liegt in ClickHouse, damit die Dashboard-Rollups und eigene SQL-Abfragen sie nativ scannen und verknüpfen können, ohne datenbanküberschreitende Round-Trips. Der Server verweigert den Start ohne `CLICKHOUSE_URL`. +ClickHouse hält Ihre Dashboards bei hohen Event-Volumina reaktionsfähig und ermöglicht es dem `/queries`-SQL-Editor, Events, Evaluierungen und Sessions in einem einzigen Store zu verknüpfen. Es ist der erforderliche kanonische Store für alle eingehenden Events, alle terminalen Evaluierungsergebnisse und die abgeleiteten Per-Session-Aggregate. PostgreSQL enthält die relationalen/veränderlichen Zustandstabellen (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); die analytische Oberfläche lebt in ClickHouse, damit die Dashboard-Rollups und Ihre eigenen SQL-Abfragen sie nativ scannen und verknüpfen können, ohne datenbankübergreifende Round-Trips. Der Server verweigert den Start ohne `CLICKHOUSE_URL`. ### Schema -Drei ClickHouse-Objekte werden beim Server-Start erstellt, alle idempotent (`CREATE IF NOT EXISTS`): +Beim Server-Start werden drei ClickHouse-Objekte erstellt, alle idempotent (`CREATE IF NOT EXISTS`): -- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, partitioniert nach `toYYYYMM(ts)`, sortiert nach `(session_id, ts, dedup_key)`. Doppelte Inserts (Collector-Retries) kollabieren zum Merge-Zeitpunkt auf eine einzige Zeile; der Server berechnet für jeden Event einen deterministischen SHA-256-`dedup_key`, sodass Retries sicher sind. -- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, partitioniert nach `toYYYYMM(finished_at)`, sortiert nach `(session_id, finished_at, dedup_key)`. Wird einmal pro terminalem Evaluierungsergebnis von der Evaluator-Pipeline geschrieben. Gleiches Dedup-Key-Modell wie bei `events`. -- **`agenteye.agent_sessions`**: ein **VIEW** über `agenteye.events`, keine physische Tabelle. Jede Spalte ist abgeleitet (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()` usw.). Kein Per-Event-Upsert und kein separates Backfill; der View spiegelt automatisch, was in `events` steht. +- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, partitioniert nach `toYYYYMM(ts)`, geordnet nach `(session_id, ts, dedup_key)`. Doppelte Einfügungen (Collector-Wiederholungen) werden beim Merge auf eine einzelne Zeile reduziert; der Server berechnet einen deterministischen SHA-256-`dedup_key` für jedes Event, sodass Wiederholungen sicher sind. +- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, partitioniert nach `toYYYYMM(finished_at)`, geordnet nach `(session_id, finished_at, dedup_key)`. Einmal pro terminalem Evaluierungsergebnis durch die Evaluierungspipeline geschrieben. Gleiches Dedup-Key-Modell wie `events`. +- **`agenteye.agent_sessions`**: ein **VIEW** über `agenteye.events`, keine physische Tabelle. Jede Spalte wird abgeleitet (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, usw.). Kein Pro-Event-Upsert und kein separates Backfill; der View reflektiert automatisch, was in `events` enthalten ist. -Für die Rückwärtskompatibilität mit gespeicherten Abfragen, die `analytics.evaluations` / `analytics.sessions` referenzieren, erstellt der Server auch eine `analytics`-ClickHouse-Datenbank mit Views über die `agenteye.*`-Tabellen; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` werden alle korrekt aufgelöst. +Für Rückwärtskompatibilität mit gespeicherten Abfragen, die `analytics.evaluations` / `analytics.sessions` referenzieren, erstellt der Server außerdem eine `analytics`-ClickHouse-Datenbank mit Views über die `agenteye.*`-Tabellen; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` werden alle korrekt aufgelöst. ### Konfiguration -Das mitgelieferte docker-compose und `deploy/base/clickhouse/` liefern einen für AgentEyes Workload optimierten ClickHouse-Dienst: +Das mitgelieferte docker-compose und `deploy/base/clickhouse/` liefern einen für AgentEye's Workload optimierten ClickHouse-Dienst: -- 2 GiB angefordert / 4 GiB Limit Arbeitsspeicher im mitgelieferten Base-Overlay (dimensioniert für kleine POC-/Staging-Nodes); Produktionskunden sollten nach oben skalieren — der empfohlene Mindestwert ist 2c / 4Gi Request, 6c / 8Gi Limit. `max_server_memory_usage_to_ram_ratio=0.9` +- 2 GiB angefordert / 4 GiB Limit Arbeitsspeicher im mitgelieferten Base-Overlay (für kleine POC/Staging-Knoten dimensioniert); Produktionskunden sollten aufwärts skalieren — der empfohlene Mindestbedarf ist 2c / 4Gi Request, 6c / 8Gi Limit. `max_server_memory_usage_to_ram_ratio=0.9` - 5 GiB Mark-Cache + 8 GiB unkomprimierter Cache - `background_pool_size=16`, `background_merges_mutations_concurrency_ratio=2` - MergeTree: `parts_to_throw_insert=3000`, `parts_to_delay_insert=1500`, `non_replicated_deduplication_window=1000` -- `local_io_method=auto` (io_uring auf unterstützten Kernels) -- `fsync_metadata=0`: akzeptabel wegen At-least-once-Ingest + ReplacingMergeTree-Dedup -- `query_log` aktiviert mit 30-Tage-TTL; `query_thread_log` entfernt (bei hohem QPS teuer) +- `local_io_method=auto` (io_uring auf unterstützten Kerneln) +- `fsync_metadata=0`: akzeptabel wegen At-Least-Once-Ingest + ReplacingMergeTree-Dedup +- `query_log` aktiviert mit 30-Tage-TTL; `query_thread_log` entfernt (teuer bei hohem QPS) - `max_execution_time=30` für benutzerseitige Abfragen -- 100 GiB PVC im StatefulSet-Template (Kunden-Overlays SOLLTEN für die Produktion auf eine schnelle SSD-Storage-Klasse umgestellt werden) +- 100 GiB PVC im StatefulSet-Template (Kunden-Overlays SOLLTEN dies für die Produktion auf eine schnelle SSD-Storage-Class überschreiben) ### Backups -Ihr vollständiger Datensatz wird nächtlich in einem einzelnen wiederherstellbaren Archiv gesichert, sodass ein Cluster- oder Speicherverlust wiederherstellbar ist. ClickHouse wird automatisch durch den täglichen `agenteye-backup`-CronJob gesichert, der PostgreSQL und ClickHouse in einem Durchgang sichert. ClickHouse wird über seine HTTP-API ausgelesen: `agenteye.events` und `agenteye.evaluations` werden im ClickHouse-nativen Format gesichert (die Views und Row Policies werden beim Server-Start neu erstellt, daher sind die Tabellendaten das vollständige Bild) und zusammen mit dem Postgres-Dump in einem einzigen komprimierten Archiv gebündelt, das in Ihren Objektspeicher hochgeladen wird. +Ihr vollständiger Datensatz wird nächtlich in einem einzelnen wiederherstellbaren Archiv gesichert, sodass ein Cluster- oder Speicherverlust behebbar ist. ClickHouse wird automatisch durch den täglichen `agenteye-backup`-CronJob gesichert, der PostgreSQL und ClickHouse in einem Durchgang sichert. ClickHouse wird über seine HTTP-API gelesen: `agenteye.events` und `agenteye.evaluations` werden im ClickHouse-nativen Format gesichert (die Views und Zeilenrichtlinien werden beim Server-Start neu erstellt, sodass die Tabellendaten das vollständige Bild sind) und zusammen mit dem Postgres-Dump in ein einzelnes komprimiertes Archiv gebündelt, das in Ihren Objektspeicher hochgeladen wird. -Der Ziel-Bucket und die Cloud-Anmeldedaten werden pro Overlay konfiguriert. Informationen zur Upload-Konfiguration und zu Wiederherstellungsschritten finden sich im Abschnitt **Backups** von [enterprise-docs/kubernetes-deployment.md](/de/agenteye/kubernetes-deployment). +Ziel-Bucket und Cloud-Anmeldedaten werden pro Overlay konfiguriert. Siehe den Abschnitt **Backups** in [enterprise-docs/kubernetes-deployment.md](/de/agenteye/kubernetes-deployment) für Upload-Konfiguration und Wiederherstellungsschritte. --- ## Redis (optionaler Cache) -Redis ist ein **optionales** gemeinsames Cache- + Rate-Limit-Backend, das von Server und Dashboard genutzt wird. Mit deployed Redis und `REDIS_URL` auf beiden Diensten: +Redis ist ein **optionales** gemeinsames Cache- und Rate-Limit-Backend, das von Server und Dashboard verwendet wird. Mit Redis und gesetztem `REDIS_URL` auf beiden Diensten: -- **Server** cached authentifizierte API-Key-Lookups, die `/events/environments`- + `/evaluations/environments`-Listen, das `/events/latency_aggregate`-Rollup (die schwerste Abfrage, die das Dashboard pollt), die `/sessions`-Liste und wechselt das OTP-Request-Rate-Limiting von Postgres `COUNT(*)` auf Redis `INCR + EXPIRE`. -- **Dashboard** cached `validateSession()`-Ergebnisse, damit die 10–20 authentifizierten API-Aufrufe eines typischen Seitenladevorgangs alle einen einzigen Upstream-Session-Check teilen. Es begrenzt auch OTP-Request und OTP-Verify am Dashboard-Edge per Rate Limit. +- **Server** cacht authentifizierte API-Key-Lookups, die `/events/environments`- und `/evaluations/environments`-Listen, das `/events/latency_aggregate`-Rollup (die schwerste Abfrage, die das Dashboard pollt), die `/sessions`-Liste und wechselt das OTP-Request-Rate-Limiting von Postgres `COUNT(*)` zu Redis `INCR + EXPIRE`. +- **Dashboard** cacht `validateSession()`-Ergebnisse, damit die 10–20 authentifizierten API-Aufrufe, die ein typischer Seitenaufruf ausgibt, alle eine gemeinsame Upstream-Session-Prüfung teilen. Es begrenzt außerdem OTP-Request und OTP-Verify am Dashboard-Edge per Rate-Limiting. -**Beide Dienste degradieren graceful, wenn Redis nicht erreichbar ist.** Jeder Cache-Aufruf gibt innerhalb eines begrenzten Timeouts `Err` zurück, und der Aufrufer fällt auf die primäre Datenquelle zurück (Postgres auf dem Server, der Upstream-Rust-Server auf dem Dashboard). OTP-Rate-Limiting fällt auf dem Server auf den Postgres-`COUNT(*)`-Pfad zurück (die Sicherheitseigenschaft bleibt erhalten); das Edge-OTP-Limit des Dashboards schlägt fehl auf offen, während das serverseitige Limit weiterhin greift. Ein ausgefallenes Redis verschlechtert die Latenz, nicht die Korrektheit. +**Beide Dienste degradieren graceful, wenn Redis nicht erreichbar ist.** Jeder Cache-Aufruf gibt innerhalb eines begrenzten Timeouts `Err` zurück und der Aufrufer fällt auf die Quelle zurück (Postgres auf dem Server, der upstream Rust-Server auf dem Dashboard). OTP-Rate-Limiting fällt auf dem Server auf den Postgres-`COUNT(*)`-Pfad zurück (die Sicherheitseigenschaft bleibt erhalten); das Edge-OTP-Limit des Dashboards fällt offen, während das serverseitige Limit weiterhin gilt. Redis-Ausfall verschlechtert die Latenz, nicht die Korrektheit. ### Konfiguration -Das docker-compose-Bundle enthält bereits einen Redis-Dienst und verdrahtet `REDIS_URL=redis://redis:6379/0` in Server und Dashboard. Für einen externen Redis `REDIS_URL` auf Ihren Endpunkt setzen und den `redis`-Dienst aus der Compose-Datei entfernen. +Das docker-compose-Bundle enthält bereits einen Redis-Dienst und verdrahtet `REDIS_URL=redis://redis:6379/0` in Server und Dashboard. Um ein externes Redis zu verwenden, setzen Sie `REDIS_URL` auf Ihren Endpunkt und entfernen Sie den `redis`-Dienst aus der Compose-Datei. -### Arbeitsspeicher + Persistenz +### Arbeitsspeicher und Persistenz -Das mitgelieferte Redis-Image läuft mit `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. AOF-Persistenz bedeutet, dass der Cache Container-Neustarts überlebt; `everysec` ist die richtige Durability-/Performance-Balance, da der Verlust der letzten Sekunde an Cache-Schreibvorgängen harmlos ist. LRU-Eviction begrenzt das Arbeitsspeicherwachstum. +Das mitgelieferte Redis-Image läuft mit `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. AOF-Persistenz bedeutet, dass der Cache Container-Neustarts überlebt; `everysec` ist die richtige Balance zwischen Haltbarkeit und Leistung, da der Verlust der letzten Sekunde an Cache-Schreibvorgängen harmlos ist. LRU-Eviction begrenzt das Speicherwachstum. -### Wann Redis NICHT deployen +### Wann Redis NICHT eingesetzt werden sollte -- Single-Instance-Dev/QA. Die In-Process-Caches auf dem Server allein liefern bereits den Großteil des Per-Replica-Vorteils; Redis fügt das Cross-Replica-Sharing hinzu, das Single-Instance-Setups nicht benötigen. -- Air-Gapped-Installationen, bei denen der Betriebsaufwand für einen weiteren Dienst den Latenzgewinn überwiegt. +- Einzelinstanz-Dev/QA. Die In-Process-Caches des Servers allein liefern den größten Per-Replikat-Vorteil; Redis fügt das Cross-Replikat-Sharing hinzu, das Einzelinstanz-Setups nicht benötigen. +- Air-Gapped-Installationen, bei denen der Betriebsaufwand für einen weiteren Dienst den Latenz-Gewinn überwiegt. --- ## Docker Compose (empfohlen) -Eine `docker-compose.yml` ist im Repository `agenteye-enterprise/releases` verfügbar. Sie startet Postgres, ClickHouse, Redis, den Server und das Dashboard mit einem einzigen Befehl. +Eine `docker-compose.yml` ist im `agenteye-enterprise/releases`-Repository verfügbar. Sie startet Postgres, den Server und das Dashboard mit einem einzigen Befehl. ```bash GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ @@ -281,24 +280,24 @@ GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ cd agenteye ``` -**Standardwerte über `.env` überschreiben:** +**Standards über `.env` überschreiben:** ``` -# URL-sichere Passwörter verwenden (keine /, +, oder =-Zeichen). +# Verwenden Sie URL-sichere Passwörter (keine /, + oder = Zeichen). # Generieren mit: openssl rand -hex 24 -POSTGRES_PASSWORD=your-db-password -ADMIN_KEY=your-admin-secret +POSTGRES_PASSWORD=ihr-db-passwort +ADMIN_KEY=ihr-admin-geheimnis # Dashboard-Authentifizierung -ADMIN_EMAIL=admin@yourcompany.com -ALLOWED_EMAILS=*@yourcompany.com +ADMIN_EMAIL=admin@ihrefirma.com +ALLOWED_EMAILS=*@ihrefirma.com -# SMTP für OTP-E-Mails (weglassen, um OTP-Codes auf stdout zu loggen) -# SMTP_HOST=smtp.yourprovider.com +# SMTP für OTP-E-Mails (weglassen, um OTP-Codes nach stdout zu loggen) +# SMTP_HOST=smtp.ihranbieter.com # SMTP_PORT=587 -# SMTP_USERNAME=your-smtp-user -# SMTP_PASSWORD=your-smtp-password -# SMTP_FROM=noreply@yourcompany.com +# SMTP_USERNAME=ihr-smtp-benutzer +# SMTP_PASSWORD=ihr-smtp-passwort +# SMTP_FROM=noreply@ihrefirma.com RUST_LOG=info ``` @@ -307,7 +306,7 @@ RUST_LOG=info docker compose up -d ``` -**Stoppen (Daten-Volume bleibt erhalten):** +**Stoppen (behält Datenvolume):** ```bash docker compose down @@ -321,78 +320,78 @@ docker compose down -v --- -## Operative Einstellungen +## Betriebseinstellungen -Eine kleine Gruppe operativer Konfigurationsschalter, die früher durch Umgebungsvariablen fixiert waren, ist jetzt pro Organisation über die **`//settings`**-Seite des Dashboards bearbeitbar; jede Org konfiguriert ihre eigenen. Änderungen treten innerhalb von Sekunden in Kraft, ohne Neustart und ohne erneutes Deployment. +Eine kleine Gruppe betrieblicher Einstellungen, die früher durch Umgebungsvariablen festgelegt waren, sind jetzt pro Organisation über die **`//settings`**-Seite des Dashboards bearbeitbar; jede Org konfiguriert ihre eigenen. Änderungen werden innerhalb von Sekunden wirksam, ohne Neustart und ohne erneutes Deployment. -| Einstellung | Bootstrap-Umgebungsvariable | Beschreibung | +| Einstellung | Bootstrap-Umgebungsvariable | Was sie steuert | |---|---|---| -| Erlaubte Anmeldungen | `ALLOWED_EMAILS` | E-Mails (oder `*@domain.com`-Wildcards), die berechtigt sind, ein OTP zu erhalten und als Benutzer hinzugefügt zu werden | -| Standard-Benutzerberechtigungen | `DEFAULT_USER_PERMISSIONS` | Kommagetrennte Berechtigungs-Tokens, die vorausgewählt sind, wenn ein Admin **+ neuer Benutzer** öffnet. Jedes Token muss eine der unter [API-Key-Berechtigungen](/de/agenteye/api-keys) aufgelisteten Zeichenketten sein. Standardmäßig das `standard`-Preset: Nur-Lese-Zugriff plus die alltäglichen On-Call-Aktionen (Re-Evaluierungen auslösen, Abfragen ausführen, Incidents bestätigen, den Assistenten nutzen). | -| Sitzungsdauer | `SESSION_TTL_SECS` | Wie lange ein Dashboard-Login gültig bleibt, bevor eine erneute Authentifizierung erforderlich ist. Das Dashboard prüft die Upstream-Sitzung alle 5 Sekunden, sodass eine Berechtigungsaktualisierung unter `//users` beim nächsten Request des betroffenen Benutzers wirksam wird, ohne erneuten Login. | -| Einmalcode-Gültigkeitsdauer | `OTP_TTL_SECS` | Wie lange ein OTP/Magic-Link verwendbar bleibt | -| Alert-Benachrichtigungskanäle | `ALERTS_ENABLED_CHANNELS` | Kommagetrennte Liste von Kanal-Typen, die der Alert-Dispatcher verwenden darf: `email`, `slack`, `webhook`. Die Per-Alert-Konfiguration wird weiterhin unter `//alerts/` vorgenommen, aber der Dispatcher filtert jede ausgehende Zustellung durch diesen Satz; ein hier deaktivierter Kanal wird mit einer `skipped_disabled`-Audit-Zeile kurzgeschlossen. Der `dashboard`-Kanal (der lokale Audit-Insert) ist immer erlaubt. Standardmäßig alle drei aktiv. | +| Erlaubte Anmeldungen | `ALLOWED_EMAILS` | E-Mails (oder `*@domain.com`-Wildcards), die berechtigt sind, ein OTP zu empfangen und als Benutzer hinzugefügt zu werden | +| Standard-Benutzerberechtigungen | `DEFAULT_USER_PERMISSIONS` | Kommagetrennte Berechtigungs-Token, die vorausgewählt sind, wenn ein Admin **+ neuer Benutzer** öffnet. Jedes Token muss einer der unter [API-Schlüsselberechtigungen](/de/agenteye/api-keys) aufgelisteten Zeichenfolgen entsprechen. Standardmäßig das `standard`-Preset: schreibgeschützter Zugriff plus die alltäglichen On-Call-Aktionen (Re-Evaluierungen auslösen, Abfragen ausführen, Incidents bestätigen, den Assistenten nutzen). | +| Sitzungsdauer | `SESSION_TTL_SECS` | Wie lange ein Dashboard-Login gültig bleibt, bevor eine erneute Authentifizierung erforderlich ist. Das Dashboard prüft die Upstream-Session alle 5 Sekunden, sodass eine Berechtigungsänderung unter `//users` beim nächsten Request des betroffenen Benutzers wirksam wird, ohne erneute Anmeldung. | +| Einmalcode-Dauer | `OTP_TTL_SECS` | Wie lange ein OTP / Magic-Link verwendbar bleibt | +| Alert-Benachrichtigungskanäle | `ALERTS_ENABLED_CHANNELS` | Kommagetrennte Liste von Kanal-Arten, die der Alert-Dispatcher verwenden darf: `email`, `slack`, `webhook`. Die Per-Alert-Konfiguration wird weiterhin unter `//alerts/` erstellt, aber der Dispatcher filtert jede ausgehende Zustellung durch diesen Satz; ein hier deaktivierter Kanal schließt mit einer `skipped_disabled`-Audit-Zeile kurz. Der `dashboard`-Kanal (der lokale Audit-Insert) ist immer erlaubt. Standardmäßig alle drei aktiviert. | ### Wie der Bootstrap funktioniert -Einstellungen werden pro Organisation in `org_settings` gespeichert. Beim ersten Start befüllt der Server die fehlenden Zeilen der Standard-Org aus der entsprechenden Umgebungsvariable (oder einem sinnvollen Standard, wenn die Umgebungsvariable nicht gesetzt ist). Danach **ist der gespeicherte Wert die maßgebliche Quelle und die Umgebungsvariable wird ignoriert**; das Ändern der Umgebungsvariable bei einem späteren Neustart hat keinen Einfluss auf den Wert einer aktiven Org, und weitere Orgs starten mit Standardwerten und konfigurieren ihre eigenen. +Einstellungen werden pro Organisation in `org_settings` gespeichert. Beim ersten Start befüllt der Server die fehlenden Zeilen der Standard-Org aus der entsprechenden Umgebungsvariablen (oder einem sinnvollen Standard, wenn die Umgebungsvariable nicht gesetzt ist). Danach **ist der gespeicherte Wert die maßgebliche Quelle und die Umgebungsvariable wird ignoriert**; das Ändern der Umgebungsvariablen bei einem späteren Neustart wirkt sich nicht auf den Wert einer aktiven Org aus, und zusätzliche Orgs starten mit Standardwerten und konfigurieren ihre eigenen. Das bedeutet: -- Für ein neues Deployment die Umgebungsvariablen wie oben angegeben setzen; die Standard-Org liest sie beim ersten Start. -- Um einen Wert später zu ändern, im Dashboard unter `//settings` einloggen und bearbeiten. Die Änderung wird innerhalb von Sekunden über alle Server-Replikas wirksam; kein Neustart nötig. -- Eine Start-Log-Zeile zeigt an, was gesetzt wurde und was bereits vorhanden war, sodass Sie bestätigen können, dass der Bootstrap wirksam war: +- Für ein frisches Deployment setzen Sie die Umgebungsvariablen wie oben gezeigt, und die Standard-Org liest sie beim ersten Start. +- Um einen Wert später zu ändern, melden Sie sich im Dashboard an und bearbeiten ihn unter `//settings`. Die Änderung gilt innerhalb von Sekunden über alle Server-Replikate; kein Neustart erforderlich. +- Eine Start-Log-Zeile zeichnet auf, was gesetzt wurde gegenüber was bereits vorhanden war, sodass Sie bestätigen können, dass der Bootstrap wirksam wurde: ```text INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true ``` -#### Anmelde-Semantik über Organisationen hinweg +#### Anmeldesemantik über Organisationen hinweg -Eine Sitzung und ein OTP sind global für den Benutzer, nicht für eine einzelne Org, daher gelten bei der Anmeldung zwei Regeln für die Per-Org-Einstellungen: +Eine Session und ein OTP sind global für den Benutzer, nicht für eine einzelne Org, sodass zwei Regeln die Pro-Org-Einstellungen bei der Anmeldung abstimmen: -- **Sitzungs-/OTP-Dauer**: Die strengste (kürzeste) Dauer unter den Orgs, zu denen der Benutzer gehört, gewinnt. -- **Erlaubte Anmeldungen**: Das Gate verknüpft die Zulassungsliste jeder Org mit der Org-Mitgliedschaft per ODER: Ein Benutzer darf ein OTP anfordern, wenn die Zulassungsliste irgendeiner Org seine E-Mail zulässt **oder** er bereits Mitglied einer Org ist. +- **Session- / OTP-Dauer**: Die strengste (kürzeste) Dauer unter den Orgs, zu denen der Benutzer gehört, gewinnt. +- **Erlaubte Anmeldungen**: Das Gate verbindet jede Org-Zulassungsliste per ODER mit der Org-Mitgliedschaft: Ein Benutzer darf ein OTP anfordern, wenn die Zulassungsliste einer beliebigen Org seine E-Mail-Adresse zulässt **oder** er bereits Mitglied einer beliebigen Org ist. ### Berechtigungen -Der Zugriff auf eine `//settings`-Seite wird durch zwei Berechtigungen gesteuert: +Der Zugriff auf eine `//settings`-Seite ist durch zwei Berechtigungen geschützt: -- `settings:read`: Seite und aktuelle Werte einsehen. +- `settings:read`: Seite und aktuelle Werte anzeigen. - `settings:write`: Änderungen speichern. -Der Bootstrap-Admin-Benutzer (aus `ADMIN_EMAIL` gesetzt) erhält beide automatisch zusammen mit allen anderen Berechtigungen. Anderen Benutzern können sie bei Bedarf über `//users` gewährt werden. +Der Bootstrap-Admin-Benutzer (aus `ADMIN_EMAIL` gesetzt) erhält automatisch beide zusammen mit allen anderen Berechtigungen. Anderen Benutzern können sie bei Bedarf unter `//users` gewährt werden. --- ## Organisationen (Multi-Tenancy) -Ein einzelnes Deployment kann mehrere isolierte **Organisationen** (Tenants) bedienen; jede Datenzeile gehört genau einer Org, und die Isolation wird in der Datenbank-Engine erzwungen. Ein Single-Tenant-Install benötigt hier nichts; alle Daten liegen in einer eingebauten `default`-Org. (Sie können dieser Org einen freundlicheren Namen und URL-Slug geben, sodass sie z. B. unter `/acme` statt `/default` erreichbar ist, indem Sie `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` vor dem ersten Start setzen oder sie jederzeit mit `agenteye-orgctl org rename` umbenennen.) +Ein einzelnes Deployment kann mehrere isolierte **Organisationen** (Tenants) bedienen; jede Datenzeile gehört genau einer Org, und die Isolation wird in der Datenbank-Engine erzwungen. Eine Single-Tenant-Installation benötigt hier nichts; alle Daten leben in einer integrierten `default`-Org. (Sie können dieser Org einen freundlicheren Namen und URL-Slug geben, sodass sie z. B. unter `/acme` statt `/default` erreichbar ist, indem Sie `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` vor dem ersten Start setzen oder sie jederzeit mit `agenteye-orgctl org rename` umbenennen.) -**Tenant-Provisionierung ist Operator-only.** Organisationen und ihre Mitgliedschaften werden mit der **`agenteye-orgctl`**-CLI erstellt und verwaltet, die **im Server-Image** (neben `agenteye-server`) mitgeliefert wird und **im bestehenden Server-Pod** läuft; es gibt **keinen separaten Pod/Job, keine HTTP-API und keinen Dashboard-Button**. Sie nutzt die `DATABASE_URL`, `CLICKHOUSE_URL` und `ORG_CH_SECRET` des Servers. +**Tenant-Provisionierung ist nur für Betreiber.** Organisationen und ihre Mitgliedschaften werden mit dem **`agenteye-orgctl`**-CLI erstellt und verwaltet, das **innerhalb des Server-Images** (neben `agenteye-server`) ausgeliefert wird und **innerhalb des vorhandenen Server-Pods** läuft; es gibt **keinen separaten Pod/Job, keine HTTP-API und keinen Dashboard-Button**. Es nutzt die `DATABASE_URL`, `CLICKHOUSE_URL` und `ORG_CH_SECRET` des Servers. ```bash -# Docker Compose - in den laufenden Server-Dienst exec: +# Docker Compose - in den laufenden Server-Dienst hineinwechseln: docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp" docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin -# Kubernetes - in das laufende Server-Deployment exec: +# Kubernetes - in das laufende Server-Deployment hineinwechseln: kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list ``` -Verfügbare Verben: `org create | list | rename | delete | purge` und `member add | list | update | remove`, mit eingebauten Berechtigungs-Sets `admin`, `standard` und `read-only`. Hinzugefügte Mitglieder erhalten beim ersten Dashboard-Login ein OTP. +Verfügbare Verben: `org create | list | rename | delete | purge` und `member add | list | update | remove`, mit integrierten Berechtigungs-Sets `admin`, `standard` und `read-only`. Hinzugefügte Mitglieder erhalten beim ersten Dashboard-Login ein OTP. -**Vor dem Anlegen einer zweiten Org:** ein starkes, stabiles `ORG_CH_SECRET` setzen (der `org create`-Befehl verweigert die Ausführung auf dem eingebauten Dev-Standard) und sicherstellen, dass Postgres **15+** ist. **Unverändert:** Per-Org-API-Schlüssel werden weiterhin im Dashboard/API von Org-Mitgliedern erstellt; nur der Org-+Mitglieds-Lebenszyklus wurde in die CLI verschoben. Vollständige Befehlsreferenz und ein ausführliches Beispiel: **[enterprise-docs/tenant-management.md](/de/agenteye/tenant-management)**. +**Bevor Sie eine zweite Org erstellen:** Setzen Sie ein starkes, stabiles `ORG_CH_SECRET` (der `org create`-Befehl verweigert die Ausführung mit dem integrierten Entwicklungsstandard) und stellen Sie sicher, dass Postgres **15+** ist. **Unverändert:** Per-Org-API-Schlüssel werden weiterhin im Dashboard/API durch Org-Mitglieder erstellt; nur der Org- und Mitglieds-Lebenszyklus wurde in den CLI verschoben. Vollständige Befehlsreferenz und ein ausgearbeitetes Beispiel: **[enterprise-docs/tenant-management.md](/de/agenteye/tenant-management)**. --- -## Context-Window-Füllung +## Kontextfenster-Füllstand -Jedes `model_response`-Event zeigt eine **Context-Fill-Pille** — Eingabe- plus Ausgabe-Token als Prozentsatz des Kontextfensters des jeweiligen Modells. Die Bänder sind `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%) und `reset context` (75–100%). AgentEye löst gängige Modell-IDs automatisch auf, sodass keine initiale Konfiguration erforderlich ist. +Jedes `model_response`-Event zeigt eine **Kontextfüllstand-Pille** — Eingabe- plus Ausgabe-Token als Prozentsatz des Kontextfensters dieses Modells. Die Bereiche sind `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%) und `reset context` (75–100%). AgentEye löst gängige Modell-IDs automatisch auf, sodass keine anfängliche Konfiguration erforderlich ist. -Jedes Modell, das eine Organisation sendet, erscheint unter **Einstellungen → Modell-Kontextfenster**. Benutzer mit `settings:write` können dessen Fenster überschreiben oder ein privates/Proxy-Modell hinzufügen (0–1.000.000 Token); `0` bedeutet „unbekannt" und unterdrückt die Pille. Änderungen werden auf neu ingistierte Events angewendet. Benutzer mit `settings:read` können die Liste einsehen. +Jedes Modell, das eine Organisation sendet, erscheint unter **Einstellungen → Modell-Kontextfenster**. Benutzer mit `settings:write` können dessen Fenster überschreiben oder ein privates/Proxy-Modell hinzufügen (0–1.000.000 Token); `0` bedeutet "unbekannt" und unterdrückt die Pille. Änderungen gelten für neu eingehende Events. Benutzer mit `settings:read` können die Liste einsehen. -Neue Events erhalten die Füllung ab dem Moment des Upgrades. Um auch **historische** Events (und die Per-Modell-Liste) für ein bestehendes Deployment zu befüllen, führen Sie das einmalige Backfill aus — es wird im Server-Image mitgeliefert (wie `agenteye-orgctl`) und läuft im bestehenden Server-Pod: +Neue Events erhalten den Füllstand ab dem Moment des Upgrades. Um auch **historische** Events (und die Pro-Modell-Liste) für ein bestehendes Deployment zu befüllen, führen Sie das einmalige Backfill aus — es wird innerhalb des Server-Images (wie `agenteye-orgctl`) ausgeliefert und läuft im vorhandenen Server-Pod: ```bash # Vorschau (gibt die Pro-Org-Mutation aus, ändert nichts): @@ -403,18 +402,18 @@ kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window docker compose exec server agenteye-backfill-context-window ``` -Es ist idempotent (sicher mehrfach ausführbar) und nutzt `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` aus dem Pod. Nach dem Bearbeiten von Modell-Fenstern erneut ausführen, wenn vorhandene Events neu berechnet werden sollen. +Es ist idempotent (sicher mehrfach ausführbar) und nutzt `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` aus dem Pod. Führen Sie es erneut aus, nachdem Sie Modellfenster bearbeitet haben, wenn Sie möchten, dass vorhandene Events neu berechnet werden. --- ## Produktionsüberlegungen -- **Postgres**: Einen verwalteten Postgres-Dienst oder eine dedizierte Instanz mit regelmäßigen Backups verwenden. Die `DATABASE_URL` unterstützt alle Standard-libpq-Parameter, einschließlich `sslmode=require` für verschlüsselte Verbindungen. -- **TLS**: Server und Dashboard hinter einem Reverse Proxy (nginx, Caddy, Traefik) betreiben, der TLS terminiert. -- **Firewall**: Der Server-Port (Standard 8080) sollte nur von Collector-Maschinen und dem Dashboard-Host erreichbar sein, nicht vom öffentlichen Internet. -- **Admin-Schlüssel**: `ADMIN_KEY` auf ein starkes zufälliges Geheimnis setzen. Nach dem Bootstrap dedizierte Scoped-Keys für Collectors und das Dashboard erstellen, statt den Admin-Schlüssel überall zu verwenden. -- **Image-Tags**: In der Produktion auf die Version in Ihren Release-Manifests pinnen (z. B. `server:v0.0.1-beta.48`) statt eines Floating-Tags, um unbeabsichtigte Upgrades zu vermeiden. Aktuelle Beta-Builds werden unter `beta-latest` veröffentlicht; `latest` wird nur stabilen Releases zugewiesen. -- **Health-Monitoring**: Auf Kubernetes verwendet die Readiness-Probe `/ready` (Postgres- + ClickHouse-Erreichbarkeit), während Liveness auf `/health` bleibt. Für flotten-weites „Ist AgentEye selbst verfügbar?"-Alerting an Slack aktivieren Sie das optionale Robusta-Add-on; siehe [enterprise-docs/health-monitoring.md](/de/agenteye/health-monitoring). +- **Postgres**: Verwenden Sie einen verwalteten Postgres-Dienst oder eine dedizierte Instanz mit regelmäßigen Backups. `DATABASE_URL` unterstützt alle Standard-libpq-Parameter, einschließlich `sslmode=require` für verschlüsselte Verbindungen. +- **TLS**: Stellen Sie Server und Dashboard hinter einen Reverse-Proxy (nginx, Caddy, Traefik), der TLS terminiert. +- **Firewall**: Der Server-Port (Standard 8080) sollte nur von Collector-Maschinen und dem Dashboard-Host erreichbar sein, nicht aus dem öffentlichen Internet. +- **Admin-Schlüssel**: Setzen Sie `ADMIN_KEY` auf ein starkes zufälliges Geheimnis. Nach dem Bootstrapping erstellen Sie dedizierte, eingeschränkte Schlüssel für Collector und Dashboard, anstatt den Admin-Schlüssel überall zu verwenden. +- **Image-Tags**: Fixieren Sie in der Produktion auf die Version in Ihren Release-Manifesten (z. B. `server:v0.0.1-beta.48`) statt auf einem Floating-Tag, um unbeabsichtigte Upgrades zu vermeiden. Aktuelle Beta-Builds werden unter `beta-latest` veröffentlicht; `latest` wird nur stabilen Releases zugewiesen. +- **Health-Monitoring**: Auf Kubernetes verwendet die Readiness-Probe `/ready` (Postgres + ClickHouse-Erreichbarkeit), während Liveness auf `/health` bleibt. Für flottenweit Alerting nach Slack bei "Ist AgentEye selbst oben?", aktivieren Sie das optionale Robusta-Add-on; siehe [enterprise-docs/health-monitoring.md](/de/agenteye/health-monitoring). --- @@ -424,4 +423,4 @@ Es ist idempotent (sicher mehrfach ausführbar) und nutzt `DATABASE_URL` / `CLIC |-----|-------------| | `latest` | Neuestes stabiles Release | | `beta-latest` | Neuestes Pre-Release (Beta) | -| `v` | Gepinnte Version, z. B. `v0.0.1-beta.48` (für die Produktion empfohlen) | \ No newline at end of file +| `v` | Fixierte Version, z. B. `v0.0.1-beta.48` (empfohlen für die Produktion) | \ No newline at end of file diff --git a/docs/de/agenteye/getting-started.mdx b/docs/de/agenteye/getting-started.mdx index 35665e34..1ebf859e 100644 --- a/docs/de/agenteye/getting-started.mdx +++ b/docs/de/agenteye/getting-started.mdx @@ -4,32 +4,32 @@ description: "AgentEye – Dokumentation für den Einstieg." --- -Diese Anleitung führt Sie durch die vollständige AgentEye-Einrichtung: Server und Dashboard bereitstellen, den Collector auf einem Agent-Rechner installieren und Ihren Python-Agent-Code instrumentieren. +Diese Anleitung führt Sie durch eine vollständige AgentEye-Einrichtung: Bereitstellung des Servers und Dashboards, Installation des Collectors auf einem Agent-Rechner sowie die Instrumentierung Ihres Python-Agent-Codes. --- ## Was ist AgentEye? -AgentEye ist eine **selbst gehostete Observability- und Evaluierungsplattform für KI-Agenten**. Sie zeichnet auf, was Ihre Agenten tun – jeden Schritt eines Durchlaufs – und bewertet automatisch die Qualität jedes abgeschlossenen Durchlaufs. So können Sie sehen, wie sich Ihre Agenten in der Produktion verhalten, und Regressionen erkennen, bevor Ihre Nutzer davon betroffen sind. +AgentEye ist eine **selbst gehostete Observability- und Evaluierungsplattform für KI-Agenten**. Sie zeichnet auf, was Ihre Agenten tun – jeden Schritt eines Laufs – und bewertet automatisch die Qualität jedes abgeschlossenen Laufs. So können Sie das Verhalten Ihrer Agenten in der Produktion nachverfolgen und Regressionen erkennen, bevor Ihre Nutzer sie bemerken. -Die Daten fließen in eine Richtung: Ihr Agent-Code sendet **Events** über das **Python SDK** → ein schlanker **Collector**-Daemon bündelt und übermittelt sie an den **Server** → Events und Analysen werden in **ClickHouse** gespeichert (operativer Zustand wie Organisationen, Nutzer, API-Keys, Dashboards und gespeicherte Abfragen liegt in **Postgres**) → Sie erkunden alles im **Dashboard**. +Die Daten fließen in eine Richtung: Ihr Agent-Code sendet **Events** über das **Python SDK** → ein leichtgewichtiger **Collector**-Daemon bündelt und übermittelt sie an den **Server** → Events und Analysen werden in **ClickHouse** gespeichert (operativer Zustand wie Organisationen, Nutzer, API-Schlüssel, Dashboards und gespeicherte Abfragen liegt in **Postgres**) → alles wird im **Dashboard** exploriert. Was Sie erhalten: -- **Events** – der rohe, schrittweise Verlauf jedes Agenten-Durchlaufs (Tool-Aufrufe, Modell-Aufrufe, Hooks, Fehler). -- **Sessions** – diese Events zu einer Zeile pro Durchlauf zusammengefasst, jede **automatisch ausgewertet** und bewertet. -- **Evaluierungen** – Qualitätsbewertungen, die von Ihren eigenen Evaluator-Diensten erzeugt werden, sodass Qualitätseinbrüche ohne manuellen Review sichtbar werden. -- **Abfragen & Dashboards** – gespeicherte ClickHouse-SQL-Abfragen über Ihre Daten, als geteilte, organisationsweite Dashboards dargestellt. -- **Alerts & Incidents** – Schwellenwertregeln, die Sie benachrichtigen (E-Mail, Slack, Webhook, im Dashboard), plus ein Incident-Workflow zur Triage. -- **CLI & KI-Assistent** – ein Terminal-Client (`agenteye`) und ein Dashboard-Assistent, mit dem Sie Fragen in natürlicher Sprache stellen können. +- **Events** — der rohe, schrittweise Verlauf jedes Agent-Laufs (Tool-Aufrufe, Modell-Aufrufe, Hooks, Fehler). +- **Sessions** — diese Events zusammengefasst zu einer Zeile pro Lauf, jeweils **automatisch bewertet** und bewertet. +- **Evaluierungen** — Qualitätswerte, die von Ihren eigenen Evaluierungs-Services erzeugt werden, damit Qualitätseinbrüche ohne manuellen Review sichtbar werden. +- **Abfragen & Dashboards** — gespeicherte ClickHouse-SQL-Abfragen über Ihre Daten, als gemeinsame, organisationsweite Dashboards dargestellt. +- **Alerts & Incidents** — Schwellenwertregeln, die Sie benachrichtigen (E-Mail, Slack, Webhook, im Dashboard) sowie ein Incident-Workflow zur Triage. +- **CLI & KI-Assistent** — ein Terminal-Client (`agenteye`) und ein Dashboard-integrierter Assistent für Fragen in natürlicher Sprache. -Sie betreiben alles in Ihrer eigenen Infrastruktur – als einzelner Docker Compose-Stack (diese Anleitung), als produktionsreife Kubernetes-Installation oder als einzelner co-located Pod. Der Rest dieser Anleitung richtet den Compose-Stack von Anfang bis Ende ein. +Sie betreiben alles in Ihrer eigenen Infrastruktur – als einzelner Docker-Compose-Stack (diese Anleitung), als produktives Kubernetes-Setup oder als einzelner co-located Pod. Der Rest dieser Anleitung richtet den Compose-Stack vollständig ein. --- ## Schritt 1: Authentifizierung -Alle AgentEye-Artefakte werden über die GitHub-Organisation `agenteye-enterprise` bereitgestellt. Als Enterprise-Entwickler können Sie einen eigenen GitHub PAT generieren. Folgen Sie [enterprise-docs/github-token.md](/de/agenteye/github-token) für genaue Schritte und erforderliche Berechtigungen. +Alle AgentEye-Artefakte werden aus der GitHub-Organisation `agenteye-enterprise` bereitgestellt. Als Enterprise-Entwickler können Sie Ihren eigenen GitHub PAT generieren. Folgen Sie [enterprise-docs/github-token.md](/de/agenteye/github-token) für genaue Schritte und erforderliche Berechtigungen. ```bash export AGENTEYE_TOKEN= @@ -42,9 +42,9 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin ## Schritt 2: Server und Dashboard bereitstellen -Der Server empfängt Events von Collectors und macht sie abfragbar; das Dashboard ist der Ort, an dem Sie sie erkunden. Eingehende Events und Analysen werden in ClickHouse gespeichert (dem erforderlichen Analytics-Store), während Postgres den operativen Zustand wie Organisationen, Nutzer, API-Keys, Dashboards und gespeicherte Abfragen hält. +Der Server empfängt Events von Collectors und macht sie abfragbar; das Dashboard ist der Ort, an dem Sie diese explorieren. Aufgenommene Events und Analysen liegen in ClickHouse (dem erforderlichen Analytics-Store), während Postgres den operativen Zustand wie Organisationen, Nutzer, API-Schlüssel, Dashboards und gespeicherte Abfragen vorhält. -**Compose-Datei herunterladen:** +**Veröffentlichte Compose-Datei herunterladen:** ```bash mkdir -p ./agenteye @@ -55,38 +55,32 @@ curl -fsSL \ cd agenteye ``` -**Geheimnisse festlegen:** +**Secrets setzen:** -Erstellen Sie eine `.env`-Datei, damit das Deployment nicht mit den Standard-`admin`-Zugangsdaten läuft. Mindestens `ADMIN_KEY` und `POSTGRES_PASSWORD` müssen gesetzt werden: +Erstellen Sie eine `.env`-Datei, damit das Deployment nicht mit den Standard-`admin`-Zugangsdaten läuft. Setzen Sie mindestens `ADMIN_KEY` und `POSTGRES_PASSWORD`: ```bash POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -Exportieren Sie `ADMIN_KEY` auch in Ihrer aktuellen Shell, damit spätere Schritte (z. B. das `curl` in Schritt 3) direkt darauf zugreifen können: - -```bash -export ADMIN_KEY=your-admin-secret -``` - **Stack starten:** ```bash docker compose up -d ``` -Dies startet den vollständigen Stack, einschließlich des erforderlichen ClickHouse-Analytics-Stores und eines optionalen Redis-Caches, zusammen mit Server und Dashboard. ClickHouse muss gesund sein, damit der Server startet. +Dadurch wird der vollständige Stack hochgefahren, einschließlich des erforderlichen ClickHouse-Analytics-Stores und eines optionalen Redis-Caches, neben Server und Dashboard. ClickHouse muss bereit sein, damit der Server starten kann. -Der Server hört nun unter `http://localhost:8080` und das Dashboard unter `http://localhost:3000`. +Der Server lauscht nun unter `http://localhost:8080` und das Dashboard unter `http://localhost:3000`. -Für Produktionsdeployments (eigenes Postgres, TLS, Reverse Proxy) siehe [enterprise-docs/deployment.md](/de/agenteye/deployment). +Für Produktions-Deployments (eigenes Postgres, TLS, Reverse Proxy) siehe [enterprise-docs/deployment.md](/de/agenteye/deployment). --- -## Schritt 3: API-Key für den Collector erstellen +## Schritt 3: API-Schlüssel für den Collector erstellen -Jeder Collector authentifiziert sich mit einem scoped API-Key. Verwenden Sie den in Schritt 2 gesetzten `ADMIN_KEY`, um einen zu erstellen: +Jeder Collector authentifiziert sich mit einem bereichsgebundenen API-Schlüssel. Verwenden Sie den in Schritt 2 gesetzten `ADMIN_KEY`, um einen zu erstellen: ```bash curl -s -X POST http://localhost:8080/keys \ @@ -95,7 +89,7 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -Den `key`-Wert legen Sie selbst fest; verwenden Sie ihn in der Collector-Konfiguration in Schritt 4. Siehe [enterprise-docs/api-keys.md](/de/agenteye/api-keys) für die vollständige Key-Verwaltung. +Den `key`-Wert legen Sie selbst fest; verwenden Sie ihn in der Collector-Konfiguration in Schritt 4. Vollständiges Key-Management finden Sie unter [enterprise-docs/api-keys.md](/de/agenteye/api-keys). --- @@ -114,7 +108,7 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> Dies lädt den **Linux x86_64**-Build herunter. Für macOS (Apple Silicon oder Intel), Linux arm64 oder Docker/systemd/launchd-Setup siehe [collector-installation.md](/de/agenteye/collector-installation), das den Download für jede Plattform auflistet – der obige Befehl installiert eine Linux-Binärdatei, die auf anderen Plattformen nicht funktioniert. +> Hiermit wird das **Linux x86_64**-Build heruntergeladen. Für macOS (Apple Silicon oder Intel), Linux arm64 oder ein Setup mit Docker / systemd / launchd siehe [collector-installation.md](/de/agenteye/collector-installation), das den Download für jede Plattform auflistet – der obige Befehl installiert eine Linux-Binärdatei, die auf anderen Plattformen nicht läuft. **Konfigurieren:** @@ -146,7 +140,7 @@ Für Docker-, systemd- und launchd-Setup siehe [enterprise-docs/collector-instal ## Schritt 5: Python SDK installieren -Installieren Sie das Wheel aus GitHub Releases auf jedem Rechner, auf dem Sie Agent-Code instrumentieren möchten. +Installieren Sie das Wheel von GitHub Releases auf jedem Rechner, auf dem Sie Agent-Code instrumentieren möchten. ```bash VERSION=0.0.1b9 @@ -160,7 +154,7 @@ pip install agenteye-${VERSION}-py3-none-any.whl ## Schritt 6: Ihren Agenten instrumentieren -Fügen Sie Events zu Ihrem Agent-Code hinzu. Senden Sie mindestens `agent_start` und `agent_end`: +Fügen Sie Events in Ihren Agent-Code ein. Senden Sie mindestens `agent_start` und `agent_end`: ```python import agenteye @@ -180,56 +174,56 @@ agenteye.event.agent_end( ) ``` -Events werden gepuffert und alle 500 ms nach `$AGENTEYE_HOME/events/` (bzw. `~/.agenteye/events/`, wenn `AGENTEYE_HOME` nicht gesetzt ist) geleert. Der Collector nimmt sie automatisch auf. +Events werden gepuffert und alle 500 ms nach `$AGENTEYE_HOME/events/` (bzw. `~/.agenteye/events/`, falls `AGENTEYE_HOME` nicht gesetzt ist) geschrieben. Der Collector nimmt sie automatisch auf. -Siehe [enterprise-docs/python-sdk.md](/de/agenteye/python-sdk) für die vollständige Event-API. +Vollständige Event-API unter [enterprise-docs/python-sdk.md](/de/agenteye/python-sdk). --- ## Schritt 7: Events im Dashboard anzeigen -Öffnen Sie `http://your-dashboard-host:3000` und melden Sie sich an. AgentEye sendet Ihnen einen Einmalcode per E-Mail (oder einen Magic Link per Klick), sodass kein Passwort verwaltet werden muss. +Öffnen Sie `http://your-dashboard-host:3000` und melden Sie sich an. AgentEye sendet Ihnen einen Einmal-Code per E-Mail (oder einen Magic Link mit einem Klick), sodass kein Passwort verwaltet werden muss. -![Der AgentEye-Anmeldebildschirm, der einen Einmalcode an Ihre E-Mail-Adresse sendet](/agenteye/images/login.png) +![Der AgentEye-Anmeldebildschirm, der einen Einmal-Code an Ihre E-Mail-Adresse sendet](/agenteye/images/login.png) -Nach dem Einloggen zeigt die Seite **Events** einen Live-Verlauf aller eingehenden Events. Filtern Sie nach `session_id` oder `agent_id`, um in einen bestimmten Durchlauf zu wechseln. +Nach der Anmeldung zeigt die Seite **Events** einen Live-Verlauf aller aufgenommenen Events. Filtern Sie nach `session_id` oder `agent_id`, um in einen bestimmten Lauf einzutauchen. -![Der Live-Events-Stream, farblich nach Event-Typ kodiert und filterbar nach Umgebung, Agent und Session](/agenteye/images/events-stream.png) +![Der Live-Events-Stream, farblich nach Event-Typ codiert und nach Umgebung, Agent und Session filterbar](/agenteye/images/events-stream.png) -Die Seite **Sessions** fasst diese Events zu einer Zeile pro Durchlauf zusammen. AgentEye wertet abgeschlossene Sessions automatisch aus, sodass jeder Durchlauf bewertet wird und Qualitätsregressionen ohne manuellen Review sichtbar werden; der aktuelle Bewertungsscore erscheint auf jeder Zeile auf einen Blick: +Die Seite **Sessions** fasst diese Events zu einer Zeile pro Lauf zusammen. AgentEye bewertet abgeschlossene Sessions automatisch, sodass jeder Lauf bewertet wird und Qualitätsregressionen ohne manuellen Review sichtbar werden; der aktuelle Bewertungswert erscheint auf einen Blick in jeder Zeile: -![Die Sessions-Liste, eine Zeile pro Durchlauf, mit Status-Badges und Bewertungsscores](/agenteye/images/sessions-list.png) +![Die Sessions-Liste, eine Zeile pro Lauf, mit Status-Indikatoren und Bewertungs-Badges](/agenteye/images/sessions-list.png) -Informationen zur Konfiguration der Session-Bewertung finden Sie unter [enterprise-docs/evaluation-suite.md](/de/agenteye/evaluation-suite). +Zur Konfiguration der Session-Bewertung siehe [enterprise-docs/evaluation-suite.md](/de/agenteye/evaluation-suite). -Klicken Sie auf eine Session, um ihren **Ausführungsgraphen** zu öffnen – eine Git-artige Ansicht, wie Agenten, Tools, Hooks und Modell-Aufrufe sich über die Zeit entfaltet haben, mit parallelen Sub-Agenten in eigenen Spuren und einer Aufschlüsselung pro Durchlauf in der rechten Seitenleiste: +Klicken Sie auf eine Session, um ihren **Ausführungsgraphen** zu öffnen – eine Git-ähnliche Ansicht, wie Agenten, Tools, Hooks und Modell-Aufrufe über die Zeit verlaufen sind, mit parallelen Sub-Agenten in eigenen Spuren und einer laufspezifischen Aufschlüsselung in der rechten Spalte: -![Der Git-artige Ausführungsgraph einer Session neben ihrer Event-Timeline mit dem Tool/Modell/Hook-Aufschlüsselungs-Panel](/agenteye/images/session-detail.png) +![Der Git-artige Ausführungsgraph einer Session neben ihrer Event-Timeline, mit dem Tool/Modell/Hook-Aufschlüsselungs-Panel](/agenteye/images/session-detail.png) --- -## Schritt 8: Erkunden, visualisieren und alertieren +## Schritt 8: Explorieren, visualisieren und Alerts einrichten -Mit fließenden Events verwandeln die **Analyse**-Seiten rohe Aktivitäten in Antworten – so können Sie das Verhalten der Agenten messen, Erkenntnisse im Team teilen und sofort benachrichtigt werden, wenn etwas regressiert. Dashboard-Seiten sind organisationsweit zugänglich, daher sind die URLs in der Adressleiste mit Ihrem Org-Slug vorangestellt (`//…`). +Sobald Events einfließen, verwandeln die **Analyse**-Seiten die rohe Aktivität in Antworten, sodass Sie das Agentenverhalten messen, Erkenntnisse im Team teilen und sofort benachrichtigt werden, wenn etwas regressiert. Dashboard-Seiten sind organisationsweit, daher sind die URLs in der Adressleiste mit Ihrem Org-Slug prefixiert (`//…`). -- **Abfragen** (`//queries`): Starten Sie mit einer Bibliothek gespeicherter, wiederverwendbarer Abfragen über Ihre Events und Evaluierungen (integrierte Vorlagen plus eigene)… +- **Abfragen** (`//queries`): Starten Sie mit einer Bibliothek gespeicherter, wiederverwendbarer Abfragen über Ihre Events und Evaluierungen (integrierte Voreinstellungen und eigene)… -![Die Bibliothek gespeicherter Abfragen: ein Raster wiederverwendbarer Abfragen, sowohl integrierte Vorlagen als auch eigene](/agenteye/images/queries.png) +![Die Bibliothek gespeicherter Abfragen: ein Raster wiederverwendbarer Abfragen, sowohl integrierte Voreinstellungen als auch benutzerdefinierte](/agenteye/images/queries.png) …öffnen Sie dann eine im SQL-Composer, um sie anzupassen und mit Live-Ergebnissen auszuführen: -![Der SQL-Abfrage-Composer, der eine gespeicherte Abfrage ausführt, mit Schema-Seitenleiste und Live-Ergebnisraster](/agenteye/images/query-lab.png) +![Der SQL-Abfrage-Composer mit einer gespeicherten Abfrage, einer Schema-Seitenleiste und einem Live-Ergebnisraster](/agenteye/images/query-lab.png) -- **Dashboards** (`//dashboards`): Heften Sie Abfragen als Linien-, Balken-, Flächen- oder Kreisdiagramm-Kacheln an geteilte, organisationsweite Dashboards. +- **Dashboards** (`//dashboards`): Heften Sie Abfragen als Linien-, Balken-, Flächen- oder Kreisdiagramm-Kacheln in gemeinsame, organisationsweite Dashboards. -![Ein aus gespeicherten Abfragen erstelltes Dashboard: eine Events-pro-Stunde-Linie, ein Fehler-nach-Typ-Balkendiagramm, ein Latenz-Flächendiagramm und Tokens nach Modell](/agenteye/images/dashboard-fleet.png) +![Ein aus gespeicherten Abfragen erstelltes Dashboard: eine Ereignisse-pro-Stunde-Linie, ein Fehler-nach-Typ-Balken, ein Latenz-Flächendiagramm und Tokens nach Modell](/agenteye/images/dashboard-fleet.png) -- **Alerts** (`//alerts`): Erheben Sie beliebige Schwellenwerte zu Benachrichtigungsregeln, die per E-Mail, Slack, Webhook oder im Dashboard informieren. Siehe [enterprise-docs/alerts.md](/de/agenteye/alerts). +- **Alerts** (`//alerts`): Wandeln Sie jeden Schwellenwert in eine Benachrichtigungsregel um, die per E-Mail, Slack, Webhook oder im Dashboard informiert. Siehe [enterprise-docs/alerts.md](/de/agenteye/alerts). --- ## Nächste Schritte -- [Deployment](/de/agenteye/deployment): Produktionsreife Absicherung +- [Deployment](/de/agenteye/deployment): Für die Produktion absichern - [API Keys](/de/agenteye/api-keys): Zugriff verwalten - [Troubleshooting](/de/agenteye/troubleshooting): Probleme diagnostizieren \ No newline at end of file diff --git a/docs/de/agenteye/managed-deployment.mdx b/docs/de/agenteye/managed-deployment.mdx index b44ec46e..398aef09 100644 --- a/docs/de/agenteye/managed-deployment.mdx +++ b/docs/de/agenteye/managed-deployment.mdx @@ -1,158 +1,158 @@ --- title: "Managed Deployment auf Ihrem Kubernetes-Cluster" -description: "Dokumentation zur AgentEye Managed Deployment auf Ihrem Kubernetes-Cluster." +description: "Dokumentation zum AgentEye Managed Deployment auf Ihrem Kubernetes-Cluster." --- -AgentEye ist eine selbst gehostete Observability- und Evaluierungsplattform für KI- und LLM-Agenten. Sie erfasst Agentensitzungen, Tool-Aufrufe, Modellanfragen und Fehler, wandelt diese in durchsuchbare Analysen und Evaluierungen um und stellt die Ergebnisse in einem Dashboard mit einem optionalen schreibgeschützten KI-Assistenten bereit. +AgentEye ist eine selbst gehostete Observability- und Evaluierungsplattform für KI- und LLM-Agenten. Sie erfasst Agenten-Sessions, Tool-Aufrufe, Modellanfragen und Fehler, verwandelt diese in durchsuchbare Analysen und Evaluierungen und stellt die Ergebnisse in einem Dashboard mit einem optionalen schreibgeschützten KI-Assistenten bereit. -Im Managed-Deployment-Modell stellen Sie einen dedizierten Kubernetes-Cluster zur Verfügung, und Exosphere betreibt die gesamte Plattform darin – Deployment, Konfiguration, Betrieb, Backups und Upgrades aller Komponenten erfolgen in Ihrem Namen. Ihr Team profitiert vom vollen Mehrwert der Plattform (Agenten-Transparenz, Analysen, Evaluierung und der optionale Assistent), ohne Datenbanken, Zertifikate oder Upgrades selbst verwalten zu müssen. Alle Daten verbleiben in Ihrem Cloud-Konto. +Im Managed-Deployment-Modell stellen Sie einen dedizierten Kubernetes-Cluster bereit, und Exosphere betreibt die gesamte Plattform darin – einschließlich Deployment, Konfiguration, Betrieb, Backup und Upgrades aller Komponenten in Ihrem Auftrag. Ihr Team profitiert vom vollen Plattformwert (Agenten-Transparenz, Analysen, Evaluierung und der optionale Assistent), ohne selbst Datenbanken, Zertifikate oder Upgrades verwalten zu müssen. Alle Daten verbleiben in Ihrem Cloud-Account. --- ## Voraussetzungen -- Ein **GitHub PAT** zum Abrufen von Container-Images und zum Herunterladen von Artefakten (siehe [GitHub Token Setup](/de/agenteye/github-token)) +- Ein **GitHub PAT** zum Abrufen von Container-Images und zum Herunterladen von Artefakten (siehe [enterprise-docs/github-token.md](/de/agenteye/github-token)) - Ein **dedizierter Kubernetes-Cluster** (siehe Anforderungen unten) - Ein **Storage-Bucket** für Datenbank-Backups - **Netzwerkkonnektivität**: Port 443 eingehend zum Load Balancer des Clusters --- -## Schritt 1: Einen dedizierten Kubernetes-Cluster bereitstellen +## Schritt 1: Dedizierten Kubernetes-Cluster bereitstellen -Erstellen Sie einen Kubernetes-Cluster, der ausschließlich für AgentEye vorgesehen ist. Er sollte nicht mit anderen Workloads geteilt werden, damit die gesamte Plattform (Anwendungsdienste, Datenbanken, Analysen und Caching) isoliert läuft, ohne Ihre bestehende Infrastruktur zu beeinträchtigen. +Erstellen Sie einen Kubernetes-Cluster, der ausschließlich für AgentEye genutzt wird. Er sollte nicht mit anderen Workloads geteilt werden, damit die gesamte Plattform (Anwendungsdienste, Datenbanken, Analysen und Caching) isoliert läuft und Ihre bestehende Infrastruktur nicht beeinträchtigt. | Anforderung | Details | |---|---| -| **Distribution** | Jedes konforme Kubernetes: EKS, GKE, AKS oder selbst verwaltet | -| **Version** | 1.27 oder höher | -| **Node-Pool** | Mindestens: **3 Nodes, je 4 vCPU / 8 GB RAM** (Standard-General-Purpose-Instanzen) | +| **Distribution** | Beliebiges konformes Kubernetes: EKS, GKE, AKS oder selbst verwaltet | +| **Version** | 1.27 oder neuer | +| **Node-Pool** | Minimum: **3 Nodes, jeweils 4 vCPU / 8 GB RAM** (Standard-General-Purpose-Instanzen) | | **Storage** | Eine Standard-StorageClass, die Block-Volumes bereitstellt (z. B. `gp3` auf AWS, `pd-ssd` auf GCP) | | **Load Balancer** | Der Cluster muss in der Lage sein, Cloud-LoadBalancer-Services bereitzustellen (Standard bei EKS, GKE, AKS) | -> Exosphere installiert und verwaltet alles Weitere innerhalb des Clusters: Ingress-Controller, TLS-Zertifikate, Datenbanken, Caching, Monitoring und alle Anwendungs-Deployments. +> Exosphere installiert und verwaltet alles weitere im Cluster: Ingress-Controller, TLS-Zertifikate, Datenbanken, Caching, Monitoring und alle Anwendungs-Deployments. --- -## Schritt 2: Dem AgentEye-Team Zugriff gewähren +## Schritt 2: Zugang für das AgentEye-Team gewähren -Exosphere benötigt Cluster-Admin-Zugriff (oder gleichwertige umfangreiche RBAC-Berechtigungen), um Namespaces, Custom Resource Definitions, Ingress-Controller und Storage-Provisioner zu verwalten. +Exosphere benötigt cluster-admin-Zugriff (oder gleichwertige umfangreiche RBAC-Berechtigungen), um Namespaces, Custom Resource Definitions, Ingress-Controller und Storage-Provisioner zu verwalten. | Anforderung | Details | |---|---| | **Zugriffsmethode** | IAM-Rolle (bevorzugt für EKS/GKE), kubeconfig oder SSO-basierter Zugriff | -| **VPN / Bastion** | Falls der Kubernetes-API-Server privat ist, stellen Sie VPN-Zugangsdaten oder Bastion-Zugriff für das Exosphere-Operations-Team bereit | +| **VPN / Bastion** | Wenn der Kubernetes-API-Server privat ist, stellen Sie VPN-Zugangsdaten oder Bastion-Zugriff für das Exosphere-Operations-Team bereit | --- ## Schritt 3: Netzwerkkonnektivität konfigurieren -Ihr Netzwerk-Team muss eingehenden Traffic auf **Port 443** zu den Load Balancern des Clusters erlauben. Das Deployment betreibt zwei separate Load Balancer: einen für die Event-Ingestion (mTLS-geschützt) und einen für das Dashboard: +Ihr Netzwerk-Team muss eingehenden Traffic auf **Port 443** zu den Load Balancern des Clusters zulassen. Das Deployment betreibt zwei separate Load Balancer: einen für die Event-Ingestion (mTLS-geschützt) und einen für das Dashboard: | Traffic | Quelle | Ziel | Sicherheit | |---|---|---|---| -| **Event-Ingestion** | Collector-Pods in Ihren Clustern | Ingest LoadBalancer, Port 443 | mTLS (Client-Zertifikat) + API-Schlüssel | -| **Dashboard** | Entwickler-Browser | Dashboard LoadBalancer, Port 443 | HTTPS auf Ihrer Domain, passwortloser E-Mail-OTP-Login | +| **Event-Ingestion** | Collector-Pods in Ihren Clustern | Ingest-LoadBalancer, Port 443 | mTLS (Client-Zertifikat) + API-Key | +| **Dashboard** | Entwickler-Browser | Dashboard-LoadBalancer, Port 443 | HTTPS auf Ihrer Domain, passwortloser E-Mail-OTP-Login | -Der Ingest-Endpunkt ist durch Mutual TLS geschützt; Collectors müssen bei jeder Anfrage sowohl ein gültiges Client-Zertifikat **als auch** einen gültigen API-Schlüssel vorweisen. Das Dashboard läuft auf seinem eigenen Load Balancer und Hostnamen, wobei der Login auf Ihre freigeschalteten E-Mail-Adressen/Domains beschränkt ist. +Der Ingest-Endpunkt ist durch gegenseitiges TLS geschützt; Collectors müssen bei jeder Anfrage sowohl ein gültiges Client-Zertifikat **als auch** einen gültigen API-Key vorweisen. Das Dashboard läuft auf seinem eigenen Load Balancer und Hostnamen, wobei der Login auf Ihre erlaubten E-Mail-Adressen/Domains beschränkt ist. -**DNS-Einträge (einmalig):** Sie erstellen zwei CNAME-Einträge unter einer Domain Ihrer Wahl – einen für den Ingest-Endpunkt und einen für das Dashboard (z. B. `agenteye.ihr-unternehmen.beispiel`) – die auf die von Exosphere bereitgestellten Load-Balancer-Hostnamen verweisen. Exosphere stellt anschließend automatisch öffentlich vertrauenswürdige TLS-Zertifikate für beide Hostnamen bereit, einschließlich der Erneuerung. +**DNS-Einträge (einmalig):** Sie erstellen zwei CNAME-Einträge unter einer Domain, die Sie kontrollieren – einen für den Ingest-Endpunkt und einen für das Dashboard (z. B. `agenteye.your-company.example`) – die auf die von Exosphere bereitgestellten Load-Balancer-Hostnamen verweisen. Exosphere stellt dann automatisch öffentlich vertrauenswürdige TLS-Zertifikate für beide Hostnamen bereit, einschließlich der Erneuerungen. -> **Hinweis zu Port 80:** Die automatisierte Zertifikatsausstellung und -erneuerung erfolgt über HTTP auf Port 80 jedes Load Balancers. Falls Ihre Sicherheitsrichtlinien es erfordern, den Dashboard-Load-Balancer auf unternehmenseigene IP-Bereiche zu beschränken, informieren Sie Exosphere im Voraus – wir wechseln dann zur DNS-basierten Zertifikatsvalidierung (ein zusätzlicher DNS-Eintrag auf Ihrer Seite), damit Erneuerungen auch hinter der Einschränkung funktionieren. +> **Hinweis zu Port 80:** Die automatische Zertifikatsausstellung und -erneuerung erfolgt über HTTP auf Port 80 jedes Load Balancers. Wenn Ihre Sicherheitsrichtlinien die Einschränkung des Dashboard-Load-Balancers auf unternehmenseigene IP-Bereiche erfordern, teilen Sie dies Exosphere vorab mit – wir wechseln dann auf eine DNS-basierte Zertifikatsvalidierung (ein zusätzlicher DNS-Eintrag auf Ihrer Seite), damit Erneuerungen auch hinter der Einschränkung funktionieren. -> **Ausgehend:** Cluster-Nodes benötigen Internetzugang, um Container-Images von `ghcr.io` abzurufen. Falls Ihr Netzwerk ausgehenden Traffic einschränkt, nehmen Sie `ghcr.io` in die Allowlist auf oder spiegeln Sie Images in Ihre interne Registry. +> **Ausgehend:** Cluster-Nodes benötigen Internet-Zugriff, um Container-Images von `ghcr.io` zu beziehen. Wenn Ihr Netzwerk ausgehenden Traffic einschränkt, nehmen Sie `ghcr.io` in die Allowlist auf oder spiegeln Sie Images in Ihre interne Registry. --- -## Schritt 4: Einen Backup-Storage-Bucket bereitstellen +## Schritt 4: Backup-Storage-Bucket bereitstellen Datenbank-Backups werden in einem Cloud-Storage-Bucket gespeichert, der Ihnen gehört. | Anforderung | Details | |---|---| | **Dienst** | S3 (AWS), GCS (GCP) oder Azure Blob Storage | -| **Zugriff** | Erteilen Sie den Cluster-Nodes Schreibzugriff über IAM-Rolle für Service Accounts (IRSA auf EKS, Workload Identity auf GKE) oder stellen Sie Zugangsdaten bereit | -| **Aufbewahrung** | Sie steuern die Lifecycle-Policy des Buckets (Aufbewahrungszeitraum, Archivierungsregeln). Exosphere schreibt Backups; Sie entscheiden, wie lange diese aufbewahrt werden | +| **Zugriff** | Gewähren Sie den Cluster-Nodes Schreibzugriff über eine IAM-Rolle für Service Accounts (IRSA auf EKS, Workload Identity auf GKE) oder stellen Sie Zugangsdaten bereit | +| **Aufbewahrung** | Sie kontrollieren die Lifecycle-Policy des Buckets (Aufbewahrungszeitraum, Archivierungsregeln). Exosphere schreibt Backups; Sie entscheiden, wie lange sie aufbewahrt werden | -Ein tägliches Backup sichert sowohl PostgreSQL (relationaler Zustand) als auch ClickHouse (Events und Evaluierungen) in einem komprimierten Archiv und lädt es in Ihren Bucket hoch. Backups werden auch vor jedem Upgrade durchgeführt. +Ein tägliches Backup sichert sowohl PostgreSQL (relationale Zustandsdaten) als auch ClickHouse (Events und Evaluierungen) in einem komprimierten Archiv und lädt es in Ihren Bucket hoch. Backups werden außerdem vor jedem Upgrade durchgeführt. --- -## Schritt 5: Einen Ansprechpartner benennen +## Schritt 5: Ansprechpartner benennen -Benennen Sie eine Person oder einen Slack/Teams-Kanal auf Ihrer Seite für Probleme auf Cluster-Ebene: Node-Gesundheit, Cloud-Kontolimits, Netzwerkänderungen. Der tägliche Betrieb erfordert diesen Kontakt nicht. +Benennen Sie eine Person oder einen Slack/Teams-Kanal auf Ihrer Seite für Fragen auf Cluster-Ebene: Node-Health, Cloud-Account-Limits, Netzwerkänderungen. Der tägliche Betrieb erfordert diesen Kontakt nicht. --- ## Was wir deployen -Sobald Exosphere Cluster-Zugriff hat, werden folgende Komponenten für Sie deployed und verwaltet: +Sobald Exosphere Cluster-Zugriff hat, werden folgende Komponenten für Sie deployt und verwaltet: -| Komponente | Rolle | +| Komponente | Funktion | |---|---| | **AgentEye Server** | HTTP-API, die Events von Collectors empfängt, Analysen ausführt und Daten an das Dashboard liefert | -| **Dashboard** | Web-Interface zur Anzeige von Agentensitzungen, Tool-Aufrufen, Modellanfragen und Fehlern; beherbergt den optionalen schreibgeschützten KI-Assistenten | -| **ClickHouse** | Erforderlicher kanonischer Speicher für aufgenommene Events, Analysen und Evaluierungen | -| **PostgreSQL** | Relationaler Speicher für Organisationen, API-Schlüssel, Benutzer, Dashboards und gespeicherte Abfragen | -| **Redis** | Optionaler gemeinsamer Cache und Rate-Limit-Backend; die Plattform degradiert bei Nichtverfügbarkeit graceful | -| **KI-Assistent (optional)** | Interner schreibgeschützter Assistenten-Container; bleibt deaktiviert, bis ein LLM-Endpunkt konfiguriert ist | -| **Ingress-Controller** | Zwei Load Balancer (einer für mTLS-geschützten Ingest, einer für das Dashboard), die TLS mit öffentlich vertrauenswürdigen, automatisch erneuerten Zertifikaten terminieren und mTLS am Ingest-Endpunkt durchsetzen | +| **Dashboard** | Web-Interface zur Anzeige von Agenten-Sessions, Tool-Aufrufen, Modellanfragen und Fehlern; enthält den optionalen schreibgeschützten KI-Assistenten | +| **ClickHouse** | Erforderlicher kanonischer Speicher für ingested Events, Analysen und Evaluierungen | +| **PostgreSQL** | Relationaler Speicher für Organisationen, API-Keys, Benutzer, Dashboards und gespeicherte Abfragen | +| **Redis** | Optionaler gemeinsamer Cache und Rate-Limit-Backend; die Plattform degradiert graceful, wenn er nicht verfügbar ist | +| **KI-Assistent (optional)** | Interner schreibgeschützter Assistenten-Container; bleibt deaktiviert, bis ein LLM-Endpunkt konfiguriert wird | +| **Ingress-Controller** | Zwei Load Balancer (einer für mTLS-geschützte Ingestion, einer für das Dashboard), die TLS mit öffentlich vertrauenswürdigen, automatisch erneuerten Zertifikaten terminieren und mTLS am Ingest-Endpunkt durchsetzen | | **cert-manager** | Automatisiert die TLS-Zertifikatsbereitstellung und die Ausstellung von mTLS-Client-Zertifikaten | -| **Zertifikats-Monitoring** | Ein geplanter Job prüft den Ablauf von Zertifikaten und sendet Benachrichtigungen (z. B. an Slack), wenn Zertifikate kurz vor der Erneuerung stehen | +| **Zertifikats-Monitoring** | Ein geplanter Job prüft den Ablauf von Zertifikaten und sendet Warnmeldungen (z. B. an Slack), wenn Zertifikate ihrer Erneuerung nähern | -Das Managed-Angebot betreibt auch die Evaluierungspipeline der Plattform, die Agentenaktivitäten anhand Ihrer Evaluierungskriterien bewertet. Siehe [Assistant](/de/agenteye/assistant) und [Evaluation Suite](/de/agenteye/evaluation-suite) für Details zu diesen Funktionen. +Das Managed-Angebot betreibt außerdem die Evaluierungspipeline der Plattform, die Agentenaktivitäten anhand Ihrer Evaluierungskriterien bewertet. Weitere Informationen zu diesen Funktionen finden Sie unter [enterprise-docs/assistant.md](/de/agenteye/assistant) und [enterprise-docs/evaluation-suite.md](/de/agenteye/evaluation-suite). --- -## Was wir Ihnen bereitstellen +## Was Sie von uns erhalten Nach Abschluss des Deployments erhalten Sie: | Element | Details | |---|---| -| **Dashboard-URL** | Ein Hostname unter Ihrer Domain (z. B. `https://agenteye.ihr-unternehmen.beispiel`), bereitgestellt mit einem öffentlich vertrauenswürdigen, automatisch erneuerten TLS-Zertifikat. Sie erstellen einen CNAME auf den von uns bereitgestellten Load-Balancer-Hostnamen; der Login erfolgt über passwortlosen E-Mail-OTP | -| **Collector-Endpunkt** | Der `/events`-Pfad des Ingest-Hostnamens (z. B. `https://ingest.ihr-unternehmen.beispiel/events`), mTLS-geschützt | -| **Client-Zertifikatspaket** | Pro Cluster: Client-Zertifikat, privater Schlüssel und CA-Zertifikat, geliefert als Kubernetes-Secret-Manifest. Einmalig pro Cluster anwenden | +| **Dashboard-URL** | Ein Hostname unter Ihrer Domain (z. B. `https://agenteye.your-company.example`), mit einem öffentlich vertrauenswürdigen, automatisch erneuerten TLS-Zertifikat bereitgestellt. Sie erstellen einen CNAME zum von uns bereitgestellten Load-Balancer-Hostnamen; der Login erfolgt passwortlos per E-Mail-OTP | +| **Collector-Endpunkt** | Der `/events`-Pfad des Ingest-Hostnamens (z. B. `https://ingest.your-company.example/events`), mTLS-geschützt | +| **Client-Zertifikat-Bundle** | Pro Cluster: Client-Zertifikat, privater Schlüssel und CA-Zertifikat, bereitgestellt als Kubernetes-Secret-Manifest. Einmalig pro Cluster anwenden | | **GitHub PAT** | Zum Herunterladen von Collector-Binärdateien und Python-SDK-Paketen | -| **Collector-API-Schlüssel** | Bereichsbegrenzte Schlüssel mit `events:add`-Berechtigung, einer pro Collector-Deployment | -| **Installationsanleitungen** | Schritt-für-Schritt-Dokumentation für Collector und Python SDK | +| **Collector-API-Keys** | Scoped Keys mit `events:add`-Berechtigung, einer pro Collector-Deployment | +| **Installationsanleitungen** | Schritt-für-Schritt-Dokumentation für Collector und Python-SDK | --- -## Was Sie nach dem Setup tun +## Was Sie nach der Einrichtung tun Ihre einzige laufende Arbeit betrifft Ihre eigenen Agent-Maschinen, nicht den AgentEye-Cluster: -1. **Installieren Sie den Collector** in jedem Kubernetes-Cluster, der KI-Agenten ausführt: Mounten Sie das Client-Zertifikat und konfigurieren Sie die Endpunkt-URL und den API-Schlüssel. Siehe [Collector Installation](/de/agenteye/collector-installation). -2. **Integrieren Sie das Python SDK** in Ihren Agenten-Code. Siehe [Python SDK](/de/agenteye/python-sdk). -3. **Öffnen Sie das Dashboard** in Ihrem Browser, um die Agentenaktivität einzusehen. +1. **Collector installieren** in jedem Kubernetes-Cluster, der KI-Agenten ausführt: Client-Zertifikat einbinden und Endpunkt-URL sowie API-Key konfigurieren. Siehe [enterprise-docs/collector-installation.md](/de/agenteye/collector-installation). +2. **Python-SDK integrieren** in Ihren Agenten-Code. Siehe [enterprise-docs/python-sdk.md](/de/agenteye/python-sdk). +3. **Dashboard öffnen** in Ihrem Browser, um Agentenaktivitäten anzuzeigen. -Kein Cluster-Betrieb, kein Datenbankmanagement, keine Zertifikatserneuerungen, keine Upgrades. +Keine Cluster-Operationen, kein Datenbankmanagement, keine Zertifikatserneuerungen, keine Upgrades. --- ## Sicherheit -- **Daten verbleiben in Ihrem Cloud-Konto.** Cluster, Storage und Datenbanken laufen alle in Ihrer Umgebung. Keine Daten verlassen Ihren Perimeter. -- **Sie kontrollieren den Zugriff.** Der Cluster liegt in Ihrem Konto. Sie können den Zugriff von Exosphere jederzeit prüfen, überwachen oder entziehen. Alle Operationen werden im Audit-Log Ihrer Cloud erfasst (CloudTrail, GCP Audit Logs usw.). -- **mTLS bei der Event-Ingestion.** Jede Collector-Anfrage erfordert sowohl ein gültiges Client-Zertifikat als auch einen API-Schlüssel. Ein geleakter Schlüssel ist ohne das Zertifikat wertlos; ein gestohlenes Zertifikat ist ohne einen gültigen Schlüssel nutzlos. -- **Dashboard-Zugangskontrolle.** Das Dashboard läuft auf seinem eigenen Load Balancer, getrennt von der Event-Ingestion, und der Login erfolgt über passwortlosen E-Mail-OTP, beschränkt auf die von Ihnen freigeschalteten E-Mail-Adressen/Domains. Eine IP-Quelladressen-Allowlist am Load Balancer ist auf Anfrage verfügbar; da die automatische Zertifikatserneuerung den Load Balancer erreichen muss, kombiniert Exosphere die Einschränkung mit DNS-basierter Zertifikatsvalidierung, damit Erneuerungen weiterhin funktionieren. -- **Cluster-spezifische Zertifikate.** Jeder Ihrer Cluster erhält ein eigenes Client-Zertifikat. Wird ein Cluster kompromittiert, kann dieses Zertifikat unabhängig widerrufen werden, ohne andere zu beeinträchtigen. +- **Daten verbleiben in Ihrem Cloud-Account.** Cluster, Storage und Datenbanken laufen ausnahmslos in Ihrer Umgebung. Keine Daten verlassen Ihre Grenzen. +- **Sie kontrollieren den Zugriff.** Der Cluster befindet sich in Ihrem Account. Sie können den Zugriff von Exosphere jederzeit prüfen, überwachen oder widerrufen. Alle Operationen werden im Audit-Log Ihrer Cloud erfasst (CloudTrail, GCP Audit Logs usw.). +- **mTLS bei der Event-Ingestion.** Jede Collector-Anfrage erfordert sowohl ein gültiges Client-Zertifikat als auch einen API-Key. Ein geleakter Key ist ohne das Zertifikat wertlos; ein gestohlenes Zertifikat ist ohne einen gültigen Key nutzlos. +- **Dashboard-Zugangskontrolle.** Das Dashboard läuft auf seinem eigenen Load Balancer, getrennt von der Event-Ingestion, und der Login erfolgt passwortlos per E-Mail-OTP, beschränkt auf die von Ihnen erlaubten E-Mail-Adressen/Domains. Eine IP-Quellbereichs-Allowlist am Load Balancer ist auf Anfrage verfügbar; da die automatische Zertifikatserneuerung den Load Balancer erreichen muss, kombiniert Exosphere die Einschränkung mit DNS-basierter Zertifikatsvalidierung, damit Erneuerungen weiterhin funktionieren. +- **Zertifikate pro Cluster.** Jeder Ihrer Cluster erhält ein eigenes Client-Zertifikat. Wenn ein Cluster kompromittiert wird, kann dieses Zertifikat unabhängig widerrufen werden, ohne andere zu beeinträchtigen. --- ## Deployment-Zeitplan -| Phase | Dauer | Ihre Beteiligung | +| Phase | Dauer | Ihr Einsatz | |---|---|---| | **Cluster-Bereitstellung** | 1–2 Tage | Cluster bereitstellen und Exosphere Zugriff gewähren | -| **Plattform-Setup** | 1 Tag | Keine; Exosphere installiert alle Infrastrukturkomponenten | -| **Anwendungs-Deployment** | 1 Tag | Keine; Exosphere deployed Server, Dashboard und erstellt API-Schlüssel | +| **Plattform-Einrichtung** | 1 Tag | Keiner; Exosphere installiert alle Infrastrukturkomponenten | +| **Anwendungs-Deployment** | 1 Tag | Keiner; Exosphere deployt Server und Dashboard und erstellt API-Keys | | **Collector-Rollout** | 1–3 Tage | Collectors in Ihren Clustern installieren (mit Unterstützung durch Exosphere) | -| **Produktions-Burn-in** | 1 Woche | Keine; Exosphere überwacht und optimiert | +| **Produktions-Burn-in** | 1 Woche | Keiner; Exosphere überwacht und optimiert | -Typische Gesamtdauer: **~2 Wochen** vom Kickoff bis zur Produktionsreife. +Typische Gesamtdauer: **ca. 2 Wochen** vom Kickoff bis zur Produktionsreife. --- @@ -164,7 +164,7 @@ Bei Fragen oder Problemen wenden Sie sich an Exosphere unter `support@exosphere. ## Nächste Schritte -- [Getting Started](/de/agenteye/getting-started): Vollständige End-to-End-Einführung +- [Getting Started](/de/agenteye/getting-started): Vollständige End-to-End-Anleitung - [Collector Installation](/de/agenteye/collector-installation): Collector installieren und konfigurieren - [Python SDK](/de/agenteye/python-sdk): Ihren Agenten-Code instrumentieren - [API Keys](/de/agenteye/api-keys): Zugriff und Berechtigungen verwalten diff --git a/docs/es/agenteye/audits.mdx b/docs/es/agenteye/audits.mdx index dbb74b3c..8b3972f3 100644 --- a/docs/es/agenteye/audits.mdx +++ b/docs/es/agenteye/audits.mdx @@ -1,107 +1,106 @@ --- -title: "Auditorías — detección de mejoras agénticas" -description: "Documentación de Auditorías de AgentEye — detección de mejoras agénticas." +title: "Auditorías — detección de mejoras mediante agentes" +description: "Documentación de las Auditorías de AgentEye — detección de mejoras mediante agentes." --- -Las auditorías son tareas recurrentes que analizan los registros de tu agente **a través de sesiones** para encontrar oportunidades de mejora. Mientras que una alerta vigila en tiempo casi real una métrica que ya conoces, una auditoría *investiga*: según la programación que establezcas, ejecuta un pase de políticas determinista sobre la ventana de tiempo y luego desencadena un **agente de fiabilidad con IA** sobre tus sesiones — el agente consulta los datos directamente, lee transcripciones sospechosas y (cuando resulta útil) ejecuta pequeños scripts de análisis, para finalmente redactar **recomendaciones de mejora** con la evidencia que respalda cada una. +Las auditorías son trabajos recurrentes que analizan tus registros de agente **entre sesiones** para encontrar aspectos susceptibles de mejora. Mientras que una alerta vigila una métrica concreta que ya conoces en tiempo casi real, una auditoría *investiga*: según el calendario que establezcas, ejecuta un pase de políticas determinístico sobre la ventana temporal y luego pone en marcha un **agente de fiabilidad de IA** sobre tus sesiones — el agente consulta los datos directamente, lee transcripciones sospechosas y (cuando resulta útil) ejecuta pequeños scripts de análisis, para después redactar **recomendaciones de mejora** respaldadas por evidencias concretas. -Usa las auditorías para responder a "¿qué debería corregir o mejorar en mis agentes?" — y las alertas para recibir una notificación en el momento en que se supere un umbral específico. Cada mejora enlaza a las sesiones y consultas exactas que la originaron, y con un solo clic puedes crear una alerta preconfigurada para detectar recurrencias. +Usa las auditorías para responder a la pregunta "¿qué debería corregir o mejorar en mis agentes?" — y las alertas para recibir una notificación en el momento en que se supere un umbral específico. Cada mejora enlaza a las sesiones y consultas exactas que la respaldan, y con un solo clic puedes crear una alerta preconfigurada para detectar recurrencias. -La superficie del panel es **`//audits`** (barra lateral → *analyze* → *audits*), protegida por los permisos `audits:read` / `audits:write`. +La vista del panel es **`//audits`** (barra lateral → *analyze* → *audits*), protegida por los permisos `audits:read` / `audits:write`. --- ## Cómo funciona una ejecución -Cada ejecución tiene dos capas: un nivel determinista de base y una investigación agéntica. +Cada ejecución tiene dos capas: una base determinística y una investigación mediante agentes. -### 1. El pase de políticas (determinista) +### 1. El pase de políticas (determinístico) -Antes de que se ejecute cualquier modelo, la auditoría lleva a cabo un catálogo de **verificaciones de políticas SQL** sobre la ventana de tiempo: consultas de agregación acotadas que señalan patrones problemáticos conocidos e informan *cuántos* eventos / *qué* sesiones coincidieron — nunca el texto coincidente en sí. El catálogo incluye: +Antes de que se ejecute ningún modelo, la auditoría realiza un pequeño catálogo de **comprobaciones de políticas SQL** sobre la ventana temporal: consultas de agregados acotados que marcan patrones problemáticos conocidos y reportan *cuántos* eventos / *qué* sesiones coincidieron — nunca el texto en sí que coincidió. El catálogo incluye: -- **Filtración de secretos o credenciales** en los payloads de eventos — claves de acceso de AWS, claves de API `sk-…`, claves privadas PEM, tokens JWT / bearer y asignaciones de credenciales `KEY=…`. -- **Marcadores de inyección de prompt** — "ignore previous instructions", "reveal your system prompt" y similares. +- **Filtración de secretos y credenciales** en las cargas útiles de eventos — claves de acceso de AWS, claves API con prefijo `sk-…`, claves privadas PEM, tokens JWT / bearer, y asignaciones de credenciales con la forma `KEY=…`. +- **Marcadores de inyección de prompts** — "ignore las instrucciones anteriores", "revela tu prompt de sistema", y similares. - **PII** — números con formato de SSN (heurístico). -- **Denegaciones de permisos de herramientas** y **bucles descontrolados de llamadas a herramientas**. +- **Denegaciones de permisos de herramientas** y **bucles desbocados de llamadas a herramientas**. -Los hallazgos de políticas se persisten como resultados (tipo `policy`) que **siempre aparecen** (nunca son recortados por el límite por ejecución) y se entregan al agente de IA como pistas iniciales. Como esta capa no requiere ningún modelo, una auditoría sigue produciendo sus señales de seguridad más importantes incluso si el agente de IA no está disponible. +Los resultados de políticas se persisten como hallazgos (tipo `policy`) que **siempre aparecen** (nunca se eliminan por el límite por ejecución), y se entregan al agente de IA como pistas de partida. Como esta capa no necesita ningún modelo, una auditoría sigue produciendo sus señales de seguridad más importantes aunque el agente de IA no esté disponible. -### 2. La investigación agéntica (IA) +### 2. La investigación mediante agentes (IA) -A continuación, la auditoría ejecuta un **agente de fiabilidad autónomo** (el mismo servicio Claude Agent SDK que impulsa el asistente del panel, con un prompt específico para auditorías). Dado el **alcance** de la auditoría (agentes × entornos seleccionados) y la **ventana de tiempo**, el agente: +La auditoría ejecuta a continuación un **agente de fiabilidad autónomo** (el mismo servicio del Claude Agent SDK que impulsa el asistente del panel, con un prompt específico para auditorías). Dado el **alcance** de la auditoría (agentes × entornos seleccionados) y la **ventana temporal**, el agente: - ejecuta consultas SQL de solo lectura contra tus tablas de análisis, -- lee un puñado de transcripciones de sesiones representativas, -- opcionalmente escribe y ejecuta breves **scripts de Python en un sandbox aislado dentro del pod** (sin red, sin acceso al sistema de archivos, secretos depurados) para análisis que SQL no puede expresar — agrupación de errores, cálculo de distribuciones, análisis de payloads ya obtenidos, +- lee un conjunto representativo de transcripciones de sesiones, +- opcionalmente escribe y ejecuta breves **scripts de Python en un sandbox aislado dentro del pod** (sin red, sin acceso al sistema de archivos, con secretos eliminados) para análisis que SQL no puede expresar — clustering de errores, cálculo de distribuciones, análisis de cargas útiles ya obtenidas, - y registra cada **mejora** bien fundamentada que encuentra. -Trabaja a través de varias líneas de investigación — agrupación de errores, desviación respecto a una línea base, fallos de objetivos en transcripciones, mal uso de herramientas, equilibrios calidad/coste y brechas de cobertura — según la **sensibilidad** de la auditoría (baja / media / alta). Cada mejora **debe citar evidencia**: los IDs de sesión que el agente inspeccionó realmente y/o el SQL que ejecutó. El servidor valida que las sesiones citadas existan y **descarta cualquier mejora sin evidencia superviviente**, de modo que el agente investiga pero nunca inventa. +El agente trabaja a través de varias líneas de investigación — clustering de errores, deriva respecto a una línea base, fallos de objetivo en transcripciones, uso indebido de herramientas, compromisos calidad/coste y brechas de cobertura — según la **sensibilidad** de la auditoría (baja / media / alta). Cada mejora **debe citar evidencias**: los IDs de sesión que el agente inspeccionó realmente y/o el SQL que ejecutó. El servidor valida que las sesiones citadas existen y **descarta cualquier mejora sin evidencias**, por lo que el agente investiga pero nunca inventa. Cada mejora incluye: -- una **recomendación** (el cambio concreto a realizar — un ajuste de prompt, una corrección del esquema de herramienta, una política de reintentos, una salvaguarda, mayor cobertura de evaluación), +- una **recomendación** (el cambio concreto que realizar — un ajuste de prompt, una corrección del esquema de una herramienta, una política de reintentos, una salvaguarda, mayor cobertura de evaluación), - un **impacto esperado** y una estimación de **esfuerzo** (bajo / medio / alto), -- una **magnitud** — `big` (un operador debe ser notificado), `medium` (pertenece al informe de la ejecución) o `small` (contexto del panel), -- una **huella** estable (derivada de la categoría + alcance del problema, *no* de las sesiones de esta ejecución) para que el mismo problema se rastree ejecución tras ejecución aunque la evidencia cambie, -- y, cuando un vigilante determinista simple podría detectar recurrencias, una **alerta sugerida** que puedes crear con un solo clic. +- una **magnitud** — `big` (hay que avisar al operador), `medium` (pertenece al informe de la ejecución) o `small` (contexto del panel), +- una **huella digital** estable (derivada de la categoría del problema + su alcance, *no* de las sesiones de esta ejecución) para que el mismo problema se rastree ejecución tras ejecución aunque las evidencias cambien, +- y, cuando un vigilante determinístico sencillo podría detectar recurrencias, una **alerta sugerida** que puedes crear con un solo clic. -> **La capa de IA es opcional pero recomendada.** Si no hay ningún agente de IA configurado para la pipeline de auditorías, las ejecuciones igualmente se llevan a cabo, persisten los hallazgos de políticas e informan honestamente que "el análisis no está disponible" para la capa agéntica, en lugar de pasar silenciosamente. +> **La capa de IA es opcional pero recomendada.** Si no hay ningún agente de IA configurado para el pipeline de auditoría, las ejecuciones se llevan a cabo igualmente, persisten los hallazgos de políticas, e informan honestamente de que "el análisis no está disponible" para la capa de agentes en lugar de pasar silenciosamente. ### Modos de fallo -Las mejoras se clasifican en el **catálogo de modos de fallo** duradero de tu organización (o proponen un nuevo modo). Los modos otorgan a los patrones una identidad estable entre ejecuciones y permiten el seguimiento de recurrencias a largo plazo. +Las mejoras se clasifican en el **catálogo de modos de fallo** duraderos de tu organización (o proponen un nuevo modo). Los modos dan a los patrones una identidad estable entre ejecuciones y permiten el seguimiento de recurrencias a largo plazo. -## Ciclo de vida del triaje +## Ciclo de vida de triaje En la página de un hallazgo (`/audits//findings/`): | Acción | Efecto | |---|---| | **acknowledge** | Mantiene el hallazgo visible pero reduce su prioridad a la mitad. | -| **resolve** | Lo marca como resuelto. Si el patrón realmente reaparece más tarde, se reabre como **nuevo** — de modo que una regresión es visible, no se pliega silenciosamente al historial. | -| **mute** / **dismiss** | Supresión duradera: la huella del patrón se recuerda y nunca vuelve a aparecer, incluso entre ejecuciones. Usa mute para "conocido y aceptado"; dismiss para "no es útil". | -| **reopen** | Elimina la supresión / resolución y vuelve a clasificar el patrón. | -| **assign** | Enruta el hallazgo a un operador (un miembro de la organización) como responsable. El estado de prioridad y supresión no cambia. | +| **resolve** | Lo marca como corregido. Si el patrón reaparece realmente más adelante, se reabre como **new** — para que una regresión sea visible, no silenciosamente archivada en el historial. | +| **mute** / **dismiss** | Supresión duradera: la huella del patrón se recuerda y nunca vuelve a aparecer, ni siquiera entre ejecuciones. Usa mute para lo que es "conocido y aceptado"; dismiss para lo que "no es útil". | +| **reopen** | Elimina la supresión / resolución y vuelve a puntuar el patrón. | -El ruido de baja señal se controla por auditoría con un límite de hallazgos por ejecución (`top_k`) sobre las mejoras agénticas. Los hallazgos de políticas omiten este límite (son relevantes para la seguridad y siempre se muestran). Todo lo que quede fuera del límite se contabiliza en las estadísticas de la ejecución — nada se descarta silenciosamente. +El ruido de baja señal se controla por auditoría con un límite de hallazgos por ejecución (`top_k`) sobre las mejoras del agente. Los hallazgos de políticas no están sujetos al límite (son relevantes para la seguridad y siempre se muestran). Todo lo que quede fuera del límite se contabiliza en las estadísticas de la ejecución — nada se descarta silenciosamente. ## Programación -- **Cadencia** (`schedule_interval_secs`): de horaria a semanal; **diaria por defecto**. Las auditorías son deliberadamente más espaciadas que las alertas — una investigación agéntica escanea ventanas completas y se ejecuta durante minutos. -- **Ventana**: ya sea un periodo de retrovisión fijo (p. ej., "cada ejecución escanea los últimos 7 días") o **desde la última ejecución** (por defecto) — cada ejecución retoma donde terminó la anterior exitosa, con una pequeña superposición para que los eventos en los límites nunca se pierdan. -- La siguiente ejecución se programa un intervalo completo después de que la anterior **finalice**, de modo que una ejecución lenta nunca apila una segunda ejecución concurrente de la misma auditoría. -- **Run now** en la página de la auditoría la hace inmediatamente elegible para ejecutarse. +- **Cadencia** (`schedule_interval_secs`): de cada hora a semanal; **la frecuencia predeterminada es diaria**. Las auditorías son deliberadamente menos frecuentes que las alertas — una investigación mediante agentes analiza ventanas completas y se ejecuta durante minutos. +- **Ventana**: ya sea una retrospectiva fija (por ejemplo, "cada ejecución analiza los últimos 7 días") o **desde la última ejecución** (el valor predeterminado) — cada ejecución continúa donde terminó la anterior exitosa, con una pequeña superposición para que nunca se pierdan eventos en los límites. +- La siguiente ejecución se programa un intervalo completo después de que la anterior **se complete**, de modo que una ejecución lenta nunca apila una segunda ejecución concurrente de la misma auditoría. +- **Run now** en la página de la auditoría la hace ejecutarse de inmediato. -## Selección de modelo +## Selección del modelo -Al crear una auditoría puedes elegir qué modelo usa la investigación, de la **lista de modelos que tu operador ha configurado** para el servicio de agentes. Con un único modelo configurado, el selector lo muestra como leyenda; con varios, puedes elegir. Si se deja sin configurar, se usa el modelo predeterminado configurado. +Al crear una auditoría puedes elegir qué modelo usa la investigación, entre la **lista de modelos que tu operador ha configurado** para el servicio de agentes. Con un único modelo configurado, el selector lo muestra como subtítulo; con varios, puedes elegir. Si lo dejas sin configurar, se usa el predeterminado configurado. ## Notificaciones -Cuando una ejecución genera hallazgos **nuevos**, la auditoría notifica a los canales configurados de tu organización — la misma puerta de `alerts.enabled_channels` y los ajustes que usa la pipeline de alertas: +Cuando una ejecución detecta hallazgos **nuevos**, la auditoría notifica a los canales configurados de tu organización — los mismos canales y configuración de `alerts.enabled_channels` que usa el pipeline de alertas: - **Slack** — un resumen de los nuevos elementos significativos (`big`) con un enlace directo. -- **Email** — un **informe de auditoría** diseñado que lista las nuevas mejoras (severidad máxima, recomendaciones por elemento, enlace directo), enviado cuando la auditoría tiene un canal de **email** adjunto y hay al menos un nuevo hallazgo. +- **Email** — un **informe de auditoría** diseñado con las nuevas mejoras (mayor severidad, recomendaciones por elemento, enlace directo), enviado cuando la auditoría tiene un canal de **email** asociado y hay al menos un nuevo hallazgo. -Los hallazgos recurrentes pero conocidos no generan nuevas notificaciones. +Los hallazgos recurrentes pero ya conocidos no generan nuevas notificaciones. ## Referencia de configuración -Las definiciones de auditoría se gestionan en el panel (`/audits/new`) o a través de la API. Los ajustes por auditoría incluyen la cadencia y ventana de programación, el alcance (`{"environments": [...], "agent_ids": [...]}`), la sensibilidad (`low` / `medium` / `high`), los canales de notificación, el límite de hallazgos por ejecución (`top_k`) y el modelo (mediante `llm_budget.model`). Los ajustes del servidor a nivel de operador (tiempos de espera, sandbox, la URL del servicio de agentes) están documentados en [deployment.md](/es/agenteye/deployment). +Las definiciones de auditoría se gestionan en el panel (`/audits/new`) o a través de la API. Los ajustes por auditoría incluyen la cadencia y ventana de programación, el alcance (`{"environments": [...], "agent_ids": [...]}`), la sensibilidad (`low` / `medium` / `high`), los canales de notificación, el límite de hallazgos por ejecución (`top_k`) y el modelo (mediante `llm_budget.model`). La configuración del servidor a nivel de operador (tiempos de espera, sandbox, la URL del servicio de agentes) está documentada en [deployment.md](/es/agenteye/deployment). ## API -Todos los endpoints tienen alcance de organización y siguen la autenticación estándar por clave bearer (consulta [api-keys.md](/es/agenteye/api-keys)). +Todos los endpoints tienen ámbito de organización y siguen la autenticación estándar por clave bearer (consulta [api-keys.md](/es/agenteye/api-keys)). | Endpoint | Permiso | Propósito | |---|---|---| | `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | Listar / crear definiciones de auditoría. | -| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Inspeccionar, editar, eliminar una auditoría. | +| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Inspeccionar, editar o eliminar una auditoría. | | `POST /audits/:id/run` | `audits:write` | Hacer que la auditoría se ejecute de inmediato. | | `GET /audits/:id/runs` | `audits:read` | Historial de ejecuciones (ventana, estado, estadísticas, conteo de hallazgos). | -| `GET /audits/findings` | `audits:read` | Hallazgos a nivel de organización, filtrables por `audit_id`, `status`; ordenados por prioridad. | -| `GET /audits/findings/:fid` | `audits:read` | Detalle completo del hallazgo (recomendación, evidencia, prioridad). | +| `GET /audits/findings` | `audits:read` | Hallazgos de toda la organización, filtrables por `audit_id`, `status`; ordenados por prioridad. | +| `GET /audits/findings/:fid` | `audits:read` | Detalle completo del hallazgo (recomendación, evidencias, prioridad). | | `POST /audits/findings/:fid/status` | `audits:write` | Triaje: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | Para los casos "la auditoría se ejecutó pero no encontró nada", "el sandbox de código está deshabilitado" y "el email de auditoría no se entregó", consulta [troubleshooting.md](/es/agenteye/troubleshooting#audits). \ No newline at end of file diff --git a/docs/es/agenteye/cli-recipes.mdx b/docs/es/agenteye/cli-recipes.mdx index 4cb85f12..012db3bd 100644 --- a/docs/es/agenteye/cli-recipes.mdx +++ b/docs/es/agenteye/cli-recipes.mdx @@ -1,29 +1,29 @@ --- -title: "Recetas de CLI para agentes" -description: "Documentación de recetas de CLI de AgentEye para agentes." +title: "Recetas CLI para agentes" +description: "Documentación de recetas CLI de AgentEye para agentes." --- -Extrae datos de sesiones, eventos y evaluaciones (y dispara reevaluaciones) directamente desde un script o agente de código, con JSON limpio en stdout que se canaliza directamente a `jq`. Estas recetas convierten los datos de observabilidad de AgentEye en algo que un usuario de terminal o un agente de código con IA (Claude Code, Cursor) puede consultar y automatizar, sin necesidad de navegar por el dashboard. +Obtén datos de sesiones, eventos y evaluaciones (y activa re-evaluaciones) directamente desde un script o agente de código, con JSON limpio en stdout que se puede canalizar directamente a `jq`. Estas recetas convierten los datos de observabilidad de AgentEye en algo que un usuario de terminal o un agente de código IA (Claude Code, Cursor) puede consultar y automatizar, sin necesidad de navegar por el panel de control. -Los patrones que se muestran a continuación están listos para copiar y pegar en la CLI de AgentEye (`agenteye`). Para instalación, autenticación y la lista completa de opciones, consulta [CLI](/es/agenteye/cli); ejecuta `agenteye -h` o `agenteye -h` para la ayuda integrada. +Los patrones a continuación están listos para copiar y pegar en el CLI de AgentEye (`agenteye`). Para la instalación, autenticación y la lista completa de opciones, consulta [CLI](/es/agenteye/cli); ejecuta `agenteye -h` o `agenteye -h` para la ayuda integrada. ## Reglas de oro -1. **Las opciones globales van *antes* del comando.** `agenteye --json sessions` es correcto; `agenteye sessions --json` no lo es. Las opciones globales son `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Usa `--json` siempre que vayas a procesar la salida.** Los datos van a **stdout** como JSON; los mensajes de estado para humanos y los errores van a **stderr**, por lo que stdout permanece limpio para canalizar a `jq`. -3. **Ramifica según el código de salida**, no por el texto de stderr: `0` ok · `2` argumentos incorrectos · `3` no se puede alcanzar el dashboard · `4` no autenticado o sesión expirada · `5` permiso insuficiente. -4. **Explora con `-h`.** Cada comando documenta sus filtros, formatos de valores y estructura JSON. +1. **Las opciones globales van *antes* del comando.** `agenteye --json sessions` es correcto; `agenteye sessions --json` no lo es. Las globales son `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **Usa `--json` siempre que vayas a procesar la salida.** Los datos van a **stdout** como JSON; los mensajes de estado y errores van a **stderr**, por lo que stdout permanece limpio para canalizarlo a `jq`. +3. **Ramifica según el código de salida**, no según el texto de stderr: `0` correcto · `2` argumentos inválidos · `3` no se puede alcanzar el panel · `4` no autenticado o sesión expirada · `5` permiso insuficiente. +4. **Explora con `-h`.** Cada comando documenta sus filtros, formatos de valor y estructura JSON. ## Configuración inicial ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # para no repetir --base-url -agenteye login --email you@example.com # pega el código enviado por correo; válido ~24h +agenteye login --email you@example.com # pega el código enviado por email; válido ~24h ``` -## Verificar autenticación antes de trabajar +## Verifica la autenticación antes de trabajar -`whoami` nunca falla por sesión inexistente o expirada; en su lugar reporta `logged_in:false`, por lo que un agente puede comprobar el estado de autenticación de forma segura. (Puede seguir retornando un código no cero si no hay URL base configurada o el dashboard no está disponible.) +`whoami` nunca falla por una sesión ausente o expirada; en su lugar reporta `logged_in:false`, por lo que un agente puede comprobar el estado de autenticación de forma segura. (Puede seguir saliendo con error si no hay URL base configurada o el panel no es accesible.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -31,44 +31,44 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## Encontrar sesiones fallidas o con puntuación baja +## Encontrar sesiones con fallos o puntuaciones bajas ```bash -# sesiones en las últimas 24h cuya evaluación arrojó error +# sesiones en las últimas 24h cuya evaluación tuvo error agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# evaluaciones con puntuación <= 0.5 en helpfulness, para un agente concreto +# evaluaciones con puntuación <= 0.5 en utilidad, para un agente específico agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -El filtrado por puntuación está en **`evals`**, no en `sessions`. `--score KEY:MIN..MAX` es repetible y se combina con AND; cualquiera de los límites es opcional (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Puedes pasar hasta 20 filtros de puntuación por solicitud; más devuelve HTTP 400. `sessions` comparte los filtros `--env`, `--status`, `--agent-id`, `--session-id` y de rango de tiempo con `evals`, pero no tiene `--score`. +El filtrado por puntuación está en **`evals`**, no en `sessions`. `--score KEY:MIN..MAX` es repetible y se combina con AND; cualquiera de los límites es opcional (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Puedes pasar hasta 20 filtros de puntuación por solicitud; más devuelve HTTP 400. `sessions` comparte los filtros `--env`, `--status`, `--agent-id`, `--session-id` y de rango temporal con `evals`, pero no tiene `--score`. ## Leer una sesión de principio a fin -No existe un comando único `session show` — combina el historial de eventos con la evaluación de la sesión: +No existe un único comando `session show` — combina el rastro de eventos con la evaluación de la sesión: ```bash # la evaluación más reciente de la sesión (estado + puntuaciones) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# todos los eventos de la ejecución (aumenta --limit para un barrido completo) +# todos los eventos de la ejecución (aumenta --limit para un recorrido completo) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# solo las llamadas a herramientas de una sesión +# solo las llamadas a herramientas en una sesión agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` ## Obtener todo (paginación) -Los resultados se muestran del más reciente al más antiguo y están paginados por cursor. +Los resultados están ordenados del más reciente al más antiguo y se paginan con cursor. ```bash -# de una vez: obtener hasta 500 filas en páginas de 200 +# de una sola vez: obtener hasta 500 filas en páginas de 200 agenteye --json events --session-id run-001 --limit 500 --all > events.json -# paginación manual: reutiliza next_cursor +# paginación manual: pasar next_cursor de vuelta page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" @@ -76,16 +76,16 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') ## Reducir la salida con --fields -Limita las claves (tanto en la tabla como con `--json`) para reducir lo que un agente debe leer. +Restringe las claves (tanto en la tabla como en `--json`) para reducir lo que un agente debe leer. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Los nombres de campo desconocidos son rechazados (salida `2`) con la lista de válidos, una forma económica de descubrir nombres de campo. +Los nombres de campo desconocidos son rechazados (salida `2`) con la lista válida, una forma sencilla de descubrir los nombres de campo. -## Descubrir valores válidos de filtros +## Descubrir valores válidos para filtros ```bash agenteye --json list envs | jq -r '.values[]' # valores para --env @@ -93,27 +93,27 @@ agenteye --json list tools | jq -r '.values[]' # nombres de herramienta agenteye --json list score_filters | jq -r '.values[]' # KEY válido para --score KEY:MIN..MAX ``` -## Seleccionar tu organización (multi-tenant) +## Seleccionar tu organización (multitenant) Si perteneces a más de una organización, elige el tenant activo al iniciar sesión (se guarda): ```bash -agenteye login --org acme --email you@corp.com # establece el tenant en el mismo paso que el login +agenteye login --org acme --email you@corp.com # configura el tenant en el mismo paso que el login agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # sobreescribe para un solo comando +agenteye --org globex --json sessions --since 24h # sobrescribe para un solo comando ``` -Un login multi-org sin `--org` termina con código no cero y muestra las organizaciones disponibles. +Un inicio de sesión con múltiples organizaciones sin `--org` sale con error no cero e imprime las organizaciones disponibles para elegir. -## Provisionar una clave API para el SDK/colector +## Aprovisionar una clave API para el SDK/colector ```bash -# el secreto se muestra UNA SOLA VEZ — con --json está en el campo .key +# el secreto se imprime UNA SOLA VEZ — con --json está en el campo .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # rotar; agenteye keys disable ci-bot --yes para revocar ``` -## Ejecutar una consulta guardada o ad-hoc +## Ejecutar una consulta guardada o ad hoc ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' @@ -125,11 +125,11 @@ agenteye --json query run errs --arg prod | jq '.rows' # una consulta guardada ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> Las mutaciones omiten automáticamente su prompt de confirmación cuando se usa `--json` o cuando stdin no es un TTY, por lo que los agentes nunca quedan bloqueados; usa `--yes`/`-y` para omitirlo explícitamente en otros contextos. +> Las mutaciones omiten automáticamente su confirmación cuando se usa `--json` o cuando stdin no es un TTY, por lo que los agentes nunca quedan bloqueados; usa `--yes`/`-y` para omitirla explícitamente en otros casos. ## Manejo de códigos de salida en un script @@ -144,7 +144,7 @@ case "${code:-0}" in esac ``` -## Estructuras de la salida JSON +## Estructuras de salida JSON | Comando | JSON en stdout (con `--json`) | |---|---| @@ -160,10 +160,10 @@ esac | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | | create/update/delete (cualquiera) | el objeto del recurso, o `{"deleted": true, "id"}` para eliminaciones | -| failure (cualquiera, con `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` en stdout | +| error (cualquiera, con `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` en stdout | -- Cada elemento **event** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. -- Cada elemento **evaluation** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. -- Cada elemento **session** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. +- Cada elemento de **evento** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. +- Cada elemento de **evaluación** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. +- Cada elemento de **sesión** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -El parámetro `--fields` de cada comando acepta exactamente los nombres de campo de sus propios elementos — el conjunto difiere entre `sessions` y `evals`, por lo que un nombre válido para uno puede ser rechazado por el otro. \ No newline at end of file +El `--fields` de cada comando acepta exactamente los nombres de campo de su propio elemento — el conjunto difiere entre `sessions` y `evals`, por lo que un nombre válido para uno puede ser rechazado por el otro. \ No newline at end of file diff --git a/docs/es/agenteye/deployment.mdx b/docs/es/agenteye/deployment.mdx index fc01acf6..4261ce7a 100644 --- a/docs/es/agenteye/deployment.mdx +++ b/docs/es/agenteye/deployment.mdx @@ -3,7 +3,6 @@ title: "Despliegue" description: "Documentación de despliegue de AgentEye." --- - Esta guía cubre el despliegue del servidor y el panel de control de AgentEye en producción. --- @@ -21,7 +20,7 @@ Esta guía cubre el despliegue del servidor y el panel de control de AgentEye en v | +--------+ | +----------------------+ | Server |<------+--->| ClickHouse 24+ | - +--------+ | | (eventos / analítica)| + +--------+ | | (eventos/analítica) | ^ | +----------------------+ API | | | | +----------------------+ @@ -31,11 +30,11 @@ Esta guía cubre el despliegue del servidor y el panel de control de AgentEye en ``` - **Server**: Servicio HTTP en Rust; recibe lotes de eventos, los escribe en ClickHouse y mantiene el estado relacional en PostgreSQL. -- **Dashboard**: Aplicación web en Next.js; lee y escribe exclusivamente a través de la API del servidor. +- **Dashboard**: Aplicación web Next.js; lee y escribe exclusivamente a través de la API del servidor. - **agenteye-collector**: se despliega en las máquinas de los agentes, no en el host del servidor. -- **Postgres 15+**: REQUERIDO. (Elevado desde la versión 14 en la versión multi-tenant; el esquema org-membership utiliza una clave foránea `ON DELETE SET NULL` con lista de columnas, que requiere Postgres 15+. Actualiza Postgres antes de desplegar esta versión.) Almacena el estado OLTP: `api_keys`, `users`, `sessions`, `evaluation_jobs` (cola), `dashboards`, `saved_queries`, `otp_codes`, más las tablas multi-tenant `orgs`, `org_memberships`, `org_settings`. -- **ClickHouse 24+**: REQUERIDO. El almacén analítico para cada evento ingestado. Motor: `ReplacingMergeTree`, particionado por mes, ordenado por `(session_id, ts, dedup_key)`. El servidor se conecta mediante `CLICKHOUSE_URL`; la configuración incluida en `deploy/base/clickhouse/` incluye una configuración de nodo único optimizada para rendimiento. **Requisito multi-tenant:** la configuración incluida habilita la gestión de acceso SQL + `users_without_row_policies_can_read_rows=false` para que el servidor pueda crear un usuario de ClickHouse de solo lectura y una política de filas por organización (el límite de aislamiento impuesto por el motor para el editor SQL y el agente de IA). Si suministras tu propia configuración de ClickHouse, traslada estos ajustes (consulta `deploy/base/clickhouse/configmap.yaml`). -- **Redis 7+**: caché compartida *opcional* + backend de límite de tasa. El servidor y el panel se conectan mediante `REDIS_URL`. Si no está presente, ambos degradan de forma elegante a rutas solo de Postgres. Consulta **Redis (caché opcional)** más abajo. +- **Postgres 15+**: OBLIGATORIO. (Actualizado desde la versión 14 en la versión multi-tenant; el esquema de pertenencia a organizaciones usa una clave foránea `ON DELETE SET NULL` con lista de columnas, disponible desde Postgres 15+. Actualiza Postgres antes de desplegar esta versión.) Almacena el estado OLTP: `api_keys`, `users`, `sessions`, `evaluation_jobs` (cola), `dashboards`, `saved_queries`, `otp_codes`, además de las tablas multi-tenant `orgs`, `org_memberships`, `org_settings`. +- **ClickHouse 24+**: OBLIGATORIO. El almacén de analítica para cada evento ingerido. Motor: `ReplacingMergeTree`, particionado por mes, ordenado por `(session_id, ts, dedup_key)`. El servidor se conecta a través de `CLICKHOUSE_URL`; el `deploy/base/clickhouse/` incluido incorpora una configuración de nodo único optimizada para rendimiento. **Requisito multi-tenant:** la configuración incluida habilita la gestión de acceso SQL + `users_without_row_policies_can_read_rows=false` para que el servidor pueda crear un usuario de ClickHouse de solo lectura + política de fila por organización (el límite de aislamiento impuesto por el motor para el editor SQL y el agente de IA). Si usas tu propia configuración de ClickHouse, incorpora estos ajustes (ver `deploy/base/clickhouse/configmap.yaml`). +- **Redis 7+**: caché compartida *opcional* + backend de limitación de tasa. El servidor y el panel se conectan a través de `REDIS_URL`. Si no está disponible, ambos degradan de forma controlada a rutas que solo usan Postgres. Consulta **Redis (caché opcional)** a continuación. --- @@ -48,77 +47,76 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> Las compilaciones actuales se publican bajo `beta-latest`; `latest` solo se asigna a versiones estables. Para producción, fija una etiqueta específica `:v`; consulta [Etiquetas de imagen disponibles](#available-image-tags). +> Las compilaciones actuales se publican con `beta-latest`; `latest` solo se asigna a versiones estables. Para producción, fija una etiqueta específica `:v`; consulta [Etiquetas de imagen disponibles](#available-image-tags). ### Variables de entorno -| Variable | Requerida | Valor predeterminado | Descripción | +| Variable | Obligatoria | Valor por defecto | Descripción | |---|---|---|---| -| `DATABASE_URL` | Sí | ninguno | DSN de Postgres. Formato de cadena de conexión libpq estándar con esquema `postgres://`. Admite `?sslmode=require` y otros parámetros libpq. La contraseña no debe contener `/`, `+` ni `=`; usa `openssl rand -hex` para generar contraseñas seguras para URLs. | -| `ADMIN_KEY` | No | ninguno | Clave API de administrador de arranque. Se inserta con todos los permisos en cada inicio. Rota cambiando el valor y reiniciando. | -| `LISTEN_ADDR` | No | `0.0.0.0:8080` | Dirección TCP donde escuchar | +| `DATABASE_URL` | Sí | ninguno | DSN de Postgres. Formato de cadena de conexión libpq estándar con esquema `postgres://`. Admite `?sslmode=require` y otros parámetros libpq. La contraseña no debe contener `/`, `+` ni `=`; usa `openssl rand -hex` para generar contraseñas seguras para URL. | +| `ADMIN_KEY` | No | ninguno | Clave de API de administrador de arranque. Se inserta o actualiza con todos los permisos en cada inicio. Rótala cambiando el valor y reiniciando. | +| `LISTEN_ADDR` | No | `0.0.0.0:8080` | Dirección TCP a la que vincularse | | `MAX_BODY_BYTES` | No | `134217728` (128 MB) | Tamaño máximo del cuerpo de la solicitud | -| `ADMIN_EMAIL` | No | ninguno | Correo electrónico del usuario administrador de arranque. Se inserta con todos los permisos en cada inicio y se marca como protegido: no puede deshabilitarse ni modificarse sus permisos desde el panel o la API. Para rotar el administrador de arranque, cambia `ADMIN_EMAIL` y reinicia; el nuevo correo se inserta como protegido, y el anterior conserva su protección hasta que se elimine manualmente en la base de datos. | -| `ALLOWED_EMAILS` | No | ninguno (todos bloqueados) | Lista separada por comas de correos permitidos para crear usuarios e iniciar sesión. Admite direcciones exactas (`user@example.com`) y comodines de dominio (`*@example.com`). Si no se configura, no se puede crear ningún usuario ni iniciar sesión. **Solo para el primer arranque**: inicializa la lista de permitidos de la org predeterminada en el primer arranque; a partir de entonces, la página [`//settings`](#operational-settings) de cada org es la fuente de verdad y cambiar esta variable de entorno no tiene efecto. | -| `SMTP_HOST` | No | ninguno | Nombre del host del servidor SMTP para enviar correos OTP. Si no se configura, los códigos OTP se registran en stdout. | +| `ADMIN_EMAIL` | No | ninguno | Correo electrónico del usuario administrador de arranque. Se inserta o actualiza con todos los permisos en cada inicio y se marca como protegido: no puede deshabilitarse ni modificarse sus permisos desde el panel/API. Para rotar el administrador de arranque, cambia `ADMIN_EMAIL` y reinicia; el nuevo correo se inserta como protegido, y el anterior conserva su protección hasta que se limpie manualmente en la base de datos. | +| `ALLOWED_EMAILS` | No | ninguno (todos bloqueados) | Lista separada por comas de correos permitidos para la creación de usuarios e inicio de sesión. Admite direcciones exactas (`user@example.com`) y comodines de dominio (`*@example.com`). Si no se establece, no se puede crear ningún usuario ni iniciar sesión. **Solo semilla en el primer arranque**: llena la lista de permitidos de la organización predeterminada en el primer arranque; a partir de entonces, la página [`//settings`](#operational-settings) de cada organización es la fuente de verdad y cambiar esta variable de entorno no tiene efecto. | +| `SMTP_HOST` | No | ninguno | Nombre de host del servidor SMTP para enviar correos OTP. Si no se establece, los códigos OTP se registran en stdout. | | `SMTP_PORT` | No | `587` | Puerto del servidor SMTP | | `SMTP_USERNAME` | No | ninguno | Nombre de usuario de autenticación SMTP | | `SMTP_PASSWORD` | No | ninguno | Contraseña de autenticación SMTP | | `SMTP_FROM` | No | ninguno | Dirección de correo del remitente para los correos OTP | -| `SMTP_TLS` | No | STARTTLS | Se usa STARTTLS a menos que lo desactives explícitamente: `false` o `0` envía texto plano (sin TLS); cualquier otro valor, incluido no configurar nada, habilita STARTTLS. | -| `DASHBOARD_URL` | No | valor predeterminado integrado | Origen del panel utilizado para construir tanto el enlace mágico del correo OTP como los enlaces mágicos de incidencias en las notificaciones de alertas. Si no se configura, recurre a un valor predeterminado integrado (y, solo para OTP, al origen derivado de la solicitud del panel primero). Configura esto en despliegues de dominio dividido para que tanto el correo como los enlaces de Slack/incidencias apunten a tu panel. Consulta **URL del enlace mágico del correo** más abajo; la mayoría de los operadores no necesitan configurarlo. | -| `SESSION_TTL_SECS` | No | `86400` (24 h) | Duración de la sesión del panel en segundos. **Solo para el primer arranque**: edita por org desde [`//settings`](#operational-settings) después del primer despliegue. | -| `OTP_TTL_SECS` | No | `600` (10 min) | Período de validez del código OTP en segundos. **Solo para el primer arranque**: edita por org desde [`//settings`](#operational-settings) después del primer despliegue. | -| `REDIS_URL` | No | ninguno | Backend opcional de caché compartida + límite de tasa, p. ej. `redis://redis:6379/0`. Cuando se configura, el servidor almacena en caché las búsquedas de claves API autenticadas, el agregado `/models` del panel, la lista de sesiones y la faceta de lista de entornos; también traslada el límite de tasa de solicitudes OTP de Postgres COUNT a Redis INCR. Si no se configura o no es accesible, el servidor funciona sin caché (el límite OTP recurre a Postgres, y todas las demás llamadas de caché pasan directamente a la fuente de verdad). Consulta **Redis (caché opcional)** más abajo. | -| `CLICKHOUSE_URL` | **Sí** | ninguno | URL base de la instancia ClickHouse, p. ej. `http://clickhouse:8123`. El servidor aplica su esquema de eventos a esta base de datos en cada inicio y se niega a arrancar si no puede alcanzar ClickHouse. Consulta **ClickHouse (almacén analítico requerido)** más abajo. | +| `SMTP_TLS` | No | STARTTLS | Se usa STARTTLS a menos que lo desactives explícitamente: `false` o `0` envía texto plano (sin TLS); cualquier otro valor — incluido no establecerlo — habilita STARTTLS. | +| `DASHBOARD_URL` | No | valor predeterminado integrado | Origen del panel usado para construir el enlace mágico del correo OTP y los enlaces mágicos de incidentes en las notificaciones de alertas. Si no se establece, recurre a un valor predeterminado integrado (y, solo para OTP, al origen de la solicitud derivado del panel primero). Establécelo para configuraciones con dominios separados de modo que tanto los correos como los enlaces de Slack/incidentes apunten a tu panel. Consulta **URL del enlace mágico por correo** a continuación; la mayoría de los operadores no necesitan configurar esto. | +| `SESSION_TTL_SECS` | No | `86400` (24 h) | Duración de la sesión del panel en segundos. **Solo semilla en el primer arranque**: edítalo por organización en [`//settings`](#operational-settings) después del primer despliegue. | +| `OTP_TTL_SECS` | No | `600` (10 min) | Período de validez del código OTP en segundos. **Solo semilla en el primer arranque**: edítalo por organización en [`//settings`](#operational-settings) después del primer despliegue. | +| `REDIS_URL` | No | ninguno | Backend opcional de caché compartida + limitación de tasa, p. ej. `redis://redis:6379/0`. Cuando se establece, el servidor almacena en caché las búsquedas de claves API autenticadas, el agregado `/models` del panel, la lista de sesiones y la faceta de lista de entornos; también mueve la limitación de tasa de solicitudes OTP de Postgres COUNT a Redis INCR. Si no se establece o es inaccesible, el servidor funciona sin caché (el límite OTP vuelve a Postgres; el resto de llamadas de caché recurren a la fuente de verdad). Consulta **Redis (caché opcional)** a continuación. | +| `CLICKHOUSE_URL` | **Sí** | ninguno | URL base de la instancia de ClickHouse, p. ej. `http://clickhouse:8123`. El servidor aplica su esquema de eventos a esta base de datos en cada inicio y se niega a arrancar si no puede alcanzar ClickHouse. Consulta **ClickHouse (almacén de analítica obligatorio)** a continuación. | | `CLICKHOUSE_DATABASE` | No | `agenteye` | Nombre de la base de datos (esquema) de ClickHouse. El servidor la crea al inicio si no existe. | -| `ORG_CH_SECRET` | No (mono-tenant) / **Sí (multi-org)** | valor de desarrollo predeterminado | Clave HMAC de la que se deriva la contraseña de ClickHouse por tenant de cada organización. El editor SQL y el `run_query` del agente de IA se ejecutan como el usuario de ClickHouse de solo lectura propio de la org, cuya política de filas aplica el aislamiento de tenant en el motor. Los despliegues mono-tenant arrancan correctamente con el valor de desarrollo integrado; **antes de aprovisionar una segunda org DEBES establecer un valor sólido y estable**, ya que el CLI `agenteye-orgctl org create` se niega a ejecutarse con el valor de desarrollo integrado. Rotarlo deja huérfanos los usuarios de ClickHouse de cada org hasta el próximo inicio (la reconciliación en el arranque lo corrige automáticamente). Mantenlo secreto y sin cambios entre réplicas. El aprovisionamiento de orgs es solo para operadores; consulta **Organizaciones (multi-tenancy)** más abajo. | -| `DEFAULT_ORG_NAME` | No | `Default` | Nombre para mostrar inicializado para la org predeterminada integrada. **Solo para el primer arranque**, y solo mientras la org conserve su identidad genérica recién migrada, aplicado al inicio y luego ignorado. Una vez que renombres la org (`agenteye-orgctl org rename`), el nombre es autoritativo y esta variable de entorno no tiene más efecto. | -| `DEFAULT_ORG_SLUG` | No | `default` | Slug de URL para la org predeterminada integrada, la ruta del panel donde reside (`//…`). Misma semántica de solo primer arranque / solo estado inicial que `DEFAULT_ORG_NAME`. Debe tener entre 1 y 40 caracteres alfanuméricos en minúsculas con guiones internos simples y no ser una [palabra reservada](#organizations-multi-tenancy); un valor inválido se ignora (la org mantiene `default`). Permite que una instalación mono-tenant aparezca como p. ej. `/acme` en lugar de `/default` sin ningún paso CLI posterior al despliegue. | +| `ORG_CH_SECRET` | No (un solo tenant) / **Sí (multi-org)** | valor predeterminado de desarrollo | Clave HMAC a partir de la cual se deriva la contraseña de ClickHouse por tenant de cada organización. El editor SQL y el `run_query` del agente de IA se ejecutan como el usuario de ClickHouse de solo lectura propio de la organización, cuya política de fila impone el aislamiento de tenant en el motor. Los despliegues de un único tenant arrancan bien con el valor predeterminado de desarrollo integrado; **antes de provisionar una segunda organización DEBES establecer un valor sólido y estable**, porque la CLI `agenteye-orgctl org create` se niega a ejecutarse con el valor predeterminado de desarrollo integrado. Rotarlo huérfana el usuario de ClickHouse de cada organización hasta el próximo inicio, que los vuelve a provisionar automáticamente. Mantenlo en secreto e igual en todas las réplicas. El provisionamiento de organizaciones es solo para operadores; consulta **Organizaciones (multi-tenancy)** a continuación. | +| `DEFAULT_ORG_NAME` | No | `Default` | Nombre de visualización sembrado para la organización predeterminada integrada. **Solo semilla en el primer arranque**, y solo mientras la organización conserve su identidad genérica recién migrada; se aplica al inicio y luego se ignora. Una vez que renombras la organización (`agenteye-orgctl org rename`), el nuevo nombre es autoritativo y esta variable de entorno no tiene más efecto. | +| `DEFAULT_ORG_SLUG` | No | `default` | Slug de URL para la organización predeterminada integrada, la ruta del panel donde reside (`//…`). Misma semántica de solo primer arranque / solo estado inicial que `DEFAULT_ORG_NAME`. Debe tener entre 1 y 40 caracteres alfanuméricos en minúsculas con guiones internos simples y no ser una [palabra reservada](#organizations-multi-tenancy); un valor inválido se ignora (la organización conserva `default`). Permite que una instalación de un único tenant se presente como p. ej. `/acme` en lugar de `/default` sin ningún paso adicional de CLI post-despliegue. | | `RUST_LOG` | No | `info` | Nivel de detalle del registro (`debug`, `warn`, `error`, `agenteye_server=trace`) | -| `EVALUATOR_ENDPOINT` | No | ninguno | URL base de tu servicio evaluador (p. ej. `http://evaluator:9000`). Cuando no se configura, toda la canalización de evaluación es un no-op; no se escriben filas en la cola ni se ejecutan workers. Consulta [Suite de Evaluación](/es/agenteye/evaluation-suite). | -| `EVALUATOR_TOKEN` | No | ninguno | Se envía como `Authorization: Bearer ` al evaluador. **Debe ser igual al valor con el que está configurado el servicio evaluador.** Solo es opcional si tu evaluador está configurado sin token. | -| `EVALUATOR_WORKERS` | No | `2` | Concurrencia: número de tareas worker por instancia del servidor que despachan evaluaciones. Es seguro ejecutar en múltiples servidores escalados horizontalmente. | -| `EVALUATOR_CLAIM_BATCH` | No | `4` | Número máximo de evaluaciones que un único worker reclama por ciclo. Los lotes se despachan **concurrentemente**, por lo que la concurrencia total en tu endpoint evaluador es `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_ENDPOINT` | No | ninguno | URL base de tu servicio evaluador (p. ej. `http://evaluator:9000`). Si no se establece, toda la canalización de evaluación es una operación vacía; no se escriben filas en la cola ni se ejecutan workers. Consulta [Suite de evaluación](/es/agenteye/evaluation-suite). | +| `EVALUATOR_TOKEN` | No | ninguno | Enviado como `Authorization: Bearer ` al evaluador. **Debe ser igual al valor con el que está configurado el servicio evaluador.** Opcional solo si tu evaluador está configurado sin token. | +| `EVALUATOR_WORKERS` | No | `2` | Concurrencia: número de tareas worker por instancia de servidor que despachan evaluaciones. Es seguro ejecutarlo en varios servidores escalados horizontalmente. | +| `EVALUATOR_CLAIM_BATCH` | No | `4` | Número máximo de evaluaciones que un solo worker reclama por ciclo. Los lotes se despachan **concurrentemente**, por lo que la concurrencia total en tu endpoint evaluador es `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | | `EVALUATOR_POLL_IDLE_SECS` | No | `2` | Tiempo que un worker duerme entre intentos de despacho cuando no hay nada pendiente. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | No | `10` | Cadencia de respaldo final (en segundos) para los sondeos `GET /evaluate/{id}` cuando el evaluador no devuelve un `next_poll_secs` por respuesta y no anuncia un `default_poll_interval_secs` desde `GET /config`. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | No | `30000` | Tiempo de espera por solicitud HTTP contra el evaluador (milisegundos). | +| `EVALUATOR_POLLING_INTERVAL_SECS` | No | `10` | Cadencia de reserva final (segundos) para los sondeos `GET /evaluate/{id}` cuando el evaluador no devuelve un `next_poll_secs` por respuesta ni anuncia un `default_poll_interval_secs` desde `GET /config`. | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | No | `30000` | Tiempo de espera por solicitud HTTP al evaluador (milisegundos). | | `EVALUATOR_MAX_ATTEMPTS` | No | `5` | Tras este número de intentos fallidos, una evaluación se registra como `error` terminal (o `timeout` si los fallos fueron tiempos de espera de solicitud). | | `EVALUATOR_CONFIG_REFRESH_SECS` | No | `300` (5 min) | Con qué frecuencia el servidor vuelve a obtener `GET /config` del evaluador. | | `EVALUATOR_MAX_POLL_DURATION_SECS` | No | `3600` (1 h) | Tiempo máximo de reloj de pared que una sesión puede permanecer en la cola de sondeo antes de que AgentEye la termine como `timeout`. Protege contra un evaluador que devuelve `pending` indefinidamente. | -| `ALERT_WORKERS` | No | `1` | Concurrencia: número de tareas worker por instancia del servidor que evalúan reglas de alerta. Consulta [Alertas](/es/agenteye/alerts). | -| `ALERT_CLAIM_BATCH` | No | `16` | Número máximo de alertas que un único worker reclama por ciclo. | +| `ALERT_WORKERS` | No | `1` | Concurrencia: número de tareas worker por instancia de servidor que evalúan reglas de alerta. Consulta [Alertas](/es/agenteye/alerts). | +| `ALERT_CLAIM_BATCH` | No | `16` | Número máximo de alertas que un solo worker reclama por ciclo. | | `ALERT_POLL_IDLE_SECS` | No | `5` | Tiempo que un worker de alertas duerme cuando la cola está vacía. | -| `ALERT_REQUEST_TIMEOUT_MS` | No | `15000` | Tiempo de espera de evaluación por activación (consultas ClickHouse + HTTP de canal de salida). | -| `ALERT_MAX_ATTEMPTS` | No | `5` | Fallos transitorios consecutivos antes de que una alerta se reprograme a su cadencia normal en lugar de retroceso exponencial. | -| `AUDIT_WORKERS` | No | `1` | Concurrencia: número de tareas worker por instancia del servidor que ejecutan auditorías. Consulta [Auditorías](/es/agenteye/audits). | -| `AUDIT_CLAIM_BATCH` | No | `1` | Número máximo de auditorías pendientes que un único worker reclama por ciclo. Una investigación agéntica es un bucle largo, por eso el valor predeterminado es 1. | +| `ALERT_REQUEST_TIMEOUT_MS` | No | `15000` | Tiempo de espera por evaluación de disparo (consultas ClickHouse + HTTP de canal saliente). | +| `ALERT_MAX_ATTEMPTS` | No | `5` | Fallos transitorios consecutivos antes de que una alerta se reprograme en su cadencia normal en lugar de con retroceso exponencial. | +| `AUDIT_WORKERS` | No | `1` | Concurrencia: número de tareas worker por instancia de servidor que ejecutan auditorías. Consulta [Auditorías](/es/agenteye/audits). | +| `AUDIT_CLAIM_BATCH` | No | `1` | Número máximo de auditorías pendientes que un solo worker reclama por ciclo. Una investigación agéntica es un bucle largo, por lo que el valor predeterminado es 1. | | `AUDIT_POLL_IDLE_SECS` | No | `30` | Tiempo que un worker de auditorías duerme cuando no hay ninguna pendiente. | -| `AUDIT_REQUEST_TIMEOUT_MS` | No | `30000` | Tiempo de espera por consulta de política contra ClickHouse (milisegundos). | -| `AUDIT_LLM_TIMEOUT_MS` | No | `1440000` | Tiempo de espera para la llamada de investigación agéntica al servicio de asistente de IA. Un bucle de agente completo puede durar minutos; mantén este valor POR ENCIMA del `AGENTEYE_AUDIT_TIMEOUT_MS` propio del agente para que el agente devuelva sus hallazgos parciales antes de que el servidor abandone. | -| `AUDIT_MAX_ATTEMPTS` | No | `5` | Fallos transitorios consecutivos antes de que una auditoría se reprograme a su cadencia normal en lugar de retroceso exponencial. | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | No | — | La investigación agéntica de la auditoría llama al servicio `agent` del asistente de IA, **reutilizando la misma conexión que el asistente** — así que configura estos dos también en el **servidor** (los manifiestos/compose incluidos lo hacen). Ambos configurados ⇒ las auditorías ejecutan la investigación de IA; cualquiera sin configurar ⇒ las auditorías ejecutan **solo políticas** (el pase de política SQL determinista aún se ejecuta), independientemente del indicador `llm_enabled` por auditoría. El agente también debe tener un LLM configurado; consulta [assistant.md](/es/agenteye/assistant). | +| `AUDIT_REQUEST_TIMEOUT_MS` | No | `30000` | Tiempo de espera por consulta de política en ClickHouse (milisegundos). | +| `AUDIT_LLM_TIMEOUT_MS` | No | `1440000` | Tiempo de espera para la llamada de investigación agéntica al servicio de asistente de IA. Un bucle de agente completo se ejecuta durante minutos; mantenlo POR ENCIMA del propio `AGENTEYE_AUDIT_TIMEOUT_MS` del agente para que este devuelva sus hallazgos parciales antes de que el servidor se rinda. | +| `AUDIT_MAX_ATTEMPTS` | No | `5` | Fallos transitorios consecutivos antes de que una auditoría se reprograme en su cadencia normal en lugar de con retroceso exponencial. | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | No | — | La investigación agéntica de la auditoría llama al servicio `agent` de asistente de IA, **reutilizando la misma conexión que el asistente** — así que establece estos dos también en el **servidor** (los manifiestos/compose incluidos lo hacen). Ambos establecidos ⇒ las auditorías ejecutan la investigación de IA; cualquiera sin establecer ⇒ las auditorías se ejecutan **solo con políticas** (el paso determinista de políticas SQL sigue ejecutándose), independientemente del indicador `llm_enabled` por auditoría. El agente también debe tener un LLM configurado — consulta [assistant.md](/es/agenteye/assistant). | -**Servicio de asistente de IA: configuración de auditoría y sandbox.** La investigación agéntica y su sandbox de Python en el pod se ajustan en el **servicio agent** (no en el servidor), todos con el prefijo `AGENTEYE_AUDIT_*` y todos opcionales: +**Servicio de asistente de IA — ajustes de auditoría y sandbox.** La investigación agéntica y su sandbox de Python en el pod se ajustan en el **servicio agent** (no en el servidor), todos con el prefijo `AGENTEYE_AUDIT_*` y todos opcionales: -| Variable | Valor predeterminado | Significado | +| Variable | Valor por defecto | Significado | |---|---|---| -| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Máximo de turnos del agente por investigación. | +| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Turnos máximos del agente por investigación. | | `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Tiempo de reloj de pared para una investigación (20 min). Debe mantenerse **por debajo** del `AUDIT_LLM_TIMEOUT_MS` del servidor. | | `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Investigaciones concurrentes por pod de agente (independiente del presupuesto del asistente de chat). | -| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Límites por script para el sandbox de bubblewrap. | +| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Límites por script para el sandbox bubblewrap. | -**Requisito de plataforma del sandbox.** El sandbox de código de auditoría ejecuta el Python del modelo dentro de una jaula bubblewrap, que necesita **espacios de nombres de usuario sin privilegios**. El pod del agente debe permitir los indicadores `clone()` — establece `seccompProfile: Unconfined` (k8s) o `security_opt: [seccomp:unconfined]` (compose) en el agente. Donde el kernel del nodo deshabilita los espacios de nombres de usuario sin privilegios (p. ej., algunas imágenes GKE COS), el sandbox **falla en la verificación previa y el auditor degrada automáticamente a solo SQL** — sin error, solo un `sandbox_available: false` en el `/health` del agente. +**Requisito de plataforma del sandbox.** El sandbox de código de auditoría ejecuta el Python del modelo dentro de una jaula bubblewrap, que necesita **espacios de nombres de usuario sin privilegios**. El pod del agente debe permitir los indicadores `clone()` — establece `seccompProfile: Unconfined` (k8s) o `security_opt: [seccomp:unconfined]` (compose) en el agente. Donde el kernel del nodo deshabilita los espacios de nombres de usuario sin privilegios (p. ej. algunas imágenes GKE COS), el sandbox **falla en la verificación previa y el auditor degrada automáticamente a solo SQL** — sin error, simplemente un `sandbox_available: false` en el `/health` del agente. ### Ejecutar -Establece `DATABASE_URL` y `CLICKHOUSE_URL` en tu entorno (el servidor se niega a arrancar sin ClickHouse) y pásalos al contenedor: +Establece `DATABASE_URL` en tu entorno y pásalo al contenedor: ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest @@ -126,33 +124,33 @@ docker run -d --restart unless-stopped \ El servidor ejecuta las migraciones de base de datos automáticamente al inicio; no se necesita ningún paso de migración separado. -### Verificación de salud +### Verificación de estado ``` GET /health # liveness - siempre {"status":"ok"} una vez que el proceso está activo -GET /ready # readiness - 200 cuando Postgres + ClickHouse son accesibles, sino 503 +GET /ready # readiness - 200 cuando Postgres + ClickHouse son accesibles, si no 503 ``` -No se requiere autenticación. Usa `/health` para las sondas de **liveness** y `/ready` para las sondas de **readiness** / balanceador de carga. `/ready` verifica las dependencias estrictas sin las que el servidor no puede funcionar (Postgres + ClickHouse), por lo que un servidor que está en ejecución pero no puede alcanzar su base de datos se retira de la rotación y aparece como `NotReady`; Redis se reporta pero nunca falla el readiness. En los manifiestos de Kubernetes incluidos, la sonda de readiness ya apunta a `/ready` y la de liveness se mantiene en `/health`. Consulta [enterprise-docs/health-monitoring.md](/es/agenteye/health-monitoring) para la imagen completa, incluidas las alertas opcionales de Kubernetes a Slack por fallos de pod. +No se requiere autenticación. Usa `/health` para sondeos de **liveness** y `/ready` para sondeos de **readiness** / balanceador de carga. `/ready` verifica las dependencias estrictas sin las que el servidor no puede funcionar (Postgres + ClickHouse), por lo que un servidor en ejecución que no puede alcanzar su base de datos se saca de rotación y aparece como `NotReady`; Redis se informa pero nunca falla la disponibilidad. En los manifiestos de Kubernetes incluidos, el sondeo de readiness ya apunta a `/ready` y el de liveness permanece en `/health`. Consulta [enterprise-docs/health-monitoring.md](/es/agenteye/health-monitoring) para la imagen completa, incluidas las alertas de fallo de pod nativas de Kubernetes con opt-in a Slack. -### URL del enlace mágico del correo +### URL del enlace mágico por correo Los correos de inicio de sesión OTP contienen un botón **abrir el panel** con un solo toque. Al hacer clic, el usuario llega a `/login?token=&email=
`; el panel intercambia ese par por una sesión y redirige a la aplicación, sin necesidad de volver a introducir el código manualmente. El servidor resuelve el origen del panel utilizado para construir el enlace en tres niveles: -1. **Cabecera `X-AgentEye-Dashboard-Url`**: establecida automáticamente por el proxy `/api/auth/otp/request` del panel desde su propio origen público. En un despliegue de mismo origen (servidor y panel comparten un host detrás de un ingress que reenvía cabeceras proxy), **no se requiere ninguna configuración**. -2. **Variable de entorno `DASHBOARD_URL`**: configúrala si tu panel es accesible en un origen diferente al que ve el endpoint de solicitud OTP del servidor (dominio dividido `api.example.com` / `app.example.com`), o si tu ingress no propaga el host público al pod del panel (de modo que `request.nextUrl.origin` resolvería a una dirección de escucha comodín como `0.0.0.0:3000`). Ejemplo: `DASHBOARD_URL=https://app.example.com`. -3. **Predeterminado**: `https://app.befailproof.ai`, usado solo si ninguno de los anteriores está presente. +1. **Encabezado `X-AgentEye-Dashboard-Url`**: lo establece automáticamente el proxy `/api/auth/otp/request` del panel desde su propio origen público. En un despliegue del mismo origen (el servidor y el panel comparten un host detrás de un ingress que reenvía encabezados proxy), **no se requiere ninguna configuración**. +2. **Variable de entorno `DASHBOARD_URL`**: establécela si tu panel es accesible en un origen diferente al que ve el endpoint de solicitud OTP del servidor (dominios separados `api.example.com` / `app.example.com`), o si tu ingress no propaga el host público al pod del panel (de modo que `request.nextUrl.origin` de otro modo resolvería a una dirección de vinculación comodín como `0.0.0.0:3000`). Ejemplo: `DASHBOARD_URL=https://app.example.com`. +3. **Valor predeterminado**: `https://app.befailproof.ai`, usado solo si ninguno de los anteriores está presente. -El valor de la cabecera se valida: solo se aceptan orígenes `https://*` y de loopback (`http://localhost*`, `http://127.0.0.1*`), y las direcciones de escucha comodín (`0.0.0.0`, `[::]`) se rechazan incluso con el esquema `https://`. Cualquier otra cosa pasa al nivel 2. +El valor del encabezado se valida: solo se aceptan orígenes `https://*` y de loopback (`http://localhost*`, `http://127.0.0.1*`), y las direcciones de vinculación comodín (`0.0.0.0`, `[::]`) se rechazan incluso con el esquema `https://`. Cualquier otra cosa cae al nivel 2. -Configúralo en un clúster en ejecución con un solo comando; sin archivos, sin reconstruir kustomize: +Establécelo en un clúster en ejecución con una sola línea; sin archivos, sin reconstrucción de kustomize: ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -Esto activa un rollout; los nuevos pods recogen el valor en la primera solicitud. Ten en cuenta que el override solo existe en el Deployment; un `kustomize build | kubectl apply` posterior contra el overlay lo eliminará a menos que añadas la misma variable de entorno al parche `server-env.yaml` de tu overlay. +Esto activa un rollout; los nuevos pods recogen el valor en la primera solicitud. Ten en cuenta que la sobreescritura solo vive en el Deployment; un `kustomize build | kubectl apply` posterior contra el overlay lo eliminará a menos que añadas la misma variable de entorno al parche `server-env.yaml` de tu overlay. --- @@ -166,15 +164,15 @@ docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest ### Variables de entorno -| Variable | Requerida | Valor predeterminado | Descripción | +| Variable | Obligatoria | Valor por defecto | Descripción | |---|---|---|---| | `AGENTEYE_SERVER_URL` | Sí | ninguno | URL base del servidor, p. ej. `http://localhost:8080` | -| `AGENTEYE_API_KEY` | Sí | ninguno | Clave API que usa el panel para autenticarse con el servidor. Necesita todos los permisos (se recomienda la clave de administrador). | -| `AE_LOG_LEVEL` | No | `info` | Nivel de detalle del registro del lado del servidor: `debug`, `info`, `warn`, `error`. Establécelo en `debug` para ver líneas de solicitud/respuesta upstream y trazas de validación de sesión al diagnosticar problemas. | -| `AE_LOG_JSON` | No | automático | `1` fuerza salida JSON por línea; `0` fuerza salida legible por humanos. Cuando no se configura, JSON se habilita automáticamente si `NODE_ENV=production`. Se recomienda JSON en producción para que los registros se analicen correctamente con `jq` o un agregador de registros. | -| `AE_ANALYTICS_DISABLED` | No | ninguno | Establece en `1`/`true` para deshabilitar la telemetría anónima de uso del producto del panel. Consulta [Telemetría y privacidad](#telemetry--privacy) más abajo. | -| `REDIS_URL` | No | ninguno | Backend opcional de caché compartida, p. ej. `redis://redis:6379/0`. Cuando se configura, el panel almacena en caché los resultados de `validateSession()` entre réplicas y comparte la caché de fetch de Next.js para las rutas proxy de agregado de latencia y lista de entornos. Los límites de tasa OTP de solicitud y verificación en el borde también usan Redis cuando está disponible (fallando abierto si Redis no es accesible; el límite del lado del servidor es el resguardo de seguridad). Consulta **Redis (caché opcional)** más abajo. | -| `AGENTEYE_AGENT_URL` | No | ninguno | URL base del servicio `agent` de asistente de IA opcional, p. ej. `http://agent:9100`. **Déjalo sin configurar para ocultar completamente el asistente**: no aparece ningún elemento del asistente en el panel. Consulta [enterprise-docs/assistant.md](/es/agenteye/assistant). | +| `AGENTEYE_API_KEY` | Sí | ninguno | Clave de API que usa el panel para autenticarse en el servidor. Necesita todos los permisos (se recomienda la clave de administrador). | +| `AE_LOG_LEVEL` | No | `info` | Nivel de detalle del registro del lado del servidor: `debug`, `info`, `warn`, `error`. Establécelo en `debug` para ver líneas de solicitud/respuesta ascendente y trazas de validación de sesión al diagnosticar problemas. | +| `AE_LOG_JSON` | No | automático | `1` fuerza la salida JSON por línea; `0` fuerza la salida legible por humanos. Si no se establece, JSON se habilita automáticamente si `NODE_ENV=production`. Se recomienda JSON en producción para que los registros se analicen limpiamente con `jq` o un agregador de registros. | +| `AE_ANALYTICS_DISABLED` | No | ninguno | Establécelo en `1`/`true` para deshabilitar la telemetría anónima de uso del producto del panel. Consulta [Telemetría y privacidad](#telemetry--privacy) a continuación. | +| `REDIS_URL` | No | ninguno | Backend opcional de caché compartida, p. ej. `redis://redis:6379/0`. Cuando se establece, el panel almacena en caché los resultados de `validateSession()` entre réplicas y comparte la caché de fetch de Next.js para las rutas proxy de agregado de latencia y lista de entornos. Los límites de tasa de solicitud y verificación OTP del lado del edge también usan Redis cuando está presente (fallando abiertos si Redis es inaccesible; el límite del lado del servidor es la salvaguarda de seguridad). Consulta **Redis (caché opcional)** a continuación. | +| `AGENTEYE_AGENT_URL` | No | ninguno | URL base del servicio `agent` de asistente de IA opcional, p. ej. `http://agent:9100`. **Déjalo sin establecer para ocultar el asistente por completo**: no aparece ninguna burbuja de asistente en el panel. Consulta [enterprise-docs/assistant.md](/es/agenteye/assistant). | | `AGENTEYE_AGENT_TOKEN` | No | ninguno | Secreto compartido que el panel presenta al servicio `agent`. Debe coincidir con el `AGENTEYE_AGENT_TOKEN` configurado en el agente. Consulta [enterprise-docs/assistant.md](/es/agenteye/assistant). | ### Ejecutar @@ -190,89 +188,89 @@ docker run -d --restart unless-stopped \ ### Telemetría y privacidad -El panel envía **análisis de uso del producto anónimos** al servicio de análisis de Exosphere (PostHog): qué páginas del panel se visualizan y algunas acciones de la interfaz como crear una clave API o volver a evaluar una sesión. Esta señal de uso informa qué funciones se priorizan. +El panel envía **analítica anónima de uso del producto** al servicio de analítica de Exosphere (PostHog): qué páginas del panel se visitan y algunas acciones de la interfaz de usuario, como crear una clave de API o volver a evaluar una sesión. Esta señal de uso informa qué funciones se priorizan. -- **Ningún dato de agente, sesión ni evento abandona tu infraestructura.** Solo se reporta el uso de la interfaz del panel. Las URLs de las páginas se eliminan de identificadores antes de enviarlas, y los operadores se identifican únicamente por un ID interno opaco, nunca por correo electrónico. -- La telemetría está **habilitada de forma predeterminada**. Para desactivarla completamente, establece `AE_ANALYTICS_DISABLED=1` en el contenedor del panel y reinicia. -- Los análisis se envían a la propia ruta `/ingest` del panel, que el panel reenvía como proxy inverso a PostHog (`https://us.i.posthog.com`). Mantener las solicitudes como first-party significa que los bloqueadores de anuncios del navegador no las descartan. El **contenedor del panel** necesita acceso de salida a PostHog; si está bloqueado, la telemetría no hace nada silenciosamente y el panel no se ve afectado. +- **Ningún dato de agente, sesión o evento sale nunca de tu infraestructura.** Solo se informa el uso de la interfaz de usuario del panel. Las URL de las páginas se eliminan de identificadores antes de enviarlas, y los operadores se identifican solo por un ID interno opaco, nunca por correo electrónico. +- La telemetría está **habilitada de forma predeterminada**. Para desactivarla completamente, establece `AE_ANALYTICS_DISABLED=1` en el contenedor del panel y reinícialo. +- La analítica se envía a la propia ruta `/ingest` del panel, que el panel envía en proxy inverso a PostHog (`https://us.i.posthog.com`). Mantener las solicitudes como propias significa que los bloqueadores de anuncios del navegador no las descartan. El **contenedor del panel** necesita acceso saliente a PostHog; si está bloqueado, la telemetría no hace nada silenciosamente y el panel no se ve afectado. --- ## Asistente de IA (opcional) -Un asistente de IA integrado en el panel permite a tu equipo hacer preguntas sobre sus datos de agentes en lenguaje natural (resumiendo sesiones, redactando SQL para el editor `/queries` y convirtiendo consultas guardadas en tiles del panel) sin salir del panel. Se ejecuta como un contenedor `agent` interno separado (sobre el Agents SDK de Claude) que solo el panel puede alcanzar, y permanece **deshabilitado hasta que configures un endpoint de LLM**. +Un asistente de IA integrado en el panel permite a tu equipo hacer preguntas sobre sus datos de agentes en lenguaje natural (resumir sesiones, redactar SQL para el editor `/queries` y convertir consultas guardadas en tiles del panel) sin salir del panel. Se ejecuta como un contenedor `agent` interno separado (sobre el Agents SDK de Claude) al que solo el panel puede acceder, y permanece **deshabilitado hasta que configures un endpoint LLM**. -Para habilitarlo, establece en el servicio `agent` una conexión LLM (**Portkey** mediante `PORTKEY_API_KEY` + un slug de catálogo de modelos `AGENTEYE_AGENT_MODEL=@/`, Anthropic directo mediante `ANTHROPIC_API_KEY`, otra pasarela mediante `ANTHROPIC_BASE_URL`, o Bedrock/Vertex), una clave de datos **dedicada**, y un `AGENTEYE_AGENT_TOKEN` compartido que coincida con el panel. Los usuarios del panel además necesitan el permiso `agent:use`. +Para habilitarlo, estableces en el servicio `agent` una conexión LLM (**Portkey** a través de `PORTKEY_API_KEY` + un slug de catálogo de modelos `AGENTEYE_AGENT_MODEL=@/`, Anthropic directo a través de `ANTHROPIC_API_KEY`, otra puerta de enlace a través de `ANTHROPIC_BASE_URL`, o Bedrock/Vertex), una clave de datos **dedicada** y un `AGENTEYE_AGENT_TOKEN` compartido que coincida con el panel. Los usuarios del panel además necesitan el permiso `agent:use`. -Para la clave de datos del asistente no necesitas crear nada manualmente: elige un secreto aleatorio, establécelo como `AGENTEYE_API_KEY` en el `agent` **y** como `AGENT_API_KEY` en el `server`, y el servidor lo inicializa al arrancar con un conjunto fijo de permisos. Su acceso a los datos es de solo lectura (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), y además tiene permisos de autoría con aprobación (`dashboards:write`, `queries:write`, `queries:run`) para que pueda redactar y validar consultas guardadas y construir tiles del panel en nombre del usuario; todo el SQL aún se ejecuta a través del rol de ClickHouse de solo lectura de la org, por lo que esto amplía lo que el asistente puede crear, no los datos a los que puede acceder. Los permisos están fijados en el código y no pueden ampliarse mediante configuración. Esa clave está protegida; no puede deshabilitarse ni regenerarse mediante la API, solo se puede rotar cambiando el valor y reiniciando. Nunca reutilices la clave de administrador/panel para esto. +Para la clave de datos del asistente no necesitas generar nada manualmente: elige un secreto aleatorio, establécelo como `AGENTEYE_API_KEY` en el `agent` **y** como `AGENT_API_KEY` en el `server`, y el servidor lo inicia con un conjunto fijo de permisos. Su acceso a datos es de solo lectura (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), y además tiene alcances de creación con aprobación requerida (`dashboards:write`, `queries:write`, `queries:run`) para que pueda redactar y validar consultas guardadas y construir tiles del panel en nombre del usuario; todo el SQL sigue ejecutándose a través del rol de ClickHouse de solo lectura de la organización, por lo que esto amplía lo que el asistente puede crear, no los datos a los que puede acceder. Los alcances están fijos en el código y no pueden ampliarse mediante configuración. Esa clave está protegida; no se puede deshabilitar ni regenerar a través de la API, solo rotarla cambiando el valor y reiniciando. Nunca reutilices la clave de administrador/panel para esto. -La configuración completa, la referencia de variables de entorno, las opciones de telemetría y el modelo de seguridad están en **[enterprise-docs/assistant.md](/es/agenteye/assistant)**. +La configuración completa, la referencia completa de variables de entorno, las opciones de telemetría y el modelo de seguridad están en **[enterprise-docs/assistant.md](/es/agenteye/assistant)**. --- -## ClickHouse (almacén analítico requerido) +## ClickHouse (almacén de analítica obligatorio) -ClickHouse mantiene tus paneles ágiles a alto volumen de eventos y permite que el editor SQL `/queries` una eventos, evaluaciones y sesiones en un único almacén. Es el almacén canónico requerido para cada evento ingestado, cada resultado de evaluación terminal y los agregados por sesión derivados. PostgreSQL mantiene las tablas relacionales / de estado mutable (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); la superficie analítica vive en ClickHouse para que los resúmenes del panel y tus propias consultas SQL puedan escanearla y unirla de forma nativa, sin viajes de ida y vuelta entre bases de datos. El servidor se niega a arrancar sin `CLICKHOUSE_URL`. +ClickHouse mantiene tus paneles responsivos a altos volúmenes de eventos y permite que el editor SQL `/queries` una eventos, evaluaciones y sesiones en un único almacén. Es el almacén canónico obligatorio para cada evento ingerido, cada resultado de evaluación terminal y los agregados por sesión derivados. PostgreSQL almacena las tablas relacionales / de estado mutable (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); la superficie analítica vive en ClickHouse para que los resúmenes del panel y tus propias consultas SQL puedan escanearlos y unirlos de forma nativa, sin viajes de ida y vuelta entre bases de datos. El servidor se niega a arrancar sin `CLICKHOUSE_URL`. ### Esquema -Al inicio del servidor se crean tres objetos de ClickHouse, todos idempotentes (`CREATE IF NOT EXISTS`): +Se crean tres objetos de ClickHouse al inicio del servidor, todos idempotentes (`CREATE IF NOT EXISTS`): -- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, particionado por `toYYYYMM(ts)`, ordenado por `(session_id, ts, dedup_key)`. Las inserciones duplicadas (reintentos del colector) se colapsan en una sola fila en el momento de la fusión; el servidor calcula un `dedup_key` SHA-256 determinista para cada evento, por lo que los reintentos son seguros. -- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, particionado por `toYYYYMM(finished_at)`, ordenado por `(session_id, finished_at, dedup_key)`. Se escribe una vez por resultado de evaluación terminal por el pipeline del evaluador. Mismo modelo de clave de deduplicación que `events`. -- **`agenteye.agent_sessions`**: una **VISTA** sobre `agenteye.events`, no una tabla física. Cada columna se deriva (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, etc.). No hay upsert por evento ni backfill separado; la vista refleja automáticamente lo que hay en `events`. +- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, particionado por `toYYYYMM(ts)`, ordenado por `(session_id, ts, dedup_key)`. Las inserciones duplicadas (reintentos del collector) colapsan a una sola fila en el momento de la fusión; el servidor calcula un `dedup_key` SHA-256 determinista para cada evento de modo que los reintentos son seguros. +- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, particionado por `toYYYYMM(finished_at)`, ordenado por `(session_id, finished_at, dedup_key)`. Escrito una vez por resultado de evaluación terminal por la canalización del evaluador. Mismo modelo de clave de deduplicación que `events`. +- **`agenteye.agent_sessions`**: una **VISTA** sobre `agenteye.events`, no una tabla física. Cada columna es derivada (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, etc.). Sin upsert por evento y sin relleno retroactivo separado; la vista refleja automáticamente lo que hay en `events`. -Para compatibilidad con versiones anteriores de consultas guardadas que referencian `analytics.evaluations` / `analytics.sessions`, el servidor también crea una base de datos de ClickHouse `analytics` con vistas sobre las tablas `agenteye.*`; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` se resuelven correctamente. +Para compatibilidad retroactiva con consultas guardadas que hacen referencia a `analytics.evaluations` / `analytics.sessions`, el servidor también crea una base de datos `analytics` de ClickHouse con vistas sobre las tablas `agenteye.*`; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` se resuelven correctamente. ### Configuración -El docker-compose incluido y `deploy/base/clickhouse/` incluyen un servicio ClickHouse ajustado para la carga de trabajo de AgentEye: +El docker-compose incluido y `deploy/base/clickhouse/` incorporan un servicio de ClickHouse ajustado para la carga de trabajo de AgentEye: -- 2 GiB solicitados / 4 GiB de límite de memoria en el overlay base incluido (dimensionado para nodos pequeños de POC/staging); los clientes de producción deben escalar hacia arriba en el overlay: el mínimo recomendado es 2c / 4Gi de solicitud, 6c / 8Gi de límite. `max_server_memory_usage_to_ram_ratio=0.9` -- Caché de marcas de 5 GiB + caché sin comprimir de 8 GiB +- 2 GiB solicitados / 4 GiB límite de memoria en el overlay base incluido (dimensionado para nodos pequeños de POC/staging); los clientes de producción deberían aumentarlo — el mínimo recomendado es 2c / 4Gi de solicitud, 6c / 8Gi de límite. `max_server_memory_usage_to_ram_ratio=0.9` +- 5 GiB de caché de marcas + 8 GiB de caché sin comprimir - `background_pool_size=16`, `background_merges_mutations_concurrency_ratio=2` - MergeTree: `parts_to_throw_insert=3000`, `parts_to_delay_insert=1500`, `non_replicated_deduplication_window=1000` - `local_io_method=auto` (io_uring en kernels compatibles) -- `fsync_metadata=0`: aceptable debido a la ingestión al menos una vez + deduplicación de ReplacingMergeTree -- `query_log` habilitado con TTL de 30 días; `query_thread_log` eliminado (costoso a alto QPS) +- `fsync_metadata=0`: aceptable por la ingestión at-least-once + deduplicación ReplacingMergeTree +- `query_log` habilitado con TTL de 30 días; `query_thread_log` eliminado (costoso con QPS alto) - `max_execution_time=30` para consultas del lado del usuario -- PVC de 100 GiB en la plantilla del StatefulSet (los overlays de clientes DEBEN sobrescribir con una clase de almacenamiento SSD rápida para producción) +- 100 GiB PVC en la plantilla StatefulSet (los overlays de los clientes DEBEN sobreescribir a una clase de almacenamiento SSD rápida para producción) ### Copias de seguridad -Todo tu conjunto de datos se captura noche a noche en un único archivo restaurable, por lo que la pérdida de un clúster o almacenamiento es recuperable. ClickHouse se respalda automáticamente mediante el CronJob diario `agenteye-backup`, que vuelca tanto PostgreSQL como ClickHouse en un solo paso. ClickHouse se lee a través de su API HTTP: `agenteye.events` y `agenteye.evaluations` se vuelcan en formato nativo de ClickHouse (las vistas y políticas de filas se recrean por el servidor al inicio, por lo que los datos de la tabla son la imagen completa) y se empaquetan con el volcado de Postgres en un único archivo comprimido que se sube a tu almacenamiento de objetos. +Tu conjunto de datos completo se captura diariamente en un archivo restaurable único, por lo que una pérdida de clúster o almacenamiento es recuperable. ClickHouse se respalda automáticamente mediante el CronJob diario `agenteye-backup`, que vuelca tanto PostgreSQL como ClickHouse en un solo paso. ClickHouse se lee a través de su API HTTP: `agenteye.events` y `agenteye.evaluations` se vuelcan en formato nativo de ClickHouse (las vistas y las políticas de fila se recrean por el servidor al inicio, por lo que los datos de la tabla son el cuadro completo) y se agrupan con el volcado de Postgres en un único archivo comprimido subido a tu almacenamiento de objetos. -El bucket de destino y las credenciales de la nube se configuran por overlay. Consulta la sección **Copias de seguridad** de [enterprise-docs/kubernetes-deployment.md](/es/agenteye/kubernetes-deployment) para la configuración de carga y los pasos de restauración. +El bucket de destino y las credenciales en la nube se configuran por overlay. Consulta la sección **Copias de seguridad** de [enterprise-docs/kubernetes-deployment.md](/es/agenteye/kubernetes-deployment) para la configuración de subida y los pasos de restauración. --- ## Redis (caché opcional) -Redis es un backend de caché compartida + límite de tasa **opcional** utilizado por el servidor y el panel. Con Redis desplegado y `REDIS_URL` configurado en ambos servicios: +Redis es un backend **opcional** de caché compartida + limitación de tasa usado por el servidor y el panel. Con Redis desplegado y `REDIS_URL` establecido en ambos servicios: -- **El servidor** almacena en caché las búsquedas de claves API autenticadas, las listas `/events/environments` + `/evaluations/environments`, el resumen `/events/latency_aggregate` (la consulta más pesada que sondea el panel), la lista `/sessions`, y cambia el límite de tasa de solicitudes OTP de un `COUNT(*)` de Postgres a un `INCR + EXPIRE` de Redis. -- **El panel** almacena en caché los resultados de `validateSession()` para que las 10-20 llamadas API autenticadas que una carga de página típica realiza compartan una sola verificación de sesión upstream. También limita la tasa de solicitudes OTP y verificación OTP en el borde del panel. +- **El servidor** almacena en caché las búsquedas de claves API autenticadas, las listas `/events/environments` + `/evaluations/environments`, el rollup `/events/latency_aggregate` (la consulta más pesada que sondea el panel), la lista `/sessions`, y cambia la limitación de tasa de solicitudes OTP de un `COUNT(*)` de Postgres a un `INCR + EXPIRE` de Redis. +- **El panel** almacena en caché los resultados de `validateSession()` para que las 10-20 llamadas API autenticadas que emite una carga de página típica compartan una sola verificación de sesión ascendente. También limita la tasa de solicitudes OTP y verificación OTP en el edge del panel. -**Ambos servicios degradan de forma elegante si Redis no es accesible.** Cada llamada de caché devuelve `Err` dentro de un tiempo de espera acotado y el llamador recurre a la fuente de verdad (Postgres en el servidor, el servidor Rust upstream en el panel). El límite de tasa OTP recurre a la ruta `COUNT(*)` de Postgres en el servidor (la propiedad de seguridad se preserva); el límite OTP en el borde del panel falla abierto mientras el límite del lado del servidor sigue vigente. Que Redis esté caído degrada la latencia, no la corrección. +**Ambos servicios degradan de forma controlada si Redis es inaccesible.** Cada llamada de caché devuelve `Err` dentro de un tiempo de espera acotado y el llamador recurre a la fuente de verdad (Postgres en el servidor, el servidor Rust ascendente en el panel). La limitación de tasa OTP recurre a la ruta `COUNT(*)` de Postgres en el servidor (la propiedad de seguridad se preserva); el límite OTP del edge del panel falla abierto mientras el límite del lado del servidor sigue vigente. Que Redis esté caído degrada la latencia, no la corrección. ### Configuración El paquete docker-compose ya incluye un servicio Redis y conecta `REDIS_URL=redis://redis:6379/0` al servidor y al panel. Para usar un Redis externo, establece `REDIS_URL` en tu endpoint y elimina el servicio `redis` del archivo compose. -### Memoria y persistencia +### Memoria + persistencia -La imagen Redis incluida se ejecuta con `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. La persistencia AOF significa que la caché sobrevive a los reinicios del contenedor; `everysec` es el equilibrio correcto entre durabilidad y rendimiento porque perder el último segundo de escrituras en caché es inofensivo. La expulsión LRU limita el crecimiento de memoria. +La imagen de Redis incluida se ejecuta con `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. La persistencia AOF significa que la caché sobrevive a los reinicios del contenedor; `everysec` es el equilibrio adecuado de durabilidad/rendimiento porque perder el último segundo de escrituras de caché es inofensivo. La expulsión LRU limita el crecimiento de la memoria. ### Cuándo NO desplegar Redis -- Desarrollo/QA de instancia única. Las cachés en proceso del servidor por sí solas ofrecen la mayor parte del beneficio por réplica; Redis añade el compartido entre réplicas que las configuraciones de instancia única no necesitan. -- Instalaciones con aislamiento de red donde el coste operativo de ejecutar un servicio más supera la ganancia en latencia. +- Desarrollo/QA de instancia única. Las cachés en proceso del servidor por sí solas ofrecen la mayor parte del beneficio por réplica; Redis añade el uso compartido entre réplicas que las configuraciones de instancia única no necesitan. +- Instalaciones aisladas de la red donde el coste operativo de ejecutar un servicio más supera la mejora de latencia. --- ## Docker Compose (recomendado) -Un `docker-compose.yml` está disponible en el repositorio `agenteye-enterprise/releases`. Levanta Postgres, ClickHouse, Redis, el servidor y el panel con un único comando. +Hay un `docker-compose.yml` disponible en el repositorio `agenteye-enterprise/releases`. Levanta Postgres, el servidor y el panel con un solo comando. ```bash GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ @@ -282,10 +280,10 @@ GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ cd agenteye ``` -**Sobrescribe los valores predeterminados mediante `.env`:** +**Sobreescribe los valores predeterminados con `.env`:** ``` -# Usa contraseñas seguras para URLs (sin caracteres /, +, ni =). +# Usa contraseñas seguras para URL (sin caracteres /, + ni =). # Genera con: openssl rand -hex 24 POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret @@ -294,7 +292,7 @@ ADMIN_KEY=your-admin-secret ADMIN_EMAIL=admin@yourcompany.com ALLOWED_EMAILS=*@yourcompany.com -# SMTP para correos OTP (omitir para registrar los códigos OTP en stdout) +# SMTP para correos OTP (omite para registrar los códigos OTP en stdout) # SMTP_HOST=smtp.yourprovider.com # SMTP_PORT=587 # SMTP_USERNAME=your-smtp-user @@ -322,27 +320,27 @@ docker compose down -v --- -## Configuración operacional +## Ajustes operativos -Un pequeño conjunto de parámetros operacionales que antes estaban fijados por variables de entorno ahora son editables por organización desde la página **`//settings`** del panel; cada org configura la suya propia. Los cambios surten efecto en segundos, sin reinicio ni redespliegue. +Un pequeño conjunto de configuraciones operativas que antes estaban fijadas por variables de entorno ahora son editables por organización desde la página **`//settings`** del panel; cada organización configura las suyas. Los cambios surten efecto en segundos, sin reinicio ni redespliegue. -| Configuración | Variable de entorno de arranque | Qué controla | +| Ajuste | Variable de entorno de arranque | Qué controla | |---|---|---| -| Inicios de sesión permitidos | `ALLOWED_EMAILS` | Correos (o comodines `*@domain.com`) autorizados a recibir un OTP y añadirse como usuarios | -| Permisos predeterminados del usuario | `DEFAULT_USER_PERMISSIONS` | Tokens de permiso separados por comas preseleccionados cuando un administrador abre **+ nuevo usuario**. Cada token debe ser una de las cadenas listadas en [Permisos de clave API](/es/agenteye/api-keys). Por defecto usa el preset `standard`: acceso de solo lectura más las acciones cotidianas de guardia (activar reevaluaciones, ejecutar consultas, confirmar incidencias, usar el asistente). | -| Duración de la sesión | `SESSION_TTL_SECS` | Cuánto tiempo permanece válido un inicio de sesión en el panel antes de requerir reautenticación. El panel vuelve a verificar la sesión upstream cada 5 segundos, por lo que una actualización de permisos en `//users` surte efecto en la próxima solicitud del usuario afectado, sin necesidad de volver a iniciar sesión. | +| Inicios de sesión permitidos | `ALLOWED_EMAILS` | Correos electrónicos (o comodines `*@domain.com`) autorizados a recibir un OTP y añadirse como usuarios | +| Permisos predeterminados de usuario | `DEFAULT_USER_PERMISSIONS` | Tokens de permiso separados por comas preseleccionados cuando un administrador abre **+ nuevo usuario**. Cada token debe ser una de las cadenas listadas en [Permisos de clave de API](/es/agenteye/api-keys). Tiene como predeterminado el preset `standard`: acceso de solo lectura más las acciones cotidianas de guardia (activar reevaluaciones, ejecutar consultas, reconocer incidentes, usar el asistente). | +| Duración de la sesión | `SESSION_TTL_SECS` | Cuánto tiempo permanece válido un inicio de sesión en el panel antes de requerir autenticación. El panel vuelve a verificar la sesión ascendente cada 5 segundos, por lo que una actualización de permisos en `//users` surte efecto en la próxima solicitud del usuario afectado, sin necesidad de volver a iniciar sesión. | | Duración del código de un solo uso | `OTP_TTL_SECS` | Cuánto tiempo permanece utilizable un OTP / enlace mágico | -| Canales de notificación de alertas | `ALERTS_ENABLED_CHANNELS` | Lista separada por comas de tipos de canales que el despachador de alertas puede usar: `email`, `slack`, `webhook`. La configuración por alerta aún se crea en `//alerts/`, pero el despachador filtra cada entrega saliente a través de este conjunto; un canal deshabilitado aquí se interrumpe con una fila de auditoría `skipped_disabled`. El canal `dashboard` (la inserción de auditoría local) siempre está permitido. Por defecto los tres están habilitados. | +| Canales de notificación de alertas | `ALERTS_ENABLED_CHANNELS` | Lista separada por comas de tipos de canales que el despachador de alertas puede usar: `email`, `slack`, `webhook`. La configuración por alerta sigue creándose en `//alerts/`, pero el despachador filtra cada entrega saliente a través de este conjunto; un canal deshabilitado aquí se cortocircuita con una fila de auditoría `skipped_disabled`. El canal `dashboard` (la inserción de auditoría local) siempre está permitido. Por defecto los tres están activados. | ### Cómo funciona el arranque -La configuración se almacena por organización en `org_settings`. En el primer arranque, el servidor inicializa las filas faltantes de la org predeterminada desde la variable de entorno correspondiente (o un valor predeterminado razonable si la variable no está configurada). A partir de entonces, **el valor almacenado es la fuente de verdad y la variable de entorno se ignora**; cambiar la variable de entorno en un reinicio posterior no afectará el valor de una org activa, y las orgs adicionales comienzan con valores predeterminados y configuran los suyos propios. +Los ajustes se almacenan por organización en `org_settings`. En el primer arranque, el servidor llena las filas faltantes de la organización predeterminada a partir de la variable de entorno correspondiente (o un valor predeterminado razonable si la variable no está establecida). A partir de ahí, **el valor almacenado es la fuente de verdad y la variable de entorno se ignora**; cambiar la variable de entorno en un reinicio posterior no afectará al valor de una organización activa, y las organizaciones adicionales parten de los valores predeterminados y configuran los suyos propios. Esto significa: -- Para un despliegue nuevo, establece las variables de entorno como se muestra arriba y la org predeterminada las leerá en el primer arranque. +- Para un despliegue nuevo, establece las variables de entorno como se muestra arriba y la organización predeterminada las leerá en el primer arranque. - Para cambiar un valor más adelante, inicia sesión en el panel y edítalo en `//settings`. El cambio se aplica en segundos en todas las réplicas del servidor; no se necesita reinicio. -- Una línea de registro al inicio registra qué se inicializó frente a qué ya estaba presente, para que puedas confirmar que el arranque surtió efecto: +- Una línea de registro al inicio registra qué se sembró frente a qué ya estaba presente, para que puedas confirmar que el arranque surtió efecto: ```text INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true @@ -350,10 +348,10 @@ Esto significa: #### Semántica de inicio de sesión entre organizaciones -Una sesión y un OTP son globales para el usuario, no para una sola org, por lo que dos reglas reconcilian la configuración por org en el momento del inicio de sesión: +Una sesión y un OTP son globales al usuario, no a una sola organización, por lo que dos reglas reconcilian los ajustes por organización en el momento del inicio de sesión: -- **Duración de sesión / OTP**: gana la duración más estricta (más corta) entre las orgs a las que pertenece el usuario. -- **Inicios de sesión permitidos**: la compuerta hace OR de la lista de permitidos de cada org con la membresía de org: un usuario puede solicitar un OTP si la lista de permitidos de cualquier org admite su correo **o** ya es miembro de alguna org. +- **Duración de sesión / OTP**: gana la duración más estricta (más corta) entre las organizaciones a las que pertenece el usuario. +- **Inicios de sesión permitidos**: la puerta hace un OR de la lista de permitidos de cada organización junto con la pertenencia a la organización: un usuario puede solicitar un OTP si la lista de permitidos de cualquier organización admite su correo electrónico **o** ya es miembro de cualquier organización. ### Permisos @@ -362,41 +360,41 @@ El acceso a una página `//settings` está controlado por dos permisos: - `settings:read`: ver la página y los valores actuales. - `settings:write`: guardar cambios. -El usuario administrador de arranque (inicializado desde `ADMIN_EMAIL`) obtiene ambos automáticamente junto con todos los demás permisos. Otórgalos a otros usuarios desde `//users` según sea necesario. +El usuario administrador de arranque (sembrado desde `ADMIN_EMAIL`) obtiene ambos automáticamente junto con todos los demás permisos. Otórgalos a otros usuarios desde `//users` según sea necesario. --- ## Organizaciones (multi-tenancy) -Un único despliegue puede servir a múltiples **organizaciones** (tenants) aisladas; cada fila de datos pertenece exactamente a una org y el aislamiento se aplica en el motor de base de datos. Una instalación mono-tenant no necesita nada aquí; todos los datos viven en una org `default` integrada. (Puedes dar a esa org un nombre más amigable y un slug de URL para que viva en p. ej. `/acme` en lugar de `/default`, estableciendo `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` antes del primer arranque, o renombrándola en cualquier momento con `agenteye-orgctl org rename`.) +Un único despliegue puede servir a múltiples **organizaciones** (tenants) aisladas; cada fila de datos pertenece exactamente a una organización y el aislamiento se impone en el motor de base de datos. Una instalación de un único tenant no necesita nada aquí; todos los datos viven en una organización `default` integrada. (Puedes darle a esa organización un nombre y slug de URL más amigables, para que viva en p. ej. `/acme` en lugar de `/default`, estableciendo `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` antes del primer arranque, o renombrándola en cualquier momento con `agenteye-orgctl org rename`.) -**El aprovisionamiento de tenants es solo para operadores.** Las organizaciones y sus membresías se crean y gestionan con el CLI **`agenteye-orgctl`**, que se incluye **dentro de la imagen del servidor** (junto a `agenteye-server`) y se ejecuta **dentro del pod del servidor existente**; no hay **ningún pod/Job separado, ninguna API HTTP y ningún botón en el panel**. Reutiliza el `DATABASE_URL`, `CLICKHOUSE_URL` y `ORG_CH_SECRET` del servidor. +**El provisionamiento de tenants es solo para operadores.** Las organizaciones y sus pertenencias se crean y gestionan con la CLI **`agenteye-orgctl`**, que se incluye **dentro de la imagen del servidor** (junto a `agenteye-server`) y se ejecuta **dentro del pod del servidor existente**; no hay **pod/Job separado, ni API HTTP, ni botón en el panel**. Reutiliza el `DATABASE_URL`, `CLICKHOUSE_URL` y `ORG_CH_SECRET` del servidor. ```bash -# Docker Compose - exec en el servicio del servidor en ejecución: +# Docker Compose - ejecutar dentro del servicio de servidor en ejecución: docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp" docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin -# Kubernetes - exec en el Deployment del servidor en ejecución: +# Kubernetes - ejecutar dentro del Deployment del servidor en ejecución: kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list ``` -Verbos disponibles: `org create | list | rename | delete | purge` y `member add | list | update | remove`, con conjuntos de permisos integrados `admin`, `standard` y `read-only`. Los miembros añadidos reciben un OTP en su primer inicio de sesión en el panel. +Verbos disponibles: `org create | list | rename | delete | purge` y `member add | list | update | remove`, con conjuntos de permisos integrados `admin`, `standard` y `read-only`. Los miembros añadidos reciben un OTP en el primer inicio de sesión en el panel. -**Antes de crear una segunda org:** establece un `ORG_CH_SECRET` sólido y estable (el comando `org create` se niega a ejecutarse con el valor de desarrollo integrado predeterminado) y asegúrate de que Postgres sea **15+**. **Sin cambios:** las claves API por org aún se crean en el panel/API por los miembros de la org; solo el ciclo de vida de org + miembro se trasladó al CLI. Referencia completa de comandos y un ejemplo detallado: **[enterprise-docs/tenant-management.md](/es/agenteye/tenant-management)**. +**Antes de crear una segunda organización:** establece un `ORG_CH_SECRET` sólido y estable (el comando `org create` se niega a ejecutarse con el valor predeterminado de desarrollo integrado) y asegúrate de que Postgres sea **15+**. **Sin cambios:** las claves de API por organización siguen siendo acuñadas en el panel/API por los miembros de la organización; solo el ciclo de vida de organizaciones + miembros se movió a la CLI. Referencia completa de comandos y un ejemplo práctico: **[enterprise-docs/tenant-management.md](/es/agenteye/tenant-management)**. --- -## Llenado de la ventana de contexto +## Relleno de la ventana de contexto -Cada evento `model_response` muestra una **píldora de llenado de contexto** — tokens de entrada más salida como porcentaje de la ventana de contexto de ese modelo. Las bandas son `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%) y `reset context` (75–100%). AgentEye resuelve los IDs de modelos comunes automáticamente, por lo que no se requiere ninguna configuración inicial. +Cada evento `model_response` muestra una **píldora de relleno de contexto** — tokens de entrada más salida como porcentaje de la ventana de contexto de ese modelo. Las bandas son `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%) y `reset context` (75–100%). AgentEye resuelve los IDs de modelos comunes automáticamente, por lo que no se requiere ninguna configuración inicial. -Cada modelo que envía una organización aparece en **Settings → model context windows**. Los usuarios con `settings:write` pueden sobrescribir su ventana o añadir un modelo privado/proxy (0–1.000.000 tokens); `0` significa "desconocido" y suprime la píldora. Los cambios se aplican a los eventos recién ingestados. Los usuarios con `settings:read` pueden ver la lista. +Cada modelo que envía una organización aparece en **Configuración → ventanas de contexto de modelos**. Los usuarios con `settings:write` pueden sobreescribir su ventana o añadir un modelo privado/proxy (0–1.000.000 tokens); `0` significa "desconocido" y suprime la píldora. Los cambios se aplican a los eventos recién ingeridos. Los usuarios con `settings:read` pueden ver la lista. -Los nuevos eventos obtienen el llenado desde el momento en que actualices. Para también completar los eventos **históricos** (y la lista por modelo) de un despliegue existente, ejecuta el backfill único — se incluye dentro de la imagen del servidor (como `agenteye-orgctl`) y se ejecuta en el pod del servidor existente: +Los nuevos eventos obtienen el relleno desde el momento en que actualizas. Para también rellenar los eventos **históricos** (y la lista por modelo) de un despliegue existente, ejecuta el relleno retroactivo único — se incluye dentro de la imagen del servidor (como `agenteye-orgctl`) y se ejecuta en el pod del servidor existente: ```bash -# vista previa (imprime la mutación por org, no cambia nada): +# vista previa (imprime la mutación por organización, no cambia nada): kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window --dry-run # aplicar: kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window @@ -404,18 +402,18 @@ kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window docker compose exec server agenteye-backfill-context-window ``` -Es idempotente (seguro de ejecutar varias veces) y reutiliza `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` del pod. Vuelve a ejecutarlo después de editar las ventanas de modelos si deseas que los eventos existentes se recalculen. +Es idempotente (seguro de volver a ejecutar) y reutiliza `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` del pod. Vuélvelo a ejecutar después de editar ventanas de modelos si quieres que los eventos existentes se recalculen. --- -## Consideraciones para producción +## Consideraciones de producción -- **Postgres**: Usa un servicio de Postgres administrado o una instancia dedicada con copias de seguridad regulares. El `DATABASE_URL` admite todos los parámetros libpq estándar, incluido `sslmode=require` para conexiones cifradas. +- **Postgres**: Usa un servicio de Postgres gestionado o una instancia dedicada con copias de seguridad regulares. El `DATABASE_URL` admite todos los parámetros libpq estándar, incluido `sslmode=require` para conexiones cifradas. - **TLS**: Coloca el servidor y el panel detrás de un proxy inverso (nginx, Caddy, Traefik) que termine TLS. -- **Firewall**: El puerto del servidor (predeterminado 8080) solo debe ser accesible desde las máquinas del colector y el host del panel, no desde la internet pública. -- **Clave de administrador**: Establece `ADMIN_KEY` como un secreto aleatorio sólido. Después del arranque inicial, crea claves con alcance dedicado para los colectores y el panel en lugar de usar la clave de administrador en todas partes. -- **Etiquetas de imagen**: Fija a la versión en tus manifiestos de lanzamiento (por ejemplo, `server:v0.0.1-beta.48`) en producción en lugar de una etiqueta flotante para evitar actualizaciones no deseadas. Las compilaciones beta actuales se publican bajo `beta-latest`; `latest` solo se asigna a versiones estables. -- **Monitoreo de salud**: En Kubernetes la sonda de readiness usa `/ready` (accesibilidad de Postgres + ClickHouse) mientras la de liveness se mantiene en `/health`. Para alertas a Slack de "¿está AgentEye en funcionamiento?" a nivel de flota, habilita el add-on Robusta opcional; consulta [enterprise-docs/health-monitoring.md](/es/agenteye/health-monitoring). +- **Firewall**: El puerto del servidor (por defecto 8080) solo debe ser accesible desde las máquinas del collector y el host del panel, no desde internet público. +- **Clave de administrador**: Establece `ADMIN_KEY` en un secreto aleatorio robusto. Después del arranque inicial, crea claves con alcance dedicado para los collectors y el panel en lugar de usar la clave de administrador en todas partes. +- **Etiquetas de imagen**: Fija la versión en los manifiestos de tu versión (por ejemplo, `server:v0.0.1-beta.48`) en producción en lugar de una etiqueta flotante para evitar actualizaciones no intencionadas. Las compilaciones beta actuales se publican con `beta-latest`; `latest` solo se asigna a versiones estables. +- **Monitoreo de salud**: En Kubernetes, el sondeo de readiness usa `/ready` (accesibilidad de Postgres + ClickHouse) mientras que el de liveness permanece en `/health`. Para alertas de "¿está AgentEye en sí mismo activo?" a toda la flota en Slack, habilita el complemento opcional de Robusta; consulta [enterprise-docs/health-monitoring.md](/es/agenteye/health-monitoring). --- @@ -424,5 +422,5 @@ Es idempotente (seguro de ejecutar varias veces) y reutiliza `DATABASE_URL` / `C | Etiqueta | Descripción | |-----|-------------| | `latest` | Última versión estable | -| `beta-latest` | Última versión preliminar (beta) | -| `v` | Versión fijada, p. ej. `v0.0.1-beta.48` (recomendado para producción) | \ No newline at end of file +| `beta-latest` | Última versión previa al lanzamiento (beta) | +| `v` | Versión fijada, p. ej. `v0.0.1-beta.48` (recomendada para producción) | \ No newline at end of file diff --git a/docs/es/agenteye/getting-started.mdx b/docs/es/agenteye/getting-started.mdx index ec45fd90..8dfda046 100644 --- a/docs/es/agenteye/getting-started.mdx +++ b/docs/es/agenteye/getting-started.mdx @@ -4,32 +4,32 @@ description: "Documentación de primeros pasos con AgentEye." --- -Esta guía te lleva paso a paso por una configuración completa de AgentEye: despliegue del servidor y el panel de control, instalación del colector en una máquina de agente e instrumentación de tu código de agente Python. +Esta guía te lleva a través de una configuración completa de AgentEye: desplegar el servidor y el panel de control, instalar el recopilador en una máquina agente e instrumentar tu código de agente Python. --- ## ¿Qué es AgentEye? -AgentEye es una **plataforma de observabilidad y evaluación autoalojada para agentes de IA**. Registra lo que hacen tus agentes — cada paso de una ejecución — y puntúa automáticamente la calidad de cada ejecución completada, para que puedas ver cómo se comportan tus agentes en producción y detectar regresiones antes de que las noten tus usuarios. +AgentEye es una **plataforma de observabilidad y evaluación autoalojada para agentes de IA**. Registra lo que hacen tus agentes —cada paso de una ejecución— y puntúa automáticamente la calidad de cada ejecución completada, para que puedas ver cómo se comportan tus agentes en producción y detectar regresiones antes de que las vean tus usuarios. -Los datos fluyen en una sola dirección: tu código de agente emite **eventos** a través del **SDK de Python** → un daemon **colector** ligero los agrupa y los envía al **servidor** → los eventos y analíticas se almacenan en **ClickHouse** (el estado operacional, como organizaciones, usuarios, claves API, paneles de control y consultas guardadas, vive en **Postgres**) → tú exploras todo en el **panel de control**. +Los datos fluyen en una sola dirección: tu código de agente emite **eventos** a través del **SDK de Python** → un daemon **recopilador** ligero los agrupa y los envía al **servidor** → los eventos y los análisis se almacenan en **ClickHouse** (el estado operacional, como organizaciones, usuarios, claves API, paneles de control y consultas guardadas, vive en **Postgres**) → explores todo en el **panel de control**. Lo que obtienes: -- **Eventos** — el rastro en bruto, paso a paso, de cada ejecución de agente (llamadas a herramientas, llamadas a modelos, hooks, errores). -- **Sesiones** — esos eventos agrupados en una fila por ejecución, cada una **evaluada y puntuada automáticamente**. -- **Evaluaciones** — puntuaciones de calidad producidas por tus propios servicios evaluadores, para que las caídas de calidad afloren sin revisión manual. -- **Consultas y paneles** — SQL de ClickHouse guardado sobre tus datos, representado en paneles compartidos con alcance de organización. -- **Alertas e incidentes** — reglas de umbral que te notifican (correo electrónico, Slack, webhook, en el panel) junto con un flujo de trabajo de gestión de incidentes. +- **Eventos** — el rastro en bruto, paso a paso, de cada ejecución del agente (llamadas a herramientas, llamadas a modelos, hooks, errores). +- **Sesiones** — esos eventos consolidados en una fila por ejecución, cada una **evaluada y puntuada automáticamente**. +- **Evaluaciones** — puntuaciones de calidad producidas por tus propios servicios evaluadores, para que los descensos de calidad sean visibles sin revisión manual. +- **Consultas y paneles** — SQL de ClickHouse guardado sobre tus datos, representado en paneles compartidos con alcance por organización. +- **Alertas e incidentes** — reglas de umbral que te notifican (email, Slack, webhook, dentro del panel) más un flujo de trabajo de incidentes para gestionarlos. - **CLI y asistente de IA** — un cliente de terminal (`agenteye`) y un asistente integrado en el panel para hacer preguntas en lenguaje natural. -Puedes ejecutarlo todo en tu propia infraestructura: como una pila Docker Compose (esta guía), una instalación de Kubernetes para producción o un único pod colocalizado. El resto de esta guía configura la pila Compose de principio a fin. +Todo se ejecuta en tu propia infraestructura, como una pila Docker Compose (esta guía), una instalación Kubernetes de producción o un único pod coubicado. El resto de esta guía configura la pila Compose de principio a fin. --- -## Paso 1: Autenticarse +## Paso 1: Autenticarte -Todos los artefactos de AgentEye se distribuyen desde la organización GitHub `agenteye-enterprise`. Como desarrollador empresarial, puedes generar tu propio PAT de GitHub. Consulta [enterprise-docs/github-token.md](/es/agenteye/github-token) para ver los pasos exactos y los permisos necesarios. +Todos los artefactos de AgentEye se distribuyen desde la organización GitHub `agenteye-enterprise`. Como desarrollador empresarial, puedes generar tu propio GitHub PAT. Sigue [enterprise-docs/github-token.md](/es/agenteye/github-token) para ver los pasos exactos y los permisos requeridos. ```bash export AGENTEYE_TOKEN= @@ -42,7 +42,7 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin ## Paso 2: Desplegar el servidor y el panel de control -El servidor recibe eventos de los colectores y los hace consultables; el panel de control es donde los exploras. Los eventos ingeridos y las analíticas viven en ClickHouse (el almacén de analíticas requerido), mientras que Postgres guarda el estado operacional, como organizaciones, usuarios, claves API, paneles de control y consultas guardadas. +El servidor recibe eventos de los recopiladores y los hace consultables; el panel de control es donde los exploras. Los eventos ingeridos y los análisis viven en ClickHouse (el almacén de análisis requerido), mientras que Postgres almacena el estado operacional como organizaciones, usuarios, claves API, paneles de control y consultas guardadas. **Descarga el archivo compose publicado:** @@ -57,36 +57,30 @@ cd agenteye **Configura tus secretos:** -Crea un archivo `.env` para que el despliegue no use la credencial predeterminada `admin`. Como mínimo, define `ADMIN_KEY` y `POSTGRES_PASSWORD`: +Crea un archivo `.env` para que el despliegue no se ejecute con la credencial predeterminada `admin`. Como mínimo, establece `ADMIN_KEY` y `POSTGRES_PASSWORD`: ```bash POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -También exporta `ADMIN_KEY` en tu shell actual para que los pasos siguientes (por ejemplo, el `curl` del Paso 3) puedan referenciarlo directamente: - -```bash -export ADMIN_KEY=your-admin-secret -``` - **Inicia la pila:** ```bash docker compose up -d ``` -Esto levanta la pila completa, incluyendo el almacén de analíticas ClickHouse requerido y una caché Redis opcional, junto con el servidor y el panel de control. ClickHouse debe estar operativo para que el servidor arranque. +Esto levanta la pila completa, incluido el almacén de análisis ClickHouse requerido y una caché Redis opcional, junto con el servidor y el panel de control. ClickHouse debe estar en buen estado para que el servidor arranque. -El servidor estará escuchando en `http://localhost:8080` y el panel de control en `http://localhost:3000`. +El servidor está ahora escuchando en `http://localhost:8080` y el panel de control en `http://localhost:3000`. Para despliegues en producción (Postgres personalizado, TLS, proxy inverso), consulta [enterprise-docs/deployment.md](/es/agenteye/deployment). --- -## Paso 3: Crear una clave API para el colector +## Paso 3: Crear una clave API para el recopilador -Cada colector se autentica con una clave API con alcance específico. Usa el `ADMIN_KEY` que definiste en el Paso 2 para crear una: +Cada recopilador se autentica con una clave API con alcance definido. Usa el `ADMIN_KEY` que estableciste en el Paso 2 para crear una: ```bash curl -s -X POST http://localhost:8080/keys \ @@ -95,13 +89,13 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -El valor de `key` lo proporcionas tú mismo; úsalo en la configuración del colector en el Paso 4. Consulta [enterprise-docs/api-keys.md](/es/agenteye/api-keys) para la gestión completa de claves. +Tú proporcionas el valor de `key`; úsalo en la configuración del recopilador en el Paso 4. Consulta [enterprise-docs/api-keys.md](/es/agenteye/api-keys) para la gestión completa de claves. --- -## Paso 4: Instalar el colector +## Paso 4: Instalar el recopilador -En cada máquina que ejecute tus agentes de IA, instala el daemon colector. +En cada máquina que ejecute tus agentes de IA, instala el daemon recopilador. **Descarga el binario (Linux x86_64):** @@ -114,7 +108,7 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> Esto descarga la compilación para **Linux x86_64**. Para macOS (Apple Silicon o Intel), Linux arm64, o configuración con Docker, systemd o launchd, consulta [collector-installation.md](/es/agenteye/collector-installation), donde se lista la descarga para cada plataforma — el comando anterior instala un binario Linux que no funcionará en otros sistemas. +> Esto descarga la compilación para **Linux x86_64**. Para macOS (Apple Silicon o Intel), Linux arm64, o la configuración con Docker / systemd / launchd, consulta [collector-installation.md](/es/agenteye/collector-installation), que lista la descarga para cada plataforma; el comando anterior instala un binario de Linux que no funcionará en otros entornos. **Configura:** @@ -134,13 +128,13 @@ EOF agenteye-collector start ``` -Verifica la conectividad con un volcado puntual (termina después de vaciar los eventos pendientes): +Verifica la conectividad con un vaciado puntual (finaliza tras vaciar cualquier evento pendiente): ```bash agenteye-collector flush ``` -Para configuración con Docker, systemd y launchd, consulta [enterprise-docs/collector-installation.md](/es/agenteye/collector-installation). +Para la configuración con Docker, systemd y launchd, consulta [enterprise-docs/collector-installation.md](/es/agenteye/collector-installation). --- @@ -160,7 +154,7 @@ pip install agenteye-${VERSION}-py3-none-any.whl ## Paso 6: Instrumentar tu agente -Añade eventos al código de tu agente. Como mínimo, emite `agent_start` y `agent_end`: +Añade eventos a tu código de agente. Como mínimo, emite `agent_start` y `agent_end`: ```python import agenteye @@ -180,7 +174,7 @@ agenteye.event.agent_end( ) ``` -Los eventos se almacenan en buffer y se vuelcan en `$AGENTEYE_HOME/events/` (o `~/.agenteye/events/` si `AGENTEYE_HOME` no está definido) cada 500 ms. El colector los recoge automáticamente. +Los eventos se almacenan en búfer y se vacían en `$AGENTEYE_HOME/events/` (o `~/.agenteye/events/` si `AGENTEYE_HOME` no está definido) cada 500 ms. El recopilador los recoge automáticamente. Consulta [enterprise-docs/python-sdk.md](/es/agenteye/python-sdk) para la API completa de eventos. @@ -188,48 +182,48 @@ Consulta [enterprise-docs/python-sdk.md](/es/agenteye/python-sdk) para la API co ## Paso 7: Ver eventos en el panel de control -Abre `http://your-dashboard-host:3000` e inicia sesión. AgentEye te envía por correo electrónico un código de un solo uso (o un enlace mágico de un clic), por lo que no hay contraseña que gestionar. +Abre `http://your-dashboard-host:3000` e inicia sesión. AgentEye te envía por email un código de un solo uso (o un enlace mágico de un clic), por lo que no hay contraseña que gestionar. -![La pantalla de inicio de sesión de AgentEye, que envía un código de un solo uso a tu correo electrónico](/agenteye/images/login.png) +![La pantalla de inicio de sesión de AgentEye, que envía un código de un solo uso a tu email](/agenteye/images/login.png) Una vez dentro, la página **Events** muestra un rastro en tiempo real de todos los eventos ingeridos. Filtra por `session_id` o `agent_id` para profundizar en una ejecución específica. ![El flujo de eventos en vivo, codificado por colores según el tipo de evento y filtrable por entorno, agente y sesión](/agenteye/images/events-stream.png) -La página **Sessions** agrupa esos eventos en una fila por ejecución. AgentEye evalúa automáticamente las sesiones completadas, de modo que cada ejecución queda puntuada y las regresiones de calidad afloran sin revisión manual; la puntuación de la última evaluación aparece en cada fila de un vistazo: +La página **Sessions** consolida esos eventos en una fila por ejecución. AgentEye evalúa automáticamente las sesiones completadas, por lo que cada ejecución queda puntuada y las regresiones de calidad son visibles sin revisión manual; la puntuación de evaluación más reciente aparece en cada fila de un vistazo: ![La lista de sesiones, una fila por ejecución, con indicadores de estado e insignias de puntuación de evaluación](/agenteye/images/sessions-list.png) Para configurar cómo se puntúan las sesiones, consulta [enterprise-docs/evaluation-suite.md](/es/agenteye/evaluation-suite). -Haz clic en cualquier sesión para abrir su **gráfico de ejecución**, una vista estilo git de cómo se desarrollaron agentes, herramientas, hooks y llamadas a modelos a lo largo del tiempo, con subagentes paralelos en sus propios carriles y un desglose por ejecución en el panel derecho: +Haz clic en cualquier sesión para abrir su **grafo de ejecución**, una vista estilo git de cómo se desplegaron agentes, herramientas, hooks y llamadas a modelos a lo largo del tiempo, con subagentes paralelos en sus propios carriles y un desglose por ejecución en el panel derecho: -![El gráfico de ejecución estilo git de una sesión junto a su línea de tiempo de eventos, con el panel de desglose de herramientas, modelos y hooks](/agenteye/images/session-detail.png) +![El grafo de ejecución estilo git de una sesión junto a su línea de tiempo de eventos, con el panel de desglose de herramientas/modelos/hooks](/agenteye/images/session-detail.png) --- -## Paso 8: Explorar, graficar y alertar +## Paso 8: Explorar, visualizar y configurar alertas -Con los eventos fluyendo, las páginas de **análisis** convierten la actividad en bruto en respuestas, para que puedas medir el comportamiento de los agentes, compartir hallazgos con el equipo y recibir notificaciones en cuanto algo regrese. Las páginas del panel están limitadas a la organización, por lo que las URL que ves en la barra de direcciones llevan el prefijo de tu slug de organización (`//…`). +Con los eventos fluyendo, las páginas de **análisis** convierten la actividad en bruto en respuestas, para que puedas medir el comportamiento de los agentes, compartir hallazgos con el equipo y recibir notificaciones en el momento en que algo regresione. Las páginas del panel tienen alcance por organización, por lo que las URL que ves en la barra de direcciones llevan el prefijo de tu slug de organización (`//…`). -- **Queries** (`//queries`): empieza desde una biblioteca de consultas guardadas y reutilizables sobre tus eventos y evaluaciones (tanto presets integrados como los tuyos propios)… +- **Queries** (`//queries`): comienza desde una biblioteca de consultas guardadas y reutilizables sobre tus eventos y evaluaciones (preajustes integrados más los tuyos)… -![La biblioteca de consultas guardadas: una cuadrícula de consultas reutilizables, tanto presets integrados como personalizadas](/agenteye/images/queries.png) +![La biblioteca de consultas guardadas: una cuadrícula de consultas reutilizables, tanto preajustes integrados como personalizadas](/agenteye/images/queries.png) …luego abre una en el compositor SQL para ajustarla y ejecutarla con resultados en tiempo real: -![El compositor de consultas SQL ejecutando una consulta guardada, con una barra lateral de esquema y una cuadrícula de resultados en tiempo real](/agenteye/images/query-lab.png) +![El compositor de consultas SQL ejecutando una consulta guardada, con una barra lateral de esquema y una cuadrícula de resultados en vivo](/agenteye/images/query-lab.png) -- **Dashboards** (`//dashboards`): ancla consultas como mosaicos de línea, barra, área o tarta en paneles compartidos con alcance de organización. +- **Dashboards** (`//dashboards`): ancla consultas como mosaicos de líneas, barras, áreas o sectores en paneles compartidos para toda la organización. -![Un panel construido a partir de consultas guardadas: una línea de eventos por hora, una barra de errores por tipo, un gráfico de área de latencia y tokens por modelo](/agenteye/images/dashboard-fleet.png) +![Un panel construido con consultas guardadas: una línea de eventos por hora, una barra de errores por tipo, un gráfico de área de latencia y tokens por modelo](/agenteye/images/dashboard-fleet.png) -- **Alerts** (`//alerts`): convierte cualquier umbral en una regla de notificación que avisa por correo electrónico, Slack, webhook o en el panel. Consulta [enterprise-docs/alerts.md](/es/agenteye/alerts). +- **Alerts** (`//alerts`): convierte cualquier umbral en una regla de notificación que avisa por email, Slack, webhook o dentro del panel. Consulta [enterprise-docs/alerts.md](/es/agenteye/alerts). --- ## Próximos pasos -- [Despliegue](/es/agenteye/deployment): refuerza para producción -- [Claves API](/es/agenteye/api-keys): gestiona el acceso -- [Solución de problemas](/es/agenteye/troubleshooting): diagnostica incidencias \ No newline at end of file +- [Despliegue](/es/agenteye/deployment): configuración robusta para producción +- [Claves API](/es/agenteye/api-keys): gestión de accesos +- [Solución de problemas](/es/agenteye/troubleshooting): diagnóstico de incidencias \ No newline at end of file diff --git a/docs/es/agenteye/managed-deployment.mdx b/docs/es/agenteye/managed-deployment.mdx index 170f170b..7bc7ccc5 100644 --- a/docs/es/agenteye/managed-deployment.mdx +++ b/docs/es/agenteye/managed-deployment.mdx @@ -3,105 +3,104 @@ title: "Despliegue Administrado en tu Clúster de Kubernetes" description: "Documentación del despliegue administrado de AgentEye en tu clúster de Kubernetes." --- +AgentEye es una plataforma de observabilidad y evaluación autoalojada para agentes de IA y LLM. Captura sesiones de agentes, llamadas a herramientas, solicitudes al modelo y errores; los convierte en analíticas y evaluaciones con capacidad de búsqueda, y presenta los resultados en un panel con un asistente de IA opcional de solo lectura. -AgentEye es una plataforma de observabilidad y evaluación autoalojada para agentes de IA y LLM. Captura sesiones de agentes, llamadas a herramientas, solicitudes a modelos y errores; los convierte en analíticas y evaluaciones con capacidad de búsqueda, y muestra los resultados en un panel con un asistente de IA opcional de solo lectura. - -En el modelo de despliegue administrado, tú proporcionas un clúster de Kubernetes dedicado y Exosphere ejecuta la plataforma completa dentro de él: despliega, configura, opera, respalda y actualiza cada componente en tu nombre. Tu equipo obtiene el valor de la plataforma (visibilidad de agentes, analíticas, evaluación y el asistente opcional) sin necesidad de operar bases de datos, certificados ni actualizaciones. Todos los datos permanecen dentro de tu cuenta de nube. +En el modelo de despliegue administrado, tú provees un clúster de Kubernetes dedicado y Exosphere ejecuta toda la plataforma dentro de él: despliega, configura, opera, hace copias de seguridad y actualiza cada componente en tu nombre. Tu equipo obtiene el valor de la plataforma (visibilidad de agentes, analíticas, evaluación y el asistente opcional) sin necesidad de gestionar bases de datos, certificados ni actualizaciones. Todos los datos permanecen dentro de tu cuenta en la nube. --- ## Requisitos previos -- Un **PAT de GitHub** para extraer imágenes de contenedor y descargar artefactos (consulta [Configuración del token de GitHub](/es/agenteye/github-token)) +- Un **PAT de GitHub** para descargar imágenes de contenedores y artefactos (consulta [enterprise-docs/github-token.md](/es/agenteye/github-token)) - Un **clúster de Kubernetes dedicado** (consulta los requisitos a continuación) - Un **bucket de almacenamiento** para copias de seguridad de bases de datos - **Conectividad de red**: puerto 443 de entrada al balanceador de carga del clúster --- -## Paso 1: Aprovisiona un Clúster de Kubernetes Dedicado +## Paso 1: Aprovisionar un Clúster de Kubernetes Dedicado -Crea un clúster de Kubernetes dedicado exclusivamente a AgentEye. No debe compartirse con otras cargas de trabajo, de modo que la plataforma completa (servicios de aplicación, bases de datos, analíticas y caché) se ejecute de forma aislada sin afectar tu infraestructura existente. +Crea un clúster de Kubernetes dedicado exclusivamente a AgentEye. No debe compartirse con otras cargas de trabajo, de modo que la plataforma completa (servicios de aplicación, bases de datos, analíticas y caché) se ejecute en aislamiento sin afectar tu infraestructura existente. | Requisito | Detalles | |---|---| -| **Distribución** | Cualquier Kubernetes conforme: EKS, GKE, AKS o autogestionado | -| **Versión** | 1.27 o superior | -| **Pool de nodos** | Mínimo: **3 nodos, 4 vCPU / 8 GB RAM cada uno** (instancias estándar de propósito general) | -| **Almacenamiento** | Una StorageClass predeterminada que aprovisione volúmenes de bloque (p. ej., `gp3` en AWS, `pd-ssd` en GCP) | +| **Distribución** | Cualquier Kubernetes conforme: EKS, GKE, AKS o autoalojado | +| **Versión** | 1.27 o posterior | +| **Pool de nodos** | Mínimo: **3 nodos, 4 vCPU / 8 GB RAM cada uno** (instancias de propósito general estándar) | +| **Almacenamiento** | Una StorageClass predeterminada que aprovisione volúmenes en bloque (p. ej. `gp3` en AWS, `pd-ssd` en GCP) | | **Balanceador de carga** | El clúster debe poder aprovisionar servicios LoadBalancer en la nube (predeterminado en EKS, GKE, AKS) | > Exosphere instala y gestiona todo lo demás dentro del clúster: controladores de ingress, certificados TLS, bases de datos, caché, monitoreo y todos los despliegues de aplicaciones. --- -## Paso 2: Otorga Acceso al Equipo de AgentEye +## Paso 2: Otorgar Acceso al Equipo de AgentEye Exosphere necesita acceso cluster-admin (o RBAC amplio equivalente) para gestionar namespaces, definiciones de recursos personalizados, controladores de ingress y aprovisionadores de almacenamiento. | Requisito | Detalles | |---|---| -| **Método de acceso** | Rol de IAM (preferido para EKS/GKE), kubeconfig o acceso basado en SSO | -| **VPN / bastión** | Si el servidor de API de Kubernetes es privado, proporciona credenciales de VPN o acceso a bastión para el equipo de operaciones de Exosphere | +| **Método de acceso** | Rol IAM (preferido para EKS/GKE), kubeconfig o acceso basado en SSO | +| **VPN / bastion** | Si el servidor de API de Kubernetes es privado, proporciona credenciales de VPN o acceso bastion para el equipo de operaciones de Exosphere | --- -## Paso 3: Configura la Conectividad de Red +## Paso 3: Configurar la Conectividad de Red -Tu equipo de red debe permitir el tráfico de entrada en el **puerto 443** hacia los balanceadores de carga del clúster. El despliegue utiliza dos balanceadores de carga separados: uno para la ingesta de eventos (protegido con mTLS) y otro para el panel: +Tu equipo de red debe permitir tráfico de entrada en el **puerto 443** hacia los balanceadores de carga del clúster. El despliegue utiliza dos balanceadores de carga separados: uno para la ingesta de eventos (protegido con mTLS) y otro para el panel: | Tráfico | Origen | Destino | Seguridad | |---|---|---|---| -| **Ingesta de eventos** | Pods del colector en tus clústeres | LoadBalancer de ingesta, puerto 443 | mTLS (certificado de cliente) + clave de API | -| **Panel** | Navegadores de desarrolladores | LoadBalancer del panel, puerto 443 | HTTPS en tu dominio, inicio de sesión sin contraseña por OTP de correo electrónico | +| **Ingesta de eventos** | Pods del colector en tus clústeres | Ingest LoadBalancer, puerto 443 | mTLS (certificado de cliente) + clave de API | +| **Panel** | Navegadores de desarrolladores | Dashboard LoadBalancer, puerto 443 | HTTPS en tu dominio, inicio de sesión OTP por correo electrónico sin contraseña | -El endpoint de ingesta está protegido por TLS mutuo; los colectores deben presentar un certificado de cliente válido **y** una clave de API válida en cada solicitud. El panel se ejecuta en su propio balanceador de carga y hostname, con el inicio de sesión restringido a las direcciones de correo electrónico/dominios que hayas permitido. +El endpoint de ingesta está protegido por TLS mutuo; los colectores deben presentar un certificado de cliente válido **y** una clave de API válida en cada solicitud. El panel se ejecuta en su propio balanceador de carga y hostname, con el inicio de sesión restringido a las direcciones de correo electrónico o dominios que incluyas en tu lista de permitidos. -**Registros DNS (una sola vez):** creas dos registros CNAME bajo un dominio que controlas — uno para el endpoint de ingesta y otro para el panel (p. ej., `agenteye.tu-empresa.ejemplo`) — apuntando a los hostnames del balanceador de carga que proporciona Exosphere. Exosphere aprovisiona entonces certificados TLS de confianza pública para ambos hostnames de forma automática, incluidas las renovaciones. +**Registros DNS (única vez):** creas dos registros CNAME bajo un dominio que controlas — uno para el endpoint de ingesta y otro para el panel (p. ej. `agenteye.tu-empresa.ejemplo`) — apuntando a los hostnames del balanceador de carga que Exosphere proporciona. Exosphere luego aprovisiona certificados TLS de confianza pública para ambos hostnames de forma automática, incluyendo las renovaciones. -> **Nota sobre el puerto 80:** la emisión y renovación automática de certificados se valida mediante HTTP en el puerto 80 de cada balanceador de carga. Si tu postura de seguridad requiere restringir el balanceador de carga del panel a rangos de IP corporativos, infórmalo a Exosphere primero — cambiamos la validación de certificados a un método basado en DNS (un registro DNS adicional de tu parte) para que las renovaciones sigan funcionando detrás de la restricción. +> **Nota sobre el puerto 80:** la emisión y renovación automática de certificados valida mediante HTTP en el puerto 80 de cada balanceador de carga. Si tu postura de seguridad requiere restringir el balanceador de carga del panel a rangos de IP corporativos, comunícaselo a Exosphere primero — cambiamos la validación de certificados a un método basado en DNS (un registro DNS adicional de tu parte) para que las renovaciones sigan funcionando detrás de la restricción. -> **Saliente:** los nodos del clúster necesitan acceso a internet para extraer imágenes de contenedor de `ghcr.io`. Si tu red restringe el tráfico saliente, incluye `ghcr.io` en la lista de permitidos o replica las imágenes en tu registro interno. +> **Saliente:** los nodos del clúster necesitan acceso a Internet para descargar imágenes de contenedores desde `ghcr.io`. Si tu red restringe el tráfico saliente, agrega `ghcr.io` a la lista de permitidos o replica las imágenes en tu registro interno. --- -## Paso 4: Proporciona un Bucket de Almacenamiento para Copias de Seguridad +## Paso 4: Proporcionar un Bucket de Almacenamiento para Copias de Seguridad -Las copias de seguridad de bases de datos se almacenan en un bucket de almacenamiento en la nube que te pertenece. +Las copias de seguridad de las bases de datos se almacenan en un bucket de almacenamiento en la nube de tu propiedad. | Requisito | Detalles | |---|---| | **Servicio** | S3 (AWS), GCS (GCP) o Azure Blob Storage | -| **Acceso** | Concede acceso de escritura a los nodos del clúster mediante rol de IAM para cuentas de servicio (IRSA en EKS, Workload Identity en GKE) o proporciona credenciales | -| **Retención** | Tú controlas la política de ciclo de vida del bucket (período de retención, reglas de archivo). Exosphere escribe las copias de seguridad; tú decides cuánto tiempo conservarlas | +| **Acceso** | Otorga acceso de escritura a los nodos del clúster mediante rol IAM para cuentas de servicio (IRSA en EKS, Workload Identity en GKE) o proporciona credenciales | +| **Retención** | Tú controlas la política de ciclo de vida del bucket (período de retención, reglas de archivado). Exosphere escribe las copias de seguridad; tú decides cuánto tiempo conservarlas | Una copia de seguridad diaria vuelca tanto PostgreSQL (estado relacional) como ClickHouse (eventos y evaluaciones) en un único archivo comprimido y lo sube a tu bucket. Las copias de seguridad también se ejecutan antes de cada actualización. --- -## Paso 5: Designa un Punto de Contacto +## Paso 5: Designar un Punto de Contacto -Proporciona una persona o un canal de Slack/Teams de tu parte para problemas a nivel de clúster: estado de los nodos, límites de cuenta en la nube, cambios de red. Las operaciones cotidianas no involucran este contacto. +Proporciona una persona o canal de Slack/Teams de tu lado para problemas a nivel de clúster: salud de nodos, límites de cuenta en la nube, cambios de red. Las operaciones del día a día no requieren involucrar a este contacto. --- ## Qué Desplegamos -Una vez que Exosphere tiene acceso al clúster, los siguientes componentes se despliegan y gestionan por ti: +Una vez que Exosphere tiene acceso al clúster, los siguientes componentes se despliegan y gestionan en tu nombre: | Componente | Función | |---|---| -| **Servidor AgentEye** | API HTTP que recibe eventos de los colectores, ejecuta analíticas y sirve datos al panel | -| **Panel** | Interfaz web para ver sesiones de agentes, llamadas a herramientas, solicitudes a modelos y errores; aloja el asistente de IA opcional de solo lectura | +| **AgentEye Server** | API HTTP que recibe eventos de los colectores, ejecuta analíticas y sirve datos al panel | +| **Dashboard** | Interfaz web para visualizar sesiones de agentes, llamadas a herramientas, solicitudes al modelo y errores; aloja el asistente de IA opcional de solo lectura | | **ClickHouse** | Almacén canónico requerido para eventos ingestados, analíticas y evaluaciones | | **PostgreSQL** | Almacén relacional para organizaciones, claves de API, usuarios, paneles y consultas guardadas | -| **Redis** | Caché compartida opcional y backend de límite de velocidad; la plataforma se degrada de forma controlada si no está disponible | -| **Asistente de IA (opcional)** | Contenedor de asistente interno de solo lectura; permanece deshabilitado hasta que se configure un endpoint de LLM | -| **Controladores de ingress** | Dos balanceadores de carga (uno para ingesta protegida con mTLS, otro para el panel) que terminan TLS con certificados de confianza pública y renovación automática, y aplican mTLS en el endpoint de ingesta | +| **Redis** | Caché compartida opcional y backend de límite de tasa; la plataforma degrada de forma elegante si no está disponible | +| **Asistente de IA (opcional)** | Contenedor de asistente interno de solo lectura; permanece deshabilitado hasta que se configure un endpoint LLM | +| **Controladores de ingress** | Dos balanceadores de carga (uno para ingesta protegida con mTLS, otro para el panel) que terminan TLS con certificados de confianza pública y renovación automática, e imponen mTLS en el endpoint de ingesta | | **cert-manager** | Automatiza el aprovisionamiento de certificados TLS y la emisión de certificados de cliente mTLS | -| **Monitoreo de certificados** | Un trabajo programado verifica la expiración de certificados y envía alertas (p. ej., a Slack) cuando los certificados se acercan a la renovación | +| **Monitoreo de certificados** | Un job programado verifica el vencimiento de certificados y envía alertas (p. ej. a Slack) cuando los certificados se aproximan a la renovación | -La oferta administrada también opera el pipeline de evaluación de la plataforma, que puntúa la actividad de los agentes según tus criterios de evaluación. Consulta [Asistente](/es/agenteye/assistant) y [Suite de Evaluación](/es/agenteye/evaluation-suite) para conocer qué ofrecen estas capacidades. +La oferta administrada también opera el pipeline de evaluación de la plataforma, que puntúa la actividad de los agentes según tus criterios de evaluación. Consulta [enterprise-docs/assistant.md](/es/agenteye/assistant) y [enterprise-docs/evaluation-suite.md](/es/agenteye/evaluation-suite) para conocer lo que estas capacidades ofrecen. --- @@ -111,9 +110,9 @@ Una vez completado el despliegue, recibes: | Elemento | Detalles | |---|---| -| **URL del panel** | Un hostname bajo tu dominio (p. ej., `https://agenteye.tu-empresa.ejemplo`), servido con un certificado TLS de confianza pública y renovación automática. Creas un CNAME hacia el hostname del balanceador de carga que proporcionamos; el inicio de sesión es sin contraseña por OTP de correo electrónico | -| **Endpoint del colector** | La ruta `/events` del hostname de ingesta (p. ej., `https://ingest.tu-empresa.ejemplo/events`), protegido con mTLS | -| **Bundle de certificado de cliente** | Por clúster: certificado de cliente, clave privada y certificado de CA entregados como un manifiesto de Secret de Kubernetes. Aplícalo una vez por clúster | +| **URL del panel** | Un hostname bajo tu dominio (p. ej. `https://agenteye.tu-empresa.ejemplo`), servido con un certificado TLS de confianza pública y renovación automática. Creas un CNAME al hostname del balanceador de carga que proporcionamos; el inicio de sesión es OTP por correo electrónico sin contraseña | +| **Endpoint del colector** | La ruta `/events` del hostname de ingesta (p. ej. `https://ingest.tu-empresa.ejemplo/events`), protegida con mTLS | +| **Bundle de certificado de cliente** | Por clúster: certificado de cliente, clave privada y certificado CA entregados como un manifiesto de Kubernetes Secret. Se aplica una vez por clúster | | **PAT de GitHub** | Para descargar binarios del colector y paquetes del SDK de Python | | **Claves de API del colector** | Claves con alcance y permiso `events:add`, una por despliegue de colector | | **Guías de instalación** | Documentación paso a paso para el colector y el SDK de Python | @@ -124,8 +123,8 @@ Una vez completado el despliegue, recibes: Tu único trabajo continuo es en tus propias máquinas de agentes, no en el clúster de AgentEye: -1. **Instala el colector** en cada clúster de Kubernetes que ejecute agentes de IA: monta el certificado de cliente y configura la URL del endpoint y la clave de API. Consulta [Instalación del Colector](/es/agenteye/collector-installation). -2. **Integra el SDK de Python** en el código de tu agente. Consulta [SDK de Python](/es/agenteye/python-sdk). +1. **Instala el colector** en cada clúster de Kubernetes que ejecute agentes de IA: monta el certificado de cliente y configura la URL del endpoint y la clave de API. Consulta [enterprise-docs/collector-installation.md](/es/agenteye/collector-installation). +2. **Integra el SDK de Python** en el código de tu agente. Consulta [enterprise-docs/python-sdk.md](/es/agenteye/python-sdk). 3. **Abre el panel** en tu navegador para ver la actividad de los agentes. Sin operaciones de clúster, sin gestión de bases de datos, sin renovaciones de certificados, sin actualizaciones. @@ -134,10 +133,10 @@ Sin operaciones de clúster, sin gestión de bases de datos, sin renovaciones de ## Seguridad -- **Los datos permanecen en tu cuenta de nube.** El clúster, el almacenamiento y las bases de datos se ejecutan en tu entorno. Ningún dato sale de tu perímetro. -- **Tú controlas el acceso.** El clúster está en tu cuenta. Puedes auditar, monitorear o revocar el acceso de Exosphere en cualquier momento. Todas las operaciones pasan por el registro de auditoría de tu nube (CloudTrail, GCP Audit Logs, etc.). +- **Los datos permanecen en tu cuenta en la nube.** El clúster, el almacenamiento y las bases de datos se ejecutan en tu entorno. Ningún dato sale de tu perímetro. +- **Tú controlas el acceso.** El clúster está en tu cuenta. Puedes auditar, monitorear o revocar el acceso de Exosphere en cualquier momento. Todas las operaciones quedan registradas en el log de auditoría de tu nube (CloudTrail, GCP Audit Logs, etc.). - **mTLS en la ingesta de eventos.** Cada solicitud del colector requiere tanto un certificado de cliente válido como una clave de API. Una clave filtrada es inútil sin el certificado; un certificado robado es inútil sin una clave válida. -- **Control de acceso al panel.** El panel se ejecuta en su propio balanceador de carga, separado de la ingesta de eventos, y el inicio de sesión es sin contraseña por OTP de correo electrónico, restringido a las direcciones de correo electrónico/dominios que hayas permitido. Una lista de rangos de IP de origen permitidos en el balanceador de carga está disponible bajo solicitud; dado que la renovación automática de certificados debe alcanzar el balanceador de carga, Exosphere combina la restricción con la validación de certificados basada en DNS para que las renovaciones sigan funcionando. +- **Control de acceso al panel.** El panel se ejecuta en su propio balanceador de carga, separado de la ingesta de eventos, y el inicio de sesión es OTP por correo electrónico sin contraseña, restringido a las direcciones de correo electrónico o dominios que incluyas en tu lista de permitidos. Una lista de rangos de IP de origen permitidos en el balanceador de carga está disponible bajo solicitud; dado que la renovación automática de certificados debe llegar al balanceador de carga, Exosphere combina la restricción con validación de certificados basada en DNS para que las renovaciones sigan funcionando. - **Certificados por clúster.** Cada uno de tus clústeres recibe su propio certificado de cliente. Si un clúster se ve comprometido, ese certificado se revoca de forma independiente sin afectar a los demás. --- @@ -146,10 +145,10 @@ Sin operaciones de clúster, sin gestión de bases de datos, sin renovaciones de | Fase | Duración | Tu participación | |---|---|---| -| **Aprovisionamiento del clúster** | 1-2 días | Aprovisionar el clúster y conceder acceso a Exosphere | +| **Aprovisionamiento del clúster** | 1-2 días | Aprovisionar el clúster y otorgar acceso a Exosphere | | **Configuración de la plataforma** | 1 día | Ninguna; Exosphere instala todos los componentes de infraestructura | | **Despliegue de la aplicación** | 1 día | Ninguna; Exosphere despliega el servidor, el panel y crea las claves de API | -| **Despliegue del colector** | 1-3 días | Instalar colectores en tus clústeres (con orientación de Exosphere) | +| **Instalación del colector** | 1-3 días | Instalar los colectores en tus clústeres (con orientación de Exosphere) | | **Rodaje en producción** | 1 semana | Ninguna; Exosphere monitorea y ajusta | Total típico: **~2 semanas** desde el inicio hasta producción lista. @@ -164,8 +163,8 @@ Para preguntas o problemas, contacta a Exosphere en `support@exosphere.host`. ## Próximos Pasos -- [Primeros Pasos](/es/agenteye/getting-started): recorrido completo de extremo a extremo -- [Instalación del Colector](/es/agenteye/collector-installation): instalar y configurar el colector +- [Primeros pasos](/es/agenteye/getting-started): recorrido completo de extremo a extremo +- [Instalación del colector](/es/agenteye/collector-installation): instalar y configurar el colector - [SDK de Python](/es/agenteye/python-sdk): instrumentar el código de tu agente -- [Claves de API](/es/agenteye/api-keys): gestionar acceso y permisos -- [Solución de Problemas](/es/agenteye/troubleshooting): problemas comunes y soluciones \ No newline at end of file +- [Claves de API](/es/agenteye/api-keys): gestionar accesos y permisos +- [Solución de problemas](/es/agenteye/troubleshooting): problemas comunes y soluciones \ No newline at end of file diff --git a/docs/fr/agenteye/audits.mdx b/docs/fr/agenteye/audits.mdx index f062990c..b8f12951 100644 --- a/docs/fr/agenteye/audits.mdx +++ b/docs/fr/agenteye/audits.mdx @@ -1,107 +1,106 @@ --- -title: "Audits — détection des améliorations agentiques" -description: "AgentEye Audits — documentation sur la détection des améliorations agentiques." +title: "Audits — détection proactive d'améliorations" +description: "AgentEye Audits — documentation sur la détection proactive d'améliorations." --- -Les audits sont des tâches récurrentes qui explorent vos journaux d'agent **entre les sessions** pour identifier ce qui mérite d'être amélioré. Là où une alerte surveille une métrique que vous connaissez déjà en quasi-temps réel, un audit *enquête* : selon un calendrier que vous définissez, il effectue un contrôle de politique déterministe sur la fenêtre temporelle, puis confie vos sessions à un **agent de fiabilité IA** — cet agent interroge les données lui-même, lit les transcriptions suspectes, et (si nécessaire) exécute de petits scripts d'analyse, avant de rédiger des **recommandations d'amélioration** accompagnées des preuves correspondantes. +Les audits sont des tâches récurrentes qui analysent vos journaux d'agent **à travers les sessions** pour identifier ce qui mérite d'être amélioré. Là où une alerte surveille en quasi-temps réel une métrique que vous connaissez déjà, un audit *enquête* : selon un calendrier que vous définissez, il effectue un contrôle de politiques déterministe sur la fenêtre temporelle, puis confie vos sessions à un **agent de fiabilité IA** — l'agent interroge les données lui-même, lit les transcriptions suspectes et (si besoin) exécute de petits scripts d'analyse, avant de rédiger des **recommandations d'amélioration** avec les preuves à l'appui. -Utilisez les audits pour répondre à la question « que dois-je corriger ou améliorer dans mes agents ? » — et les alertes pour être notifié dès qu'un seuil précis est franchi. Chaque amélioration renvoie aux sessions et requêtes exactes qui la sous-tendent, et un seul clic crée une alerte préremplie pour détecter les récurrences. +Utilisez les audits pour répondre à la question « que dois-je corriger ou améliorer dans mes agents ? » — et les alertes pour être notifié dès qu'un seuil précis est franchi. Chaque amélioration renvoie aux sessions et requêtes exactes qui la sous-tendent, et un seul clic crée une alerte préremplie pour intercepter les récurrences. -La surface du tableau de bord est **`//audits`** (barre latérale → *analyze* → *audits*), soumise aux permissions `audits:read` / `audits:write`. +L'interface du tableau de bord est accessible via **`//audits`** (barre latérale → *analyser* → *audits*), conditionnée par les permissions `audits:read` / `audits:write`. --- -## Fonctionnement d'une exécution +## Déroulement d'une exécution Chaque exécution comporte deux couches : un socle déterministe et une investigation agentique. -### 1. Le contrôle de politique (déterministe) +### 1. Le contrôle de politiques (déterministe) -Avant tout démarrage du modèle, l'audit exécute un petit catalogue de **vérifications SQL par politique** sur la fenêtre : des requêtes agrégées bornées qui signalent les patterns problématiques connus et indiquent *combien* d'événements / *quelles* sessions correspondent — jamais le texte correspondant lui-même. Le catalogue comprend : +Avant l'exécution de tout modèle, l'audit lance un ensemble de **contrôles SQL par politiques** sur la fenêtre : des requêtes agrégées délimitées qui signalent les patterns problématiques connus et indiquent *combien* d'événements / *quelles* sessions ont correspondu — jamais le texte correspondant lui-même. Le catalogue inclut : -- **Fuite de secrets / identifiants** dans les charges utiles d'événements — clés d'accès AWS, clés API `sk-…`, clés privées PEM, tokens JWT / bearer, et assignations d'identifiants `KEY=…`. -- **Marqueurs d'injection de prompt** — « ignore previous instructions », « reveal your system prompt », et similaires. +- **Fuites de secrets / identifiants** dans les charges utiles d'événements — clés d'accès AWS, clés API `sk-…`, clés privées PEM, tokens JWT / bearer et assignations de type `KEY=…`. +- **Marqueurs d'injection de prompt** — « ignore previous instructions », « reveal your system prompt » et formulations similaires. - **Données personnelles (PII)** — numéros au format SSN (heuristique). -- **Refus de permission d'outil** et **boucles de cycles d'appels d'outils incontrôlées**. +- **Refus de permission d'outil** et **boucles de dépassement d'appels d'outils**. -Les correspondances de politique sont persistées comme résultats (type `policy`) qui **s'affichent toujours** (ils ne sont jamais écrêtés par le plafond par exécution), et ils sont transmis à l'agent IA comme points de départ. Cette couche ne nécessitant aucun modèle, un audit produit ses signaux de sécurité les plus importants même si l'agent IA est indisponible. +Les correspondances de politiques sont persistées en tant que résultats (type `policy`) qui **apparaissent toujours** (ils ne sont jamais écrêtés par le plafond par exécution), et sont transmis à l'agent IA comme pistes de départ. Cette couche ne nécessitant aucun modèle, un audit produit ses signaux de sécurité les plus importants même si l'agent IA est indisponible. ### 2. L'investigation agentique (IA) -L'audit lance ensuite un **agent de fiabilité autonome** (le même service Claude Agent SDK qui alimente l'assistant du tableau de bord, avec un prompt spécifique à l'audit). Compte tenu du **périmètre** de l'audit (agents sélectionnés × environnements) et de la **fenêtre temporelle**, l'agent : +L'audit lance ensuite un **agent de fiabilité autonome** (le même service Claude Agent SDK qui alimente l'assistant du tableau de bord, avec un prompt spécifique aux audits). Compte tenu du **périmètre** de l'audit (agents sélectionnés × environnements) et de la **fenêtre temporelle**, l'agent : -- exécute des requêtes SQL en lecture seule sur vos tables analytiques, +- exécute des requêtes SQL en lecture seule sur vos tables d'analytique, - lit quelques transcriptions de sessions représentatives, -- écrit et exécute optionnellement de courts **scripts Python dans un bac à sable isolé en pod** (pas de réseau, pas d'accès au système de fichiers, secrets supprimés) pour des analyses que SQL ne peut pas exprimer — regroupement d'erreurs, calcul de distributions, parcours des charges utiles déjà récupérées, -- et enregistre chaque **amélioration** bien étayée qu'il découvre. +- rédige et exécute optionnellement de courts **scripts Python dans un sandbox isolé en pod** (sans réseau, sans accès au système de fichiers, secrets supprimés) pour les analyses que SQL ne peut pas exprimer — regroupement d'erreurs, calcul de distributions, balayage des charges utiles déjà récupérées, +- et consigne chaque **amélioration** bien étayée qu'il découvre. -Il explore plusieurs axes d'investigation — regroupement d'erreurs, dérive par rapport à une référence, échec d'objectif dans les transcriptions, mauvaise utilisation des outils, compromis qualité/coût, et lacunes de couverture — selon la **sensibilité** de l'audit (faible / moyenne / élevée). Chaque amélioration **doit citer des preuves** : les identifiants de session que l'agent a réellement inspectés et/ou le SQL qu'il a exécuté. Le serveur vérifie que les sessions citées existent et **écarte toute amélioration sans preuve valide**, de sorte que l'agent enquête sans jamais inventer. +Il explore plusieurs axes d'investigation — regroupement d'erreurs, dérive par rapport à une référence, échecs d'objectifs dans les transcriptions, mauvaise utilisation des outils, compromis qualité/coût et lacunes de couverture — selon la **sensibilité** de l'audit (faible / moyenne / élevée). Chaque amélioration **doit citer des preuves** : les identifiants de session que l'agent a réellement inspectés et/ou le SQL qu'il a exécuté. Le serveur vérifie que les sessions citées existent et **rejette toute amélioration sans preuve subsistante**, ainsi l'agent enquête sans jamais inventer. Chaque amélioration comporte : -- une **recommandation** (le changement concret à apporter — une modification de prompt, une correction de schéma d'outil, une politique de réessai, un garde-fou, une meilleure couverture d'évaluation), +- une **recommandation** (la modification concrète à apporter — un ajustement de prompt, une correction de schéma d'outil, une politique de réessai, un garde-fou, une couverture d'évaluation accrue), - un **impact attendu** et une estimation de l'**effort** (faible / moyen / élevé), -- une **magnitude** — `big` (un opérateur doit être alerté), `medium` (appartient au rapport d'exécution), ou `small` (contexte du tableau de bord), -- une **empreinte** stable (issue de la catégorie et du périmètre du problème, *pas* des sessions de cette exécution) pour que le même problème soit suivi d'exécution en exécution même si les preuves changent, -- et, lorsqu'un observateur déterministe simple pourrait détecter les récurrences, une **alerte suggérée** que vous pouvez créer en un clic. +- une **magnitude** — `big` (un opérateur devrait être notifié), `medium` (à inclure dans le rapport d'exécution) ou `small` (contexte du tableau de bord), +- une **empreinte** stable (dérivée de la catégorie et du périmètre du problème, *pas* des sessions de cette exécution) permettant de suivre le même problème d'une exécution à l'autre même si les preuves changent, +- et, lorsqu'un observateur déterministe simple pourrait détecter une récurrence, une **alerte suggérée** créable en un seul clic. -> **La couche IA est optionnelle mais recommandée.** Si aucun agent IA n'est configuré pour le pipeline d'audit, les exécutions se déroulent quand même, les résultats de politique sont persistés, et le rapport indique honnêtement « analyse indisponible » pour la couche agentique plutôt que de passer silencieusement. +> **La couche IA est optionnelle mais recommandée.** Si aucun agent IA n'est configuré pour le pipeline d'audits, les exécutions se déroulent quand même, persistent les résultats de politiques, et signalent honnêtement « analyse indisponible » pour la couche agentique plutôt que de passer silencieusement. ### Modes d'échec -Les améliorations se classent dans le **catalogue de modes d'échec** durable de votre organisation (ou proposent un nouveau mode). Les modes donnent aux patterns une identité stable entre les exécutions et permettent un suivi des récurrences sur le long terme. +Les améliorations sont classées dans le **catalogue de modes d'échec** durable de votre organisation (ou proposent un nouveau mode). Les modes confèrent aux patterns une identité stable à travers les exécutions et permettent un suivi des récurrences sur le long terme. ## Cycle de triage -Sur une page de résultat (`/audits//findings/`) : +Sur la page d'un résultat (`/audits//findings/`) : | Action | Effet | |---|---| | **acknowledge** | Garde le résultat visible mais divise sa priorité par deux. | -| **resolve** | Le marque comme corrigé. Si le pattern réapparaît plus tard, il se rouvre comme **nouveau** — une régression est donc visible, pas silencieusement noyée dans l'historique. | -| **mute** / **dismiss** | Suppression durable : l'empreinte du pattern est mémorisée et ne s'affiche plus jamais, même entre les exécutions. Utilisez mute pour « connu, accepté » ; dismiss pour « non utile ». | -| **reopen** | Efface la suppression / résolution et classe de nouveau le pattern. | -| **assign** | Confie le résultat à un opérateur (un membre de l'organisation) pour en assumer la responsabilité. La priorité et l'état de suppression restent inchangés. | +| **resolve** | Le marque comme corrigé. Si le pattern réapparaît réellement par la suite, il se rouvre en tant que **new** — une régression est ainsi signalée clairement, sans être silencieusement fondue dans l'historique. | +| **mute** / **dismiss** | Suppression durable : l'empreinte du pattern est mémorisée et ne remonte plus jamais, même entre les exécutions. Utilisez mute pour « connu, accepté » ; dismiss pour « non pertinent ». | +| **reopen** | Lève la suppression / résolution et remet le pattern dans le classement. | -Le bruit à faible signal est contrôlé par audit avec un plafond de résultats par exécution (`top_k`) sur les améliorations agentiques. Les résultats de politique contournent ce plafond (ils sont pertinents pour la sécurité et toujours affichés). Tout ce qui est écrêté par le plafond est comptabilisé dans les statistiques de l'exécution — rien n'est silencieusement supprimé. +Le bruit à faible signal est contrôlé par audit via un plafond de résultats par exécution (`top_k`) sur les améliorations agentiques. Les résultats de politiques contournent ce plafond (ils sont pertinents pour la sécurité et toujours affichés). Tout ce qui est écrêté par le plafond est comptabilisé dans les statistiques de l'exécution — rien n'est supprimé silencieusement. ## Planification -- **Cadence** (`schedule_interval_secs`) : de toutes les heures à une fois par semaine ; **quotidien par défaut**. Les audits sont délibérément plus grossiers que les alertes — une investigation agentique analyse des fenêtres entières et s'exécute pendant plusieurs minutes. -- **Fenêtre** : soit un historique glissant fixe (p. ex. « chaque exécution analyse les 7 derniers jours »), soit **depuis la dernière exécution** (par défaut) — chaque exécution reprend là où la précédente réussie s'est arrêtée, avec un léger chevauchement pour ne jamais manquer les événements en limite de fenêtre. -- La prochaine exécution est planifiée un intervalle complet après la **fin** de la précédente, de sorte qu'une exécution lente ne provoque jamais une deuxième exécution concurrente du même audit. -- **Run now** sur la page d'audit la déclenche immédiatement. +- **Cadence** (`schedule_interval_secs`) : de toutes les heures à une fois par semaine ; **quotidien par défaut**. Les audits sont délibérément moins fréquents que les alertes — une investigation agentique analyse des fenêtres entières et s'exécute pendant plusieurs minutes. +- **Fenêtre** : soit un lookback glissant fixe (p. ex. « chaque exécution analyse les 7 derniers jours »), soit **depuis la dernière exécution** (par défaut) — chaque exécution reprend là où la précédente réussie s'est terminée, avec un léger chevauchement pour ne jamais manquer les événements en limite. +- La prochaine exécution est planifiée un intervalle complet après la **fin** de la précédente, de sorte qu'une exécution lente n'empile jamais une seconde exécution concurrente du même audit. +- **Exécuter maintenant** sur la page de l'audit la rend immédiatement due. ## Sélection du modèle -Lors de la création d'un audit, vous pouvez choisir le modèle utilisé pour l'investigation, parmi la **liste des modèles que votre opérateur a configurés** pour le service d'agent. Avec un seul modèle configuré, le sélecteur l'affiche en légende ; avec plusieurs, vous choisissez. Laisser le champ vide utilise le modèle par défaut configuré. +Lors de la création d'un audit, vous pouvez choisir le modèle utilisé par l'investigation parmi la **liste des modèles configurés par votre opérateur** pour le service d'agent. Avec un seul modèle configuré, le sélecteur l'affiche en légende ; avec plusieurs, vous choisissez. Laisser ce champ vide utilise le modèle par défaut configuré. ## Notifications -Lorsqu'une exécution fait apparaître de **nouveaux** résultats, l'audit notifie les canaux configurés de votre organisation — le même portail `alerts.enabled_channels` et les mêmes paramètres que ceux utilisés par le pipeline d'alertes : +Lorsqu'une exécution remonte de **nouveaux** résultats, l'audit notifie les canaux configurés de votre organisation — la même porte `alerts.enabled_channels` et les mêmes paramètres qu'utilise le pipeline d'alertes : - **Slack** — un résumé des nouveaux éléments significatifs (`big`) avec un lien direct. -- **Email** — un **rapport d'audit** structuré listant les nouvelles améliorations (gravité maximale, recommandations par élément, lien direct), envoyé lorsque l'audit dispose d'un canal **email** et qu'il y a au moins un nouveau résultat. +- **Email** — un **rapport d'audit** structuré listant les nouvelles améliorations (par gravité décroissante, recommandations par élément, lien direct), envoyé lorsque l'audit dispose d'un canal **email** associé et qu'il y a au moins un nouveau résultat. -Les résultats récurrents mais déjà connus ne génèrent pas de nouvelle notification. +Les résultats récurrents mais connus ne génèrent pas de nouvelle notification. ## Référence de configuration -Les définitions d'audit sont gérées dans le tableau de bord (`/audits/new`) ou via l'API. Les paramètres par audit comprennent la cadence et la fenêtre de planification, le périmètre (`{"environments": [...], "agent_ids": [...]}`), la sensibilité (`low` / `medium` / `high`), les canaux de notification, le plafond de résultats par exécution (`top_k`), et le modèle (via `llm_budget.model`). Les paramètres serveur au niveau de l'opérateur (délais d'attente, bac à sable, URL du service d'agent) sont documentés dans [deployment.md](/fr/agenteye/deployment). +Les définitions d'audit sont gérées dans le tableau de bord (`/audits/new`) ou via l'API. Les paramètres par audit incluent la cadence et la fenêtre de planification, le périmètre (`{"environments": [...], "agent_ids": [...]}`), la sensibilité (`low` / `medium` / `high`), les canaux de notification, le plafond de résultats par exécution (`top_k`) et le modèle (via `llm_budget.model`). Les paramètres serveur au niveau opérateur (délais d'expiration, sandbox, URL du service d'agent) sont documentés dans [deployment.md](/fr/agenteye/deployment). ## API Tous les endpoints sont limités à l'organisation et suivent l'authentification standard par clé bearer (voir [api-keys.md](/fr/agenteye/api-keys)). -| Endpoint | Permission | Objectif | +| Endpoint | Permission | Objet | |---|---|---| | `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | Lister / créer des définitions d'audit. | | `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Consulter, modifier, supprimer un audit. | -| `POST /audits/:id/run` | `audits:write` | Déclencher l'audit immédiatement. | +| `POST /audits/:id/run` | `audits:write` | Rendre l'audit immédiatement dû. | | `GET /audits/:id/runs` | `audits:read` | Historique des exécutions (fenêtre, statut, statistiques, nombre de résultats). | | `GET /audits/findings` | `audits:read` | Résultats à l'échelle de l'organisation, filtrables par `audit_id`, `status` ; triés par priorité. | -| `GET /audits/findings/:fid` | `audits:read` | Détail complet du résultat (recommandation, preuves, priorité). | +| `GET /audits/findings/:fid` | `audits:read` | Détail complet d'un résultat (recommandation, preuves, priorité). | | `POST /audits/findings/:fid/status` | `audits:write` | Triage : `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | -Pour les cas « l'audit s'est exécuté mais n'a rien trouvé », « le bac à sable de code est désactivé » et « l'email d'audit n'a pas été livré », consultez [troubleshooting.md](/fr/agenteye/troubleshooting#audits). \ No newline at end of file +Pour les cas « l'audit s'est exécuté mais n'a rien trouvé », « le sandbox de code est désactivé » et « l'email d'audit n'a pas été délivré », consultez [troubleshooting.md](/fr/agenteye/troubleshooting#audits). \ No newline at end of file diff --git a/docs/fr/agenteye/cli-recipes.mdx b/docs/fr/agenteye/cli-recipes.mdx index e8c44782..0cb42471 100644 --- a/docs/fr/agenteye/cli-recipes.mdx +++ b/docs/fr/agenteye/cli-recipes.mdx @@ -1,62 +1,61 @@ --- -title: "Recettes CLI pour les agents" -description: "Documentation des recettes CLI AgentEye pour les agents." +title: "Recettes CLI pour agents" +description: "Documentation des recettes CLI AgentEye pour agents." --- +Récupérez les données de sessions, d'événements et d'évaluations (et déclenchez des réévaluations) directement depuis un script ou un agent de code, avec du JSON propre sur stdout qui s'enchaîne directement avec `jq`. Ces recettes transforment les données d'observabilité d'AgentEye en quelque chose qu'un utilisateur de terminal ou un agent de code IA (Claude Code, Cursor) peut interroger et automatiser, sans passer par le tableau de bord. -Récupérez les données de sessions, d'événements et d'évaluations (et déclenchez des réévaluations) directement depuis un script ou un agent de codage, avec du JSON propre sur stdout qui se connecte directement à `jq`. Ces recettes transforment les données d'observabilité d'AgentEye en quelque chose qu'un utilisateur en ligne de commande ou un agent de codage IA (Claude Code, Cursor) peut interroger et automatiser, sans avoir à naviguer dans le tableau de bord. - -Les patterns ci-dessous sont prêts à être copiés-collés pour le CLI AgentEye (`agenteye`). Pour l'installation, l'authentification et la liste complète des options, consultez [CLI](/fr/agenteye/cli) ; exécutez `agenteye -h` ou `agenteye -h` pour l'aide intégrée. +Les patterns ci-dessous sont prêts à copier-coller pour le CLI AgentEye (`agenteye`). Pour l'installation, l'authentification et la liste complète des options, consultez [CLI](/fr/agenteye/cli) ; lancez `agenteye -h` ou `agenteye -h` pour l'aide intégrée. ## Règles d'or 1. **Les options globales se placent *avant* la commande.** `agenteye --json sessions` est correct ; `agenteye sessions --json` ne l'est pas. Les options globales sont `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Passez `--json` dès que vous analysez la sortie.** Les données vont sur **stdout** au format JSON ; les statuts lisibles et les erreurs vont sur **stderr**, ce qui permet à stdout de rester propre pour être connecté à `jq`. -3. **Basez-vous sur le code de sortie**, pas sur le texte de stderr : `0` ok · `2` arguments incorrects · `3` impossible d'atteindre le tableau de bord · `4` non connecté ou session expirée · `5` permission manquante. +2. **Passez `--json` dès que vous analysez la sortie.** Les données vont sur **stdout** en JSON ; les statuts humains et les erreurs vont sur **stderr**, ce qui permet à stdout de rester propre pour être redirigé vers `jq`. +3. **Branchez-vous sur le code de sortie**, pas sur le texte de stderr : `0` ok · `2` arguments invalides · `3` impossible de joindre le tableau de bord · `4` non connecté ou session expirée · `5` permission manquante. 4. **Explorez avec `-h`.** Chaque commande documente ses filtres, formats de valeurs et structure JSON. ## Configuration initiale ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # pour éviter de répéter --base-url -agenteye login --email you@example.com # collez le code reçu par e-mail ; valide ~24h +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # pour ne pas répéter --base-url +agenteye login --email you@example.com # collez le code reçu par e-mail ; valable ~24h ``` -## Vérifier l'authentification avant de travailler +## Vérifier l'authentification avant d'agir -`whoami` ne génère jamais d'erreur en cas de session manquante ou expirée ; il renvoie `logged_in:false` à la place, permettant à un agent de sonder l'état d'authentification en toute sécurité. (Il peut quand même se terminer avec un code non nul si aucune URL de base n'est définie ou si le tableau de bord est inaccessible.) +`whoami` ne retourne jamais d'erreur pour une session manquante ou expirée ; il rapporte `logged_in:false` à la place, ce qui permet à un agent de tester l'état d'authentification en toute sécurité. (Il peut quand même sortir avec un code non nul si aucune URL de base n'est définie ou si le tableau de bord est inaccessible.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then - echo "Not authenticated. Run: agenteye login" >&2; exit 1 + echo "Non authentifié. Lancez : agenteye login" >&2; exit 1 fi ``` -## Trouver les sessions en échec ou à faible score +## Trouver les sessions en échec ou mal notées ```bash -# sessions des dernières 24h dont l'évaluation a échoué +# sessions des dernières 24h dont l'évaluation est en erreur agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# évaluations avec un score helpfulness <= 0.5, pour un agent spécifique +# évaluations avec un score helpfulness <= 0.5, pour un agent donné agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -Le filtrage par score s'effectue sur **`evals`**, pas sur `sessions`. `--score KEY:MIN..MAX` est répétable et combiné en AND ; chaque borne est optionnelle (`..0.5` signifie ≤ 0.5, `0.9..` signifie ≥ 0.9). Vous pouvez passer jusqu'à 20 filtres de score par requête ; au-delà, une erreur HTTP 400 est renvoyée. `sessions` partage les filtres `--env`, `--status`, `--agent-id`, `--session-id` et les plages temporelles avec `evals`, mais ne dispose pas de `--score`. +Le filtrage par score s'applique à **`evals`**, pas à `sessions`. `--score KEY:MIN..MAX` est répétable et combiné en AND ; chaque borne est optionnelle (`..0.5` signifie ≤ 0.5, `0.9..` signifie ≥ 0.9). Vous pouvez passer jusqu'à 20 filtres de score par requête ; au-delà, la réponse est HTTP 400. `sessions` partage les filtres `--env`, `--status`, `--agent-id`, `--session-id` et de plage temporelle avec `evals`, mais n'a pas de `--score`. ## Lire une session de bout en bout -Il n'existe pas de commande unique `session show` — combinez la trace d'événements avec l'évaluation de la session : +Il n'existe pas de commande unique `session show` — combinez le journal d'événements avec l'évaluation de la session : ```bash -# la dernière évaluation de la session (statut + scores) +# dernière évaluation de la session (statut + scores) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# tous les événements du run (augmentez --limit pour un parcours complet) +# tous les événements de l'exécution (augmentez --limit pour un parcours complet) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# uniquement les appels d'outils d'une session +# uniquement les appels d'outils dans une session agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` @@ -66,10 +65,10 @@ agenteye --json events --session-id run-001 --event-type tool_use,tool_result -- Les résultats sont triés du plus récent au plus ancien et paginés par curseur. ```bash -# en une fois : récupère jusqu'à 500 lignes en pages de 200 lignes +# en une seule fois : récupère jusqu'à 500 lignes en pages de 200 agenteye --json events --session-id run-001 --limit 500 --all > events.json -# pagination manuelle : réinjectez next_cursor +# pagination manuelle : réinjecter next_cursor page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" @@ -77,14 +76,14 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') ## Réduire la sortie avec --fields -Limitez les clés (aussi bien dans le tableau que dans `--json`) pour réduire ce qu'un agent doit lire. +Restreignez les clés (dans le tableau et avec `--json`) pour limiter ce qu'un agent doit lire. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Les noms de champs inconnus sont rejetés (sortie `2`) avec la liste des noms valides, un moyen pratique de découvrir les noms de champs. +Les noms de champs inconnus sont rejetés (sortie `2`) avec la liste valide, un moyen pratique de découvrir les noms de champs. ## Découvrir les valeurs de filtre valides @@ -94,43 +93,43 @@ agenteye --json list tools | jq -r '.values[]' # noms d'outils ; aussi agenteye --json list score_filters | jq -r '.values[]' # KEY valide pour --score KEY:MIN..MAX ``` -## Choisir votre organisation (multi-tenant) +## Choisir son organisation (multi-tenant) -Si vous appartenez à plusieurs organisations, choisissez le tenant actif lors de la connexion (il est sauvegardé) : +Si vous appartenez à plusieurs organisations, choisissez le tenant actif à la connexion (il est sauvegardé) : ```bash agenteye login --org acme --email you@corp.com # définir le tenant en même temps que la connexion agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # remplacer pour une seule commande +agenteye --org globex --json sessions --since 24h # remplacement pour une seule commande ``` -Une connexion multi-org sans `--org` se termine avec un code non nul et affiche les organisations parmi lesquelles choisir. +Une connexion multi-org sans `--org` sort avec un code non nul et affiche les organisations parmi lesquelles choisir. ## Créer une clé API pour le SDK/collecteur ```bash -# le secret est affiché UNE SEULE FOIS — avec --json c'est le champ .key +# le secret est affiché UNE SEULE FOIS — avec --json, c'est le champ .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # rotation ; agenteye keys disable ci-bot --yes pour révoquer ``` -## Exécuter une requête sauvegardée ou ad-hoc +## Exécuter une requête sauvegardée ou ad hoc ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # une requête sauvegardée + un argument positionnel $1 +agenteye --json query run errs --arg prod | jq '.rows' # une requête sauvegardée + un $1 positionnel ``` -## Gérer un incident de manière non interactive +## Gérer un incident sans interaction ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> Les mutations ignorent automatiquement leur invite de confirmation sous `--json` ou lorsque stdin n'est pas un TTY, de sorte que les agents ne se bloquent jamais ; passez `--yes`/`-y` pour l'ignorer explicitement ailleurs. +> Les mutations ignorent automatiquement leur invite de confirmation sous `--json` ou lorsque stdin n'est pas un TTY, de sorte que les agents ne restent jamais bloqués ; passez `--yes`/`-y` pour l'ignorer explicitement ailleurs. ## Gestion des codes de sortie dans un script @@ -138,14 +137,14 @@ agenteye incidents resolve "$id" --yes out=$(agenteye --json sessions --since 1h) || code=$? case "${code:-0}" in 0) echo "$out" | jq '.sessions | length' ;; - 4) echo "Session expired - run 'agenteye login'." >&2 ;; - 5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;; - 3) echo "Dashboard unreachable - check the URL." >&2 ;; - *) echo "Unexpected error (exit ${code})." >&2 ;; + 4) echo "Session expirée - lancez 'agenteye login'." >&2 ;; + 5) echo "Permission manquante (demandez à un admin evaluations:read)." >&2 ;; + 3) echo "Tableau de bord inaccessible - vérifiez l'URL." >&2 ;; + *) echo "Erreur inattendue (sortie ${code})." >&2 ;; esac ``` -## Formats de sortie JSON +## Structures de sortie JSON | Commande | JSON sur stdout (avec `--json`) | |---|---| @@ -167,4 +166,4 @@ esac - Chaque élément **evaluation** (`evals`) : `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. - Chaque élément **session** (`sessions`) : `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -Le `--fields` de chaque commande accepte exactement les noms de champs de ses propres éléments — l'ensemble diffère entre `sessions` et `evals`, donc un nom valide pour l'un peut être rejeté par l'autre. \ No newline at end of file +Le `--fields` de chaque commande accepte uniquement les noms de champs de ses propres éléments — l'ensemble diffère entre `sessions` et `evals`, donc un nom valide pour l'un peut être rejeté par l'autre. \ No newline at end of file diff --git a/docs/fr/agenteye/deployment.mdx b/docs/fr/agenteye/deployment.mdx index a6c8ca98..e3100eb7 100644 --- a/docs/fr/agenteye/deployment.mdx +++ b/docs/fr/agenteye/deployment.mdx @@ -1,6 +1,6 @@ --- title: "Déploiement" -description: "Documentation de déploiement AgentEye." +description: "Documentation de déploiement d'AgentEye." --- @@ -14,28 +14,28 @@ Ce guide couvre le déploiement du serveur et du tableau de bord AgentEye en pro [ Machines des agents IA ] [ Votre infrastructure ] Python SDK - | écrit en JSONL +----------------------+ + | writes JSONL +----------------------+ v +--->| PostgreSQL 15+ | - agenteye-collector --HTTP--+ | | (stockage relationnel)| + agenteye-collector --HTTP--+ | | (relational store) | | | +----------------------+ v | +--------+ | +----------------------+ | Server |<------+--->| ClickHouse 24+ | - +--------+ | | (événements/analytics)| + +--------+ | | (events / analytics) | ^ | +----------------------+ API | | | | +----------------------+ - +-----------+ +- - >| Redis 7+ (optionnel)| + +-----------+ +- - >| Redis 7+ (optional) | | Dashboard | +----------------------+ +-----------+ ``` -- **Server** : service HTTP en Rust ; reçoit les lots d'événements, les écrit dans ClickHouse et maintient l'état relationnel dans PostgreSQL. -- **Dashboard** : application web Next.js ; lit et écrit exclusivement via l'API du serveur. +- **Serveur** : service HTTP Rust qui reçoit les lots d'événements, les écrit dans ClickHouse et maintient l'état relationnel dans PostgreSQL. +- **Tableau de bord** : application web Next.js qui lit et écrit exclusivement via l'API du serveur. - **agenteye-collector** : déployé sur les machines des agents, pas sur l'hôte du serveur. -- **Postgres 15+** : REQUIS. (Relevé de 14 lors de la version multi-tenant ; le schéma d'appartenance aux organisations utilise une clé étrangère `ON DELETE SET NULL` avec liste de colonnes, fonctionnalité disponible à partir de Postgres 15+. Mettez à niveau Postgres avant de déployer cette version.) Stocke l'état OLTP : `api_keys`, `users`, `sessions`, `evaluation_jobs` (file d'attente), `dashboards`, `saved_queries`, `otp_codes`, ainsi que les tables multi-tenant `orgs`, `org_memberships`, `org_settings`. -- **ClickHouse 24+** : REQUIS. Le stockage analytique pour chaque événement ingéré. Moteur : `ReplacingMergeTree`, partitionné par mois, ordonné par `(session_id, ts, dedup_key)`. Le serveur se connecte via `CLICKHOUSE_URL` ; la configuration `deploy/base/clickhouse/` fournie embarque une configuration mono-nœud optimisée pour les performances. **Exigence multi-tenant :** la configuration fournie active la gestion des accès SQL + `users_without_row_policies_can_read_rows=false` afin que le serveur puisse créer un utilisateur ClickHouse en lecture seule ainsi qu'une politique de lignes par organisation (frontière d'isolation appliquée par le moteur pour l'éditeur SQL et l'agent IA). Si vous fournissez votre propre configuration ClickHouse, reprenez ces paramètres (voir `deploy/base/clickhouse/configmap.yaml`). -- **Redis 7+** : cache partagé *optionnel* + backend de limitation de débit. Le serveur et le tableau de bord se connectent tous deux via `REDIS_URL`. En l'absence de Redis, les deux dégradent gracieusement vers des chemins Postgres uniquement. Voir **Redis (cache optionnel)** ci-dessous. +- **Postgres 15+** : OBLIGATOIRE. (Relevé de la version 14 lors de la mise à jour multi-tenant ; le schéma org-membership utilise une clé étrangère `ON DELETE SET NULL` avec liste de colonnes, fonctionnalité propre à Postgres 15+. Mettez à niveau Postgres avant de déployer cette version.) Stocke l'état OLTP : `api_keys`, `users`, `sessions`, `evaluation_jobs` (queue), `dashboards`, `saved_queries`, `otp_codes`, ainsi que les tables multi-tenant `orgs`, `org_memberships`, `org_settings`. +- **ClickHouse 24+** : OBLIGATOIRE. Le store analytique pour chaque événement ingéré. Moteur : `ReplacingMergeTree`, partitionné par mois, ordonné par `(session_id, ts, dedup_key)`. Le serveur se connecte via `CLICKHOUSE_URL` ; le répertoire `deploy/base/clickhouse/` fourni embarque une configuration mono-nœud optimisée pour les performances. **Exigence multi-tenant :** la configuration fournie active la gestion des accès SQL + `users_without_row_policies_can_read_rows=false` afin que le serveur puisse créer un utilisateur ClickHouse en lecture seule et une politique de lignes par organisation (la frontière d'isolation appliquée par le moteur pour l'éditeur SQL et l'agent IA). Si vous fournissez votre propre configuration ClickHouse, reportez ces paramètres (voir `deploy/base/clickhouse/configmap.yaml`). +- **Redis 7+** : cache partagé et backend de limitation de débit *optionnels*. Le serveur et le tableau de bord se connectent tous deux via `REDIS_URL`. En l'absence de Redis, les deux dégradent gracieusement vers des chemins Postgres uniquement. Voir **Redis (cache optionnel)** ci-dessous. --- @@ -48,111 +48,110 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> Les builds actuels publient sous `beta-latest` ; `latest` n'est attribué qu'aux versions stables. Pour la production, épinglez un tag spécifique `:v` ; voir [Tags d'image disponibles](#available-image-tags). +> Les builds actuels sont publiés sous `beta-latest` ; `latest` est réservé aux versions stables. En production, épinglez un tag `:v` spécifique ; voir [Tags d'images disponibles](#available-image-tags). ### Variables d'environnement | Variable | Requise | Défaut | Description | |---|---|---|---| -| `DATABASE_URL` | Oui | aucun | DSN Postgres. Chaîne de connexion libpq standard avec le schéma `postgres://`. Prend en charge `?sslmode=require` et d'autres paramètres libpq. Le mot de passe ne doit pas contenir `/`, `+` ou `=` ; utilisez `openssl rand -hex` pour générer des mots de passe sûrs pour les URL. | -| `ADMIN_KEY` | Non | aucun | Clé API d'administration de bootstrap. Insérée ou mise à jour avec toutes les permissions à chaque démarrage. Pour la faire tourner, modifiez la valeur et redémarrez. | +| `DATABASE_URL` | Oui | aucun | DSN Postgres. Format de chaîne de connexion libpq standard avec le schéma `postgres://`. Supporte `?sslmode=require` et d'autres paramètres libpq. Le mot de passe ne doit pas contenir `/`, `+` ou `=` ; utilisez `openssl rand -hex` pour générer des mots de passe sûrs pour les URL. | +| `ADMIN_KEY` | Non | aucun | Clé API d'administration de démarrage. Mise à jour avec toutes les permissions à chaque démarrage. Faites pivoter en changeant la valeur et en redémarrant. | | `LISTEN_ADDR` | Non | `0.0.0.0:8080` | Adresse TCP à écouter | | `MAX_BODY_BYTES` | Non | `134217728` (128 Mo) | Taille maximale du corps de la requête | -| `ADMIN_EMAIL` | Non | aucun | Email de l'utilisateur administrateur de bootstrap. Inséré ou mis à jour avec toutes les permissions à chaque démarrage et marqué comme protégé : ne peut pas être désactivé ni avoir ses permissions modifiées via le tableau de bord ou l'API. Pour changer l'administrateur de bootstrap, modifiez `ADMIN_EMAIL` et redémarrez ; le nouvel email est inséré/mis à jour comme protégé, et le précédent conserve sa protection jusqu'à ce qu'elle soit manuellement supprimée en base de données. | -| `ALLOWED_EMAILS` | Non | aucun (tout bloqué) | Liste d'emails autorisés, séparés par des virgules, pour la création d'utilisateurs et la connexion. Prend en charge les adresses exactes (`user@example.com`) et les jokers de domaine (`*@example.com`). Si non défini, aucun utilisateur ne peut être créé ni se connecter. **Initialisation au premier démarrage uniquement** : alimente la liste d'autorisation de l'organisation par défaut au premier démarrage ; par la suite, la page [`//settings`](#operational-settings) de chaque organisation fait foi et toute modification de cette variable d'environnement n'a aucun effet. | -| `SMTP_HOST` | Non | aucun | Nom d'hôte du serveur SMTP pour l'envoi des emails OTP. Si non défini, les codes OTP sont journalisés sur stdout à la place. | +| `ADMIN_EMAIL` | Non | aucun | Email de l'utilisateur administrateur de démarrage. Mis à jour avec toutes les permissions à chaque démarrage et marqué comme protégé : ne peut pas être désactivé ni voir ses permissions modifiées via le tableau de bord/l'API. Pour faire pivoter l'administrateur de démarrage, changez `ADMIN_EMAIL` et redémarrez ; le nouvel email est mis à jour comme protégé, et l'ancien conserve sa protection jusqu'à ce qu'elle soit manuellement supprimée en base de données. | +| `ALLOWED_EMAILS` | Non | aucun (tout bloqué) | Liste d'emails autorisés séparés par des virgules pour la création d'utilisateurs et la connexion. Supporte les adresses exactes (`user@example.com`) et les jokers de domaine (`*@example.com`). Si non défini, aucun utilisateur ne peut être créé ni se connecter. **Initialisation au premier démarrage uniquement** : alimente la liste blanche de l'organisation par défaut au premier démarrage ; ensuite, la page [`//settings`](#operational-settings) de chaque organisation fait foi et toute modification de cette variable d'environnement n'a aucun effet. | +| `SMTP_HOST` | Non | aucun | Nom d'hôte du serveur SMTP pour l'envoi des emails OTP. Si non défini, les codes OTP sont enregistrés sur stdout. | | `SMTP_PORT` | Non | `587` | Port du serveur SMTP | -| `SMTP_USERNAME` | Non | aucun | Nom d'utilisateur d'authentification SMTP | -| `SMTP_PASSWORD` | Non | aucun | Mot de passe d'authentification SMTP | -| `SMTP_FROM` | Non | aucun | Adresse email d'expéditeur pour les emails OTP | -| `SMTP_TLS` | Non | STARTTLS | STARTTLS est utilisé sauf désactivation explicite : `false` ou `0` envoie en clair (sans TLS) ; toute autre valeur — y compris non définie — active STARTTLS. | -| `DASHBOARD_URL` | Non | valeur par défaut intégrée | Origine du tableau de bord utilisée pour construire à la fois le lien magique de l'email OTP et les liens magiques d'incident dans les notifications d'alerte. Si non défini, le système utilise une valeur par défaut intégrée (et, pour l'OTP uniquement, l'origine de la requête dérivée du tableau de bord en premier). Définissez cette variable pour les configurations à domaines séparés afin que les liens email et Slack/incident pointent vers votre tableau de bord. Voir **URL du lien magique email** ci-dessous ; la plupart des opérateurs n'ont pas besoin de la définir. | +| `SMTP_USERNAME` | Non | aucun | Nom d'utilisateur pour l'authentification SMTP | +| `SMTP_PASSWORD` | Non | aucun | Mot de passe pour l'authentification SMTP | +| `SMTP_FROM` | Non | aucun | Adresse email expéditeur pour les emails OTP | +| `SMTP_TLS` | Non | STARTTLS | STARTTLS est utilisé sauf si vous le désactivez explicitement : `false` ou `0` envoie en texte clair (sans TLS) ; toute autre valeur — y compris l'absence de définition — active STARTTLS. | +| `DASHBOARD_URL` | Non | valeur par défaut intégrée | Origine du tableau de bord utilisée pour construire à la fois le lien magique de l'email OTP et les liens magiques d'incidents dans les notifications d'alerte. Si non défini, il revient à une valeur par défaut intégrée (et, pour les OTP uniquement, à l'origine de la requête dérivée du tableau de bord en premier). Définissez-le pour les configurations à domaines séparés afin que les liens email et Slack/incident pointent vers votre tableau de bord. Voir **URL du lien magique email** ci-dessous ; la plupart des opérateurs n'ont pas besoin de le définir. | | `SESSION_TTL_SECS` | Non | `86400` (24 h) | Durée de session du tableau de bord en secondes. **Initialisation au premier démarrage uniquement** : modifiable par organisation via [`//settings`](#operational-settings) après le premier déploiement. | | `OTP_TTL_SECS` | Non | `600` (10 min) | Durée de validité du code OTP en secondes. **Initialisation au premier démarrage uniquement** : modifiable par organisation via [`//settings`](#operational-settings) après le premier déploiement. | -| `REDIS_URL` | Non | aucun | Backend optionnel de cache partagé + limitation de débit, ex. `redis://redis:6379/0`. Lorsqu'il est défini, le serveur met en cache les recherches de clés API authentifiées, l'agrégat `/models` du tableau de bord, la liste des sessions et la facette de liste d'environnements ; il déplace également la limitation de débit des requêtes OTP de `COUNT` Postgres vers `INCR` Redis. Si non défini ou injoignable, le serveur fonctionne sans cache (la limite OTP revient à Postgres, tous les autres appels de cache se rabattent sur la source de vérité). Voir **Redis (cache optionnel)** ci-dessous. | -| `CLICKHOUSE_URL` | **Oui** | aucun | URL de base de l'instance ClickHouse, ex. `http://clickhouse:8123`. Le serveur applique son schéma d'événements à cette base de données à chaque démarrage et refuse de démarrer s'il ne peut pas atteindre ClickHouse. Voir **ClickHouse (stockage analytique requis)** ci-dessous. | +| `REDIS_URL` | Non | aucun | Backend de cache partagé et de limitation de débit optionnel, ex. `redis://redis:6379/0`. Lorsqu'il est défini, le serveur met en cache les lookups de clés API authentifiées, l'agrégat `/models` du tableau de bord, la liste des sessions, et la facette de liste des environnements ; il déplace également la limitation de débit des requêtes OTP de Postgres COUNT vers Redis INCR. Si non défini ou inaccessible, le serveur fonctionne sans cache (la limite OTP revient à Postgres, tous les autres appels au cache passent à la source de vérité). Voir **Redis (cache optionnel)** ci-dessous. | +| `CLICKHOUSE_URL` | **Oui** | aucun | URL de base de l'instance ClickHouse, ex. `http://clickhouse:8123`. Le serveur applique son schéma d'événements à cette base de données à chaque démarrage et refuse de démarrer s'il ne peut pas atteindre ClickHouse. Voir **ClickHouse (store analytique requis)** ci-dessous. | | `CLICKHOUSE_DATABASE` | Non | `agenteye` | Nom de la base de données (schéma) ClickHouse. Le serveur la crée au démarrage si elle n'existe pas. | -| `ORG_CH_SECRET` | Non (mono-tenant) / **Oui (multi-org)** | valeur de développement par défaut | Clé HMAC à partir de laquelle le mot de passe ClickHouse par tenant de chaque organisation est dérivé. L'éditeur SQL et le `run_query` de l'agent IA s'exécutent en tant qu'utilisateur ClickHouse en lecture seule propre à l'organisation, dont la politique de lignes applique l'isolation des tenants dans le moteur. Les déploiements mono-tenant démarrent correctement avec la valeur de développement par défaut intégrée ; **avant de provisionner une deuxième organisation, vous DEVEZ définir une valeur forte et stable**, car le CLI `agenteye-orgctl org create` refuse de s'exécuter avec la valeur de développement par défaut. La rotation orpheline l'utilisateur ClickHouse de chaque organisation jusqu'au prochain démarrage (le rapprochement au démarrage corrige cela automatiquement). Gardez-la secrète et inchangée sur tous les réplicas. Le provisionnement des organisations est réservé aux opérateurs ; voir **Organisations (multi-tenant)** ci-dessous. | -| `DEFAULT_ORG_NAME` | Non | `Default` | Nom d'affichage initialisé pour l'organisation par défaut intégrée. **Initialisation au premier démarrage uniquement**, et seulement tant que l'organisation conserve son identité générique issue de la migration, appliqué au démarrage puis ignoré. Une fois l'organisation renommée (`agenteye-orgctl org rename`), le renommage fait foi et cette variable d'environnement n'a plus d'effet. | -| `DEFAULT_ORG_SLUG` | Non | `default` | Slug d'URL pour l'organisation par défaut intégrée, le chemin du tableau de bord où elle réside (`//…`). Même sémantique de premier démarrage uniquement / identité vierge que `DEFAULT_ORG_NAME`. Doit comporter entre 1 et 40 caractères alphanumériques minuscules avec des tirets internes simples et ne doit pas être un [mot réservé](#organizations-multi-tenancy) ; une valeur invalide est ignorée (l'organisation conserve `default`). Permet à une installation mono-tenant de s'afficher par exemple en `/acme` au lieu de `/default` sans étape CLI post-déploiement. | +| `ORG_CH_SECRET` | Non (mono-tenant) / **Oui (multi-org)** | valeur dev par défaut | Clé HMAC à partir de laquelle le mot de passe ClickHouse par tenant de chaque organisation est dérivé. L'éditeur SQL et le `run_query` de l'agent IA s'exécutent en tant qu'utilisateur ClickHouse en lecture seule propre à l'organisation, dont la politique de lignes applique l'isolation des tenants dans le moteur. Les déploiements mono-tenant démarrent correctement avec la valeur dev intégrée ; **avant de provisionner une seconde organisation, vous DEVEZ définir une valeur forte et stable**, car la CLI `agenteye-orgctl org create` refuse de s'exécuter avec la valeur dev intégrée. La faire pivoter orpheline l'utilisateur ClickHouse de chaque organisation jusqu'au prochain démarrage qui les re-provisionne automatiquement. Gardez-la secrète et inchangée entre les réplicas. Le provisionnement des organisations est réservé aux opérateurs ; voir **Organisations (multi-tenancy)** ci-dessous. | +| `DEFAULT_ORG_NAME` | Non | `Default` | Nom d'affichage initialisé pour l'organisation par défaut intégrée. **Initialisation au premier démarrage uniquement**, et uniquement tant que l'organisation conserve son identité générique fraîchement migrée, appliquée au démarrage, puis ignorée. Une fois que vous renommez l'organisation (`agenteye-orgctl org rename`), le renommage fait autorité et cette variable d'environnement n'a plus aucun effet. | +| `DEFAULT_ORG_SLUG` | Non | `default` | Slug d'URL pour l'organisation par défaut intégrée, le chemin du tableau de bord où elle réside (`//…`). Mêmes sémantiques de premier démarrage uniquement / état initial que `DEFAULT_ORG_NAME`. Doit comporter 1 à 40 caractères alphanumériques minuscules avec des tirets internes simples et ne pas être un [mot réservé](#organizations-multi-tenancy) ; une valeur invalide est ignorée (l'organisation conserve `default`). Permet à une installation mono-tenant de se présenter par ex. comme `/acme` au lieu de `/default` sans aucune étape CLI post-déploiement. | | `RUST_LOG` | Non | `info` | Verbosité des logs (`debug`, `warn`, `error`, `agenteye_server=trace`) | -| `EVALUATOR_ENDPOINT` | Non | aucun | URL de base de votre service d'évaluation (ex. `http://evaluator:9000`). Si non défini, l'ensemble du pipeline d'évaluation est inopérant ; aucune ligne de file d'attente n'est écrite, aucun worker ne s'exécute. Voir [Suite d'évaluation](/fr/agenteye/evaluation-suite). | -| `EVALUATOR_TOKEN` | Non | aucun | Envoyé comme `Authorization: Bearer ` à l'évaluateur. **Doit être égal à la valeur avec laquelle le service évaluateur est configuré.** Optionnel uniquement si votre évaluateur est configuré sans token. | -| `EVALUATOR_WORKERS` | Non | `2` | Concurrence : nombre de tâches worker par instance de serveur qui envoient les évaluations. Sûr à exécuter sur plusieurs serveurs à mise à l'échelle horizontale. | -| `EVALUATOR_CLAIM_BATCH` | Non | `4` | Nombre maximum d'évaluations qu'un seul worker revendique par cycle. Les lots sont envoyés **concurremment**, donc la concurrence totale sur votre endpoint évaluateur est `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | Non | `2` | Durée de sommeil d'un worker entre les tentatives d'envoi quand rien n'est en attente. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | Non | `10` | Cadence de repli finale (en secondes) pour les sondages `GET /evaluate/{id}` quand l'évaluateur ne retourne pas de `next_poll_secs` par réponse et n'annonce pas de `default_poll_interval_secs` via `GET /config`. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | Non | `30000` | Délai d'expiration par requête HTTP vers l'évaluateur (en millisecondes). | -| `EVALUATOR_MAX_ATTEMPTS` | Non | `5` | Après ce nombre de tentatives échouées, une évaluation est enregistrée comme `error` terminal (ou `timeout` si les échecs étaient des délais d'expiration de requête). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | Non | `300` (5 min) | Fréquence à laquelle le serveur récupère à nouveau `GET /config` depuis l'évaluateur. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Non | `3600` (1 h) | Durée maximale en temps réel pendant laquelle une session peut rester dans la file de sondage avant qu'AgentEye ne la termine en `timeout`. Protège contre un évaluateur qui retourne `pending` indéfiniment. | +| `EVALUATOR_ENDPOINT` | Non | aucun | URL de base de votre service d'évaluation (ex. `http://evaluator:9000`). Si non défini, l'intégralité du pipeline d'évaluation est sans effet ; aucune ligne de queue n'est écrite, aucun worker ne s'exécute. Voir [Suite d'évaluation](/fr/agenteye/evaluation-suite). | +| `EVALUATOR_TOKEN` | Non | aucun | Envoyé en tant que `Authorization: Bearer ` à l'évaluateur. **Doit être égal à la valeur avec laquelle le service d'évaluation est configuré.** Optionnel uniquement si votre évaluateur est configuré sans token. | +| `EVALUATOR_WORKERS` | Non | `2` | Concurrence : nombre de tâches worker par instance de serveur qui dispatche les évaluations. Sûr à exécuter sur plusieurs serveurs à mise à l'échelle horizontale. | +| `EVALUATOR_CLAIM_BATCH` | Non | `4` | Nombre maximum d'évaluations qu'un seul worker revendique par tick. Les lots sont dispatchés **de façon concurrente**, donc la concurrence totale sur votre endpoint d'évaluation est `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | Non | `2` | Durée de sommeil d'un worker entre les tentatives de dispatch lorsqu'aucune évaluation n'est en attente. | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Non | `10` | Cadence de repli finale (en secondes) pour les sondages `GET /evaluate/{id}` lorsque l'évaluateur ne retourne pas de `next_poll_secs` par réponse et n'annonce pas de `default_poll_interval_secs` via `GET /config`. | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | Non | `30000` | Timeout par requête HTTP vers l'évaluateur (en millisecondes). | +| `EVALUATOR_MAX_ATTEMPTS` | Non | `5` | Après autant de tentatives échouées, une évaluation est enregistrée comme `error` terminal (ou `timeout` si les échecs étaient des timeouts de requête). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | Non | `300` (5 min) | Fréquence à laquelle le serveur re-récupère `GET /config` depuis l'évaluateur. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Non | `3600` (1 h) | Temps d'horloge murale maximum pendant lequel une session peut rester dans la queue de sondage avant qu'AgentEye la termine en `timeout`. Protège contre un évaluateur qui retourne indéfiniment `pending`. | | `ALERT_WORKERS` | Non | `1` | Concurrence : nombre de tâches worker par instance de serveur qui évaluent les règles d'alerte. Voir [Alertes](/fr/agenteye/alerts). | -| `ALERT_CLAIM_BATCH` | Non | `16` | Nombre maximum d'alertes qu'un seul worker revendique par cycle. | -| `ALERT_POLL_IDLE_SECS` | Non | `5` | Durée de sommeil d'un worker d'alertes quand la file est vide. | -| `ALERT_REQUEST_TIMEOUT_MS` | Non | `15000` | Délai d'expiration par évaluation de déclenchement (requêtes ClickHouse + HTTP de canal sortant). | -| `ALERT_MAX_ATTEMPTS` | Non | `5` | Échecs transitoires consécutifs avant qu'une alerte soit replanifiée à sa cadence normale plutôt qu'avec un backoff exponentiel. | -| `AUDIT_WORKERS` | Non | `1` | Concurrence : nombre de tâches worker par instance de serveur qui exécutent les audits. Voir [Audits](/fr/agenteye/audits). | -| `AUDIT_CLAIM_BATCH` | Non | `1` | Nombre maximum d'audits échus qu'un seul worker revendique par cycle. Une investigation agentique est une longue boucle, d'où la valeur par défaut de 1. | -| `AUDIT_POLL_IDLE_SECS` | Non | `30` | Durée de sommeil d'un worker d'audits quand aucun audit n'est dû. | -| `AUDIT_REQUEST_TIMEOUT_MS` | Non | `30000` | Délai d'expiration par requête de politique vers ClickHouse (en millisecondes). | -| `AUDIT_LLM_TIMEOUT_MS` | Non | `1440000` | Délai d'expiration pour l'appel d'investigation agentique au service assistant IA. Une boucle d'agent complète dure plusieurs minutes ; maintenez cette valeur AU-DESSUS du propre `AGENTEYE_AUDIT_TIMEOUT_MS` de l'agent afin que l'agent retourne ses résultats partiels avant que le serveur n'abandonne. | -| `AUDIT_MAX_ATTEMPTS` | Non | `5` | Échecs transitoires consécutifs avant qu'un audit soit replanifié à sa cadence normale plutôt qu'avec un backoff exponentiel. | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | Non | — | L'investigation agentique de l'audit appelle le service `agent` d'assistant IA, **en réutilisant la même connexion que l'assistant** — définissez donc ces deux variables sur le **serveur** également (les manifestes/compose fournis le font). Les deux définies ⇒ les audits exécutent l'investigation IA ; l'une ou l'autre non définie ⇒ les audits s'exécutent **en mode politique uniquement** (la passe de politique SQL déterministe s'exécute quand même), indépendamment de l'indicateur `llm_enabled` par audit. L'agent doit également avoir un LLM configuré — voir [assistant.md](/fr/agenteye/assistant). | - -**Service assistant IA — paramètres d'audit et de sandbox.** L'investigation agentique et son sandbox Python en pod sont réglés sur le **service agent** (pas sur le serveur), tous avec le préfixe `AGENTEYE_AUDIT_*` et tous optionnels : +| `ALERT_CLAIM_BATCH` | Non | `16` | Nombre maximum d'alertes qu'un seul worker revendique par tick. | +| `ALERT_POLL_IDLE_SECS` | Non | `5` | Durée de sommeil d'un worker d'alertes lorsque la queue est vide. | +| `ALERT_REQUEST_TIMEOUT_MS` | Non | `15000` | Timeout d'évaluation par déclenchement (requêtes ClickHouse + HTTP de canal sortant). | +| `ALERT_MAX_ATTEMPTS` | Non | `5` | Nombre d'échecs transitoires consécutifs avant qu'une alerte soit replanifiée à sa cadence normale plutôt qu'avec un backoff exponentiel. | +| `AUDIT_WORKERS` | Non | `1` | Concurrence : nombre de tâches worker par instance de serveur qui exécutent des audits. Voir [Audits](/fr/agenteye/audits). | +| `AUDIT_CLAIM_BATCH` | Non | `1` | Nombre maximum d'audits dus qu'un seul worker revendique par tick. Une investigation agentique est une longue boucle, d'où le défaut à 1. | +| `AUDIT_POLL_IDLE_SECS` | Non | `30` | Durée de sommeil d'un worker d'audits lorsqu'aucun audit n'est dû. | +| `AUDIT_REQUEST_TIMEOUT_MS` | Non | `30000` | Timeout par requête de politique vers ClickHouse (en millisecondes). | +| `AUDIT_LLM_TIMEOUT_MS` | Non | `1440000` | Timeout pour l'appel d'investigation agentique au service d'assistant IA. Une boucle d'agent complète s'exécute pendant plusieurs minutes ; gardez-le AU-DESSUS du propre `AGENTEYE_AUDIT_TIMEOUT_MS` de l'agent pour que l'agent retourne ses conclusions partielles avant que le serveur abandonne. | +| `AUDIT_MAX_ATTEMPTS` | Non | `5` | Nombre d'échecs transitoires consécutifs avant qu'un audit soit replanifié à sa cadence normale plutôt qu'avec un backoff exponentiel. | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | Non | — | L'investigation agentique de l'audit appelle le service `agent` d'assistant IA, **réutilisant la même connexion que l'assistant** — définissez donc ces deux variables sur le **serveur** également (les manifestes/compose fournis le font). Les deux définis ⇒ les audits exécutent l'investigation IA ; l'un ou l'autre non défini ⇒ les audits s'exécutent **en mode politique uniquement** (la passe de politique SQL déterministe s'exécute quand même), quel que soit le flag `llm_enabled` par audit. L'agent doit également avoir un LLM configuré — voir [assistant.md](/fr/agenteye/assistant). | + +**Service d'assistant IA — paramètres d'audit et de sandbox.** L'investigation agentique et son sandbox Python dans le pod sont configurés sur le **service agent** (pas le serveur), tous avec le préfixe `AGENTEYE_AUDIT_*` et tous optionnels : | Variable | Défaut | Signification | |---|---|---| | `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Nombre maximum de tours d'agent par investigation. | -| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Durée en temps réel pour une investigation (20 min). Doit rester **inférieure** au `AUDIT_LLM_TIMEOUT_MS` du serveur. | -| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Investigations simultanées par pod agent (indépendamment du budget de l'assistant de chat). | +| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Temps d'horloge murale pour une investigation (20 min). Doit rester **en dessous** du `AUDIT_LLM_TIMEOUT_MS` du serveur. | +| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Investigations concurrentes par pod agent (séparé du budget de l'assistant de chat). | | `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Limites par script pour le sandbox bubblewrap. | -**Exigence de plateforme pour le sandbox.** Le sandbox de code d'audit exécute le Python du modèle dans une cage bubblewrap, qui nécessite des **espaces de noms utilisateur non privilégiés**. Le pod agent doit autoriser les indicateurs `clone()` — définissez `seccompProfile: Unconfined` (k8s) ou `security_opt: [seccomp:unconfined]` (compose) sur l'agent. Lorsque le noyau du nœud désactive les espaces de noms utilisateur non privilégiés (ex. certaines images GKE COS), le **prévol du sandbox échoue et l'auditeur se dégrade automatiquement en mode SQL uniquement** — pas d'erreur, juste un `sandbox_available: false` sur le `/health` de l'agent. +**Exigence de plateforme pour le sandbox.** Le sandbox de code d'audit exécute le Python du modèle dans une cage bubblewrap, ce qui nécessite des **espaces de noms utilisateurs non privilégiés**. Le pod agent doit autoriser les flags `clone()` — définissez `seccompProfile: Unconfined` (k8s) ou `security_opt: [seccomp:unconfined]` (compose) sur l'agent. Lorsque le noyau du nœud désactive les espaces de noms utilisateurs non privilégiés (ex. certaines images GKE COS), le **preflight du sandbox échoue et l'auditeur se dégrade automatiquement en mode SQL uniquement** — pas d'erreur, juste un `sandbox_available: false` sur le `/health` de l'agent. ### Démarrer -Définissez `DATABASE_URL` et `CLICKHOUSE_URL` dans votre environnement (le serveur refuse de démarrer sans ClickHouse), puis transmettez-les au conteneur : +Définissez `DATABASE_URL` dans votre environnement, puis transmettez-le au conteneur : ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest ``` -Le serveur exécute les migrations de base de données automatiquement au démarrage ; aucune étape de migration séparée n'est nécessaire. +Le serveur exécute automatiquement les migrations de base de données au démarrage ; aucune étape de migration séparée n'est nécessaire. -### Vérification de santé +### Vérification de l'état ``` GET /health # liveness - toujours {"status":"ok"} une fois le processus démarré -GET /ready # readiness - 200 quand Postgres + ClickHouse sont joignables, sinon 503 +GET /ready # readiness - 200 quand Postgres + ClickHouse sont accessibles, sinon 503 ``` -Aucune authentification requise. Utilisez `/health` pour les sondes de **liveness** et `/ready` pour les sondes de **readiness** / d'équilibreur de charge. `/ready` vérifie les dépendances strictes sans lesquelles le serveur ne peut pas servir (Postgres + ClickHouse), donc un serveur en cours d'exécution mais incapable d'atteindre sa base de données est retiré de la rotation et apparaît comme `NotReady` ; Redis est rapporté mais ne fait jamais échouer la readiness. Dans les manifestes Kubernetes fournis, la sonde de readiness pointe déjà sur `/ready` et la liveness reste sur `/health`. Voir [enterprise-docs/health-monitoring.md](/fr/agenteye/health-monitoring) pour la vue d'ensemble complète, y compris les alertes Slack optionnelles natives Kubernetes sur les défaillances de pods. +Aucune authentification requise. Utilisez `/health` pour les sondes de **liveness** et `/ready` pour les sondes de **readiness** / d'équilibreur de charge. `/ready` vérifie les dépendances essentielles sans lesquelles le serveur ne peut pas fonctionner (Postgres + ClickHouse), donc un serveur en cours d'exécution mais incapable d'atteindre sa base de données est retiré de la rotation et apparaît comme `NotReady` ; Redis est rapporté mais ne fait jamais échouer la readiness. Sur les manifestes Kubernetes fournis, la sonde de readiness pointe déjà sur `/ready` et la liveness reste sur `/health`. Voir [enterprise-docs/health-monitoring.md](/fr/agenteye/health-monitoring) pour l'image complète, y compris les alertes Slack optionnelles pour les défaillances de pods Kubernetes. ### URL du lien magique email -Les emails de connexion OTP contiennent un bouton **ouvrir le tableau de bord** en un clic. En cliquant dessus, l'utilisateur arrive sur `/login?token=&email=
` ; le tableau de bord échange cette paire contre une session et redirige vers l'application, sans ressaisie manuelle du code. Le serveur résout l'origine du tableau de bord utilisée pour construire le lien selon trois niveaux : +Les emails de connexion OTP contiennent un bouton **ouvrir le tableau de bord** en un clic. En cliquant dessus, l'utilisateur atterrit sur `/login?token=&email=
` ; le tableau de bord échange cette paire contre une session et redirige vers l'application, sans ressaisie manuelle du code. Le serveur résout l'origine du tableau de bord utilisée pour construire le lien en trois niveaux : -1. **En-tête `X-AgentEye-Dashboard-Url`** : défini automatiquement par le proxy `/api/auth/otp/request` du tableau de bord depuis sa propre origine publique. Dans un déploiement sur la même origine (serveur et tableau de bord partagent un hôte derrière un ingress unique qui transfère les en-têtes proxy), **aucune configuration n'est requise**. -2. **Variable d'environnement `DASHBOARD_URL`** : définissez-la si votre tableau de bord est joignable sur une origine différente de celle que voit le endpoint de requête OTP du serveur (configuration `api.example.com` / `app.example.com` séparée), ou si votre ingress ne propage pas l'hôte public dans le pod tableau de bord (de sorte que `request.nextUrl.origin` se résoudrait sinon en une adresse générique comme `0.0.0.0:3000`). Exemple : `DASHBOARD_URL=https://app.example.com`. -3. **Défaut** : `https://app.befailproof.ai`, utilisé uniquement si aucune des options ci-dessus n'est présente. +1. **En-tête `X-AgentEye-Dashboard-Url`** : défini automatiquement par le proxy `/api/auth/otp/request` du tableau de bord depuis sa propre origine publique. Dans un déploiement à même origine (serveur et tableau de bord partagent un hôte derrière un seul ingress qui transmet les en-têtes proxy), **aucune configuration n'est requise**. +2. **Variable d'environnement `DASHBOARD_URL`** : définissez-la si votre tableau de bord est accessible sur une origine différente de celle que voit l'endpoint de requête OTP du serveur (séparation `api.example.com` / `app.example.com`), ou si votre ingress ne propage pas l'hôte public dans le pod tableau de bord (de sorte que `request.nextUrl.origin` résoudrait sinon vers une adresse générique comme `0.0.0.0:3000`). Exemple : `DASHBOARD_URL=https://app.example.com`. +3. **Par défaut** : `https://app.befailproof.ai`, utilisé uniquement si aucun des cas ci-dessus n'est présent. -La valeur de l'en-tête est validée : seules les origines `https://*` et loopback (`http://localhost*`, `http://127.0.0.1*`) sont acceptées, et les adresses de liaison génériques (`0.0.0.0`, `[::]`) sont rejetées même avec le schéma `https://`. Tout le reste passe au niveau 2. +La valeur de l'en-tête est validée : seules les origines `https://*` et de loopback (`http://localhost*`, `http://127.0.0.1*`) sont acceptées, et les adresses de liaison génériques (`0.0.0.0`, `[::]`) sont rejetées même avec le schéma `https://`. Tout le reste passe au niveau 2. -Mettez-la à jour sur un cluster en cours d'exécution avec une commande simple ; aucun fichier, aucune reconstruction kustomize : +Définissez-le sur un cluster en cours d'exécution en une seule commande ; pas de fichier, pas de reconstruction kustomize : ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -Cela déclenche un rollout ; les nouveaux pods récupèrent la valeur dès la première requête. Notez que la surcharge ne réside que sur le Deployment ; un `kustomize build | kubectl apply` ultérieur sur l'overlay la supprimera sauf si vous ajoutez la même variable d'environnement au patch `server-env.yaml` de votre overlay. +Cela déclenche un rollout ; les nouveaux pods récupèrent la valeur à la première requête. Notez que la substitution ne vit que sur le Deployment ; un `kustomize build | kubectl apply` ultérieur contre l'overlay l'effacera sauf si vous ajoutez la même variable d'environnement au patch `server-env.yaml` de votre overlay. --- @@ -169,13 +168,13 @@ docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest | Variable | Requise | Défaut | Description | |---|---|---|---| | `AGENTEYE_SERVER_URL` | Oui | aucun | URL de base du serveur, ex. `http://localhost:8080` | -| `AGENTEYE_API_KEY` | Oui | aucun | Clé API que le tableau de bord utilise pour s'authentifier auprès du serveur. Toutes les permissions sont requises (clé admin recommandée). | -| `AE_LOG_LEVEL` | Non | `info` | Verbosité des logs côté serveur : `debug`, `info`, `warn`, `error`. Définissez sur `debug` pour voir les lignes de requête/réponse amont et les traces de validation de session lors du diagnostic de problèmes. | -| `AE_LOG_JSON` | Non | automatique | `1` force la sortie JSON par ligne ; `0` force la sortie lisible par l'humain. Si non défini, JSON est activé automatiquement si `NODE_ENV=production`. JSON est recommandé en production pour que les logs se parsent proprement avec `jq` ou un agrégateur de logs. | +| `AGENTEYE_API_KEY` | Oui | aucun | Clé API que le tableau de bord utilise pour s'authentifier auprès du serveur. Nécessite toutes les permissions (clé admin recommandée). | +| `AE_LOG_LEVEL` | Non | `info` | Verbosité des logs côté serveur : `debug`, `info`, `warn`, `error`. Définissez sur `debug` pour voir les lignes de requête/réponse en amont et les traces de validation de session lors du diagnostic de problèmes. | +| `AE_LOG_JSON` | Non | auto | `1` force la sortie JSON par ligne ; `0` force la sortie lisible par l'humain. Si non défini, JSON est activé automatiquement si `NODE_ENV=production`. JSON est recommandé en production pour que les logs soient analysés proprement avec `jq` ou un agrégateur de logs. | | `AE_ANALYTICS_DISABLED` | Non | aucun | Définissez sur `1`/`true` pour désactiver la télémétrie anonyme d'utilisation du produit du tableau de bord. Voir [Télémétrie et confidentialité](#telemetry--privacy) ci-dessous. | -| `REDIS_URL` | Non | aucun | Backend de cache partagé optionnel, ex. `redis://redis:6379/0`. Lorsqu'il est défini, le tableau de bord met en cache les résultats de `validateSession()` entre les réplicas et partage le cache de récupération Next.js pour les routes proxy d'agrégat de latence / liste d'environnements. Les limites de débit OTP côté edge pour les requêtes et vérifications utilisent également Redis si présent (avec repli ouvert si Redis est injoignable ; la limite côté serveur est le filet de sécurité). Voir **Redis (cache optionnel)** ci-dessous. | -| `AGENTEYE_AGENT_URL` | Non | aucun | URL de base du service `agent` assistant IA optionnel, ex. `http://agent:9100`. **Laissez-le non défini pour masquer complètement l'assistant** : aucune bulle d'assistant n'apparaît dans le tableau de bord. Voir [enterprise-docs/assistant.md](/fr/agenteye/assistant). | -| `AGENTEYE_AGENT_TOKEN` | Non | aucun | Secret partagé que le tableau de bord présente au service `agent`. Doit correspondre à `AGENTEYE_AGENT_TOKEN` configuré sur l'agent. Voir [enterprise-docs/assistant.md](/fr/agenteye/assistant). | +| `REDIS_URL` | Non | aucun | Backend de cache partagé optionnel, ex. `redis://redis:6379/0`. Lorsqu'il est défini, le tableau de bord met en cache les résultats de `validateSession()` entre les réplicas et partage le cache de récupération Next.js pour les routes proxy d'agrégat de latence et de liste d'environnements. Les limites de débit des requêtes et vérifications OTP côté edge utilisent également Redis lorsqu'il est présent (échouant ouvertes si Redis est inaccessible ; la limite côté serveur est le garde-fou de sécurité). Voir **Redis (cache optionnel)** ci-dessous. | +| `AGENTEYE_AGENT_URL` | Non | aucun | URL de base du service `agent` d'assistant IA optionnel, ex. `http://agent:9100`. **Laissez-le non défini pour masquer entièrement l'assistant** : aucune bulle d'assistant n'apparaît dans le tableau de bord. Voir [enterprise-docs/assistant.md](/fr/agenteye/assistant). | +| `AGENTEYE_AGENT_TOKEN` | Non | aucun | Secret partagé que le tableau de bord présente au service `agent`. Doit correspondre à l'`AGENTEYE_AGENT_TOKEN` configuré sur l'agent. Voir [enterprise-docs/assistant.md](/fr/agenteye/assistant). | ### Démarrer @@ -190,57 +189,57 @@ docker run -d --restart unless-stopped \ ### Télémétrie et confidentialité -Le tableau de bord envoie des **analytics anonymes d'utilisation du produit** au service d'analytics d'Exosphere (PostHog) : quelles pages du tableau de bord sont consultées et quelques actions d'interface utilisateur telles que la création d'une clé API ou la réévaluation d'une session. Ce signal d'utilisation oriente la priorisation des fonctionnalités. +Le tableau de bord envoie des **analyses d'utilisation anonymes du produit** au service d'analyse d'Exosphere (PostHog) : les pages du tableau de bord consultées et quelques actions de l'interface utilisateur comme la création d'une clé API ou la réévaluation d'une session. Ce signal d'utilisation informe la priorisation des fonctionnalités. -- **Aucune donnée d'agent, de session ou d'événement ne quitte jamais votre infrastructure.** Seule l'utilisation de l'interface du tableau de bord est rapportée. Les URL de pages sont dépouillées de leurs identifiants avant envoi, et les opérateurs ne sont identifiés que par un identifiant interne opaque, jamais par email. +- **Aucune donnée d'agent, de session ou d'événement ne quitte jamais votre infrastructure.** Seule l'utilisation de l'interface du tableau de bord est rapportée. Les URL des pages sont dépouillées de leurs identifiants avant l'envoi, et les opérateurs ne sont identifiés que par un identifiant interne opaque, jamais par email. - La télémétrie est **activée par défaut**. Pour la désactiver complètement, définissez `AE_ANALYTICS_DISABLED=1` sur le conteneur du tableau de bord et redémarrez. -- Les analytics sont envoyées vers le propre chemin `/ingest` du tableau de bord, que le tableau de bord reverse-proxy vers PostHog (`https://us.i.posthog.com`). Conserver les requêtes en first-party signifie que les bloqueurs de publicité des navigateurs ne les suppriment pas. Le **conteneur du tableau de bord** a besoin d'un accès sortant vers PostHog ; s'il est bloqué, la télémétrie ne fait rien silencieusement et le tableau de bord n'est pas affecté. +- Les analyses sont envoyées vers le propre chemin `/ingest` du tableau de bord, que le tableau de bord relaie en proxy inverse vers PostHog (`https://us.i.posthog.com`). Garder les requêtes en first-party signifie que les bloqueurs de publicité des navigateurs ne les suppriment pas. Le **conteneur du tableau de bord** a besoin d'un accès sortant vers PostHog ; s'il est bloqué, la télémétrie ne fait silencieusement rien et le tableau de bord n'est pas affecté. --- ## Assistant IA (optionnel) -Un assistant IA intégré au tableau de bord permet à votre équipe de poser des questions sur leurs données d'agents en langage naturel (résumé de sessions, rédaction de SQL pour l'éditeur `/queries`, et transformation de requêtes sauvegardées en tuiles de tableau de bord) sans quitter le tableau de bord. Il fonctionne comme un conteneur `agent` interne séparé (sur le Claude Agents SDK) que seul le tableau de bord peut atteindre, et reste **désactivé jusqu'à ce que vous configuriez un endpoint LLM**. +Un assistant IA intégré au tableau de bord permet à votre équipe de poser des questions sur les données de leurs agents en langage naturel (résumer des sessions, rédiger du SQL pour l'éditeur `/queries`, et transformer des requêtes sauvegardées en tuiles de tableau de bord) sans quitter le tableau de bord. Il fonctionne comme un conteneur `agent` interne séparé (basé sur le Claude Agents SDK) que seul le tableau de bord peut atteindre, et reste **désactivé jusqu'à ce que vous configuriez un endpoint LLM**. -Pour l'activer, définissez sur le service `agent` une connexion LLM (**Portkey** via `PORTKEY_API_KEY` + un slug de catalogue de modèles `AGENTEYE_AGENT_MODEL=@/`, Anthropic direct via `ANTHROPIC_API_KEY`, une autre passerelle via `ANTHROPIC_BASE_URL`, ou Bedrock/Vertex), une clé de données **dédiée**, et un `AGENTEYE_AGENT_TOKEN` partagé correspondant au tableau de bord. Les utilisateurs du tableau de bord ont en outre besoin de la permission `agent:use`. +Pour l'activer, définissez sur le service `agent` une connexion LLM (**Portkey** via `PORTKEY_API_KEY` + un slug de catalogue de modèles `AGENTEYE_AGENT_MODEL=@/`, Anthropic direct via `ANTHROPIC_API_KEY`, une autre passerelle via `ANTHROPIC_BASE_URL`, ou Bedrock/Vertex), une clé de données **dédiée**, et un `AGENTEYE_AGENT_TOKEN` partagé correspondant au tableau de bord. Les utilisateurs du tableau de bord ont également besoin de la permission `agent:use`. -Pour la clé de données de l'assistant, vous n'avez rien à créer manuellement : choisissez un secret aléatoire, définissez-le comme `AGENTEYE_API_KEY` sur l'`agent` **et** comme `AGENT_API_KEY` sur le `server`, et le serveur l'initialise au démarrage avec un ensemble de permissions fixe. Son accès aux données est en lecture seule (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), et il détient en plus des portées d'authoring avec approbation requise (`dashboards:write`, `queries:write`, `queries:run`) afin qu'il puisse rédiger et valider des requêtes sauvegardées et créer des tuiles de tableau de bord pour le compte de l'utilisateur ; tout le SQL s'exécute quand même via le rôle ClickHouse en lecture seule de l'organisation, donc cela élargit ce que l'assistant peut créer, pas les données auxquelles il peut accéder. Les portées sont fixes dans le code et ne peuvent pas être élargies par configuration. Cette clé est protégée ; elle ne peut pas être désactivée ou régénérée via l'API, uniquement en changeant la valeur et en redémarrant. Ne réutilisez jamais la clé admin/tableau de bord pour cela. +Pour la clé de données de l'assistant, vous n'avez rien à créer manuellement : choisissez un secret aléatoire, définissez-le comme `AGENTEYE_API_KEY` sur l'`agent` **et** comme `AGENT_API_KEY` sur le `server`, et le serveur l'initialise au démarrage avec un ensemble de permissions fixes. Son accès aux données est en lecture seule (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), et il détient en outre des portées d'authoring soumises à approbation (`dashboards:write`, `queries:write`, `queries:run`) pour qu'il puisse rédiger et valider des requêtes sauvegardées et construire des tuiles de tableau de bord au nom de l'utilisateur ; tout le SQL s'exécute quand même via le rôle ClickHouse en lecture seule de l'organisation, ce qui élargit ce que l'assistant peut créer, pas les données auxquelles il peut accéder. Les portées sont fixes dans le code et ne peuvent pas être élargies par configuration. Cette clé est protégée ; elle ne peut pas être désactivée ou régénérée via l'API, uniquement pivotée en changeant la valeur et en redémarrant. Ne réutilisez jamais la clé admin/tableau de bord pour cela. -La configuration complète, la référence complète des variables d'environnement, les options de télémétrie et le modèle de sécurité se trouvent dans **[enterprise-docs/assistant.md](/fr/agenteye/assistant)**. +La configuration complète, la référence complète des variables d'environnement, les options de télémétrie et le modèle de sécurité sont dans **[enterprise-docs/assistant.md](/fr/agenteye/assistant)**. --- -## ClickHouse (stockage analytique requis) +## ClickHouse (store analytique requis) -ClickHouse maintient la réactivité de vos tableaux de bord à des volumes d'événements élevés et permet à l'éditeur SQL `/queries` de joindre événements, évaluations et sessions dans un seul stockage. C'est le stockage canonique requis pour chaque événement ingéré, chaque résultat d'évaluation terminal et les agrégats dérivés par session. PostgreSQL contient les tables d'état relationnel/mutable (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries) ; la surface analytique réside dans ClickHouse afin que les agrégats du tableau de bord et vos propres requêtes SQL puissent les parcourir et les joindre nativement, sans allers-retours entre bases de données. Le serveur refuse de démarrer sans `CLICKHOUSE_URL`. +ClickHouse maintient la réactivité de vos tableaux de bord à des volumes d'événements élevés et permet à l'éditeur SQL `/queries` de joindre événements, évaluations et sessions dans un seul store. Il est le store canonique requis pour chaque événement ingéré, chaque résultat d'évaluation terminal, et les agrégats par session dérivés. PostgreSQL contient les tables d'état relationnel/mutable (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries) ; la surface analytique vit dans ClickHouse pour que les rollups du tableau de bord et vos propres requêtes SQL puissent l'analyser et la joindre nativement, sans allers-retours entre bases de données. Le serveur refuse de démarrer sans `CLICKHOUSE_URL`. ### Schéma Trois objets ClickHouse sont créés au démarrage du serveur, tous idempotents (`CREATE IF NOT EXISTS`) : -- **`agenteye.events`** : `ReplacingMergeTree(ingested_at)`, partitionné par `toYYYYMM(ts)`, ordonné par `(session_id, ts, dedup_key)`. Les insertions dupliquées (tentatives du collecteur) se réduisent à une seule ligne à la fusion ; le serveur calcule un `dedup_key` SHA-256 déterministe pour chaque événement, rendant les tentatives sûres. +- **`agenteye.events`** : `ReplacingMergeTree(ingested_at)`, partitionné par `toYYYYMM(ts)`, ordonné par `(session_id, ts, dedup_key)`. Les insertions dupliquées (nouvelles tentatives du collecteur) se réduisent à une seule ligne lors de la fusion ; le serveur calcule un `dedup_key` SHA-256 déterministe pour chaque événement afin que les nouvelles tentatives soient sûres. - **`agenteye.evaluations`** : `ReplacingMergeTree(ingested_at)`, partitionné par `toYYYYMM(finished_at)`, ordonné par `(session_id, finished_at, dedup_key)`. Écrit une fois par résultat d'évaluation terminal par le pipeline d'évaluation. Même modèle de clé de déduplication que `events`. -- **`agenteye.agent_sessions`** : une **VUE** sur `agenteye.events`, pas une table physique. Chaque colonne est dérivée (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, etc.). Pas d'upsert par événement et pas de backfill séparé ; la vue reflète automatiquement ce qui se trouve dans `events`. +- **`agenteye.agent_sessions`** : une **VUE** sur `agenteye.events`, pas une table physique. Chaque colonne est dérivée (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, etc.). Pas d'upsert par événement ni de backfill séparé ; la vue reflète automatiquement ce qui est dans `events`. Pour la compatibilité ascendante avec les requêtes sauvegardées qui référencent `analytics.evaluations` / `analytics.sessions`, le serveur crée également une base de données ClickHouse `analytics` avec des vues sur les tables `agenteye.*` ; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` se résolvent tous correctement. ### Configuration -Le docker-compose fourni et `deploy/base/clickhouse/` embarquent un service ClickHouse réglé pour la charge de travail d'AgentEye : +Le docker-compose fourni et `deploy/base/clickhouse/` embarquent un service ClickHouse optimisé pour la charge de travail d'AgentEye : -- 2 Gio demandés / 4 Gio limite de mémoire dans l'overlay de base fourni (dimensionné pour les petits nœuds POC/staging) ; les clients en production devraient augmenter — le plancher recommandé est 2c / 4Gi demandé, 6c / 8Gi limite. `max_server_memory_usage_to_ram_ratio=0.9` -- 5 Gio de cache de marque + 8 Gio de cache non compressé +- 2 Gio demandés / 4 Gio limite de mémoire dans l'overlay de base fourni (dimensionné pour tenir dans de petits nœuds POC/staging) ; les clients en production devraient augmenter — le plancher recommandé est 2c / 4Gi demandé, 6c / 8Gi limite. `max_server_memory_usage_to_ram_ratio=0.9` +- Cache de marques de 5 Gio + cache non compressé de 8 Gio - `background_pool_size=16`, `background_merges_mutations_concurrency_ratio=2` - MergeTree : `parts_to_throw_insert=3000`, `parts_to_delay_insert=1500`, `non_replicated_deduplication_window=1000` - `local_io_method=auto` (io_uring sur les noyaux supportés) -- `fsync_metadata=0` : acceptable en raison de l'ingestion au moins une fois + déduplication ReplacingMergeTree -- `query_log` activé avec une TTL de 30 jours ; `query_thread_log` supprimé (coûteux à QPS élevé) +- `fsync_metadata=0` : acceptable grâce à l'ingest au-moins-une-fois + déduplication ReplacingMergeTree +- `query_log` activé avec TTL de 30 jours ; `query_thread_log` supprimé (coûteux à fort QPS) - `max_execution_time=30` pour les requêtes côté utilisateur -- PVC de 100 Gio au template StatefulSet (les overlays clients DEVRAIENT surcharger avec une classe de stockage SSD rapide pour la production) +- PVC de 100 Gio au template StatefulSet (les overlays clients DEVRAIENT le remplacer par une classe de stockage SSD rapide pour la production) ### Sauvegardes -Votre jeu de données complet est capturé chaque nuit dans une archive restaurable unique, de sorte qu'une perte de cluster ou de stockage est récupérable. ClickHouse est sauvegardé automatiquement par le CronJob quotidien `agenteye-backup`, qui vide à la fois PostgreSQL et ClickHouse en un seul passage. ClickHouse est lu via son API HTTP : `agenteye.events` et `agenteye.evaluations` sont vidés au format natif ClickHouse (les vues et politiques de lignes sont recréées par le serveur au démarrage, donc les données de table constituent le tableau complet) et regroupés avec le dump Postgres dans une archive compressée unique téléchargée vers votre stockage objet. +Votre jeu de données complet est capturé chaque nuit dans une seule archive restaurable, de sorte qu'une perte de cluster ou de stockage est récupérable. ClickHouse est sauvegardé automatiquement par le CronJob quotidien `agenteye-backup`, qui dump à la fois PostgreSQL et ClickHouse en une seule passe. ClickHouse est lu via son API HTTP : `agenteye.events` et `agenteye.evaluations` sont dumpés au format natif ClickHouse (les vues et politiques de lignes sont recréées par le serveur au démarrage, donc les données des tables constituent le tableau complet) et regroupés avec le dump Postgres dans une seule archive compressée téléchargée vers votre stockage objet. Le bucket de destination et les identifiants cloud sont configurés par overlay. Voir la section **Sauvegardes** de [enterprise-docs/kubernetes-deployment.md](/fr/agenteye/kubernetes-deployment) pour la configuration de téléchargement et les étapes de restauration. @@ -248,31 +247,31 @@ Le bucket de destination et les identifiants cloud sont configurés par overlay. ## Redis (cache optionnel) -Redis est un backend de cache partagé + limitation de débit **optionnel** utilisé par le serveur et le tableau de bord. Avec Redis déployé et `REDIS_URL` défini sur les deux services : +Redis est un backend de cache partagé et de limitation de débit **optionnel** utilisé par le serveur et le tableau de bord. Avec Redis déployé et `REDIS_URL` défini sur les deux services : -- **Le serveur** met en cache les recherches de clés API authentifiées, les listes `/events/environments` + `/evaluations/environments`, l'agrégat `/events/latency_aggregate` (la requête la plus lourde que le tableau de bord sonde), la liste `/sessions`, et passe la limitation de débit des requêtes OTP d'un `COUNT(*)` Postgres à un `INCR + EXPIRE` Redis. -- **Le tableau de bord** met en cache les résultats de `validateSession()` afin que les 10-20 appels API authentifiés qu'un chargement de page typique émet partagent tous une seule vérification de session amont. Il limite également le débit des requêtes OTP et des vérifications OTP au niveau de l'edge du tableau de bord. +- **Le serveur** met en cache les lookups de clés API authentifiées, les listes `/events/environments` + `/evaluations/environments`, le rollup `/events/latency_aggregate` (la requête la plus lourde que le tableau de bord interroge), la liste `/sessions`, et bascule la limitation de débit des requêtes OTP d'un `COUNT(*)` Postgres vers un `INCR + EXPIRE` Redis. +- **Le tableau de bord** met en cache les résultats de `validateSession()` pour que les 10 à 20 appels API authentifiés qu'un chargement de page typique émet partagent tous une seule vérification de session en amont. Il limite également le débit des requêtes OTP et des vérifications OTP au niveau edge du tableau de bord. -**Les deux services dégradent gracieusement si Redis est injoignable.** Chaque appel de cache retourne `Err` dans un délai limité et l'appelant se rabat sur la source de vérité (Postgres sur le serveur, le serveur Rust amont sur le tableau de bord). La limitation de débit OTP se rabat sur le chemin `COUNT(*)` Postgres sur le serveur (la propriété de sécurité est préservée) ; la limite OTP de l'edge du tableau de bord s'ouvre en cas d'échec tandis que la limite côté serveur tient toujours. Une panne Redis dégrade la latence, pas la cohérence. +**Les deux services se dégradent gracieusement si Redis est inaccessible.** Chaque appel au cache retourne `Err` dans un timeout borné et l'appelant revient à la source de vérité (Postgres sur le serveur, le serveur Rust en amont sur le tableau de bord). La limitation de débit OTP revient au chemin `COUNT(*)` Postgres sur le serveur (la propriété de sécurité est préservée) ; la limite OTP edge du tableau de bord échoue ouverte tandis que la limite côté serveur tient toujours. L'indisponibilité de Redis dégrade la latence, pas la correction. ### Configuration -Le bundle docker-compose inclut déjà un service Redis et câble `REDIS_URL=redis://redis:6379/0` dans le serveur et le tableau de bord. Pour utiliser un Redis externe, définissez `REDIS_URL` vers votre endpoint et supprimez le service `redis` du fichier compose. +Le bundle docker-compose inclut déjà un service Redis et câble `REDIS_URL=redis://redis:6379/0` dans le serveur et le tableau de bord. Pour utiliser un Redis externe, définissez `REDIS_URL` vers votre endpoint et retirez le service `redis` du fichier compose. ### Mémoire et persistance -L'image Redis fournie s'exécute avec `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. La persistance AOF signifie que le cache survit aux redémarrages de conteneur ; `everysec` est le bon équilibre durabilité/performance car perdre la dernière seconde d'écritures de cache est sans conséquence. L'éviction LRU plafonne la croissance de la mémoire. +L'image Redis fournie s'exécute avec `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. La persistance AOF signifie que le cache survit aux redémarrages des conteneurs ; `everysec` est le bon équilibre durabilité/performances car perdre la dernière seconde d'écritures cache est sans conséquence. L'éviction LRU plafonne la croissance mémoire. ### Quand NE PAS déployer Redis -- Développement/QA à instance unique. Les caches en cours de processus sur le serveur seul apportent la plupart des bénéfices par réplica ; Redis ajoute le partage inter-réplicas dont les configurations à instance unique n'ont pas besoin. -- Installations air-gapped où le coût opérationnel de faire fonctionner un service supplémentaire l'emporte sur le gain de latence. +- Développement/QA sur instance unique. Les caches en mémoire du serveur seul offrent la plupart des bénéfices par réplica ; Redis ajoute le partage inter-réplicas dont les configurations mono-instance n'ont pas besoin. +- Installations isolées (air-gapped) où le coût opérationnel de faire tourner un service supplémentaire dépasse le gain en latence. --- ## Docker Compose (recommandé) -Un `docker-compose.yml` est disponible dans le dépôt `agenteye-enterprise/releases`. Il lance Postgres, ClickHouse, Redis, le serveur et le tableau de bord avec une seule commande. +Un `docker-compose.yml` est disponible dans le dépôt `agenteye-enterprise/releases`. Il démarre Postgres, le serveur et le tableau de bord avec une seule commande. ```bash GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ @@ -282,7 +281,7 @@ GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ cd agenteye ``` -**Surcharger les valeurs par défaut via `.env` :** +**Remplacer les valeurs par défaut via `.env` :** ``` # Utilisez des mots de passe sûrs pour les URL (sans /, + ou =). @@ -324,53 +323,53 @@ docker compose down -v ## Paramètres opérationnels -Un petit ensemble de paramètres opérationnels qui étaient auparavant fixés par des variables d'environnement sont maintenant modifiables par organisation depuis la page **`//settings`** du tableau de bord ; chaque organisation configure les siens. Les modifications prennent effet en quelques secondes, sans redémarrage ni redéploiement. +Un petit ensemble de réglages opérationnels qui étaient autrefois fixés par des variables d'environnement sont maintenant modifiables par organisation depuis la page **`//settings`** du tableau de bord ; chaque organisation configure les siens. Les modifications prennent effet en quelques secondes, sans redémarrage ni redéploiement. -| Paramètre | Variable d'environnement de bootstrap | Ce qu'il contrôle | +| Paramètre | Variable d'environnement de démarrage | Ce qu'il contrôle | |---|---|---| | Connexions autorisées | `ALLOWED_EMAILS` | Emails (ou jokers `*@domain.com`) autorisés à recevoir un OTP et à être ajoutés comme utilisateurs | -| Permissions utilisateur par défaut | `DEFAULT_USER_PERMISSIONS` | Tokens de permission séparés par des virgules présélectionnés quand un administrateur ouvre **+ nouvel utilisateur**. Chaque token doit être l'une des chaînes listées sous [Permissions des clés API](/fr/agenteye/api-keys). Par défaut, le préréglage `standard` : accès en lecture seule plus les actions quotidiennes d'astreinte (déclencher des réévaluations, exécuter des requêtes, acquitter des incidents, utiliser l'assistant). | -| Durée de vie de la session | `SESSION_TTL_SECS` | Durée pendant laquelle une connexion au tableau de bord reste valide avant une nouvelle authentification. Le tableau de bord revérifie la session amont toutes les 5 secondes, donc une mise à jour des permissions sur `//users` prend effet à la prochaine requête de l'utilisateur concerné, sans reconnexion. | +| Permissions utilisateur par défaut | `DEFAULT_USER_PERMISSIONS` | Tokens de permission séparés par des virgules présélectionnés lorsqu'un administrateur ouvre **+ nouvel utilisateur**. Chaque token doit être l'une des chaînes listées sous [Permissions des clés API](/fr/agenteye/api-keys). Par défaut, le préréglage `standard` : accès en lecture seule plus les actions quotidiennes d'astreinte (déclencher des réévaluations, exécuter des requêtes, acquitter des incidents, utiliser l'assistant). | +| Durée de vie de la session | `SESSION_TTL_SECS` | Durée pendant laquelle une connexion au tableau de bord reste valide avant une nouvelle authentification. Le tableau de bord re-vérifie la session en amont toutes les 5 secondes, donc une mise à jour des permissions sur `//users` prend effet à la prochaine requête de l'utilisateur concerné, sans reconnexion. | | Durée de vie du code à usage unique | `OTP_TTL_SECS` | Durée pendant laquelle un OTP / lien magique reste utilisable | -| Canaux de notification d'alerte | `ALERTS_ENABLED_CHANNELS` | Liste de types de canaux séparés par des virgules que le répartiteur d'alertes est autorisé à utiliser : `email`, `slack`, `webhook`. La configuration par alerte est toujours créée sur `//alerts/`, mais le répartiteur filtre chaque livraison sortante à travers cet ensemble ; un canal désactivé ici court-circuite avec une ligne d'audit `skipped_disabled`. Le canal `dashboard` (l'insertion d'audit locale) est toujours autorisé. Par défaut, les trois sont activés. | +| Canaux de notification d'alerte | `ALERTS_ENABLED_CHANNELS` | Liste séparée par des virgules des types de canaux que le dispatcher d'alertes est autorisé à utiliser : `email`, `slack`, `webhook`. La configuration par alerte est toujours créée sur `//alerts/`, mais le dispatcher filtre chaque livraison sortante à travers cet ensemble ; un canal désactivé ici court-circuite avec une ligne d'audit `skipped_disabled`. Le canal `dashboard` (l'insertion d'audit locale) est toujours autorisé. Par défaut, les trois sont activés. | -### Fonctionnement du bootstrap +### Fonctionnement du démarrage -Les paramètres sont stockés par organisation dans `org_settings`. Au premier démarrage, le serveur initialise les lignes manquantes de l'organisation par défaut à partir de la variable d'environnement correspondante (ou d'une valeur par défaut raisonnable si la variable d'environnement n'est pas définie). Après cela, **la valeur stockée fait foi et la variable d'environnement est ignorée** ; modifier la variable d'environnement lors d'un redémarrage ultérieur n'affectera pas la valeur d'une organisation en production, et les organisations supplémentaires démarrent avec les valeurs par défaut et configurent les leurs. +Les paramètres sont stockés par organisation dans `org_settings`. Au premier démarrage, le serveur alimente les lignes manquantes de l'organisation par défaut à partir de la variable d'environnement correspondante (ou d'une valeur par défaut raisonnable si la variable d'environnement n'est pas définie). Après cela, **la valeur stockée est la source de vérité et la variable d'environnement est ignorée** ; modifier la variable d'environnement lors d'un redémarrage ultérieur n'affectera pas la valeur d'une organisation active, et les organisations supplémentaires démarrent avec des valeurs par défaut et configurent les leurs. Cela signifie : - Pour un nouveau déploiement, définissez les variables d'environnement comme indiqué ci-dessus et l'organisation par défaut les lira au premier démarrage. - Pour modifier une valeur ultérieurement, connectez-vous au tableau de bord et modifiez-la sous `//settings`. La modification s'applique en quelques secondes sur tous les réplicas du serveur ; aucun redémarrage n'est nécessaire. -- Une ligne de log au démarrage enregistre ce qui a été initialisé par rapport à ce qui était déjà présent, afin que vous puissiez confirmer que le bootstrap a pris effet : +- Une ligne de log au démarrage enregistre ce qui a été initialisé vs. ce qui était déjà présent, pour vous permettre de confirmer que le démarrage a pris effet : ```text INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true ``` -#### Sémantique de connexion entre organisations +#### Sémantiques de connexion entre organisations -Une session et un OTP sont globaux à l'utilisateur, pas à une seule organisation, donc deux règles réconcilent les paramètres par organisation au moment de la connexion : +Une session et un OTP sont globaux à l'utilisateur, pas à une seule organisation, donc deux règles conccilient les paramètres par organisation au moment de la connexion : -- **Durée de vie de la session / OTP** : la durée la plus stricte (la plus courte) parmi les organisations auxquelles l'utilisateur appartient l'emporte. -- **Connexions autorisées** : le filtre effectue un OU de la liste d'autorisation de chaque organisation avec l'appartenance à l'organisation : un utilisateur peut demander un OTP si la liste d'autorisation d'une organisation admet son email **ou** s'il est déjà membre d'une organisation. +- **Durée de vie de la session / OTP** : la durée de vie la plus stricte (la plus courte) parmi les organisations auxquelles l'utilisateur appartient l'emporte. +- **Connexions autorisées** : la porte fait un OU de la liste blanche de chaque organisation avec l'appartenance à l'organisation : un utilisateur peut demander un OTP si la liste blanche de n'importe quelle organisation admet son email **ou** s'il est déjà membre de n'importe quelle organisation. ### Permissions L'accès à une page `//settings` est conditionné par deux permissions : - `settings:read` : voir la page et les valeurs actuelles. -- `settings:write` : enregistrer les modifications. +- `settings:write` : sauvegarder les modifications. -L'utilisateur administrateur de bootstrap (initialisé depuis `ADMIN_EMAIL`) obtient les deux automatiquement avec toutes les autres permissions. Accordez-les à d'autres utilisateurs depuis `//users` selon les besoins. +L'utilisateur administrateur de démarrage (initialisé à partir de `ADMIN_EMAIL`) obtient les deux automatiquement avec toutes les autres permissions. Accordez-les à d'autres utilisateurs depuis `//users` selon les besoins. --- -## Organisations (multi-tenant) +## Organisations (multi-tenancy) -Un seul déploiement peut servir plusieurs **organisations** (tenants) isolées ; chaque ligne de données appartient exactement à une organisation et l'isolation est appliquée dans le moteur de base de données. Une installation mono-tenant n'a besoin de rien ici ; toutes les données résident dans une organisation `default` intégrée. (Vous pouvez donner à cette organisation un nom plus convivial et un slug d'URL, afin qu'elle réside par exemple en `/acme` plutôt qu'en `/default`, en définissant `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` avant le premier démarrage, ou en la renommant à tout moment avec `agenteye-orgctl org rename`.) +Un seul déploiement peut servir plusieurs **organisations** (tenants) isolées ; chaque ligne de données appartient exactement à une organisation et l'isolation est appliquée dans le moteur de base de données. Une installation mono-tenant n'a rien à faire ici ; toutes les données vivent dans une organisation `default` intégrée. (Vous pouvez donner à cette organisation un nom plus convivial et un slug d'URL, pour qu'elle vive par ex. à `/acme` au lieu de `/default`, en définissant `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` avant le premier démarrage, ou en la renommant à tout moment avec `agenteye-orgctl org rename`.) -**Le provisionnement des tenants est réservé aux opérateurs.** Les organisations et leurs appartenances sont créées et gérées avec le CLI **`agenteye-orgctl`**, qui est livré **à l'intérieur de l'image du serveur** (aux côtés de `agenteye-server`) et s'exécute **à l'intérieur du pod serveur existant** ; il n'y a **pas de pod/Job séparé, pas d'API HTTP et pas de bouton dans le tableau de bord**. Il réutilise le `DATABASE_URL`, `CLICKHOUSE_URL` et `ORG_CH_SECRET` du serveur. +**Le provisionnement des tenants est réservé aux opérateurs.** Les organisations et leurs membres sont créés et gérés avec la CLI **`agenteye-orgctl`**, qui est embarquée **dans l'image du serveur** (aux côtés de `agenteye-server`) et s'exécute **dans le pod serveur existant** ; il n'y a **pas de pod/Job séparé, pas d'API HTTP, et pas de bouton dans le tableau de bord**. Elle réutilise `DATABASE_URL`, `CLICKHOUSE_URL` et `ORG_CH_SECRET` du serveur. ```bash # Docker Compose - exec dans le service serveur en cours d'exécution : @@ -381,19 +380,19 @@ docker compose exec server agenteye-orgctl member add --org acme --email alice@a kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list ``` -Verbes disponibles : `org create | list | rename | delete | purge` et `member add | list | update | remove`, avec des ensembles de permissions intégrés `admin`, `standard` et `read-only`. Les membres ajoutés reçoivent un OTP lors de leur première connexion au tableau de bord. +Verbes disponibles : `org create | list | rename | delete | purge` et `member add | list | update | remove`, avec les ensembles de permissions intégrés `admin`, `standard` et `read-only`. Les membres ajoutés reçoivent un OTP lors de leur première connexion au tableau de bord. -**Avant de créer une deuxième organisation :** définissez un `ORG_CH_SECRET` fort et stable (la commande `org create` refuse de s'exécuter avec la valeur de développement par défaut intégrée) et assurez-vous que Postgres est en **15+**. **Inchangé :** les clés API par organisation sont toujours créées dans le tableau de bord/API par les membres de l'organisation ; seul le cycle de vie des organisations + membres a été déplacé vers le CLI. Référence complète des commandes et exemple concret : **[enterprise-docs/tenant-management.md](/fr/agenteye/tenant-management)**. +**Avant de créer une deuxième organisation :** définissez un `ORG_CH_SECRET` fort et stable (la commande `org create` refuse de s'exécuter avec la valeur dev intégrée par défaut) et assurez-vous que Postgres est en version **15+**. **Inchangé :** les clés API par organisation sont toujours créées dans le tableau de bord/l'API par les membres de l'organisation ; seul le cycle de vie des organisations et des membres a été déplacé vers la CLI. Référence complète des commandes et exemple détaillé : **[enterprise-docs/tenant-management.md](/fr/agenteye/tenant-management)**. --- ## Remplissage de la fenêtre de contexte -Chaque événement `model_response` affiche une **pastille de remplissage de contexte** — les tokens d'entrée plus les tokens de sortie en pourcentage de la fenêtre de contexte de ce modèle. Les bandes sont `healthy` (0-24 %), `watch` (25-49 %), `compacting` (50-74 %) et `reset context` (75-100 %). AgentEye résout automatiquement les identifiants de modèles courants, donc aucune configuration initiale n'est requise. +Chaque événement `model_response` affiche une **pastille de remplissage de contexte** — les tokens d'entrée plus les tokens de sortie en pourcentage de la fenêtre de contexte de ce modèle. Les plages sont `healthy` (0–24 %), `watch` (25–49 %), `compacting` (50–74 %), et `reset context` (75–100 %). AgentEye résout automatiquement les identifiants de modèles courants, donc aucune configuration initiale n'est requise. -Chaque modèle qu'une organisation envoie apparaît sous **Paramètres → fenêtres de contexte des modèles**. Les utilisateurs avec `settings:write` peuvent remplacer sa fenêtre ou ajouter un modèle privé/proxy (0-1 000 000 tokens) ; `0` signifie inconnu et supprime la pastille. Les modifications s'appliquent aux événements nouvellement ingérés. Les utilisateurs avec `settings:read` peuvent consulter la liste. +Chaque modèle qu'une organisation envoie apparaît sous **Paramètres → fenêtres de contexte de modèle**. Les utilisateurs avec `settings:write` peuvent remplacer sa fenêtre ou ajouter un modèle privé/proxy (0–1 000 000 tokens) ; `0` signifie « inconnu » et supprime la pastille. Les modifications s'appliquent aux événements nouvellement ingérés. Les utilisateurs avec `settings:read` peuvent consulter la liste. -Les nouveaux événements obtiennent le remplissage dès le moment où vous mettez à niveau. Pour également renseigner les événements **historiques** (et la liste par modèle) pour un déploiement existant, exécutez le backfill ponctuel — il est livré à l'intérieur de l'image du serveur (comme `agenteye-orgctl`) et s'exécute dans le pod serveur existant : +Les nouveaux événements reçoivent le remplissage à partir du moment où vous effectuez la mise à niveau. Pour également renseigner les événements **historiques** (et la liste par modèle) pour un déploiement existant, exécutez le backfill ponctuel — il est embarqué dans l'image du serveur (comme `agenteye-orgctl`) et s'exécute dans le pod serveur existant : ```bash # aperçu (affiche la mutation par organisation, ne change rien) : @@ -404,25 +403,25 @@ kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window docker compose exec server agenteye-backfill-context-window ``` -Il est idempotent (sûr à relancer) et réutilise `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` depuis le pod. Relancez-le après avoir modifié les fenêtres de modèles si vous souhaitez que les événements existants soient recalculés. +Il est idempotent (sûr à ré-exécuter) et réutilise `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` depuis le pod. Ré-exécutez-le après avoir modifié les fenêtres de modèles si vous souhaitez que les événements existants soient recalculés. --- -## Considérations de production +## Considérations pour la production -- **Postgres** : Utilisez un service Postgres géré ou une instance dédiée avec des sauvegardes régulières. Le `DATABASE_URL` prend en charge tous les paramètres libpq standard, y compris `sslmode=require` pour les connexions chiffrées. -- **TLS** : Placez le serveur et le tableau de bord derrière un reverse proxy (nginx, Caddy, Traefik) qui termine TLS. -- **Pare-feu** : Le port du serveur (par défaut 8080) ne doit être accessible que depuis les machines de collecteur et l'hôte du tableau de bord, pas depuis l'internet public. -- **Clé admin** : Définissez `ADMIN_KEY` sur un secret aléatoire fort. Après le bootstrap, créez des clés dédiées et restreintes pour les collecteurs et le tableau de bord plutôt que d'utiliser la clé admin partout. -- **Tags d'image** : Épinglez la version dans vos manifestes de release (par exemple, `server:v0.0.1-beta.48`) en production plutôt qu'un tag flottant pour éviter les mises à niveau non intentionnelles. Les builds bêta actuels publient sous `beta-latest` ; `latest` n'est attribué qu'aux versions stables. -- **Surveillance de la santé** : Sur Kubernetes, la sonde de readiness utilise `/ready` (accessibilité Postgres + ClickHouse) tandis que la liveness reste sur `/health`. Pour les alertes Slack à l'échelle de la flotte sur l'état d'AgentEye, activez le module complémentaire Robusta optionnel ; voir [enterprise-docs/health-monitoring.md](/fr/agenteye/health-monitoring). +- **Postgres** : Utilisez un service Postgres géré ou une instance dédiée avec des sauvegardes régulières. Le `DATABASE_URL` supporte tous les paramètres libpq standard, y compris `sslmode=require` pour les connexions chiffrées. +- **TLS** : Placez le serveur et le tableau de bord derrière un proxy inverse (nginx, Caddy, Traefik) qui termine TLS. +- **Pare-feu** : Le port du serveur (par défaut 8080) ne doit être accessible que depuis les machines collectrices et l'hôte du tableau de bord, pas depuis l'internet public. +- **Clé admin** : Définissez `ADMIN_KEY` avec un secret aléatoire fort. Après l'initialisation, créez des clés dédiées à portée limitée pour les collecteurs et le tableau de bord plutôt que d'utiliser la clé admin partout. +- **Tags d'images** : Épinglez à la version dans vos manifestes de release (par exemple, `server:v0.0.1-beta.48`) en production plutôt qu'un tag flottant pour éviter les mises à niveau non intentionnelles. Les builds beta actuels sont publiés sous `beta-latest` ; `latest` est réservé aux versions stables. +- **Surveillance de l'état** : Sur Kubernetes, la sonde de readiness utilise `/ready` (accessibilité Postgres + ClickHouse) tandis que la liveness reste sur `/health`. Pour des alertes Slack à l'échelle de la flotte sur la disponibilité d'AgentEye lui-même, activez l'add-on Robusta opt-in ; voir [enterprise-docs/health-monitoring.md](/fr/agenteye/health-monitoring). --- -## Tags d'image disponibles +## Tags d'images disponibles | Tag | Description | |-----|-------------| | `latest` | Dernière version stable | -| `beta-latest` | Dernière pré-version (bêta) | +| `beta-latest` | Dernière version pré-release (bêta) | | `v` | Version épinglée, ex. `v0.0.1-beta.48` (recommandé pour la production) | \ No newline at end of file diff --git a/docs/fr/agenteye/getting-started.mdx b/docs/fr/agenteye/getting-started.mdx index 5d669ed7..c2921653 100644 --- a/docs/fr/agenteye/getting-started.mdx +++ b/docs/fr/agenteye/getting-started.mdx @@ -1,10 +1,10 @@ --- -title: "Démarrer avec AgentEye" +title: "Démarrage avec AgentEye" description: "Documentation de démarrage avec AgentEye." --- -Ce guide vous accompagne dans une configuration complète d'AgentEye : déploiement du serveur et du tableau de bord, installation du collecteur sur une machine agent, et instrumentation de votre code d'agent Python. +Ce guide vous accompagne pas à pas dans la configuration complète d'AgentEye : déploiement du serveur et du tableau de bord, installation du collecteur sur une machine d'agent, et instrumentation de votre code d'agent Python. --- @@ -12,18 +12,18 @@ Ce guide vous accompagne dans une configuration complète d'AgentEye : déploiem AgentEye est une **plateforme d'observabilité et d'évaluation auto-hébergée pour les agents IA**. Elle enregistre ce que font vos agents — chaque étape d'une exécution — et note automatiquement la qualité de chaque exécution terminée, afin que vous puissiez observer le comportement de vos agents en production et détecter les régressions avant vos utilisateurs. -Les données circulent dans un seul sens : votre code agent émet des **événements** via le **SDK Python** → un daemon **collecteur** léger les regroupe et les envoie au **serveur** → les événements et les analyses sont stockés dans **ClickHouse** (l'état opérationnel, comme les organisations, les utilisateurs, les clés API, les tableaux de bord et les requêtes sauvegardées, est conservé dans **Postgres**) → vous explorez tout depuis le **tableau de bord**. +Les données circulent dans un seul sens : votre code d'agent émet des **événements** via le **SDK Python** → un démon **collecteur** léger les regroupe et les envoie au **serveur** → les événements et les analyses sont stockés dans **ClickHouse** (l'état opérationnel comme les organisations, les utilisateurs, les clés API, les tableaux de bord et les requêtes sauvegardées réside dans **Postgres**) → vous explorez tout dans le **tableau de bord**. Ce que vous obtenez : - **Événements** — la trace brute, étape par étape, de chaque exécution d'agent (appels d'outils, appels de modèles, hooks, erreurs). - **Sessions** — ces événements regroupés en une ligne par exécution, chacune **évaluée et notée automatiquement**. -- **Évaluations** — scores de qualité produits par vos propres services d'évaluation, afin que les baisses de qualité remontent sans révision manuelle. -- **Requêtes et tableaux de bord** — SQL ClickHouse sauvegardé sur vos données, visualisé dans des tableaux de bord partagés à l'échelle de l'organisation. -- **Alertes et incidents** — règles de seuil qui vous notifient (e-mail, Slack, webhook, dans le tableau de bord) et un workflow d'incidents pour les traiter. +- **Évaluations** — scores de qualité produits par vos propres services d'évaluation, pour que les baisses de qualité remontent à la surface sans révision manuelle. +- **Requêtes et tableaux de bord** — SQL ClickHouse sauvegardé sur vos données, transformé en tableaux de bord partagés à portée organisationnelle. +- **Alertes et incidents** — règles de seuil qui vous notifient (email, Slack, webhook, dans le tableau de bord), avec un workflow de triage des incidents. - **CLI et assistant IA** — un client terminal (`agenteye`) et un assistant intégré au tableau de bord pour poser des questions en langage naturel. -Vous faites tourner l'ensemble dans votre propre infrastructure, sous forme d'une stack Docker Compose (ce guide), d'une installation Kubernetes en production, ou d'un pod co-localisé. La suite de ce guide configure la stack Compose de bout en bout. +Vous faites tourner l'ensemble dans votre propre infrastructure, sous forme d'une stack Docker Compose (ce guide), d'une installation Kubernetes en production, ou d'un pod unique co-localisé. La suite de ce guide configure la stack Compose de bout en bout. --- @@ -42,7 +42,7 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin ## Étape 2 : Déployer le serveur et le tableau de bord -Le serveur reçoit les événements des collecteurs et les rend interrogeables ; le tableau de bord est l'endroit où vous les explorez. Les événements ingérés et les analyses résident dans ClickHouse (la base d'analyse requise), tandis que Postgres conserve l'état opérationnel tel que les organisations, les utilisateurs, les clés API, les tableaux de bord et les requêtes sauvegardées. +Le serveur reçoit les événements des collecteurs et les rend interrogeables ; le tableau de bord est l'endroit où vous les explorez. Les événements ingérés et les analyses résident dans ClickHouse (le store d'analyse requis), tandis que Postgres conserve l'état opérationnel comme les organisations, les utilisateurs, les clés API, les tableaux de bord et les requêtes sauvegardées. **Télécharger le fichier compose publié :** @@ -57,26 +57,20 @@ cd agenteye **Définir vos secrets :** -Créez un fichier `.env` pour que le déploiement ne tourne pas avec le credential `admin` par défaut. Définissez au minimum `ADMIN_KEY` et `POSTGRES_PASSWORD` : +Créez un fichier `.env` pour que le déploiement ne tourne pas avec les identifiants `admin` par défaut. Définissez au minimum `ADMIN_KEY` et `POSTGRES_PASSWORD` : ```bash POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -Exportez également `ADMIN_KEY` dans votre shell courant pour que les étapes suivantes (par exemple le `curl` de l'étape 3) puissent le référencer directement : - -```bash -export ADMIN_KEY=your-admin-secret -``` - **Démarrer la stack :** ```bash docker compose up -d ``` -Cela lance la stack complète, incluant la base d'analyse ClickHouse requise et un cache Redis optionnel, aux côtés du serveur et du tableau de bord. ClickHouse doit être opérationnel pour que le serveur puisse démarrer. +Cela lance la stack complète, incluant le store d'analyse ClickHouse requis et un cache Redis optionnel, aux côtés du serveur et du tableau de bord. ClickHouse doit être opérationnel pour que le serveur démarre. Le serveur écoute désormais sur `http://localhost:8080` et le tableau de bord sur `http://localhost:3000`. @@ -95,13 +89,13 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -Vous fournissez vous-même la valeur `key` ; utilisez-la dans la configuration du collecteur à l'étape 4. Consultez [enterprise-docs/api-keys.md](/fr/agenteye/api-keys) pour la gestion complète des clés. +Vous fournissez vous-même la valeur de `key` ; utilisez-la dans la configuration du collecteur à l'étape 4. Consultez [enterprise-docs/api-keys.md](/fr/agenteye/api-keys) pour la gestion complète des clés. --- ## Étape 4 : Installer le collecteur -Sur chaque machine qui exécute vos agents IA, installez le daemon collecteur. +Sur chaque machine qui exécute vos agents IA, installez le démon collecteur. **Télécharger le binaire (Linux x86_64) :** @@ -114,7 +108,7 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> Ceci télécharge le build **Linux x86_64**. Pour macOS (Apple Silicon ou Intel), Linux arm64, ou la configuration Docker / systemd / launchd, consultez [collector-installation.md](/fr/agenteye/collector-installation), qui liste les téléchargements pour chaque plateforme — la commande ci-dessus installe un binaire Linux qui ne fonctionnera pas ailleurs. +> Ceci télécharge le build **Linux x86_64**. Pour macOS (Apple Silicon ou Intel), Linux arm64, ou la configuration Docker / systemd / launchd, consultez [collector-installation.md](/fr/agenteye/collector-installation), qui liste le téléchargement pour chaque plateforme — la commande ci-dessus installe un binaire Linux qui ne fonctionnera pas ailleurs. **Configurer :** @@ -128,19 +122,19 @@ cat > ~/.agenteye/config.json </…`). +Avec les événements qui transitent, les pages **analyser** transforment l'activité brute en réponses, pour mesurer le comportement des agents, partager les résultats avec l'équipe et être notifié dès qu'une régression survient. Les pages de tableau de bord sont à portée organisationnelle, donc les URLs visibles dans la barre d'adresse sont préfixées par votre slug d'organisation (`//…`). -- **Requêtes** (`//queries`) : partez d'une bibliothèque de requêtes sauvegardées et réutilisables sur vos événements et évaluations (préréglages intégrés et les vôtres)… +- **Requêtes** (`//queries`) : commencez par une bibliothèque de requêtes sauvegardées et réutilisables sur vos événements et évaluations (préréglages intégrés et les vôtres)… ![La bibliothèque de requêtes sauvegardées : une grille de requêtes réutilisables, à la fois des préréglages intégrés et des requêtes personnalisées](/agenteye/images/queries.png) - …puis ouvrez-en une dans le compositeur SQL pour la modifier et l'exécuter avec des résultats en direct : + …puis ouvrez-en une dans le compositeur SQL pour l'ajuster et l'exécuter avec des résultats en direct : ![Le compositeur de requêtes SQL exécutant une requête sauvegardée, avec une barre latérale de schéma et une grille de résultats en direct](/agenteye/images/query-lab.png) -- **Tableaux de bord** (`//dashboards`) : épinglez des requêtes sous forme de tuiles en courbe, barres, aires ou secteurs dans des tableaux de bord partagés à l'échelle de l'organisation. +- **Tableaux de bord** (`//dashboards`) : épinglez des requêtes sous forme de tuiles ligne, barre, aire ou camembert dans des tableaux de bord partagés à l'échelle de l'organisation. -![Un tableau de bord construit à partir de requêtes sauvegardées : une courbe d'événements par heure, un graphique en barres d'erreurs par type, un graphique en aires de latence, et les tokens par modèle](/agenteye/images/dashboard-fleet.png) +![Un tableau de bord construit à partir de requêtes sauvegardées : une ligne d'événements par heure, un graphique à barres d'erreurs par type, un graphique en aire de latence et des tokens par modèle](/agenteye/images/dashboard-fleet.png) -- **Alertes** (`//alerts`) : transformez n'importe quel seuil en règle de notification par e-mail, Slack, webhook ou dans le tableau de bord. Consultez [enterprise-docs/alerts.md](/fr/agenteye/alerts). +- **Alertes** (`//alerts`) : transformez n'importe quel seuil en règle de notification par email, Slack, webhook ou dans le tableau de bord. Consultez [enterprise-docs/alerts.md](/fr/agenteye/alerts). --- -## Étapes suivantes +## Prochaines étapes - [Déploiement](/fr/agenteye/deployment) : renforcer pour la production - [Clés API](/fr/agenteye/api-keys) : gérer les accès diff --git a/docs/fr/agenteye/managed-deployment.mdx b/docs/fr/agenteye/managed-deployment.mdx index c130548d..b602e140 100644 --- a/docs/fr/agenteye/managed-deployment.mdx +++ b/docs/fr/agenteye/managed-deployment.mdx @@ -3,16 +3,15 @@ title: "Déploiement géré sur votre cluster Kubernetes" description: "Documentation du déploiement géré AgentEye sur votre cluster Kubernetes." --- +AgentEye est une plateforme d'observabilité et d'évaluation auto-hébergée pour les agents IA et LLM. Elle capture les sessions d'agents, les appels d'outils, les requêtes aux modèles et les erreurs, les transforme en analyses et évaluations interrogeables, et présente les résultats dans un tableau de bord avec un assistant IA optionnel en lecture seule. -AgentEye est une plateforme d'observabilité et d'évaluation auto-hébergée pour les agents IA et LLM. Elle capture les sessions d'agents, les appels d'outils, les requêtes de modèles et les erreurs, les transforme en analyses et évaluations consultables, et présente les résultats dans un tableau de bord avec un assistant IA optionnel en lecture seule. - -Dans le modèle de déploiement géré, vous fournissez un cluster Kubernetes dédié et Exosphere exécute la plateforme complète en son sein — déployant, configurant, opérant, sauvegardant et mettant à jour chaque composant en votre nom. Votre équipe bénéficie de la valeur de la plateforme (visibilité sur les agents, analyses, évaluation et l'assistant optionnel) sans avoir à gérer les bases de données, les certificats ou les mises à jour. Toutes les données restent dans votre compte cloud. +Dans le modèle de déploiement géré, vous fournissez un cluster Kubernetes dédié et Exosphere exécute l'ensemble de la plateforme en son sein : déploiement, configuration, exploitation, sauvegarde et mise à jour de chaque composant en votre nom. Votre équipe bénéficie de toute la valeur de la plateforme (visibilité sur les agents, analyses, évaluation et assistant optionnel) sans avoir à gérer des bases de données, des certificats ou des mises à jour. Toutes les données restent dans votre compte cloud. --- ## Prérequis -- Un **GitHub PAT** pour extraire les images de conteneurs et télécharger les artefacts (voir [Configuration du token GitHub](/fr/agenteye/github-token)) +- Un **GitHub PAT** pour récupérer les images de conteneurs et télécharger les artefacts (voir [enterprise-docs/github-token.md](/fr/agenteye/github-token)) - Un **cluster Kubernetes dédié** (voir les exigences ci-dessous) - Un **bucket de stockage** pour les sauvegardes de bases de données - **Connectivité réseau** : port 443 entrant vers le load balancer du cluster @@ -21,17 +20,17 @@ Dans le modèle de déploiement géré, vous fournissez un cluster Kubernetes d ## Étape 1 : Provisionner un cluster Kubernetes dédié -Créez un cluster Kubernetes dédié à AgentEye. Il ne doit pas être partagé avec d'autres charges de travail, afin que la plateforme complète (services applicatifs, bases de données, analyses et mise en cache) s'exécute en isolation sans impacter votre infrastructure existante. +Créez un cluster Kubernetes dédié à AgentEye. Il ne doit pas être partagé avec d'autres charges de travail, afin que l'ensemble de la plateforme (services applicatifs, bases de données, analyses et cache) s'exécute de manière isolée sans impacter votre infrastructure existante. | Exigence | Détails | |---|---| -| **Distribution** | Tout Kubernetes conforme : EKS, GKE, AKS, ou autogéré | +| **Distribution** | Tout Kubernetes conforme : EKS, GKE, AKS ou autogéré | | **Version** | 1.27 ou ultérieure | | **Pool de nœuds** | Minimum : **3 nœuds, 4 vCPU / 8 Go de RAM chacun** (instances standard à usage général) | | **Stockage** | Une StorageClass par défaut qui provisionne des volumes bloc (ex. `gp3` sur AWS, `pd-ssd` sur GCP) | | **Load Balancer** | Le cluster doit être capable de provisionner des services LoadBalancer cloud (par défaut sur EKS, GKE, AKS) | -> Exosphere installe et gère tout le reste à l'intérieur du cluster : contrôleurs d'ingress, certificats TLS, bases de données, mise en cache, monitoring et tous les déploiements applicatifs. +> Exosphere installe et gère tout le reste à l'intérieur du cluster : contrôleurs d'ingress, certificats TLS, bases de données, cache, supervision et tous les déploiements applicatifs. --- @@ -41,67 +40,67 @@ Exosphere a besoin d'un accès cluster-admin (ou d'un RBAC étendu équivalent) | Exigence | Détails | |---|---| -| **Méthode d'accès** | Rôle IAM (recommandé pour EKS/GKE), kubeconfig, ou accès SSO | -| **VPN / bastion** | Si le serveur API Kubernetes est privé, fournissez des identifiants VPN ou un accès bastion pour l'équipe opérationnelle Exosphere | +| **Méthode d'accès** | Rôle IAM (recommandé pour EKS/GKE), kubeconfig ou accès SSO | +| **VPN / bastion** | Si le serveur API Kubernetes est privé, fournissez des identifiants VPN ou un accès bastion à l'équipe opérationnelle Exosphere | --- ## Étape 3 : Configurer la connectivité réseau -Votre équipe réseau doit autoriser le trafic entrant sur le **port 443** vers les load balancers du cluster. Le déploiement utilise deux load balancers distincts : l'un pour l'ingestion d'événements (protégé par mTLS) et l'autre pour le tableau de bord : +Votre équipe réseau doit autoriser le trafic entrant sur le **port 443** vers les load balancers du cluster. Le déploiement utilise deux load balancers distincts : un pour l'ingestion d'événements (protégé par mTLS) et un pour le tableau de bord : | Trafic | Source | Destination | Sécurité | |---|---|---|---| | **Ingestion d'événements** | Pods collecteurs dans vos clusters | Load Balancer d'ingestion, port 443 | mTLS (certificat client) + clé API | | **Tableau de bord** | Navigateurs des développeurs | Load Balancer du tableau de bord, port 443 | HTTPS sur votre domaine, connexion OTP par email sans mot de passe | -Le point d'entrée d'ingestion est protégé par TLS mutuel ; les collecteurs doivent présenter un certificat client valide **et** une clé API valide à chaque requête. Le tableau de bord s'exécute sur son propre load balancer et nom d'hôte, avec la connexion restreinte aux adresses e-mail/domaines que vous avez autorisés. +Le point de terminaison d'ingestion est protégé par TLS mutuel ; les collecteurs doivent présenter un certificat client valide **et** une clé API valide à chaque requête. Le tableau de bord fonctionne sur son propre load balancer et son propre nom d'hôte, avec la connexion restreinte aux adresses e-mail/domaines que vous avez autorisés. -**Enregistrements DNS (une seule fois) :** vous créez deux enregistrements CNAME sous un domaine que vous contrôlez — l'un pour le point d'entrée d'ingestion et l'autre pour le tableau de bord (ex. `agenteye.votre-entreprise.exemple`) — pointant vers les noms d'hôtes des load balancers fournis par Exosphere. Exosphere provisionne ensuite automatiquement des certificats TLS publiquement approuvés pour les deux noms d'hôtes, y compris les renouvellements. +**Enregistrements DNS (opération unique) :** vous créez deux enregistrements CNAME sous un domaine que vous contrôlez — un pour le point de terminaison d'ingestion et un pour le tableau de bord (ex. `agenteye.votre-entreprise.example`) — pointant vers les noms d'hôtes des load balancers fournis par Exosphere. Exosphere provisionne ensuite automatiquement des certificats TLS publiquement fiables pour les deux noms d'hôtes, y compris les renouvellements. -> **Note sur le port 80 :** l'émission et le renouvellement automatiques des certificats s'effectuent via HTTP sur le port 80 de chaque load balancer. Si votre politique de sécurité nécessite de restreindre le load balancer du tableau de bord aux plages d'adresses IP d'entreprise, informez-en Exosphere au préalable — nous basculons la validation des certificats vers une méthode DNS (un enregistrement DNS supplémentaire de votre côté) afin que les renouvellements continuent de fonctionner derrière la restriction. +> **Note sur le port 80 :** l'émission et le renouvellement automatiques des certificats s'effectuent via HTTP sur le port 80 de chaque load balancer. Si votre politique de sécurité exige de restreindre le load balancer du tableau de bord à des plages d'IP d'entreprise, informez-en Exosphere au préalable — nous basculons la validation des certificats vers une méthode basée sur DNS (un enregistrement DNS supplémentaire de votre côté) afin que les renouvellements continuent de fonctionner derrière la restriction. -> **Trafic sortant :** les nœuds du cluster ont besoin d'un accès internet pour extraire les images de conteneurs depuis `ghcr.io`. Si votre réseau restreint le trafic sortant, autorisez `ghcr.io` ou copiez les images dans votre registre interne. +> **Sortant :** les nœuds du cluster ont besoin d'un accès internet pour récupérer les images de conteneurs depuis `ghcr.io`. Si votre réseau restreint le trafic sortant, autorisez `ghcr.io` ou mirrorez les images vers votre registre interne. --- ## Étape 4 : Fournir un bucket de stockage pour les sauvegardes -Les sauvegardes de bases de données sont stockées dans un bucket de stockage cloud qui vous appartient. +Les sauvegardes des bases de données sont stockées dans un bucket de stockage cloud qui vous appartient. | Exigence | Détails | |---|---| -| **Service** | S3 (AWS), GCS (GCP), ou Azure Blob Storage | -| **Accès** | Accordez l'accès en écriture aux nœuds du cluster via un rôle IAM pour les comptes de service (IRSA sur EKS, Workload Identity sur GKE) ou fournissez des identifiants | -| **Rétention** | Vous contrôlez la politique de cycle de vie du bucket (période de rétention, règles d'archivage). Exosphere écrit les sauvegardes ; vous décidez de la durée de conservation | +| **Service** | S3 (AWS), GCS (GCP) ou Azure Blob Storage | +| **Accès** | Accordez un accès en écriture aux nœuds du cluster via un rôle IAM pour les comptes de service (IRSA sur EKS, Workload Identity sur GKE) ou fournissez des identifiants | +| **Rétention** | Vous contrôlez la politique de cycle de vie du bucket (durée de rétention, règles d'archivage). Exosphere écrit les sauvegardes ; vous décidez de leur durée de conservation | -Une sauvegarde quotidienne unique exporte à la fois PostgreSQL (état relationnel) et ClickHouse (événements et évaluations) dans une archive compressée et la télécharge dans votre bucket. Les sauvegardes s'exécutent également avant chaque mise à jour. +Une sauvegarde quotidienne unique exporte à la fois PostgreSQL (état relationnel) et ClickHouse (événements et évaluations) dans une archive compressée qui est chargée dans votre bucket. Des sauvegardes sont également effectuées avant chaque mise à jour. --- ## Étape 5 : Désigner un point de contact -Désignez une personne ou un canal Slack/Teams de votre côté pour les problèmes au niveau du cluster : santé des nœuds, limites du compte cloud, modifications réseau. Les opérations courantes ne nécessitent pas ce contact. +Désignez une personne ou un canal Slack/Teams de votre côté pour les problèmes au niveau du cluster : santé des nœuds, limites du compte cloud, changements réseau. Les opérations quotidiennes n'impliquent pas ce contact. --- ## Ce que nous déployons -Une fois qu'Exosphere dispose d'un accès au cluster, les composants suivants sont déployés et gérés pour vous : +Une fois qu'Exosphere a accès au cluster, les composants suivants sont déployés et gérés pour vous : | Composant | Rôle | |---|---| -| **Serveur AgentEye** | API HTTP qui reçoit les événements des collecteurs, exécute les analyses et sert les données au tableau de bord | -| **Tableau de bord** | Interface web pour visualiser les sessions d'agents, les appels d'outils, les requêtes de modèles et les erreurs ; héberge l'assistant IA optionnel en lecture seule | -| **ClickHouse** | Stockage canonique requis pour les événements ingérés, les analyses et les évaluations | -| **PostgreSQL** | Stockage relationnel pour les organisations, les clés API, les utilisateurs, les tableaux de bord et les requêtes sauvegardées | -| **Redis** | Cache partagé optionnel et backend de limitation de débit ; la plateforme se dégrade gracieusement s'il est indisponible | -| **Assistant IA (optionnel)** | Conteneur d'assistant interne en lecture seule ; reste désactivé jusqu'à ce qu'un point d'entrée LLM soit configuré | -| **Contrôleurs d'ingress** | Deux load balancers (l'un pour l'ingestion protégée par mTLS, l'autre pour le tableau de bord) terminant TLS avec des certificats renouvelés automatiquement et publiquement approuvés, et appliquant mTLS sur le point d'entrée d'ingestion | -| **cert-manager** | Automatise le provisionnement des certificats TLS et l'émission des certificats clients mTLS | -| **Surveillance des certificats** | Une tâche planifiée vérifie l'expiration des certificats et envoie des alertes (ex. sur Slack) à l'approche du renouvellement | - -L'offre gérée opère également le pipeline d'évaluation de la plateforme, qui évalue l'activité des agents par rapport à vos critères d'évaluation. Consultez [Assistant](/fr/agenteye/assistant) et [Suite d'évaluation](/fr/agenteye/evaluation-suite) pour en savoir plus sur ces fonctionnalités. +| **AgentEye Server** | API HTTP qui reçoit les événements des collecteurs, exécute les analyses et sert les données au tableau de bord | +| **Tableau de bord** | Interface web pour visualiser les sessions d'agents, les appels d'outils, les requêtes aux modèles et les erreurs ; héberge l'assistant IA optionnel en lecture seule | +| **ClickHouse** | Magasin canonique requis pour les événements ingérés, les analyses et les évaluations | +| **PostgreSQL** | Magasin relationnel pour les organisations, les clés API, les utilisateurs, les tableaux de bord et les requêtes sauvegardées | +| **Redis** | Cache partagé optionnel et backend de limitation de débit ; la plateforme se dégrade de manière gracieuse en cas d'indisponibilité | +| **Assistant IA (optionnel)** | Conteneur d'assistant interne en lecture seule ; reste désactivé jusqu'à la configuration d'un point de terminaison LLM | +| **Contrôleurs d'ingress** | Deux load balancers (un pour l'ingestion protégée par mTLS, un pour le tableau de bord) terminant TLS avec des certificats publiquement fiables et renouvelés automatiquement, et appliquant le mTLS sur le point de terminaison d'ingestion | +| **cert-manager** | Automatise le provisionnement des certificats TLS et l'émission des certificats client mTLS | +| **Supervision des certificats** | Une tâche planifiée vérifie l'expiration des certificats et envoie des alertes (ex. vers Slack) à l'approche du renouvellement | + +L'offre gérée exploite également le pipeline d'évaluation de la plateforme, qui note l'activité des agents par rapport à vos critères d'évaluation. Consultez [enterprise-docs/assistant.md](/fr/agenteye/assistant) et [enterprise-docs/evaluation-suite.md](/fr/agenteye/evaluation-suite) pour découvrir ce que ces fonctionnalités apportent. --- @@ -111,24 +110,24 @@ Une fois le déploiement terminé, vous recevez : | Élément | Détails | |---|---| -| **URL du tableau de bord** | Un nom d'hôte sous votre domaine (ex. `https://agenteye.votre-entreprise.exemple`), servi avec un certificat TLS renouvelé automatiquement et publiquement approuvé. Vous créez un CNAME vers le nom d'hôte du load balancer que nous fournissons ; la connexion est par OTP email sans mot de passe | -| **Point d'entrée collecteur** | Le chemin `/events` du nom d'hôte d'ingestion (ex. `https://ingest.votre-entreprise.exemple/events`), protégé par mTLS | +| **URL du tableau de bord** | Un nom d'hôte sous votre domaine (ex. `https://agenteye.votre-entreprise.example`), servi avec un certificat TLS publiquement fiable et renouvelé automatiquement. Vous créez un CNAME vers le nom d'hôte du load balancer que nous fournissons ; la connexion est sans mot de passe via OTP par email | +| **Point de terminaison du collecteur** | Le chemin `/events` du nom d'hôte d'ingestion (ex. `https://ingest.votre-entreprise.example/events`), protégé par mTLS | | **Bundle de certificat client** | Par cluster : certificat client, clé privée et certificat CA livrés sous forme de manifest Kubernetes Secret. À appliquer une fois par cluster | | **GitHub PAT** | Pour télécharger les binaires du collecteur et les packages du SDK Python | -| **Clés API collecteur** | Clés à portée limitée avec permission `events:add`, une par déploiement de collecteur | -| **Guides d'installation** | Documentation étape par étape pour le collecteur et le SDK Python | +| **Clés API du collecteur** | Clés à portée limitée avec la permission `events:add`, une par déploiement de collecteur | +| **Guides d'installation** | Documentation pas à pas pour le collecteur et le SDK Python | --- -## Ce que vous faites après la configuration +## Ce que vous faites après la mise en place -Votre seul travail continu concerne vos propres machines d'agents, pas le cluster AgentEye : +Votre seul travail continu concerne vos propres machines d'agents, et non le cluster AgentEye : -1. **Installez le collecteur** dans chaque cluster Kubernetes exécutant des agents IA : montez le certificat client et configurez l'URL du point d'entrée et la clé API. Voir [Installation du collecteur](/fr/agenteye/collector-installation). -2. **Intégrez le SDK Python** dans votre code d'agent. Voir [SDK Python](/fr/agenteye/python-sdk). +1. **Installez le collecteur** dans chaque cluster Kubernetes exécutant des agents IA : montez le certificat client et configurez l'URL du point de terminaison et la clé API. Voir [enterprise-docs/collector-installation.md](/fr/agenteye/collector-installation). +2. **Intégrez le SDK Python** dans votre code d'agent. Voir [enterprise-docs/python-sdk.md](/fr/agenteye/python-sdk). 3. **Ouvrez le tableau de bord** dans votre navigateur pour visualiser l'activité des agents. -Aucune opération sur le cluster, aucune gestion de base de données, aucun renouvellement de certificat, aucune mise à jour. +Aucune opération de cluster, aucune gestion de base de données, aucun renouvellement de certificat, aucune mise à jour. --- @@ -136,8 +135,8 @@ Aucune opération sur le cluster, aucune gestion de base de données, aucun reno - **Les données restent dans votre compte cloud.** Le cluster, le stockage et les bases de données s'exécutent tous dans votre environnement. Aucune donnée ne quitte votre périmètre. - **Vous contrôlez l'accès.** Le cluster est dans votre compte. Vous pouvez auditer, surveiller ou révoquer l'accès d'Exosphere à tout moment. Toutes les opérations passent par le journal d'audit de votre cloud (CloudTrail, GCP Audit Logs, etc.). -- **mTLS sur l'ingestion d'événements.** Chaque requête de collecteur nécessite à la fois un certificat client valide et une clé API. Une clé compromise est inutile sans le certificat ; un certificat volé est inutile sans une clé valide. -- **Contrôle d'accès au tableau de bord.** Le tableau de bord s'exécute sur son propre load balancer, séparé de l'ingestion d'événements, et la connexion est par OTP email sans mot de passe restreinte aux adresses e-mail/domaines que vous avez autorisés. Une liste blanche de plages d'adresses IP sources sur le load balancer est disponible sur demande ; étant donné que le renouvellement automatique des certificats doit accéder au load balancer, Exosphere associe la restriction à la validation des certificats par DNS pour que les renouvellements continuent de fonctionner. +- **mTLS sur l'ingestion d'événements.** Chaque requête de collecteur nécessite à la fois un certificat client valide et une clé API. Une clé divulguée est inutilisable sans le certificat ; un certificat volé est inutilisable sans une clé valide. +- **Contrôle d'accès au tableau de bord.** Le tableau de bord fonctionne sur son propre load balancer, distinct de l'ingestion d'événements, et la connexion est sans mot de passe via OTP par email, restreinte aux adresses e-mail/domaines que vous autorisez. Une liste d'autorisation de plages d'IP sources sur le load balancer est disponible sur demande ; comme le renouvellement automatique des certificats doit atteindre le load balancer, Exosphere associe la restriction à une validation de certificat basée sur DNS afin que les renouvellements continuent de fonctionner. - **Certificats par cluster.** Chacun de vos clusters reçoit son propre certificat client. Si un cluster est compromis, ce certificat est révoqué indépendamment sans affecter les autres. --- @@ -147,12 +146,12 @@ Aucune opération sur le cluster, aucune gestion de base de données, aucun reno | Phase | Durée | Votre implication | |---|---|---| | **Provisionnement du cluster** | 1-2 jours | Provisionner le cluster et accorder l'accès à Exosphere | -| **Configuration de la plateforme** | 1 jour | Aucune ; Exosphere installe tous les composants d'infrastructure | +| **Mise en place de la plateforme** | 1 jour | Aucune ; Exosphere installe tous les composants d'infrastructure | | **Déploiement de l'application** | 1 jour | Aucune ; Exosphere déploie le serveur, le tableau de bord et crée les clés API | -| **Déploiement des collecteurs** | 1-3 jours | Installer les collecteurs dans vos clusters (avec les conseils d'Exosphere) | +| **Déploiement des collecteurs** | 1-3 jours | Installer les collecteurs dans vos clusters (avec l'accompagnement d'Exosphere) | | **Rodage en production** | 1 semaine | Aucune ; Exosphere surveille et ajuste | -Durée totale typique : **~2 semaines** du lancement à la mise en production. +Durée totale typique : **~2 semaines** du lancement au passage en production. --- @@ -164,7 +163,7 @@ Pour toute question ou problème, contactez Exosphere à l'adresse `support@exos ## Prochaines étapes -- [Démarrage rapide](/fr/agenteye/getting-started) : présentation complète de bout en bout +- [Démarrage](/fr/agenteye/getting-started) : parcours complet de bout en bout - [Installation du collecteur](/fr/agenteye/collector-installation) : installer et configurer le collecteur - [SDK Python](/fr/agenteye/python-sdk) : instrumenter votre code d'agent - [Clés API](/fr/agenteye/api-keys) : gérer les accès et les permissions diff --git a/docs/he/agenteye/audits.mdx b/docs/he/agenteye/audits.mdx index 1c2c39b2..7741a606 100644 --- a/docs/he/agenteye/audits.mdx +++ b/docs/he/agenteye/audits.mdx @@ -1,107 +1,106 @@ --- -title: "Audits — זיהוי שיפורים עבור סוכנים" -description: "תיעוד AgentEye Audits — זיהוי שיפורים עבור סוכנים." +title: "审计 — 代理改进检测" +description: "AgentEye 审计 — 代理改进检测文档。" --- -Audits הם משימות חוזרות שחופרות בתוך יומני הסוכן שלך **על פני מושבים** כדי למצוא דברים שכדאי לשפר. כאשר alert עוקב אחרי מטרית יחידה שאתה כבר מכיר בזמן קרוב למציאות, audit *חוקר*: לפי לוח זמנים שאתה קובע, הוא מריץ מעבר מדיניות דטרמיניסטי על החלון, ואז מפרק **סוכן AI לאמינות** על המושבים שלך — הסוכן שואל את הנתונים בעצמו, קורא תמלילים חשודים, וכאשר זה עוזר, מריץ סקריפטים ניתוח קטנים, ואז כותב **המלצות שיפור** עם הראיות מאחורי כל אחת. +审计是定期的任务，用于挖掘**跨会话**的代理日志，找出值得改进的地方。告警监视你已经了解的单个指标并进行近实时通知，而审计*调查*：按照你设定的计划，它对时间窗口执行确定性策略检查，然后让一个 **AI 可靠性代理**在你的会话中开展工作 — 该代理自行查询数据、阅读可疑记录，并在需要时运行小型分析脚本，然后生成**改进建议**并附带每条建议的证据。 -השתמש ב-audits כדי לענות על "מה אני צריך לתקן או לשפר בסוכנים שלי?" — ו-alerts כדי להיות מעורר ברגע שסף ספציפי חוצה. כל שיפור מקשור לסשנים וחקירות בדיוק, וקליק אחד יוצר alert מלא מראש כדי לתפוס חזרות. +使用审计来回答"我的代理中应该修复或改进什么？" — 并使用告警在特定阈值被触及时进行分页通知。每项改进都链接到其背后的具体会话和查询，一键即可创建预填充的告警来捕捉重复问题。 -משטח הדאשבורד הוא **`//audits`** (סרגל צד → *analyze* → *audits*), מגונן על ידי ההרשאות `audits:read` / `audits:write`. +仪表板位于 **`//audits`**（侧边栏 → *analyze* → *audits*），由 `audits:read` / `audits:write` 权限控制。 --- -## איך ריצה עובדת +## 运行如何工作 -לכל ריצה יש שתי שכבות — בסיס דטרמיניסטי וחקירה מסוכנת. +每次运行有两层 — 确定性基础层和代理调查层。 -### 1. מעבר המדיניות (דטרמיניסטי) +### 1. 策略检查（确定性） -לפני שמודל כלשהו רץ, audit מריץ קטלוג קטן של **בדיקות מדיניות SQL** על החלון: שאילתות צבור מוגבלות המדגלות דפוסים רעים ידועים ודיווח *כמה* אירועים / *אילו* סשנים תאמו — לעולם לא הטקסט המתאים עצמו. הקטלוג כולל: +在任何模型运行之前，审计对时间窗口执行小型 **SQL 策略检查**目录：受限的聚合查询，标记已知的不良模式并报告*有多少*事件 / *哪些*会话匹配 — 绝不报告匹配的文本本身。该目录包括： -- **דליפת סודות / אישורים** בעומסי אירועים — AWS access keys, `sk-…` API keys, PEM private keys, JWT / bearer tokens, וְ `KEY=…` הקצאות אישורים. -- **סימני הזרקת prompt** — "ignore previous instructions", "reveal your system prompt", וכדומה. -- **PII** — מספרים בצורת SSN (היוריסטי). -- **שלילות הרשאות כלי** ו**לולאות קריאות כלי חוזרות**. +- 事件负载中的**机密/凭证泄露** — AWS 访问密钥、`sk-…` API 密钥、PEM 私钥、JWT / bearer 令牌和 `KEY=…` 凭证分配。 +- **提示注入标记** — "忽略之前的指令"、"揭示你的系统提示"等类似内容。 +- **PII** — SSN 形式的数字（启发式）。 +- **工具权限拒绝**和**失控工具调用循环**。 -מכות מדיניות מתמשכות כממצאים (סוג `policy`) ש**תמיד משטחות** (הן לעולם לא קוצצות על ידי הקאפ לכל ריצה), והן מועברות לסוכן ה-AI כעלויות התחלה. מכיוון ששכבה זו לא צריכה מודל, audit עדיין מייצר את האותות הביטחוני החשובים ביותר שלו גם אם סוכן ה-AI אינו זמין. +策略命中被持久化为发现项（类型 `policy`），**始终显示**（绝不会因运行限制而被修剪），并作为初始线索提交给 AI 代理。由于此层不需要模型，即使 AI 代理不可用，审计仍能产生其最重要的安全信号。 -### 2. החקירה המסוכנת (AI) +### 2. 代理调查（AI） -לאחר מכן audit מריץ **סוכן אמינות עצמאי** (אותו שירות Agents SDK שמעניק כוח לעוזר הדאשבורד, עם prompt ספציפי לביקורת). בהינתן **ההיקף** של audit (סוכנים שנבחרו × סביבות) ו**החלון הזמני**, הסוכן: +审计随后运行一个**自主可靠性代理**（与驱动仪表板助手的 Claude Agent SDK 服务相同，具有审计特定的提示）。给定审计的**范围**（选定的代理 × 环境）和**时间窗口**，该代理： -- מריץ שאילתות SQL קריאה בלבד נגד טבלאות הנתונים שלך, -- קורא קומץ תמלילי סשנים מייצגים, -- כתיבה אופציונלית והרצה של סקריפטים **Python קצרים בחומת חול נעולה בתוך ה-pod** (אין רשת, אין גישה למערכת קבצים, סודות נקוביים) לניתוח ש-SQL לא יכול להביע — clustering שגיאות, חישוב התפלגויות, סריקת עומסים שהוא כבר הביא, -- והוא רושם כל **שיפור** שתוק בראיות שמצא. +- 针对你的分析表运行只读 SQL 查询， +- 阅读数个代表性会话记录， +- 可选地在锁定的在线沙箱中编写和运行短小的 **Python 脚本**（无网络、无文件系统访问、机密已清理）进行 SQL 无法表达的分析 — 错误聚类、计算分布、扫描已获取的负载， +- 并记录它发现的每项有充分证据支持的**改进**。 -זה עובד דרך כמה קווי חקירה — clustering שגיאות, סחף לעומת בסיס, כישלון מטרה בתמלילים, שימוש לא נכון בכלים, פשרות איכות/עלות, וחסמי כיסוי — ב**רגישות** של audit (נמוך / בינוני / גבוה). כל שיפור **חייב להצטטות ראיות**: ה-session ids שהסוכן בעצם ביקר בהם ו/או ה-SQL שהוא הריץ. השרת מאמת שסשנים מצוטטים קיימים ו**מסיר כל שיפור ללא ראיות שורדות**, אז הסוכן חוקר אך לעולם לא משדך. +它通过多条调查线 — 错误聚类、相对基线的漂移、记录中的目标失败、工具误用、质量/成本权衡和覆盖率缺口 — 按照审计的**灵敏度**（低 / 中 / 高）工作。每项改进**必须引用证据**：代理实际检查的会话 ID 和/或运行的 SQL。服务器验证引用的会话是否存在，**放弃任何没有存活证据的改进**，所以代理调查但从不凭空想象。 -כל שיפור נושא: +每项改进包括： -- **המלצה** (השינוי הקונקרטי לביצוע — התאמת prompt, תיקון schema כלי, מדיניות ניסיון, guardrail, כיסוי eval נוסף), -- **השפעה צפויה** וְ**הערכת מאמץ** (נמוך / בינוני / גבוה), -- **גודל** — `big` (מפעיל צריך להיות מעורר), `medium` (שייך לדוח הריצה), או `small` (הקשר דאשבורד), -- **טביעת יד** יציבה (מקטגוריית הבעיה + היקף, *לא* סשנים של ריצה זו) כך שאותה בעיה מעוקבת מריצה לריצה גם כאשר הראיות משתנות, -- וכאשר משקיף דטרמיניסטי פשוט יכול לתפוס חזרה, **alert מוצע** שאתה יכול ליצור בקליק אחד. +- **建议**（具体的改动 — 提示调整、工具架构修复、重试策略、防护栏、更多评估覆盖）， +- **预期影响**和**工作量**估计（低 / 中 / 高）， +- **规模** — `big`（应通知操作员）、`medium`（属于运行报告）或 `small`（仪表板上下文）， +- 稳定的**指纹**（从问题的类别 + 范围而来，*不*来自此次运行的会话），以便同一问题即使证据改变也能跨运行跟踪， +- 以及在简单确定性监视器可以捕捉重复的情况下，**建议的告警**，你可以一键创建。 -> **שכבת ה-AI היא אופציונלית אך מומלצת.** אם לא קונפיגורירו סוכן AI לצינור ביקורת, ריצות עדיין מתבצעות, תמשך את ממצאי המדיניות, וידווחו בכנות "analysis unavailable" לשכבה המסוכנת במקום להעביר בדיממוקה. +> **AI 层是可选但推荐的。** 如果没有为审计管道配置 AI 代理，运行仍会执行、持久化策略发现项，并诚实地报告 AI 层"分析不可用"，而不是默默通过。 -### מצבי כישלון +### 失败模式 -שיפורים מסווגים לתוך **קטלוג מצבי כישלון** עמיד של הארגון שלך (או מציעים מצב חדש). מצבים נותנים לדפוסים זהות יציבה על פני ריצות ועקיבות אופק ארוך. +改进被分类到你组织的持久**失败模式目录**中（或提议新模式）。模式跨运行为模式赋予稳定的身份，并实现长期的重复追踪。 -## מחזור חיי סיווג +## 分类生命周期 -בעמוד ממצא (`/audits//findings/`): +在发现页面（`/audits//findings/`）上： -| פעולה | השפעה | +| 操作 | 效果 | |---|---| -| **acknowledge** | שומר את הממצא גלוי אך חוצה את העדיפות שלו. | -| **resolve** | סימון כתוקן. אם הדפוס באמת חוזר מאוחר יותר, הוא חוזר לפתיחה כ-**new** — אז רגרסיה גם היא חזקה, לא מקופלת בשקט לתוך ההיסטוריה. | -| **mute** / **dismiss** | דיכוי עמיד: טביעת היד של הדפוס זוכרת ולא משטחת לעולם שוב, גם על פני ריצות. השתמש ב-mute ל"ידוע, מקובל"; dismiss ל"לא שימושי". | -| **reopen** | מחוקות דיכוי / רזולוציה ודרגות את הדפוס שוב. | -| **assign** | מנתב את הממצא למפעיל (חבר ארגון) לבעלות. מצב העדיפות והדיכוי לא משתנים. | +| **acknowledge** | 保持发现项可见但将其优先级减半。 | +| **resolve** | 标记为已修复。如果模式后来确实返回，它作为**新**项重新打开 — 所以回归是明显的，而不是默默折叠到历史中。 | +| **mute** / **dismiss** | 持久抑制：模式的指纹被记住，永远不会再出现，即使跨运行也是如此。用 mute 表示"已知、已接受"；dismiss 表示"无用"。 | +| **reopen** | 清除抑制/解决状态，并重新排列模式优先级。 | -הרעש של אות נמוך נשלט לכל ביקורת עם כובע ממצאים לכל ריצה (top_k`) על השיפורים המסוכנים. ממצאי מדיניות עוקפים את הכובע (הם רלוונטיים לביטחון ותמיד מוצגים). כל דבר שנחתך על ידי הכובע מתואר בסטטיסטיקות הריצה — שום דבר לא מוטל בשקט. +低信号噪音通过每个审计的每运行发现项限制（`top_k`）来控制代理改进。策略发现项绕过限制（它们与安全相关，始终显示）。因限制而被削减的任何内容都计入运行的统计数据 — 没有任何内容被默默放弃。 -## תזמון +## 调度 -- **Cadence** (`schedule_interval_secs`): שעתי עד שבועי; **יומי הוא ברירת המחדל**. Audits הם בכוונה גסים יותר מ-alerts — חקירה מסוכנת סורקת חלונות שלמים וחוזרת לדקות. -- **Window**: או lookback מתגלגל קבוע (למשל "כל ריצה סורקת את 7 הימים האחרונים") או **since-last-run** (ברירת המחדל) — כל ריצה מתעדכנת מהמקום שהריצה הקודמת שהצליחה הסתיימה, עם חפיפה קטנה אז אירועי גבול לעולם לא מתחמקים. -- הריצה הבאה משוללת מרווח מלא לאחר הקודמת **משלימה**, אז ריצה איטית לעולם לא ערימות ריצה שנייה קונקוריתית של אותה ביקורת. -- **Run now** בעמוד ביקורת הופך אותה למעונייינת מיד. +- **频率**（`schedule_interval_secs`）：每小时到每周；**每天是默认值**。审计故意比告警更粗糙 — 代理调查扫描整个窗口并运行数分钟。 +- **窗口**：要么是固定的滚动回顾（例如"每次运行扫描过去 7 天"），要么是**自上次运行以来**（默认值） — 每次运行从上次成功运行结束的地方继续，有小范围重叠以确保边界事件不被遗漏。 +- 下一次运行计划在前一次运行**完成**后的完整间隔内进行，所以慢运行永远不会堆积同一审计的第二个并发运行。 +- 审计页面上的**立即运行**使其立即到期。 -## בחירת מודל +## 模型选择 -בעת יצירת ביקורת אתה יכול לבחור איזה מודל החקירה משתמשת, מ**רשימת המודלים שהמפעיל שלך קונפיגורירו** לשירות סוכנים. עם מודל יחיד מוגדר, הסלקטור מציג אותו ככיתוביות; עם מספרים, אתה בוחר. השאירו אותו לא מוגדר משתמש בברירת המחדל המוגדרת. +创建审计时，你可以从**操作员为代理服务配置的模型列表**中选择调查使用的模型。配置了单个模型时，选择器将其显示为标题；配置了多个时，你可以选择。保持未设置使用已配置的默认值。 -## התראות +## 通知 -כאשר ריצה משטחת **חדש** ממצאים, ביקורת מודיעה לערוצים שנקבעו של הארגון שלך — אותה `alerts.enabled_channels` שער והגדרות צינור alerts משתמש: +当运行出现**新的**发现项时，审计通知你组织已配置的频道 — 与告警管道使用的相同 `alerts.enabled_channels` 门控和设置： -- **Slack** — סיכום הפריטים החדשים המשמעותיים (`big`) עם קישור עמוק. -- **Email** — **דוח ביקורת** מעוצב המציגה את השיפורים החדשים (חומרה עליונה, המלצות לכל פריט, קישור עמוק), שנשלח כאשר ביקורת יש ערוץ **email** מצורף ויש לפחות ממצא חדש אחד. +- **Slack** — 重要（`big`）新项的摘要，附带深度链接。 +- **电子邮件** — 设计好的**审计报告**，列出新改进项（按严重性排序、每项建议、深度链接），在审计附加了**电子邮件**频道且至少有一项新发现时发送。 -ממצאים חוזרים אך ידועים אינם מודיעים שוב. +重复但已知的发现项不会重新通知。 -## הפניית תצורה +## 配置参考 -הגדרות Audit מנוהלות בדאשבורד (`/audits/new`) או דרך ה-API. הגדרות לכל ביקורת כוללות את קדנס לוח הזמנים והחלון, ההיקף (`{"environments": [...], "agent_ids": [...]}`), הרגישות (`low` / `medium` / `high`), ערוצי ההתראות, כובע הממצאים לכל ריצה (`top_k`), והמודל (דרך `llm_budget.model`). הגדרות שרת ברמת מפעיל (timeouts, sandbox, כתובת ה-agent-service) תועדות ב-[deployment.md](/he/agenteye/deployment). +审计定义通过仪表板（`/audits/new`）或 API 进行管理。每个审计的设置包括计划频率和窗口、范围（`{"environments": [...], "agent_ids": [...]}`）、灵敏度（`low` / `medium` / `high`）、通知频道、每运行发现项限制（`top_k`）和模型（通过 `llm_budget.model`）。操作员级服务器设置（超时、沙箱、代理服务 URL）在 [deployment.md](/he/agenteye/deployment) 中记录。 ## API -כל נקודות הקצה הן ממלקוח וצעד בעקבות auth מפתח נושא סטנדרטי (ראה [api-keys.md](/he/agenteye/api-keys)). +所有端点均为组织范围，遵循标准 bearer 密钥认证（参见 [api-keys.md](/he/agenteye/api-keys)）。 -| נקודה קצה | הרשאה | תכלית | +| 端点 | 权限 | 目的 | |---|---|---| -| `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | רשום / צור הגדרות ביקורת. | -| `GET` / `PUT` / `DELETE /audits/:id` | קרא / כתוב / כתוב | בדוק, ערוך, מחק ביקורת. | -| `POST /audits/:id/run` | `audits:write` | הפוך את ביקורת מעונייינת מיד. | -| `GET /audits/:id/runs` | `audits:read` | היסטוריית ריצה (חלון, סטטוס, סטטיסטיקה, ספירת ממצאים). | -| `GET /audits/findings` | `audits:read` | ממצאים בכל הארגון, סינון עם `audit_id`, `status`; ממוין לפי עדיפות. | -| `GET /audits/findings/:fid` | `audits:read` | פרט מלא ממצא (המלצה, ראיות, עדיפות). | -| `POST /audits/findings/:fid/status` | `audits:write` | סיווג: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | - -ל"ביקורת הריצה אבל לא מצא כלום", "חומת החול של קוד מנוטרלת", ו"דוא"ל ביקורת לא סופק", ראה [troubleshooting.md](/he/agenteye/troubleshooting#audits). \ No newline at end of file +| `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | 列出/创建审计定义。 | +| `GET` / `PUT` / `DELETE /audits/:id` | 读 / 写 / 写 | 检查、编辑、删除审计。 | +| `POST /audits/:id/run` | `audits:write` | 使审计立即到期。 | +| `GET /audits/:id/runs` | `audits:read` | 运行历史（窗口、状态、统计、发现项计数）。 | +| `GET /audits/findings` | `audits:read` | 组织范围发现项，可按 `audit_id`、`status` 筛选；按优先级排序。 | +| `GET /audits/findings/:fid` | `audits:read` | 完整发现项详情（建议、证据、优先级）。 | +| `POST /audits/findings/:fid/status` | `audits:write` | 分类：`{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`。 | + +关于"审计运行但未找到任何内容"、"代码沙箱已禁用"和"审计电子邮件未送达"，参见 [troubleshooting.md](/he/agenteye/troubleshooting#audits)。 \ No newline at end of file diff --git a/docs/he/agenteye/cli-recipes.mdx b/docs/he/agenteye/cli-recipes.mdx index 7e376421..e4a33677 100644 --- a/docs/he/agenteye/cli-recipes.mdx +++ b/docs/he/agenteye/cli-recipes.mdx @@ -1,29 +1,31 @@ --- +--- title: "מתכונים CLI לסוכנים" description: "תיעוד מתכונים CLI של AgentEye לסוכנים." --- -משוך נתוני session, event והערכה (והפעל הערכות מחדש) ישירות מסקריפט או סוכן קידוד, עם JSON נקי ב-stdout שמצנח ישירות ל-`jq`. המתכונים הללו הופכים את נתוני ה-observability של AgentEye למשהו שמשתמש טרמינל או סוכן קידוד AI (Claude Code, Cursor) יכול לשאול עליו ולהשתמש בו באופן אוטומטי, ללא לחיצה דרך ה-dashboard. -התבניות להלן מוכנות לשכפול עבור AgentEye CLI (`agenteye`). להתקנה, אימות וקائמת האפשרויות המלאה ראה [CLI](/he/agenteye/cli); הרץ `agenteye -h` או `agenteye -h` לקבלת העזרה המובנית. +משכו נתוני הפעלה, אירועים והערכה (והפעילו הערכה מחדש) ישירות מסקריפט או מסוכן קודינג, עם JSON נקי ב-stdout שמועבר ישירות ל-`jq`. המתכונים האלה הופכים את נתוני הנצפיות של AgentEye למשהו שמשתמש בטרמינל או סוכן קודינג AI (Claude Code, Cursor) יכול לשאול ולהפוך לאוטומציה, בלי ללחוץ דרך לוח הבקרה. + +הדפוסים בהמשך מוכנים להעתקה ישירה ל-CLI של AgentEye (`agenteye`). להתקנה, אימות וההצעה המלאה ראו [CLI](/he/agenteye/cli); הריצו `agenteye -h` או `agenteye -h` להשגת העזרה המובנית. -## הכללים הזהובים +## כללים ממוקדים -1. **אפשרויות גלובליות נמצאות *לפני* הפקודה.** `agenteye --json sessions` נכון; `agenteye sessions --json` לא. ה-globals הם `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **עבור `--json` בכל פעם שאתה מנתח פלט.** הנתונים עוברים ל-**stdout** כ-JSON; סטטוס אנושי ושגיאות עוברים ל-**stderr**, כך stdout נשאר נקי להצנחה ל-`jq`. -3. **התניה בקוד היציאה**, לא בטקסט stderr: `0` בסדר · `2` ארגומנטים רעים · `3` לא ניתן להגיע ל-dashboard · `4` לא מחובר או פג תוקף · `5` הרשאה חסרה. -4. **גלה עם `-h`.** כל פקודה מתעדת את הפילטרים שלה, פורמטי ערך וצורת JSON. +1. **אפשרויות גלובליות חייבות להופיע *לפני* הפקודה.** `agenteye --json sessions` נכון; `agenteye sessions --json` לא. הגלובליים הם `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **העבירו `--json` בכל פעם שאתם מנתחים פלט.** נתונים עוברים ל-**stdout** כ-JSON; סטטוס אנושי ושגיאות עוברים ל-**stderr**, כדי ש-stdout יישאר נקי להעברה ל-`jq`. +3. **הסתמכו על קוד היציאה, לא על טקסט stderr**: `0` בסדר · `2` ארגומנטים שגויים · `3` לא מוצא את לוח הבקרה · `4` לא מחובר או פג תוקף · `5` הרשאה חסרה. +4. **גלו עם `-h`.** כל פקודה מתעדת את הסינונים שלה, פורמטי ערך ותצורת JSON. -## הגדרה חד-פעמית +## התקנה חד-פעמית ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # כדי שלא תחזור על --base-url -agenteye login --email you@example.com # הדבק את הקוד שהתקבל בדואר; תקף ~24h +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # כדי לא לחזור על --base-url +agenteye login --email you@example.com # הדביקו את הקוד שנשלח בדוא"ל; תקף ~24h ``` -## אשר אימות לפני ביצוע עבודה +## אשרו אימות לפני ביצוע עבודה -`whoami` לעולם לא שוגה בחסר או session שפג תוקף; זה דיווח `logged_in:false` במקום זאת, כך שסוכן יכול לבדוק את מצב האימות בבטחה. (זה עדיין יכול לצאת עם קוד שאינו אפס אם לא מוגדרת כתובת URL של base או ה-dashboard אינו זמין.) +`whoami` לעולם לא יחזור בשגיאה בהפעלה חסרה או פגה; הוא מדווח `logged_in:false` במקום זה, כך שסוכן יכול לבדוק את מצב האימות בבטחה. (עדיין יכול להחזור non-zero אם לא הוגדרה כתובת בסיס או לוח הבקרה לא זמין.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -31,105 +33,105 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## מצא sessions שנכשלו או בעלי ניקוד נמוך +## מצאו הפעלות בעלות ניקוד נמוך או כשלון ```bash -# sessions ב-24 השעות האחרונות שההערכה שלהם שגתה +# הפעלות ב-24 השעות האחרונות שהערכתן הסתיימה בשגיאה agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# הערכות בעלות ניקוד <= 0.5 ב-helpfulness, לסוכן אחד +# הערכות בניקוד <= 0.5 בעזרתיות, לסוכן אחד agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -סינון ניקוד חי ב-**`evals`**, לא `sessions`. `--score KEY:MIN..MAX` חוזר ו-AND-משולב; כל גבול הוא אופציונלי (`..0.5` אומר ≤ 0.5, `0.9..` אומר ≥ 0.9). אתה יכול להעביר עד 20 מסננים ניקוד לבקשה; יותר מחזיר HTTP 400. `sessions` משתף את `--env`, `--status`, `--agent-id`, `--session-id`, ומסננים טווח זמן עם `evals`, אבל אין לו `--score`. +סינון הניקוד נמצא ב-**`evals`**, לא `sessions`. `--score KEY:MIN..MAX` חוזר וניתן לשילוב עם AND; כל גבול אופציונלי (`..0.5` פירושו ≤ 0.5, `0.9..` פירושו ≥ 0.9). אתם יכולים להעביר עד 20 סינוני ניקוד לכל בקשה; יותר מזה מחזיר HTTP 400. `sessions` חולק את הסינונים `--env`, `--status`, `--agent-id`, `--session-id` וטווח זמן עם `evals`, אך אין לו `--score`. -## קרא session מקצה לקצה +## קרא הפעלה אחת מקצה לקצה -אין פקודת `session show` יחידה — שלב את שביל האירועים עם ההערכה של ה-session: +אין פקודת `session show` יחידה — שלבו את רצף האירוע עם ההערכה של ההפעלה: ```bash -# ההערכה האחרונה של ה-session (סטטוס + ניקוד) +# ההערכה האחרונה של ההפעלה (סטטוס + ניקוד) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# כל אירוע בריצה (הרם --limit לסוויפ מלא) +# כל אירוע בריצה (הרימו את --limit לסריקה מלאה) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# רק קריאות הכלים ב-session +# רק קריאות הכלי בהפעלה agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -## אחזר הכל (pagination) +## משכו הכל (עימוד) -התוצאות הן newest-first ו-cursor-paginated. +התוצאות הן החדשות ביותר תחילה ועומדות להעברה תור. ```bash -# בשיגור אחד: אחזר עד 500 שורות בעמודים של 200 שורות +# בזריקה אחת: משוך עד 500 שורות בדפים של 200 שורות agenteye --json events --session-id run-001 --limit 500 --all > events.json -# pagination ידני: הזן את next_cursor חזרה +# עימוד ידני: החזירו את next_cursor חזרה פנימה page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## הרזן את הפלט עם --fields +## הצרו את הפלט עם --fields -הגבל את המפתחות (גם בטבלה וגם ב-`--json`) כדי להפחית מה סוכן צריך לקרוא. +הגבלו את המפתחות (בטבלה וב-`--json`) כדי להקטין את מה שסוכן חייב לקרוא. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -שמות שדות לא ידועים נדחים (exit `2`) עם הרשימה התקפה, דרך זולה לגילוי שמות שדות. +שמות שדות לא ידועים נדחים (exit `2`) עם הרשימה התקנה, דרך זולה להגדרת שמות שדות. -## גלה ערכי פילטר תקפים +## גלו ערכי סינון תקפים ```bash -agenteye --json list envs | jq -r '.values[]' # ערכים עבור --env -agenteye --json list tools | jq -r '.values[]' # שמות כלים; גם agents, models, event_types, … -agenteye --json list score_filters | jq -r '.values[]' # KEY תקף עבור --score KEY:MIN..MAX +agenteye --json list envs | jq -r '.values[]' # ערכים ל---env +agenteye --json list tools | jq -r '.values[]' # שמות כלים; גם סוכנים, מודלים, event_types, … +agenteye --json list score_filters | jq -r '.values[]' # KEY תקף ל---score KEY:MIN..MAX ``` -## בחר את ה-org שלך (multi-tenant) +## בחרו את הארגון שלכם (ריבוי דיירים) -אם אתה שייך ליותר מ-org אחד, בחר את ה-tenant הפעיל בעת הכניסה (זה נשמר): +אם אתם שייכים ליותר מארגון אחד, בחרו בדיייר הפעיל בהתחברות (הוא נשמר): ```bash -agenteye login --org acme --email you@corp.com # הגדר את ה-tenant באותו השלב כמו הכניסה +agenteye login --org acme --email you@corp.com # קבעו את הדיייר באותו שלב כמו התחברות agenteye --json orgs list | jq -r '.orgs[].org_slug' agenteye --org globex --json sessions --since 24h # דרוס לפקודה אחת ``` -כניסה multi-org ללא `--org` יוצאת עם קוד שאינו אפס והדפסת ה-orgs לבחירה. +התחברות ריבוי-ארגון ללא `--org` חוזרת non-zero והדפסה של הארגונים לבחירה. -## סיפק מפתח API עבור SDK/collector +## יצור מפתח API ל-SDK/מאסף ```bash -# הסוד מודפס פעם אחת בלבד — עם --json זה שדה .key +# הסוד מודפס פעם אחת — עם --json זה שדה .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # סובב; agenteye keys disable ci-bot --yes לשלילת הרשאות +agenteye keys regenerate ci-bot --yes # סיבוב; agenteye keys disable ci-bot --yes לשלילה ``` -## הרץ שאילתה שמורה או ad-hoc +## הריצו שאילתה שמורה או ad-hoc ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # שאילתה שמורה + $1 positional +agenteye --json query run errs --arg prod | jq '.rows' # שאילתה שמורה + $1 משתנה ``` -## טריאג' אירוע בעדכון ללא אינטראקטיבי +## יהלם תקרית ללא אינטראקטיביות ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> מוטציות דילוג אוטומטי בהנחתן תשובה תחת `--json` או כאשר stdin אינו TTY, כך שסוכנים לעולם לא תלויים; עבור `--yes`/`-y` לדלוג עליו בקפדנות במקום אחר. +> מוטציות דלג-אוטומטי על הנקודת האישור שלהם תחת `--json` או כאשר stdin אינו TTY, כדי שסוכנים לא תלויים; העברו `--yes`/`-y` לדלג עליה באופן מפורש במקומות אחרים. ## טיפול בקוד יציאה בסקריפט @@ -144,7 +146,7 @@ case "${code:-0}" in esac ``` -## צורות פלט JSON +## תצורות פלט JSON | פקודה | stdout JSON (עם `--json`) | |---|---| @@ -159,11 +161,11 @@ esac | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (כל) | אובייקט המשאב, או `{"deleted": true, "id"}` למחיקות | -| כישלון (כל, עם `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` ב-stdout | +| יצירה/עדכון/מחיקה (כל אחד) | אובייקט המשאב, או `{"deleted": true, "id"}` למחיקות | +| כשל (כל אחד, עם `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` ב-stdout | -- כל פריט **event** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. -- כל פריט **evaluation** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. -- כל פריט **session** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. +- כל פריט **אירוע** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. +- כל פריט **הערכה** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. +- כל פריט **הפעלה** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -`--fields` של כל פקודה קובל בדיוק שמות שדות של הפריט שלה — הסט שונה בין `sessions` ו-`evals`, כך ששם חוקי לאחד עלול להיות דחוי על ידי השני. \ No newline at end of file +כל פקודה של `--fields` מקבלת בדיוק את שמות השדות של הפריט שלה — הסט שונה בין `sessions` ו-`evals`, כך ששם תקף לאחד עלול להידחות על ידי השני. \ No newline at end of file diff --git a/docs/he/agenteye/deployment.mdx b/docs/he/agenteye/deployment.mdx index b9c62af7..5530056a 100644 --- a/docs/he/agenteye/deployment.mdx +++ b/docs/he/agenteye/deployment.mdx @@ -1,11 +1,10 @@ --- ---- title: "פריסה" description: "תיעוד פריסה של AgentEye." --- -מדריך זה מכסה את פריסת שרת AgentEye ולוח המחוונים בייצור. +מדריך זה מכסה את פריסת שרת AgentEye ולוח הבקרה בייצור. --- @@ -31,154 +30,153 @@ description: "תיעוד פריסה של AgentEye." +-----------+ ``` -- **Server**: שירות HTTP ב-Rust; מקבל אצווות של אירועים, כותב אותם ל-ClickHouse ומשמר מצב יחסי ב-PostgreSQL. -- **Dashboard**: אפליקציית Next.js; קוראת וכותבת אך ורק דרך ה-API של השרת. -- **agenteye-collector**: מפורסת על מכונות ה-agent, לא על הוסט של השרת. -- **Postgres 15+**: נדרש. (הועלה מ-14 בהוצאה מולטי-דיירנית; סכמת החברות בארגון משתמשת בעמודה-רשימה `ON DELETE SET NULL` במפתח חוץ, המצריך Postgres 15+. שדרגו את Postgres לפני פריסה של גרסה זו.) מאחסן מצב OLTP: `api_keys`, `users`, `sessions`, `evaluation_jobs` (תור), `dashboards`, `saved_queries`, `otp_codes`, בתוספת הטבלאות מולטי-דיירניות `orgs`, `org_memberships`, `org_settings`. -- **ClickHouse 24+**: נדרש. חנות הניתוחים עבור כל אירוע שהוזן. Engine: `ReplacingMergeTree`, מחולק לפי חודש, מסודר לפי `(session_id, ts, dedup_key)`. השרת מתחבר דרך `CLICKHOUSE_URL`; התיקייה המרוכזת `deploy/base/clickhouse/` מספקת תצורה בעלת ביצועים מכוונת של צומת יחיד. **דרישת מולטי-דיירנית:** התיקייה המרוכזת מאפשרת ניהול גישה SQL + `users_without_row_policies_can_read_rows=false` כך שהשרת יכול ליצור משתמש ClickHouse בקריאה בלבד + מדיניות שורה אחת לכל ארגון (גבול בידוד כפוי-engine של עורך SQL וה-AI agent). אם אתה מספק תצורת ClickHouse משלך, העבר הגדרות אלה (ראה `deploy/base/clickhouse/configmap.yaml`). -- **Redis 7+**: *אופציונלי* חסומה משותפת + תשתית קצב-הגבלה. שרת ודשבורד מתחברים שניהם דרך `REDIS_URL`. אם חסר, שניהם מתדרדרים בחן בטוב ללבד דרכים ללא Postgres. ראה **Redis (אופציונלי חסומה)** להלן. +- **Server**: שירות HTTP בשפת Rust; מקבל אצוות אירועים, כותב אותן ל-ClickHouse ותמונת מצב יחסית שמורה ב-PostgreSQL. +- **Dashboard**: אפליקציית Next.js; קוראת וכותבת בעקביות דרך API השרת בלבד. +- **agenteye-collector**: מפורסת על מכונות agent, לא על מארח השרת. +- **Postgres 15+**: נדרש. (הועלה מ-14 בהוצאה מרובה-דיירים; סכימת חברות הארגון משתמשת בעמודה `ON DELETE SET NULL` במפתח זר, שהוא Postgres 15+. שדרג את Postgres לפני פריסת גרסה זו.) מאחסן מצב OLTP: `api_keys`, `users`, `sessions`, `evaluation_jobs` (תור), `dashboards`, `saved_queries`, `otp_codes`, בתוספת טבלאות מרובות-דיירים `orgs`, `org_memberships`, `org_settings`. +- **ClickHouse 24+**: נדרש. אחסן האנליטיקה לכל אירוע שנספג. מנוע: `ReplacingMergeTree`, מחולק לפי חודש, סדור לפי `(session_id, ts, dedup_key)`. השרת מתחבר דרך `CLICKHOUSE_URL`; ה-`deploy/base/clickhouse/` המצורף משדר תצורת יחיד-קשר עם כיוונון ביצועים. **דרישת מרובה-דיירים:** התצורה המצורפת מאפשרת ניהול גישה SQL + `users_without_row_policies_can_read_rows=false` כך שהשרת יכול ליצור משתמש ClickHouse לקריאה בלבד ממנהל שורות אחד לכל ארגון (גבול בידוד שנאכף במנוע לעורך SQL וביעילות agent). אם אתה מספק תצורת ClickHouse משלך, הנקל את ההגדרות הללו (ראה `deploy/base/clickhouse/configmap.yaml`). +- **Redis 7+**: *אופציונלי* אחסן זיכרון משותף + בקצה שיעור הגבלה. שרת ולוח בקרה מתחברים דרך `REDIS_URL`. אם חסר, שניהם יורדים בחן לנתיבים Postgres בלבד. ראה **Redis (אחסן זיכרון אופציונלי)** למטה. --- ## שרת -### שלוף את התמונה +### משוך את התמונה ```bash echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> בנייה נוכחית מפרסמת תחת `beta-latest`; `latest` מוקצה רק לשחרורים יציבים. לייצור, צמד לתגית `:v` ספציפית; ראה [תגיות תמונה זמינות](#available-image-tags). +> בניות נוכחיות מפרסמות תחת `beta-latest`; `latest` מוקצה רק להוצאות יציבות. לייצור, הצמד גרסה ספציפית `:v`; ראה [תגיות תמונה זמינות](#available-image-tags). -### משתנים סביבה +### משתני סביבה | משתנה | נדרש | ברירת מחדל | תיאור | |---|---|---|---| -| `DATABASE_URL` | כן | בלא | Postgres DSN. מחרוזת חיבור libpq סטנדרטית עם סכמה `postgres://`. תומך ב-`?sslmode=require` ופרמטרים libpq אחרים. הסיסמה לא חייבת להכיל `/`, `+`, או `=`; השתמש ב-`openssl rand -hex` ליצירת סיסמאות בטוחות-URL. | -| `ADMIN_KEY` | לא | בלא | מפתח API admin bootstrap. Upserted עם כל ההרשאות בכל הפעלה. סיבוב על ידי שינוי הערך והפעלה מחדש. | -| `LISTEN_ADDR` | לא | `0.0.0.0:8080` | כתובת TCP להתחברות | +| `DATABASE_URL` | כן | ללא | DSN של Postgres. מחרוזת חיבור libpq סטנדרטית עם סכימה `postgres://`. תומך ב-`?sslmode=require` ופרמטרים libpq אחרים. הסיסמה לא חייבת להיות מכילה `/`, `+`, או `=`; השתמש ב-`openssl rand -hex` ליצירת סיסמאות בטוחות-URL. | +| `ADMIN_KEY` | לא | ללא | מפתח API אדמין bootstrap. מוערך עם כל ההרשאות בכל הפעלה. סובב על ידי שינוי הערך והפעלה מחדש. | +| `LISTEN_ADDR` | לא | `0.0.0.0:8080` | כתובת TCP שתיקשור אליה | | `MAX_BODY_BYTES` | לא | `134217728` (128 MB) | גודל גוף בקשה מרבי | -| `ADMIN_EMAIL` | לא | בלא | כתובת דוא"ל של משתמש admin bootstrap. Upserted עם כל ההרשאות בכל הפעלה וסימן מוגן: אינו יכול להיות מוגבל או שיש הרשאות שונות דרך הדשבורד/API. לסיבוב ה-admin bootstrap, שנה את `ADMIN_EMAIL` והפעל מחדש; הדוא"ל החדש מוטמע כמוגן, וקודם שימור ההגנה שלו עד לניקוי ידני בבסיס הנתונים. | -| `ALLOWED_EMAILS` | לא | בלא (כל חסום) | רשימה מופרדת בפסיקים של דוא"לים מורשים ליצירה וכניסה של משתמש. תומך בכתובות מדויקות (`user@example.com`) ותמיכה בתחום בתחום (`*@example.com`). אם לא מוגדר, לא ניתן ליצור משתמשים או להיכנס. **זרע ברגל ראשונה בלבד**: זורעת את רשימת ההכחה של ארגון ברירת המחדל בהפעלה ראשונה; לאחר מכן, כל ארגון [`//settings`](#operational-settings) עמוד הוא מקור האמת וחוקים בעריכה של משתנה env זה אין השפעה. | -| `SMTP_HOST` | לא | בלא | שם הוסט של שרת SMTP לשליחת דוא"ל OTP. אם לא מוגדר, קודי OTP מוקלטים ל-stdout. | +| `ADMIN_EMAIL` | לא | ללא | כתובת דוא"ל של משתמש admin bootstrap. מוערך עם כל ההרשאות בכל הפעלה וסומן מוגן: לא ניתן להשבית או לשנות הרשאות דרך לוח הבקרה/API. כדי לסובב את admin bootstrap, שנה `ADMIN_EMAIL` והפעל מחדש; הדוא"ל החדש מוערך כמוגן, והקודם שומר על הגנתו עד לניקיון ידני במסד הנתונים. | +| `ALLOWED_EMAILS` | לא | ללא (הכל חסום) | רשימה מופרדת בפסיקים של דוא"לים מורשים ליצירה וכניסה של משתמש. תומך בכתובות מדויקות (`user@example.com`) ותעדול דומיין (`*@example.com`). אם אינו מוגדר, אין משתמשים יכולים ליצור או להיכנס. **זריעה בהפעלה ראשונה בלבד**: זורע את רשימת ההרשאות של הארגון ברירת המחדל בהפעלה ראשונה; לאחר מכן עמוד [`//settings`](#operational-settings) של כל ארגון הוא מקור האמת ושינוי משתנה env זה אין השפעה. | +| `SMTP_HOST` | לא | ללא | שם מארח שרת SMTP לשליחת דוא"לי OTP. אם אינו מוגדר, קודי OTP מתועדים ל-stdout. | | `SMTP_PORT` | לא | `587` | יציאת שרת SMTP | -| `SMTP_USERNAME` | לא | בלא | שם משתמש אימות SMTP | -| `SMTP_PASSWORD` | לא | בלא | סיסמת אימות SMTP | -| `SMTP_FROM` | לא | בלא | כתובת דוא"ל שולח לדוא"ל OTP | -| `SMTP_TLS` | לא | STARTTLS | STARTTLS משמש אלא אם כן תוציא זאת במפורש: `false` או `0` שולח טקסט רגול (ללא TLS); כל ערך אחר — לרבות לא מוגדר — מאפשר STARTTLS. | -| `DASHBOARD_URL` | לא | ברירת מחדל מובנית | מקור דשבורד המשמש לבנייה גם הקישור הקסום של דוא"ל OTP וגם קישורי השיוך בהודעות התראה. אם לא מוגדר, זה חוזר לברירת מחדל מובנית (ו, ל-OTP בלבד, למקור דשבורד-נגזר לבקשה). קבע זאת לרכיבי תחום מפוצלים כך שקישורים בדוא"ל וSlack/incident יוצבעו בדשבורד שלך. ראה **כתובת קישור קסום של דוא"ל** להלן; מפעילים רובים לא צריכים להגדיר זאת. | -| `SESSION_TTL_SECS` | לא | `86400` (24 שעות) | משך סשן דשבורד בשניות. **זרע ברגל ראשונה בלבד**: עדכן לכל ארגון דרך [`//settings`](#operational-settings) לאחר פריסה ראשונה. | -| `OTP_TTL_SECS` | לא | `600` (10 דק') | תקופת תוקף קוד OTP בשניות. **זרע ברגל ראשונה בלבד**: עדכן לכל ארגון דרך [`//settings`](#operational-settings) לאחר פריסה ראשונה. | -| `REDIS_URL` | לא | בלא | תשתית חסומה משותפת + קצב-הגבלה, למשל `redis://redis:6379/0`. כאשר מוגדר, השרת משימר בחסומה פקודות API-key מאומתות, סיכומי דשבורד `/models`, רשימת סשנים, ופן רשימה סביבה; הוא גם מעביר קצב OTP מ-Postgres COUNT ל-Redis INCR. אם לא מוגדר או לא זמין, השרת פועל ללא החסומה (קצב OTP חוזר ל-Postgres, כל קריאת חסומה אחרת חוזרת למקור האמת). ראה **Redis (אופציונלי חסומה)** להלן. | -| `CLICKHOUSE_URL` | **כן** | בלא | כתובת URL בסיסית של מופע ClickHouse, למשל `http://clickhouse:8123`. השרת יישם את סכמת האירועים שלו למסד נתונים זה בכל התחלה ויסרב להתחיל אם לא יוכל להגיע ל-ClickHouse. ראה **ClickHouse (חנות ניתוחים נדרשת)** להלן. | -| `CLICKHOUSE_DATABASE` | לא | `agenteye` | שם בסיס הנתונים ClickHouse (סכמה). השרת יוצר אותו בהתחלה אם הוא לא קיים. | -| `ORG_CH_SECRET` | לא (יחיד-דיירני) / **כן (מולטי-ארגון)** | ברירת מחדל פיתוח | מפתח HMAC שממנו נגזר סיסמת ClickHouse ייחודית לדיירן של כל ארגון. עורך ה-SQL וה-`run_query` של ה-AI agent מתבצעים כמשתמש ClickHouse בקריאה-בלבד של הארגון, שמדיניות השורה שלו כוחה בידוד דיירני בתוך Engine. פריסות יחיד-דיירניות התחילו כמו נעימה על ברירת המחדל של פיתוח המובנית; **לפני אספקת ארגון שני חייב להגדיר ערך חזק וקבוע**, כי הCLI `agenteye-orgctl org create` מסרב לרוץ על ברירת המחדל של פיתוח המובנית. סיבוב משאיר כל משתמש ClickHouse של ארגון יתום עד להתחלה הבאה לספק מחדש אותם (החוקק הזמן-התחלה מרפא זאת באופן אוטומטי). שמור זאת בסוד ולא שונה על פני משכפלות. פרוביזיה ארגון עצמו היא אופרטור-בלבד; ראה **ארגונים (מולטי-דיירנות)** להלן. | -| `DEFAULT_ORG_NAME` | לא | `Default` | שם תצוגה זרוע לארגון ברירת המחדל המובנה. **זרע ברגל ראשונה בלבד**, ורק בזמן שהארגון עדיין נושא את הזהות הגנרית שלו זה עתה הנדידה, יושם בהתחלה, ואז התעלם. לאחר שינוי שם הארגון (`agenteye-orgctl org rename`) השם הוא סמכות ולא עוד לעדכן משתנה env זה. | -| `DEFAULT_ORG_SLUG` | לא | `default` | תיבת URL לארגון ברירת המחדל המובנה, נתיב הדשבורד שהוא חי בו (`//…`). אותה דינמיקה ברגל ראשונה בלבד / טהור בלבד כמו `DEFAULT_ORG_NAME`. חייב להיות 1-40 אלפא-ספרות קטנות עם מקפים פנימיים יחידים ולא [מילה שמורה](#organizations-multi-tenancy); ערך לא חוקי מתעלם (הארגון שומר `default`). מאפשר התקנה יחיד-דיירנית לייצג כ-`/acme` במקום `/default` ללא שום שלב post-deploy CLI. | -| `RUST_LOG` | לא | `info` | קיבוץ יומן (`debug`, `warn`, `error`, `agenteye_server=trace`) | -| `EVALUATOR_ENDPOINT` | לא | בלא | כתובת URL בסיסית של שירות ה-evaluator שלך (למשל `http://evaluator:9000`). כאשר לא מוגדר כל צינור הערכה הוא no-op; שום שורות תור לא כתובות, אין עובדים מריצים. ראה [חדר הערכה](/he/agenteye/evaluation-suite). | -| `EVALUATOR_TOKEN` | לא | בלא | נשלח בתור `Authorization: Bearer ` ל-evaluator. **חייב להיות שווה לאותו ערך שהערכה משוערך מוגדרת עם.** אופציונלי רק אם הערכה מוגדרת ללא token. | -| `EVALUATOR_WORKERS` | לא | `2` | קונקור: מספר משימות עובד לכל מופע שרת המשדרות הערכות. בטוח לרוץ על שרתים בקנה-מידה אופקי מרובים. | -| `EVALUATOR_CLAIM_BATCH` | לא | `4` | מספר הערכות מרבי שעובד יחיד תובע לכל תופעה. אצווות משודרות **בו-זמנית**, כך שקונקור כללי על endpoint evaluator שלך הוא `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | לא | `2` | כמה זמן עובד ישן בין ניסיונות שיגור כאשר כלום אינו בא. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | לא | `10` | קדנס choke-back סופי (שניות) לעדכונים `GET /evaluate/{id}` כאשר המעריך אינו חוזר `next_poll_secs` לכל התגובה ואינו מפרסם `default_poll_interval_secs` מ `GET /config`. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | לא | `30000` | עדכון לכל בקשת HTTP כנגד המעריך (אלפית השניה). | -| `EVALUATOR_MAX_ATTEMPTS` | לא | `5` | לאחר הרבה ניסיונות כושלים כל כך הערכה מוקלטת כטרמינל `error` (או `timeout` אם הכשלות היו בקשה timeout). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | לא | `300` (5 דק') | כמה פעמים השרת re-fetches `GET /config` מ-evaluator. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | לא | `3600` (1 h) | זמן wallclock מרבי סשן עשוי להישאר בתור סקר לפני AgentEye מסיים אותו כ-`timeout`. משמרות נגד evaluator שחוזר `pending` לעד. | -| `ALERT_WORKERS` | לא | `1` | קונקור: מספר משימות עובד לכל מופע שרת המעריכות כללי התראה. ראה [התראות](/he/agenteye/alerts). | -| `ALERT_CLAIM_BATCH` | לא | `16` | מספר התראות מרבי עובד יחיד תובע לכל תופעה. | -| `ALERT_POLL_IDLE_SECS` | לא | `5` | כמה זמן עובד התראות ישן כאשר התור ריק. | -| `ALERT_REQUEST_TIMEOUT_MS` | לא | `15000` | עדכון הערכה להדלקת (ClickHouse queries + HTTP ערוץ יוצא). | -| `ALERT_MAX_ATTEMPTS` | לא | `5` | כשלים חולפים עוקבים לפני התראה משדרים בקדנס רגיל במקום backoff אקספוננציאלי. | -| `AUDIT_WORKERS` | לא | `1` | קונקור: מספר משימות עובד לכל מופע שרת המבצעות ביקורות. ראה [ביקורות](/he/agenteye/audits). | -| `AUDIT_CLAIM_BATCH` | לא | `1` | מספר מקסימום ביקורות בעבודה עובד יחיד תובע לכל תופעה. חקירה agentic היא לולאה ארוכה אחת, כך שברירת המחדל היא 1. | -| `AUDIT_POLL_IDLE_SECS` | לא | `30` | כמה זמן עובד ביקורות ישן כאשר אין ביקורת בעבודה. | -| `AUDIT_REQUEST_TIMEOUT_MS` | לא | `30000` | עדכון ממנו-query לכל-מדיניות נגד ClickHouse (אלפית השניה). | -| `AUDIT_LLM_TIMEOUT_MS` | לא | `1440000` | timeout לשיחה חקירה agentic עם שירות AI assistant. לולאת agent שלמה פועלת לדקות; שמור זאת למעלה מ-`AGENTEYE_AUDIT_TIMEOUT_MS` שלו agent כך ש-agent חוזר ממצאים חלקיים לפני השרת מתוך זמן. | -| `AUDIT_MAX_ATTEMPTS` | לא | `5` | כשלים חולפים עוקבים לפני ביקורת משדרות בקדנס רגיל במקום backoff אקספוננציאלי. | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | לא | — | חקירה agentic של ביקורת קורא שירות AI-assistant `agent`, **למעשה הקשר זהה כ-assistant** — כך הגדר את שני אלה גם על ה-**server** (המשכפלות המרוכזות/רכיבי לבוש עושים). שתי קבוצות ⇒ ביקורות פעולות חקירה AI; אחד לא מוגדר ⇒ ביקורות פעולות **policy-only** (מעבר מדיניות דטרמיניסטי SQL עדיין פועל), ללא קשר לדגל לכל ביקורת `llm_enabled`. ה-agent חייב גם LLM מוגדר — ראה [assistant.md](/he/agenteye/assistant). | - -**שירות AI assistant — הגדרות ביקורת + sandbox.** החקירה agentic וה-Python sandbox שלה בתוך-pod עדכון על ה-**agent service** (לא השרת), הכל על `AGENTEYE_AUDIT_*` prefix וכל אופציונלי: +| `SMTP_USERNAME` | לא | ללא | שם משתמש אימות SMTP | +| `SMTP_PASSWORD` | לא | ללא | סיסמת אימות SMTP | +| `SMTP_FROM` | לא | ללא | כתובת דוא"ל של השולח לדוא"לי OTP | +| `SMTP_TLS` | לא | STARTTLS | STARTTLS משמש אלא אם אתה כבה אותו במפורש: `false` או `0` שולח טקסט רגול (ללא TLS); כל ערך אחר — כולל אינו מוגדר — מאפשר STARTTLS. | +| `DASHBOARD_URL` | לא | ברירת מחדל מובנית | מקור לוח בקרה המשמש לבניית קישור קסום בדוא"ל OTP וקישורים קסומים בהודעות התריעות. אם אינו מוגדר זה חוזר לברירת מחדל מובנית (ובעבור OTP בלבד, למקור הנגזר מלוח הבקרה תחילה). הגדר זאת לעיצובי תחום-מפוצל כך שקישורי דוא"ל ו-Slack/התרעה מצביעים על לוח הבקרה שלך. ראה **URL קישור קסום דוא"ל** למטה; רוב המפעילים לא צריכים להגדיר את זה. | +| `SESSION_TTL_SECS` | לא | `86400` (24 ש"א) | משך הפעלת לוח בקרה בשניות. **זריעה בהפעלה ראשונה בלבד**: ערוך לכל ארגון דרך [`//settings`](#operational-settings) אחרי ההפעלה הראשונה. | +| `OTP_TTL_SECS` | לא | `600` (10 דק') | תקופת תוקף קוד OTP בשניות. **זריעה בהפעלה ראשונה בלבד**: ערוך לכל ארגון דרך [`//settings`](#operational-settings) אחרי ההפעלה הראשונה. | +| `REDIS_URL` | לא | ללא | אחסן זיכרון משותף אופציונלי + בקצה שיעור הגבלה, למשל `redis://redis:6379/0`. כשנקבע, השרת שומר מחשבים התייקדויות API-key, הצבירה `/models` של לוח הבקרה, רשימת הפעילויות וקצה תחום env; זה גם מעביר שיעור הגבלת בקשות OTP מ-Postgres COUNT ל-Redis INCR. אם לא מוגדר או לא מושג, השרת פועל ללא אחסן זיכרון (הגבלת OTP חוזרת ל-Postgres, כל קריאת אחסן זיכרון נופלת דרך למקור האמת). ראה **Redis (אחסן זיכרון אופציונלי)** למטה. | +| `CLICKHOUSE_URL` | **כן** | ללא | URL בסיס של מכונת ClickHouse, למשל `http://clickhouse:8123`. השרת מיישם את סכימת האירועים שלו למסד נתונים זה בכל הפעלה ומסרב לטעון אם הוא לא יכול להגיע ל-ClickHouse. ראה **ClickHouse (אחסן אנליטיקה נדרש)** למטה. | +| `CLICKHOUSE_DATABASE` | לא | `agenteye` | שם מסד נתונים (סכימה) של ClickHouse. השרת יוצר אותו בהפעלה אם הוא לא קיים. | +| `ORG_CH_SECRET` | לא (דיירים-יחיד) / **כן (מרובה-ארגון)** | ברירת מחדל dev | מפתח HMAC שממנו נגזר סיסמת ClickHouse לכל דיירים של כל ארגון. עורך SQL וביעילות agent של `run_query` מבצעים כמשתמש ClickHouse לקריאה בלבד של הארגון, שמנהל השורות שלו אוכף בידוד דיירים במנוע. פריסות דיירים-יחיד אתחול בסדר על ברירת המחדל dev מובנית; **לפני הפקת ארגון שני אתה חייב להגדיר ערך חזק יציב**, מכיוון ש-CLI `agenteye-orgctl org create` מסרב להיות ברירת המחדל dev מובנית. סיבוב זה משריד כל משתמש ClickHouse של הארגון עד להפעלה הבאה שסידרה מחדש אותו (סידור boot-time מרפא זה באופן אוטומטי). שמור את זה בסוד וללא שינוי על כל השכפלים. הפקת ארגון עצמה היא-פעיל-בלבד; ראה **ארגונים (רב-דיירים)** למטה. | +| `DEFAULT_ORG_NAME` | לא | `Default` | שם תצוגה שנזרע לארגון ברירת המחדל המובנה. **זריעה בהפעלה ראשונה בלבד**, ורק בזמן שהארגון עדיין נושא את זהותו הגנרית טרי-מהוגרה, מיושמת בהפעלה, ואז התעלמות. ברגע שתשנה את שם הארגון (`agenteye-orgctl org rename`) השינוי הוא סמכותי והמשתנה env זה אין עוד השפעה. | +| `DEFAULT_ORG_SLUG` | לא | `default` | תעד URL לארגון ברירת המחדל המובנה, נתיב לוח הבקרה שהוא חי בו (`//…`). אותם סמנטיקה זריעה-בהפעלה-ראשונה / טהורה-בלבד כמו `DEFAULT_ORG_NAME`. חייב להיות 1-40 alphanumerics קטנים עם מקפים פנימיים יחידים ולא מילה [שמורה](#organizations-multi-tenancy); ערך לא חוקי התעלם (הארגון שומר `default`). מאפשר התקנה דיירים-יחיד להציג כמו `/acme` במקום `/default` ללא שום שלב CLI פוסט-קומפוזיציה. | +| `RUST_LOG` | לא | `info` | רמת עלבון יומן (`debug`, `warn`, `error`, `agenteye_server=trace`) | +| `EVALUATOR_ENDPOINT` | לא | ללא | URL בסיס של שירות ההערכה שלך (למשל `http://evaluator:9000`). כשלא מוגדר כל קו האורך הערכה הוא no-op; שום שורות תור אינן כתובות, אין עובדים. ראה [Evaluation Suite](/he/agenteye/evaluation-suite). | +| `EVALUATOR_TOKEN` | לא | ללא | נשלח כ-`Authorization: Bearer ` להערכה. **חייב להיות שווה לערך זהה בו שירות ההערכה מוגדר.** אופציונלי רק אם ההערכה שלך מוגדרת ללא אסימון. | +| `EVALUATOR_WORKERS` | לא | `2` | בקצה: מספר משימות עובד לכל מכונת שרת שמשגרת הערכות. בטוח להיות מקבוצות מרובות אופקיות שרתים. | +| `EVALUATOR_CLAIM_BATCH` | לא | `4` | מספר הערכות מרבי שעובד יחיד תוביע לכל טיק. אצוות משגרות **במקביל**, אז סך הקצה על נקודת הקצה שלך ההערכה הוא `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | לא | `2` | כמה זמן עובד ישן בין ניסיונות שליחה כשכלום הוא בעתיד. | +| `EVALUATOR_POLLING_INTERVAL_SECS` | לא | `10` | קצב נופל סופי (שניות) לסקר `GET /evaluate/{id}` כשההערכה לא מחזירה `next_poll_secs` לכל תגובה ולא מפרסמת `default_poll_interval_secs` מ-`GET /config`. | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | לא | `30000` | timeout לכל בקשה HTTP כנגד ההערכה (אלפיות שנייה). | +| `EVALUATOR_MAX_ATTEMPTS` | לא | `5` | אחרי כל כך הרבה ניסיונות שנכשלו הערכה מתועדת כטרמינל `error` (או `timeout` אם הכישלונות היו timeouts בקשה). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | לא | `300` (5 דק') | כמה בתדירות השרת מחזיר `GET /config` מההערכה. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | לא | `3600` (1 שעה) | זמן קיר מרבי שפעילות ניסיון יכולה להישאר בתור הסקר לפני AgentEye מסיימת אותו כ-`timeout`. מגנים נגד הערכה שמחזירה `pending` לנצח. | +| `ALERT_WORKERS` | לא | `1` | בקצה: מספר משימות עובד לכל מכונת שרת שמערכות כללי התריעה. ראה [התריעות](/he/agenteye/alerts). | +| `ALERT_CLAIM_BATCH` | לא | `16` | מספר התריעות מרבי שעובד יחיד תוביע לכל טיק. | +| `ALERT_POLL_IDLE_SECS` | לא | `5` | כמה זמן עובד התריעות ישן כשהתור ריק. | +| `ALERT_REQUEST_TIMEOUT_MS` | לא | `15000` | timeout הערכה התריעה לכל טריגר (ClickHouse שאילתות + HTTP ערוץ יוצא). | +| `ALERT_MAX_ATTEMPTS` | לא | `5` | כישלונות חולפים עוקבים לפני התריעה מתוזמנת מחדש בקצבה הרגילה שלה במקום backoff מעריכי. | +| `AUDIT_WORKERS` | לא | `1` | בקצה: מספר משימות עובד לכל מכונת שרת שמבצעות ביקורות. ראה [ביקורות](/he/agenteye/audits). | +| `AUDIT_CLAIM_BATCH` | לא | `1` | מספר ביקורות בעתיד מרבי שעובד יחיד תוביע לכל טיק. חקירה סוכנית היא לולאה ארוכה אחת, אז ברירת המחדל היא 1. | +| `AUDIT_POLL_IDLE_SECS` | לא | `30` | כמה זמן עובד ביקורות ישן כשאף ביקורת אינה בעתיד. | +| `AUDIT_REQUEST_TIMEOUT_MS` | לא | `30000` | timeout לכל שאילתה-מדיניות כנגד ClickHouse (אלפיות שנייה). | +| `AUDIT_LLM_TIMEOUT_MS` | לא | `1440000` | timeout לשיחת חקירה סוכנית לשירות עוזר AI. לולאת סוכן מלאה פועלת לדקות; שמור את זה מעל שלך הסוכן שלו `AGENTEYE_AUDIT_TIMEOUT_MS` אז הסוכן מחזיר ממצאים חלקיים לפני השרת מוותר. | +| `AUDIT_MAX_ATTEMPTS` | לא | `5` | כישלונות חולפים עוקבים לפני ביקורת מתוזמנת מחדש בקצבה הרגילה שלה במקום backoff מעריכי. | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | לא | — | השיחה החקירה הסוכנית של ביקורת קוראת שירות עוזר AI `agent`, **משימוש בחיבור זהה כמו העוזר** — אז הגדר את אלה שתיים גם **בשרת** (פריסות משודרות/compose עושה). שניהם להגדיר ⇒ ביקורות הפעלת חקירת AI; או לא מוגדר ⇒ ביקורות הפעלת **מדיניות-רק** (עבור SQL דטרמיניסטי מדיניות עדיין פועל), בעלות דגל `llm_enabled` לכל ביקורת. הסוכן חייב גם LLM מוגדר — ראה [assistant.md](/he/agenteye/assistant). | + +**עוזר AI שירות — ביקורת + הגדרות חממה.** החקירה הסוכנית והחממה Python בתוך-פוד שלה מכוונות **שירות סוכן** (לא השרת), הכל בתחילית `AGENTEYE_AUDIT_*` והכל אופציונלי: | משתנה | ברירת מחדל | משמעות | |---|---|---| -| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | מקס סיבוב agent לכל חקירה. | -| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | wallclock לחקירה אחת (20 דק'). חייב להישאר **למעלה** מ-`AUDIT_LLM_TIMEOUT_MS` שלו שרת. | -| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | חקירות בו-זמניות לכל pod agent (בנפרד מהתקציב של chat assistant). | -| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | גבולות לכל-סקריפט לכל bubblewrap sandbox. | +| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | טיפול סוכן מרבי לחקירה. | +| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | קיר-שעון לחקירה אחת (20 דק'). חייב להישאר **תחת** השרת שלך `AUDIT_LLM_TIMEOUT_MS`. | +| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | חקירות במקביל לכל פוד סוכן (נפרד מתקציב העוזר הצ'אט). | +| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | לתסריט גבולות אחד לחממה bubblewrap. | -**דרישת פלטפורמת Sandbox.** קוד ביקורת sandbox פעולה בתוך Python של דוגמן בתוך כלא bubblewrap, אשר זקוק **משתמש לא חיזוק user namespaces**. pod ה-agent חייב לאפשר את `clone()` flags — הגדר `seccompProfile: Unconfined` (k8s) או `security_opt: [seccomp:unconfined]` (compose) על agent. כאשר kernel של צומת משבית user namespaces לא-חיזוק (למשל כמה GKE COS images), ה-sandbox **preflight נכשל ו-auditor משדרות SQL-בלבד באופן אוטומטי** — אין שגיאה, פשוט `sandbox_available: false` על `/health` של agent. | +**דרישת פלטפורמה חממה.** חממה קוד ביקורת פעלנית Python של המודל בתוך כלא bubblewrap, הזקוק **מרחבי משתמש ללא הרשאות**. פוד הסוכן חייב להרשות דגלי `clone()` — הגדר `seccompProfile: Unconfined` (k8s) או `security_opt: [seccomp:unconfined]` (compose) בסוכן. איפה קרנל הצומת מנטרל מרחבי משתמש ללא הרשאות (למשל כמה GKE COS תמונות), חממה **preflight כשל וביקורת שפלה SQL-רק באופן אוטומטי** — אף טעות, רק `sandbox_available: false` בסוכן שלך `/health`. -### הפעל +### הרץ -הגדר `DATABASE_URL` ו-`CLICKHOUSE_URL` בסביבתך (השרת מסרב להתחיל ללא ClickHouse), ואז תמסור אותם דרך לכלי: +הגדר `DATABASE_URL` בסביבה שלך, ואז העבר את זה דרך למכל: ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest ``` -השרת משמיע הגדרות בסיס נתונים באופן אוטומטי בהתחלה; שום שלב הגדרה נפרד נחוץ. +השרת מריץ הנדסות מסד נתונים באופן אוטומטי בהפעלה; אין שלב הנדסה נפרד נדרש. ### בדיקת בריאות ``` -GET /health # liveness - תמיד {"status":"ok"} לאחר שהתהליך פועל -GET /ready # readiness - 200 כאשר Postgres + ClickHouse הם זמינים, אחרת 503 +GET /health # liveness - always {"status":"ok"} once the process is up +GET /ready # readiness - 200 when Postgres + ClickHouse are reachable, else 503 ``` -אין דרישה לאימות. השתמש ב-`/health` לסיקור **liveness** ו-`/ready` לסיקורי **readiness** / load-balancer. `/ready` בדיקות התלויות הקשות שהשרת לא יכול לשרת ללא (Postgres + ClickHouse), כך שכלי שפועל אך אינו יכול להגיע לבסיס הנתונים שלו מוצא מתוך סיבוב ומציג כ-`NotReady`; Redis דיווח אך לעולם נכשל readiness. על המניפסטים המרוכזים של Kubernetes הסיקור readiness כבר מוצבע ב-`/ready` ו-liveness נשאר ב-`/health`. ראה [enterprise-docs/health-monitoring.md](/he/agenteye/health-monitoring) לתמונה המוקדמת, כולל opt-in Kubernetes-native pod-failure התראה ל-Slack. +אין אימות נדרש. השתמש ב-`/health` ל-**liveness** בחדשות ו-`/ready` ל-**readiness** / עומס מאזן בחדשות. `/ready` בודקות התלויות הקשות שהשרת לא יכול להשרת ללא (Postgres + ClickHouse), אז שרת שפעיל אך לא יכול להגיע למסד הנתונים שלו מוצא מהסיבוב ומוצג כ-`NotReady`; Redis מדווח אך לעולם לא נכשל readiness. על פריסות Kubernetes משודרות פגם readiness כבר מצביע על `/ready` ו-liveness נשאר ב-`/health`. ראה [enterprise-docs/health-monitoring.md](/he/agenteye/health-monitoring) לתמונה המלאה, כולל opt-in ניטור כשל פוד Kubernetes-ילידי ל-Slack. -### כתובת קישור קסום של דוא"ל +### URL קישור קסום דוא"ל -דוא"לי התחברות OTP מכילים כפתור **פתח דשבורד** חד-הקשה. לחיצה עליו מנחתת את המשתמש על `/login?token=&email=
`; הדשבורד מחליף צמד זה לסשן וחוזר אל האפליקציה, ללא הזנת קוד ידנית חוזרת. השרת פותר מקור הדשבורד המשמש לבנייה הקישור בשלוש רמות: +דוא"לי כניסה OTP כוללים כפתור **לפתוח את לוח הבקרה** בעלויות לכל דבר. לחיצה בו נוחתת המשתמש על `/login?token=&email=
`; לוח הבקרה מחליף זוג זה לפעילות וניתוב ל-אפליקציה, ללא re-entry קוד ידני. השרת פותר את מקור לוח הבקרה שמשמש לבניית הקישור בשלוש רמות: -1. **`X-AgentEye-Dashboard-Url` header**: הגדר באופן אוטומטי על ידי proxy `/api/auth/otp/request` של הדשבורד מהמקור הציבורי שלו. בפריסה same-origin (שרת ודשבורד שיתוף בעל אחד מאחורי ערסל אחד המעביר headers proxy), **אין תצורה נדרשת**. -2. **`DASHBOARD_URL` env var**: הגדר זאת אם הדשבורד שלך זמין על מקור שונה מה-origin שנקודת בקשת OTP של השרת רואה (split `api.example.com` / `app.example.com`), או אם ערסל שלך אינו הפוץ את host הציבורי לתוך pod הדשבורד (כך `request.nextUrl.origin` אחרת יפתור עדכון כגון `0.0.0.0:3000`). דוגמה: `DASHBOARD_URL=https://app.example.com`. -3. **ברירת מחדל**: `https://app.befailproof.ai`, בשימוש רק אם לא אחד משנייהם לעיל קיים. +1. **כותר `X-AgentEye-Dashboard-Url`**: הגדר באופן אוטומטי על ידי פרוקסי `/api/auth/otp/request` של לוח הבקרה מהמקור הציבורי שלו. בפריסה same-origin (שרת ולוח בקרה חלוקים מארח מאחורי ingress אחד שהכותרות פרוקסי מעבר), **אין תצורה נדרשת**. +2. **`DASHBOARD_URL` env var**: הגדר זאת אם לוח הבקרה שלך מושג ב-origin אחר מזה שנקודת הקשה OTP של השרת רואה (split `api.example.com` / `app.example.com`), או אם ingress שלך לא מתפשר את המארח הציבורי לתוך פוד לוח הבקרה (אז `request.nextUrl.origin` יפתור אחרת כמו `0.0.0.0:3000`). דוגמה: `DASHBOARD_URL=https://app.example.com`. +3. **ברירת מחדל**: `https://app.befailproof.ai`, משומש רק אם לא אחד משני הלעיל קיים. -ערך header מאומת: רק `https://*` ו-loopback (`http://localhost*`, `http://127.0.0.1*`) מקורות מקובלים, וכתובות bind wildcard (`0.0.0.0`, `[::]`) נדחות אפילו עם ה-`https://` סכמה. כל דבר אחר חוזר אל רמה 2. +ערך הכותר מאומת: רק `https://*` ו-loopback (`http://localhost*`, `http://127.0.0.1*`) origins מקובלים, וכתובות wildcard bind (`0.0.0.0`, `[::]`) דחויים גם עם התוכנית `https://`. כל דבר אחר נופל דרך לרמה 2. -הגדר זאת על אשכול פועל עם one-liner; לא קובץ, לא rebuild kustomize: +הגדר אותו על אשכול רץ עם בר תיל; אין קובץ, אין kustomize שיבוא מחדש: ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -זה מעלה rollout; pod החדש בוחר את הערך בבקשה ראשונה. שימו לב כי override חי רק על Deployment; `kustomize build | kubectl apply` לאחר כך כנגד overlay ימחק אותו אלא אם כן הוספת משתנה env זהה לתיקייה patch `server-env.yaml` של overlay שלך. +זה מפעיל rollout; הפודים החדשים תופסים את הערך בבקשה הראשונה. שים לב שה-override חי רק על ה-Deployment; `kustomize build | kubectl apply` עוקב נגד ה-overlay ימחוק את זה אלא אם אתה מוסיף את משתנה env זהה ל-patch `server-env.yaml` של ה-overlay שלך. --- -## דשבורד +## לוח בקרה -### שלוף את התמונה +### משוך את התמונה ```bash docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest ``` -### משתנים סביבה +### משתני סביבה | משתנה | נדרש | ברירת מחדל | תיאור | |---|---|---|---| -| `AGENTEYE_SERVER_URL` | כן | בלא | כתובת URL בסיסית של השרת, למשל `http://localhost:8080` | -| `AGENTEYE_API_KEY` | כן | בלא | מפתח API דשבורד משתמש לאימות לשרת. צרכים כל הרשאות (מפתח admin מומלץ). | -| `AE_LOG_LEVEL` | לא | `info` | קיבוץ יומן צד-שרת: `debug`, `info`, `warn`, `error`. הגדר ל-`debug` לראות בקשה מעלה/תשובה שורות וסשן-validation עקבות כאשר אבחון ממצאים. | -| `AE_LOG_JSON` | לא | אוטומטי | `1` כופה JSON-per-line פלט; `0` כופה פלט קריא לאדם. כאשר לא מוגדר, JSON מופעל באופן אוטומטי אם `NODE_ENV=production`. JSON מומלץ בייצור כך יומנים parse בצורה נקייה עם `jq` או מערכת לוגים. | -| `AE_ANALYTICS_DISABLED` | לא | בלא | הגדר ל-`1`/`true` כדי להשבית את telemetry שימוש בשימוש דשבורד אנונימי. ראה [Telemetry & privacy](#telemetry--privacy) להלן. | -| `REDIS_URL` | לא | בלא | אופציונלי חסומה משותפת backend, למשל `redis://redis:6379/0`. כאשר מוגדר, דשבורד משימור `validateSession()` תוצאות על משכפלות ויתרות הבא.js fetch חסומה לנתבי proxy latency-aggregate / env-list. קצב OTP בקשה ו-verify גם השתמש Redis כאשר קיים (נפילה פתוח אם Redis לא זמין; קצב צד-שרת הוא backstop ביטחון). ראה **Redis (אופציונלי חסומה)** להלן. | -| `AGENTEYE_AGENT_URL` | לא | בלא | כתובת URL בסיסית של שירות `agent` AI-assistant אופציונלי, למשל `http://agent:9100`. **השאר אותו לא מוגדר להסתיר את ה-assistant לחלוטין**: בועת assistant אינה מופיעה בדשבורד. ראה [enterprise-docs/assistant.md](/he/agenteye/assistant). | -| `AGENTEYE_AGENT_TOKEN` | לא | בלא | סוד משותף דשבורד מופיע לשירות `agent`. חייב להתאים את `AGENTEYE_AGENT_TOKEN` מוגדר על ה-agent. ראה [enterprise-docs/assistant.md](/he/agenteye/assistant). | +| `AGENTEYE_SERVER_URL` | כן | ללא | URL בסיס של השרת, למשל `http://localhost:8080` | +| `AGENTEYE_API_KEY` | כן | ללא | מפתח API בו לוח הבקרה משתמש כדי להצטייד לשרת. צריך כל הרשאות (מפתח admin מומלץ). | +| `AE_LOG_LEVEL` | לא | `info` | רמת עלבון יומן בצד שרת: `debug`, `info`, `warn`, `error`. הגדר ל-`debug` לראות שורות בקשה/תגובה עלות זרם וטרייסות אימות פעילות כשאתה אבחון בעיות. | +| `AE_LOG_JSON` | לא | אוטו | `1` כופה פלט JSON-לכל-שורה; `0` כופה פלט קריא לאדם. כשלא מוגדר, JSON מופעל באופן אוטומטי אם `NODE_ENV=production`. JSON מומלץ בייצור כך יומנים נתחתו בנקיוות עם `jq` או מפתח לוג. | +| `AE_ANALYTICS_DISABLED` | לא | ללא | הגדר ל-`1`/`true` להשבית טלמטריה שימוש מוצר אנונימיות של לוח הבקרה. ראה [טלמטריה & פרטיות](#telemetry--privacy) למטה. | +| `REDIS_URL` | לא | ללא | אחסן זיכרון משותף אופציונלי, למשל `redis://redis:6379/0`. כשנקבע, לוח הבקרה משמור `validateSession()` תוצאות על כל השכפלים וחלוקה ה-Next.js השלך שומר אחסן לנתיבי צבירה זמן-חזון / env-רשימה. גם קצבה תור ומאמת OTP בצד גופן משתמשים Redis כשקיים (נופל פתוח אם Redis לא מושג; ניטור בצד שרת הוא backstop בטיחות). ראה **Redis (אחסן זיכרון אופציונלי)** למטה. | +| `AGENTEYE_AGENT_URL` | לא | ללא | URL בסיס של שירות עוזר AI אופציונלי `agent`, למשל `http://agent:9100`. **השאר את זה לא מוגדר להסתיר את העוזר לחלוטין**: אף בועת עוזר מופיעה בלוח הבקרה. ראה [enterprise-docs/assistant.md](/he/agenteye/assistant). | +| `AGENTEYE_AGENT_TOKEN` | לא | ללא | סוד משותף ב-לוח הבקרה מציג לשירות `agent`. חייב להתאים `AGENTEYE_AGENT_TOKEN` מוגדר בסוכן. ראה [enterprise-docs/assistant.md](/he/agenteye/assistant). | -### הפעל +### הרץ ```bash docker run -d --restart unless-stopped \ @@ -189,91 +187,91 @@ docker run -d --restart unless-stopped \ ghcr.io/agenteye-enterprise/dashboard:beta-latest ``` -### Telemetry & privacy +### טלמטריה & פרטיות -הדשבורד שולח **analytics שימוש בשימוש אנונימי** לשירות analytics של Exosphere (PostHog): דפי דשבורד נצפו וקומץ פעולות UI כמו יצירת מפתח API או re-evaluating סשן. אות שימוש זה מודיע אילו תכונות עדיפות. +לוח הבקרה שולח **ניתוח שימוש מוצר אנונימי** לשירות ניתוח של Exosphere (PostHog): איזה עמודי לוח בקרה יוצגו וקבוצה של פעולות UI כמו יצירת מפתח API או הערכה מחדש של פעילות. אות שימוש זה מהמידע איזה תכונות יעדיפו. -- **אין agent, סשן, או נתוני אירוע עוזבת את התשתית שלך.** רק שימוש UI דשבורד דיווח. כתובות עמוד מעוטות מזהים לפני שליחה, ותפעילים מזוהים רק על ידי opaque פנימי id, לעולם לא כמו דוא"ל. -- Telemetry הוא **מופעל כברירת מחדל**. כדי לכבות אותו לחלוטין, הגדר `AE_ANALYTICS_DISABLED=1` על כלי דשבורד ו-restart. -- Analytics משלוח ל-`/ingest` דרך של דשבורד, אשר דשבורד reverse-proxies PostHog (`https://us.i.posthog.com`). שימור requests first-party פירושו browser ad-blockers לא משנה אותם. ה-**dashboard container** צרכים יוצא גישה ל-PostHog; אם זה חסום, telemetry בשקט לא עושה כלום והדשבורד לא מושפע. +- **אף אחד סוכן, פעילות, או נתונים אירוע לעולם עוזב את התשתית שלך.** רק שימוש UI לוח בקרה מדווח. כתובות דף מעלות זיהוי לפני שליחה, ומפעילים מזוהים רק על ידי id פנימי אטום, לעולם לא על ידי דוא"ל. +- טלמטריה **מופעלת כברירת מחדל**. כדי להכבות זאת לחלוטין, הגדר `AE_ANALYTICS_DISABLED=1` בתא לוח הבקרה והפעל מחדש. +- אנליטיקה נשלחה ללוח הבקרה שלה בעצמו `/ingest` נתיב, בו לוח הבקרה reverse-proxies ל-PostHog (`https://us.i.posthog.com`). שמירת בקשות first-party אומר חוסמי פרסומות בדפדפן לא טרופים אותם. **תא לוח הבקרה** צריך גישה יוצאת ל-PostHog; אם זה חסום, טלמטריה שמחרישת ולוח הבקרה לא מושפע. --- -## AI Assistant (אופציונלי) +## עוזר AI (אופציונלי) -in-dashboard AI assistant מאפשר לצוות שלך לשאול שאלות של agent נתוני בשפה רגילה (summarising סשנים, drafting SQL עבור עורך `/queries`, והפיכה של שאלות שמורות כדי דשבורד רעפים) ללא עזיבת דשבורד. זה פעולה כ-pod container `agent` פנימי נפרד (ב-Claude Agent SDK) שרק דשבורד יכול להגיע, ו-stays **השבת עד שתחפש LLM endpoint**. +עוזר AI בתוך-לוח בקרה מאפשר לצוות שלך לשאול שאלות של נתוני agent שלהם בשפת טבע (סיכום פעילויות, טיוטה SQL לעורך `/queries`, וטיוטה שמורה שאילתות ללוח בקרה מרות) ללא עזוב את לוח הבקרה. זה פועל כתא פנימי נפרד `agent` (ב-Claude Agent SDK) שרק לוח הבקרה יכול להגיע, ונשאר **מושבת עד שתורכל סוף LLM**. -כדי לאפשר זאת אתה הגדרת, על שירות `agent`, חיבור LLM (**Portkey** דרך `PORTKEY_API_KEY` + דגם-catalog slug `AGENTEYE_AGENT_MODEL=@/`, Anthropic ישיר דרך `ANTHROPIC_API_KEY`, gateway אחר דרך `ANTHROPIC_BASE_URL`, או Bedrock/Vertex), **מפתח נתוני דתי**, ו-`AGENTEYE_AGENT_TOKEN` משותף תאם דשבורד. משתמשי דשבורד בנוסף צרכים `agent:use` הרשאות. +כדי להפעיל את זה אתה הגדרת, ב-שירות `agent`, חיבור LLM (**Portkey** דרך `PORTKEY_API_KEY` + קטלוג-מודל slug `AGENTEYE_AGENT_MODEL=@/`, Anthropic ישיר דרך `ANTHROPIC_API_KEY`, שער אחר דרך `ANTHROPIC_BASE_URL`, או Bedrock/Vertex), **ייעודי** מפתח נתונים, וMiDARK `AGENTEYE_AGENT_TOKEN` התאמה לוח הבקרה. משתמשי לוח הבקרה בנוסף צריכים הרשאה `agent:use`. -עבור מפתח נתוני דתי של assistant אתה לא לעטוף כלום ביד: בחרו secret אקראי, הגדר אותו בתור `AGENTEYE_API_KEY` על `agent` **ו** כמו `AGENT_API_KEY` ב `server`, ו-server זורעת אותו בעת התחלה עם set הרשאות קבוע. גישת נתוני שלה היא read-only (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), ובנוסף מחזקה authoring scopes אישור-gated (`dashboards:write`, `queries:write`, `queries:run`) כך שהוא יכול draft ו-validate שאלות שמורות בנים דשבורד רעפים על המשתמש של behalf; כל SQL עדיין פעולה דרך ארגון read-only ClickHouse תפקיד, כך ש-widening פירוש מה-assistant יכול author, לא אשר נתונים זה יכול להגיע. ה-scopes הם קבוע בקוד ו-cannot להרחיב על ידי תצורה. מפתח זה מוגן; זה לא יכול להיות השבת או תחדול דרך API, רק סיבוב על ידי עדכון הערך ו-restart. לעולם לא reuse admin/dashboard מפתח לזה. +לנתוני מפתח של העוזר אתה לא מטבע כלום ביד: בחר סוד אקראי, הגדר את זה כמו `AGENTEYE_API_KEY` בסוכן **ו** כמו `AGENT_API_KEY` בשרת, והשרת זורע אותו בהפעלה עם כמה הרשאות קבועות. גישת נתונים שלו היא read-only (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), ובנוסף מחזיק אישור-gated כתיבה scopes (`dashboards:write`, `queries:write`, `queries:run`) כך זה יכול לטיוטה ותמונות שאילתות שמורות ובניה מרות לוח בקרה בעבור המשתמש; כל SQL עדיין הפעלה דרך תפקיד ClickHouse read-only של הארגון, אז זה מרחיב מה העוזר יכול יוצר, לא נתונים אותו יכול הגיע. Scopes קבועים בקוד ולא יכול להיות מורחב בתצורה. מפתח זה מוגן; זה לא יכול מושבת או regenerated דרך ה-API, רק rotated על ידי שינוי הערך והפעלה מחדש. לעולם לא השתמש מחדש admin/dashboard מפתח לכך. -הגדרה מלאה, reference משתנה סביבה מלאה, אפשרויות telemetry, ו-security דגם נמצאים ב-**[enterprise-docs/assistant.md](/he/agenteye/assistant)**. +הגדרה מלאה, ה-משתנה סביבה כללו התייחסות, טלמטריה אפשרויות, וביטחון הדגם הם ב-**[enterprise-docs/assistant.md](/he/agenteye/assistant)**. --- -## ClickHouse (חנות ניתוחים נדרשת) +## ClickHouse (אחסן אנליטיקה נדרש) -ClickHouse שומר דשבורד שלך מגיב בנתח גבוה אירוע ותן `/queries` עורך SQL לצטרף על פני אירועים, הערכות, וסשנים בחנות יחיד. זה חנות הקנוני הנדרשת עבור כל אירוע ingested, כל תוצאת הערכה סופית, ו-derived לכל-סשן aggregates. PostgreSQL מאחסן יחסי / mutable-state טבלאות (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); ה-analytical משטח חיים ב-ClickHouse כדי דשבורד הרולאפים ו-SQL queries שלך יכול כוח וצטרף זה באופן native, ללא בין-בסיס-נתונים round-trips. השרת מסרב להתחיל ללא `CLICKHOUSE_URL`. +ClickHouse שומר לוחי בקרה שלך הגיוני בכרכים אירוע גבוה ומאפשר SQL של עורך `/queries` צירוף על אירועים, הערכות, ופעילויות בחנות יחידה. זה את החנות קנוני נדרש לכל אירוע שנספג, כל פעילות מסוף תוצאה, והנגזר לכל-פעילות צבירות. PostgreSQL מחזיק את יחסית / mutable-מצב טבלאות (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); ה-משטח אנליטי חי ב-ClickHouse כך לוח הבקרה's rollups וה-SQL שלך שאילתות יכול סריקה וצירוף זה בעצמו, ללא cross-database סיבובים. השרת מסרב טעון ללא `CLICKHOUSE_URL`. -### סכמה +### סכימה -שלוש עצמים ClickHouse נוצרים בהתחלת שרת, הכל idempotent (`CREATE IF NOT EXISTS`): +שלוש ClickHouse עצמים נוצרים בהפעלת שרת, כל idempotent (`CREATE IF NOT EXISTS`): -- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, מחולק על ידי `toYYYYMM(ts)`, מסודר על ידי `(session_id, ts, dedup_key)`. כפול מכניס (collector retries) שיתוף שורה יחיד בעת merge זמן; השרת מחשבות deterministic SHA-256 `dedup_key` עבור כל אירוע כדי retries בטוחות. -- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, מחולק על ידי `toYYYYMM(finished_at)`, מסודר על ידי `(session_id, finished_at, dedup_key)`. כתוב פעם לתוצאת הערכה סופית על ידי צינור evaluator. אותה dedup-key דגם כמו `events`. -- **`agenteye.agent_sessions`**: a **VIEW** על `agenteye.events`, לא טבלה פיזית. כל עמודה היא נגזרת (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, וכו'). שום לכל-אירוע upsert ו-no separate backfill; view auto-reflects מה הוא בתוך `events`. +- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, חולק לפי `toYYYYMM(ts)`, סדור לפי `(session_id, ts, dedup_key)`. כפול insert (collector ניסיונות) קוטע שורה יחידה בהתמזגות זמן; השרת מחשב קובע SHA-256 `dedup_key` לכל אירוע אז ניסיונות בטוחים. +- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, חולק לפי `toYYYYMM(finished_at)`, סדור לפי `(session_id, finished_at, dedup_key)`. כתובה פעם אחת לכל טרמינל הערכה תוצאה על ידי קו האורך evaluator. אותם dedup-key דגם כמו `events`. +- **`agenteye.agent_sessions`**: **VIEW** על `agenteye.events`, לא טבלה פיזית. כל עמודה נגזרת (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, וכו'). אף לא לכל-אירוע upsert ולא ממלא נפרד; ה-view auto-מחזיר איך הוא בתוך `events`. -עבור backwards-compat עם שאלות שמורות שהפניות `analytics.evaluations` / `analytics.sessions`, השרת גם יוצר `analytics` ClickHouse בסיס נתונים עם עיקולים על `agenteye.*` טבלאות; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` כל החל שלוח. +לעבור-compat עם שמורה שאילתות שהגיע `analytics.evaluations` / `analytics.sessions`, השרת גם יוצר `analytics` ClickHouse מסד נתונים עם נבטים על `agenteye.*` טבלאות; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` כל התמיד בנקיוות. ### תצורה -docker-compose המרוכז ו `deploy/base/clickhouse/` חנות ClickHouse שירות tuned עבור workload של AgentEye: +ה-משודר docker-compose וגם `deploy/base/clickhouse/` משדר שירות ClickHouse כיוונון לעומס עבודה של AgentEye: -- 2 GiB בקשה / 4 GiB restrict זיכרון בתיקייה משלחת base overlay (sized להתאים קטן POC/staging צמתים); ייצור לקוחות צריך overlay למעלה — הרצפה מומלצת היא 2c / 4Gi בקשה, 6c / 8Gi restrict. `max_server_memory_usage_to_ram_ratio=0.9` -- 5 GiB סימן חסומה + 8 GiB uncompressed חסומה +- 2 GiB בקשה / 4 GiB כחוג זיכרון בבסיס משודר overlay (בגודל לעמוד קטן POC/staging צמתים); ייצור לקוחות צריכים overlay עד — הרצפה מומלצת היא 2c / 4Gi בקשה, 6c / 8Gi כחוג. `max_server_memory_usage_to_ram_ratio=0.9` +- 5 GiB סימן אחסן + 8 GiB דחוסu אחסן - `background_pool_size=16`, `background_merges_mutations_concurrency_ratio=2` - MergeTree: `parts_to_throw_insert=3000`, `parts_to_delay_insert=1500`, `non_replicated_deduplication_window=1000` -- `local_io_method=auto` (io_uring על supported kernels) -- `fsync_metadata=0`: קביל כי של לפחות-פעם-אחת ingest + ReplacingMergeTree dedup +- `local_io_method=auto` (io_uring בתמיכת צמתים) +- `fsync_metadata=0`: קביל כי לפחות-פעם ingest + ReplacingMergeTree dedup - `query_log` מופעל עם 30-יום TTL; `query_thread_log` הוסר (יקר בגבוה QPS) -- `max_execution_time=30` עבור בצד-משתמש queries -- 100 GiB PVC בתבנית StatefulSet (משתמש overlays צריך override ל-fast SSD storage class עבור ייצור) +- `max_execution_time=30` לשאילתות בצד משתמש +- 100 GiB PVC בתבנית StatefulSet (לקוח overlays צריך לעלות מהיר SSD סוג אחסן לייצור) -### Backups +### גיבויים -ערכת הנתונים המוקדמת שלך מתקבלת nightly בחוקי יחיד restoreable, כל צומת או אחסן הפסד recoverable. ClickHouse מגובה באופן אוטומטי על ידי יומי `agenteye-backup` CronJob, אשר חנויות PostgreSQL וClickHouse ב-pass אחד. ClickHouse קרוא על פני HTTP API שלו: `agenteye.events` ו `agenteye.evaluations` dumped ב-ClickHouse-native עיצוב (ה-views וקו מדיניות recreated על ידי שרת בעת התחלה, כדי טבלה נתונים היא התמונה מלאה) וצרור עם Postgres dump כדי archive דחוס יחיד upload ל-object אחסן שלך. +הנתונים המלאים שלך נתפסים כל לילה בארכיון תערוקה יחיד, אז אשכול או אובדן אחסן ניתן להחזיר. ClickHouse נתמך באופן אוטומטי על ידי ה`agenteye-backup` CronJob יומי, דפדפן אחוות PostgreSQL וClickHouse בעבור. ClickHouse קרא על ה-HTTP API שלה: `agenteye.events` וגם `agenteye.evaluations` דפדפן ב-ClickHouse-ילידי פורמט (ה-נבטים וקצבה מדיניות יוצרו מחדש על ידי השרת בהפעלה, אז נתונים טבלה הוא תמונה מלאה) וקיבוץ עם מצע Postgres לארכיון דחוסu יחיד מוספות לאחסן עצמים שלך. -יעד bucket וודת credentials עננים configured לכל overlay. ראה את **Backups** סעיף של [enterprise-docs/kubernetes-deployment.md](/he/agenteye/kubernetes-deployment) עבור upload תצורה ו-restore שלבים. +ה-bucket היעד וערבון מהוד מוגדרים לכל overlay. ראה סעיף **גיבויים** של [enterprise-docs/kubernetes-deployment.md](/he/agenteye/kubernetes-deployment) לעלות תצורה וחזור שלבים. --- -## Redis (אופציונלי חסומה) +## Redis (אחסן זיכרון אופציונלי) -Redis היא **אופציונלי** משותפת חסומה + קצב-הגבלה backend בשימוש על ידי שרת ודשבורד. עם Redis deployed ו `REDIS_URL` הגדר על שניהם שירותים: +Redis היא **אופציונלי** אחסן זיכרון משותף + בקצה שיעור הגבלה בשימוש על ידי השרת ולוח הבקרה. עם Redis פרוסה ו-`REDIS_URL` קבוע על שני שירותים: -- **Server** משימור מאומת API-key lookups, `/events/environments` + `/evaluations/environments` רשימות, `/events/latency_aggregate` rollup (הכבדה ביותר query דשבורד סקרים), `/sessions` רשימות, וmoves קצב OTP בקשה מ-Postgres `COUNT(*)` ל-Redis `INCR + EXPIRE`. -- **Dashboard** משימור `validateSession()` תוצאות כדי 10-20 authed API קוראות typicalpage load ממנו כל שיתוף בעלות סשן בודד. זה גם קצב-גבולות OTP בקשה וOTP-verify בדשבורד edge. +- **Server** משמור התייקדויות API-key, ה-`/events/environments` + `/evaluations/environments` רשימות, ה-`/events/latency_aggregate` rollup (הכבד ביותר שאילתה לוח הבקרה סקרים), ה-`/sessions` רשימה, וסוויץ' שיעור הגבלה בקשה OTP מ-Postgres `COUNT(*)` ל-Redis `INCR + EXPIRE`. +- **Dashboard** משמור `validateSession()` תוצאות אז ה-10-20 authed API מטלות עלות דף טיפול שכל חלוקה משותף אחד בדיקה זרם שרת. זה גם משעות מקצב OTP-בקשה וOTP-עד זה קצה לוח הבקרה. -**שניים שירותים degrade gracefully אם Redis להגיע.** כל חסומה קריאה מחזירה `Err` בתוך bounded timeout וקורא חוזר למקור האמת (Postgres על שרת, ה-Rust שרת upstream על דשבורד). קצב OTP חוזר ל-Postgres `COUNT(*)` דרך על שרת (ביטחון רכוש היא preserved); דשבורד edge OTP הגבול נכשל פתוח בזמן שרת-צד הגבול עדיין מחזיק. Redis להיות למטה degrades latency, לא correctness. +**שני שירותים יורדים בחן אם Redis לא מושג.** כל קריאת אחסן זיכרון מחזירה `Err` בתוך timeout קשור וקורא חוזר ל-מקור האמת (Postgres בשרת, הנחמד Rust שרת בלוח הבקרה). OTP שיעור הגבלה חוזר ל-Postgres `COUNT(*)` נתיב בשרת (הביטחון רכוש שמור); לוח הבקרה's קצה OTP הגבלה נופל פתוח בזמן השרת בצד הגבלה עדיין ממשיכה. Redis הווה למטה פוגע זמן-חזון, לא תקינות. ### תצורה -docker-compose חבילה כבר כולל Redis שירות וhardwares `REDIS_URL=redis://redis:6379/0` לתוך שרת ודשבורד. לשימוש בחיצוני Redis, הגדר `REDIS_URL` ל-endpoint ושלך הסר `redis` שירות מ-compose קובץ. +ה-docker-compose צרור כבר כולל שירות Redis וקווי `REDIS_URL=redis://redis:6379/0` לשרת ולוח הבקרה. כדי להשתמש ב-Redis חיצוני, הגדר `REDIS_URL` לנקודה הקצה שלך והסר את `redis` שירות מקובץ הרכבה. -### זיכרון + persistence +### זיכרון + התמשכות -bundled Redis תמונה פעולה עם `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. AOF persistence פירוש החסומה survives כלי restarts; `everysec` הוא האמצע נכון durability/perf כי losing את אחרוני secondes של החסומה כתיבות בטל. LRU eviction caps זיכרון גדילה. +ה-משודר Redis תמונה פועלת עם `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. AOF התמשכות מקבל אחסן זיכרון מן שרת תא; `everysec` הוא הנכון קביעות/ביצועים איזון מכיוון שאבד אחרון שנייה של אחסן זיכרון כתיבה harmless. LRU eviction תקווה זיכרון גדילה. -### כאשר לא ל-deploy Redis +### מתי לא פרוס Redis -- יחיד-מופע פיתוח/QA. ה-in-process caches על שרת לבדו deliver רוב of per-replica הטבה; Redis מוסיף את הצלב-replica חלוקה שהיחיד-מופע setups לא צורך. -- אוויר-gapped מתקנים כאשר על פעולתי עלות של ריצה אחד יותר שירות outweighs את latency לצד חלוקה. +- יחיד-instance dev/QA. ה-in-process אחסנים בשרת לבד לספק כמו כל לכל-חזרה טובה; Redis מוסיף את כל-חזרה שיתוף עומס שיחיד-instance להגדרות לא צורך. +- אויר-מנותק התקנות איפה שהם תפעול עלות של הפעלה אחד יותר שירות משקל הזמן-חזון. --- ## Docker Compose (מומלץ) -A `docker-compose.yml` זמין ב `agenteye-enterprise/releases` repo. זה מעלה Postgres, ClickHouse, Redis, שרת, ודשבורד עם פקודה יחיד. +ה-`docker-compose.yml` זמין בריפו `agenteye-enterprise/releases`. זה עלויות Postgres, השרת, ולוח הבקרה עם פקודה יחידה. ```bash GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ @@ -283,19 +281,19 @@ GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ cd agenteye ``` -**דרוג ברירות מחדל דרך `.env`:** +**עלויות ברירות מחדל דרך `.env`:** ``` -# שימוש URL-safe סיסמאות (לא /, +, או = תווים). -# ייצור עם: openssl rand -hex 24 +# Use URL-safe passwords (no /, +, or = characters). +# Generate with: openssl rand -hex 24 POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret -# דשבורד אימות +# Dashboard authentication ADMIN_EMAIL=admin@yourcompany.com ALLOWED_EMAILS=*@yourcompany.com -# SMTP עבור דוא"ל OTP (השמט ל-log קודי OTP ל-stdout) +# SMTP for OTP emails (omit to log OTP codes to stdout) # SMTP_HOST=smtp.yourprovider.com # SMTP_PORT=587 # SMTP_USERNAME=your-smtp-user @@ -309,13 +307,13 @@ RUST_LOG=info docker compose up -d ``` -**עצור (שומר נתוני כרך):** +**עצור (שומר נתונים כרך):** ```bash docker compose down ``` -**עצור וwipe כל נתונים:** +**עצור וחזל כל הנתונים:** ```bash docker compose down -v @@ -323,78 +321,65 @@ docker compose down -v --- -## הגדרות תפעוליות +## הגדרות תפעול -קבוצה קטנה של תפעול קנבסים שבשימוש להיות נעוצה על ידי env vars הם כעת editable לכל ארגון מ-**`//settings`** דשבורד עמוד; כל ארגון מוגדר שלה שלה. שינויים לא עובר בתוך שניות, עם לא restart ואין redeploy. +כמה קבוצה של קבוצת תפעול הצמד להיות משודר על ידי env vars הם כעת editable לכל ארגון מ-**`//settings`** דף לוח הבקרה; כל ארגון מורכב משלה. שינויים ייכנסו ליום שניות, עם אף restart ו-אף redeploy. -| הגדרה | Bootstrap env var | מה שזה שולטים | +| הגדרה | Bootstrap env var | מה זה בקרה | |---|---|---| -| חתימה מורשית-ins | `ALLOWED_EMAILS` | דוא"לים (או `*@domain.com` wildcards) מורשים לקבל OTP ויהיו משתמשים | -| ברירת מחדל הרשאות משתמש | `DEFAULT_USER_PERMISSIONS` | פסיק-בתור רשימה רשאות tokens pre-selected כאשר admin פתוחים **+ משתמש חדש**. כל token חייב להיות אחד מה-strings רשום תחת [הרשאות מפתח API](/he/agenteye/api-keys). defaults ל-`standard` preset: read-only גישה בתוספת כל יום אודון-התיחות (תעסוקה re-evaluations, פעולה queries, ack incidents, שימוש assistant). | -| סשן lifetime | `SESSION_TTL_SECS` | אנגשת ארוך dash לוגין נשאר תוקף לפני re-auth. דשבורד re-checks upstream סשן כל 5 שניות, כדי הרשאה עדכון על `//users` לוקח השפעה על השפעו משתמש של בקשה הבאה, עם לא relogin. | -| חד-זמן-קוד lifetime | `OTP_TTL_SECS` | אנגשת ארוך OTP / קסום-link נשאר usable | -| התראה notification ערוצים | `ALERTS_ENABLED_CHANNELS` | פסיק-בתור רשימה ערוץ סוגים dispatcher התראה מורשה להשתמש: `email`, `slack`, `webhook`. לכל-alert תצורה עדיין authored על `//alerts/`, אך dispatcher מסננים כל יוצא-dispatch דרך set זה; ערוץ השבת כאן short-circuits עם `skipped_disabled` ביקורת שורה. `dashboard` ערוץ (local ביקורת הוסף) תמיד מורשה. Defaults להכל שלוש על. | +| מורשה sign-ins | `ALLOWED_EMAILS` | דוא"לים (או `*@domain.com` תעדול) בהיתר OTP לקבל וליהיות יצור כמו משתמשים | +| המשתמש הרשאות ברירת מחדל | `DEFAULT_USER_PERMISSIONS` | פסיק-מופרדים הרשאה אסימונים preselected מתי admin פועל **+ חדש משתמש**. כל אסימון חייב להיות אחד מ-מחרוזות תחת [API key הרשאות](/he/agenteye/api-keys). ברירות ל-`standard` preset: read-only גישה בתוספת בכל-יום on-call פעולות (טריגר re-הערכות, הפעלה שאילתות, ack התרעות, השתמש העוזר). | +| פעילות lifetime | `SESSION_TTL_SECS` | כמה זמן לוח בקרה כניסה נשאר תקף לפני re-auth. לוח הבקרה re-בדיקות זרם שרת פעילות כל 5 שניות, אז הרשאה update על `//users` בעלויות השפעו משתמש הבא בקשה, ללא relogin. | +| חד-פעמי-קוד lifetime | `OTP_TTL_SECS` | כמה זמן OTP / קסום-קישור נשאר usable | +| התריעה הודעות ערוצים | `ALERTS_ENABLED_CHANNELS` | פסיק-מופרדים רשימה ערוץ סוגים מפזר התריעה היא בהיתר להשתמש: `email`, `slack`, `webhook`. לכל-התריעה תצורה עדיין יוצר על `//alerts/`, אך מפזר משפעות כל משלוח יוצא דרך סט זה; ערוץ מנוטרל כאן קצר-מעגלים עם `skipped_disabled` ביקורת שורה. ה-`dashboard` ערוץ (המקום ביקורת הדחק) תמיד בהיתר. ברירות ל-כל שלוש בעל. -### איך bootstrap פעולה +### כיצד bootstrap עבודות -הגדרות מאוחסן לכל ארגון בתוך `org_settings`. בעת boot ראשונה, שרת זורעות ברירת מחדל ארגון של שורות חסרות מ-matching env var (או default sensible אם env var הוא unset). אחרי כן, **הערך מאוחסן היא המקור של אמת ו-env var הוא התעלם**; עדכון env var בעת restart לאחר מכן לא ישפיע על לחיות ארגון של ערך, ו-additional ארגונים התחיל מברירות מחדל וconfigure שלהם שלהם. +הגדרות מאוחסנות לכל ארגון ב-`org_settings`. בהפעלה ראשונה, השרת זורעות בברירת המחדל ארגון דפופים שורות מ-התאמה env var (או קוונטי ברירת מחדל אם env var הוא unset). אחרי כך, **מאוחסן ערך הוא מקור האמת ו-env var התעלם**; שינוי env var עם מאוחר restart לא ישפיעו ב-אורך ארגון חי ערך, וקבוצות בנוסף התחלה מ-ברירות ותורכל משלהם. -פירושו זה: +זה אומר: -- עבור fresh deploy, הגדר env vars כמו לעיל ו-default ארגון משמיע אותם בעת boot ראשונה. -- כדי לשנות ערך מאוחר, חתום לתוך דשבורד וedit זה תחת `//settings`. שינוי חל בתוך שניות על כל server משכפלות; לא restart נדרש. -- A startup יומן שורה רשומות מה קיבל seeded לעומת מה היה כבר מתנו, כדי אתה יכול לאשר bootstrap took השפעה: +- ל-טרי redeploy, קבוע env vars כמו לעיל ו-ברירת המחדל ארגון קוראים אותם בהפעלה ראשונה. +- כדי שנה ערך מאוחר, היכנס לוח הבקרה ו-עריכה זה תחת `//settings`. השינוי מיושם בתוך שניות על כל שרת חזרות; אף restart נדרש. +- הפעלה יומן ישר רשמות מה זרע לעומת מה היה כבר קיים, אז אתה יכול לבטח bootstrap לקח אפקט: ```text INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true ``` -#### חתימה-in semantics על פני ארגונים +#### Sign-in סמנטיקה על פני ארגונים -סשן ו-OTP הם גלובלי ל-user, לא ל-single ארגון, כדי שני כללים מסכם לכל-ארגון הגדרות בעת sign-in: +פעילות ו-OTP היא גלובלי ל-משתמש, לא ל-יחיד ארגון, אז שניים כללים התמיר לכל-ארגון הגדרות ב-sign-in זמן: -- **Seshon / OTP lifetime**: את strictest (קצר) lifetime בין ארגונים משתמש שייך ל-wins. -- **Allowed sign-ins**: ה-gate ORs כל ארגון allowlist ביחד עם ארגון חברות: משתמש אולי בקשה OTP אם כלום ארגון allowlist admits דוא"ל שלהם **או** הם כבר חברה של כלום ארגון. +- **פעילות / OTP lifetime**: הקפיד (הקצרה) lifetime בין ארגונים משתמש שייכות לחמש. +- **מורשה sign-ins**: ה-קרית OR כל-ארגון allowlist יחד עם ארגון חברות: משתמש יכול בקשה OTP אם כל-ארגון allowlist יחמנים דוא"ל **או** הם כבר חברות של כל-ארגון. ### הרשאות -גישה ל-`//settings` עמוד היא gated על ידי שתי הרשאות: +גישה ל-`//settings` עמוד gated על ידי שניים הרשאות: -- `settings:read`: ראה עמוד וערכים הנוכחיים. +- `settings:read`: ראה העמוד וערכים נוכחיים. - `settings:write`: שמור שינויים. -bootstrap admin משתמש (seeded מ `ADMIN_EMAIL`) קבל שניהם באופן אוטומטי יחד עם כל הרשאה אחרת. מתן אותם ל-users אחרים מ `//users` כמו נדרש. +ה-bootstrap admin משתמש (זורע מ-`ADMIN_EMAIL`) מקבל שניהם באופן אוטומטי יחד עם כל הרשאה אחרת. תן אותם משתמשים אחרים מ-`//users` כמו יש צורך. --- -## ארגונים (מולטי-דיירנות) +## ארגונים (רב-דיירים) -פריסה יחיד יכול לשרת מרובים מבודדים **ארגונים** (דיירנים); כל שורה נתוני שייך ל-org בדיוק אחד וגידול הוא כפוי-engine בבסיס הנתונים. יחיד-דיירני התקנה צרכים כלום כאן; כל נתוני חיים ב-built-in `default` ארגון. (אתה יכול תן את ארגון friendly שם ו-URL slug, כדי זה חיים ב-e.g. `/acme` במקום `/default`, על ידי הגדרת `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` לפני ראשון boot, או על ידי הפיכת שם זה כלום זמן עם `agenteye-orgctl org rename`.) +פריסה יחידה יכול להשרת מרובה מבודדות **ארגונים** (דיירים); כל שורה נתונים שייכות בדיוק אחד ארגון ובידוד אוכף בצד מסד הנתונים. דיירים-יחיד התקנה צורך כלום כאן; כל נתונים חי בבנוי `default` ארגון. (אתה יכול לתן ארגון זה chatty שם וURL תעד, אז זה חי ב-, `/acme` במקום `/default`, על ידי הגדרה `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` לפני הראשון boot, או על ידי שינוי שם זה בכל זמן עם `agenteye-orgctl org rename`.) -**דיירן provisioning הוא אופרטור-בלבד.** ארגונים וחברויות שלהם נוצרים וניהול עם **`agenteye-orgctl`** CLI, אשר חנויות **בתוך שרת תמונה** (יחד עם `agenteye-server`) וריצה **בתוך קיים שרת pod**; יש **אין pod/Job נפרד, אין HTTP API, ואין dשbורד כפתור**. זה reuses שרת של `DATABASE_URL`, `CLICKHOUSE_URL`, ו `ORG_CH_SECRET`. +**Tenant הפקה הוא תפעול-רק.** ארגונים וחברות שלהם יוצרות וניהול עם **`agenteye-orgctl`** CLI, זה משודר **בתוך שרת תמונה** (יחד עם `agenteye-server`) והפעלות **בתוך שרת קיים פוד**; יש **אף נפרד פוד/עבודה, אף HTTP API, וא לוח בקרה כפתור**. זה השתמש מחדש בשרת `DATABASE_URL`, `CLICKHOUSE_URL`, וגם `ORG_CH_SECRET`. ```bash -# Docker Compose - exec לתוך בפעולה שרת שירות: +# Docker Compose - exec into the running server service: docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp" docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin -# Kubernetes - exec לתוך פעולה שרת Deployment: +# Kubernetes - exec into the running server Deployment: kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list ``` -זמין verbs: `org create | list | rename | delete | purge` ו `member add | list | update | remove`, עם builtin הרשאה מוגדרות `admin`, `standard`, ו `read-only`. נוסף חברים קבל OTP בעת dash בעליל לראשונה. - -**לפני יצירה שנייה ארגון:** הגדר חזק, יציב `ORG_CH_SECRET` (ה `org create` פקודה מסרב לרוץ על ה-built-in פיתוח ברירת מחדל) ו-ensure Postgres הוא **15+**. **Unchanged:** לכל-ארגון API מפתחות עדיין minted בדשבורד/API על ידי ארגון חברים; רק ארגון + חברות lifecycle התמורה לCLI. מלא פקודה reference ועבד דוגמה: **[enterprise-docs/tenant-management.md](/he/agenteye/tenant-management)**. - ---- - -## Context-window fill - -כל `model_response` אירוע מציג **context-fill כדור** — input בתוספת output תוקן כמו אחוז של אותו דוגמן של context חלון. ה-bands הם `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%), ו `reset context` (75–100%). AgentEye פתר דוגמן ids נפוץ באופן אוטומטי, כדי לא ראשוני תצורה נדרש. - -כל דוגמן ארגון חנויות מופיע תחת **הגדרות → דוגמן context חלונות**. משתמשים עם `settings:write` יכול דרוג חלון שלו או הוסף פרטי/proxy דוגמן (0–1,000,000 תוקנים); `0` פירוש "לא ידוע" וsuppresses הכדור. שינויים חל ל-newly ingested אירועים. משתמשים עם `settings:read` יכול צפה הרשימה. - -חדש אירועים קבל fill מן הרגע הוא upgrade. כדי גם למלא **היסטורי** אירועים (ו-per-model רשימה) עבור קיים deployment, הפעיל את one-off backfill — זה חנויות בתוך שרת תמונה (כמו `agenteye-orgctl`) וריצה בקיים שרת pod: +זמין פעלים: `org create | list | rename | delete | purge` וגם `member add | list | update | remove`, עם הגדרות הרשאות מובנות `admin`, `standard`, וגם `read-only`. יצור חברות ממש OTP בהפעלה לוח הבקרה ראשון. -# preview (הדפסות per-org השינוי, שינויים כלום): -kubectl -n agenteye exec deploy/server -- \ No newline at end of file +**לפני יצירת שניה ארגון:** הגדר חזק, יציב `ORG_CH_SECRET` (ה-`org create` פקודה מסרב להפעלה בברירת המחדל dev מובנית) ותמונה בטוח Postgres \ No newline at end of file diff --git a/docs/he/agenteye/getting-started.mdx b/docs/he/agenteye/getting-started.mdx index 1479ff78..c9fea936 100644 --- a/docs/he/agenteye/getting-started.mdx +++ b/docs/he/agenteye/getting-started.mdx @@ -5,32 +5,32 @@ description: "תיעוד התחלה עם AgentEye." --- -מדריך זה מוביל אתכם דרך התקנה מלאה של AgentEye: פריסת השרת והלוח מחוונים, התקנת הקולטן על מכונת סוכן, והוספת instrumention לקוד הסוכן Python שלכם. +מדריך זה מלמד אתכם על הגדרת AgentEye מלאה: פריסת השרת והלוח הבקרה, התקנת המאסף על מכונת סוכן, ואינסטרומנטציה של קוד סוכן Python. --- ## מה זה AgentEye? -AgentEye הוא **פלטפורמת observability והערכה בעצמי לסוכנים בבינה מלאכותית**. הוא רושם מה הסוכנים שלכם עושים — כל שלב בריצה — והוא מעניק ניקוד אוטומטי לאיכות כל ריצה שהושלמה, כך שתוכלו לראות כיצד הסוכנים שלכם מתנהגים בייצור ולתפוס regression לפני שהמשתמשים שלכם יעשו זאת. +AgentEye היא **פלטפורמה לצפייה והערכה של סוכנים AI, המתפעלת בעצמאות**. היא מתעדת מה הסוכנים שלכם עושים — כל שלב של ריצה — וציוני באופן אוטומטי את איכות כל ריצה שהושלמה, כדי שתוכלו לראות כיצד הסוכנים שלכם מתנהגים בייצור וללכוד רגרסיות לפני שהמשתמשים שלכם עושים זאת. -הנתונים זורמים בכיוון אחד בלבד: קוד הסוכן שלכם פולט **events** דרך **ה-SDK של Python** → daemon קולטן קל משקל אוגדתים ושולח אותם לשרת → events וניתוח מאוחסנים ב-**ClickHouse** (מצב תפעולי כגון ארגונים, משתמשים, מפתחות API, לוחות מחוונים ושאילתות שמורות חיות ב-**Postgres**) → אתם חוקרים הכל בלוח **המחוונים**. +הנתונים זורמים בכיוון אחד: קוד הסוכן שלכם פולט **אירועים** דרך **ה-SDK של Python** → דמון **מאסף** קל משקל מקבצ וקרוא שהם לשרת → אירועים וניתוחים מאוחסנים ב-**ClickHouse** (מצב תפעולי כמו ארגונים, משתמשים, מפתחות API, לוחות בקרה וחיפושים שמורים גרים ב-**Postgres**) → אתה חוקר הכל ב-**לוח הבקרה**. -מה אתם מקבלים: +מה אתה מקבל: -- **Events** — שביל גולמי לכל צעד בכל ריצת סוכן (קריאות כלי, קריאות מודל, hooks, שגיאות). -- **Sessions** — אירועים אלה מגורגרים לשורה אחת לכל ריצה, כל אחת **מוערכת ומדורגת באופן אוטומטי**. -- **Evaluations** — ניקודי איכות המיוצרים על ידי שירותי ה-evaluator שלכם, כך שירידות באיכות יופיעו ללא סקירה ידנית. -- **Queries & dashboards** — SQL ClickHouse שמור על הנתונים שלכם, מעוצב לתוך לוחות מחוונים משותפים בהיקף ארגוני. -- **Alerts & incidents** — כללי סף המעניקים לכם דף (דוא"ל, Slack, webhook, בתוך הלוח) בנוסף לזרימת עבודה של incident כדי לבחור אותם. -- **CLI & AI assistant** — לקוח טרמינל (`agenteye`) וסוכן בתוך הלוח לשאילת שאלות בשפה אנגלית רגילה. +- **אירועים** — שביל גולמי, לכל שלב של כל ריצת סוכן (קריאות כלים, קריאות מודל, hooks, שגיאות). +- **סשנים** — אירועים אלה מגולגלים לשורה אחת לכל ריצה, כל אחת **מוערכת באופן אוטומטי** וציונים. +- **הערכות** — ציוני איכות המיוצרים על ידי שירותי ההערכה שלך, כך שירידות בציון איכות מופיעות ללא בדיקה ידנית. +- **חיפושים ולוחות בקרה** — SQL ClickHouse שמור על הנתונים שלך, מעוצב לתוך לוחות בקרה משותפים בהיקף ארגוני. +- **התראות ותקריות** — כללי סף שמתריעים אותך (דוא"ל, Slack, webhook, בלוח בקרה) בתוספת זרימת עבודה של תקריות לטיפול בהן. +- **CLI ועוזר AI** — לקוח טרמינל (`agenteye`) ועוזר בלוח בקרה לשאלות בשפה טבעית. -אתם מריצים הכל בתשתית שלכם, כ-stack יחיד של Docker Compose (מדריך זה), התקנת Kubernetes בייצור, או pod יחיד שנמצא במקום. שאר המדריך מגדיר את stack ה-Compose מלא וקצה. +אתה מריץ את כל זה בתשתית שלך, כערימת Docker Compose אחת (מדריך זה), התקנת Kubernetes בייצור, או תרמיל אחד שיתופי. שאר המדריך הזה מגדיר את ערימת ה-Compose מקצה לקצה. --- -## שלב 1: הזדהות +## שלב 1: אימות -כל הנכסים של AgentEye מופצים מארגון `agenteye-enterprise` GitHub. כמפתח enterprise אתם יכולים ליצור את ה-GitHub PAT שלכם. עקבו אחר [enterprise-docs/github-token.md](/he/agenteye/github-token) לשלבים מדויקים והרשאות נדרשות. +כל עדויות AgentEye מופצות מהארגון ב-GitHub `agenteye-enterprise`. כמפתח ארגון, אתה יכול ליצור את ה-GitHub PAT שלך. עקוב אחר [enterprise-docs/github-token.md](/he/agenteye/github-token) לדרכים מדויקים והרשאות נדרשות. ```bash export AGENTEYE_TOKEN= @@ -41,11 +41,11 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin --- -## שלב 2: פרוס את השרת והלוח +## שלב 2: פרסם את השרת ולוח הבקרה -השרת מקבל events מקולטנים ועושה אותם ניתנים לשאילתה; הלוח הוא המקום שבו אתם חוקרים אותם. Events וניתוח שנצרכו חיים ב-ClickHouse (חנות הניתוח הנדרשת), בעוד Postgres מחזיק מצב תפעולי כגון ארגונים, משתמשים, מפתחות API, לוחות מחוונים ושאילתות שמורות. +השרת מקבל אירועים ממאספים וגורם להם להיות שאילתים; לוח הבקרה הוא המקום שבו אתה חוקר אותם. אירועים מודעים וניתוחים חיים ב-ClickHouse (חנות הניתוחים הנדרשת), בעוד Postgres מחזיק מצב תפעולי כמו ארגונים, משתמשים, מפתחות API, לוחות בקרה וחיפושים שמורים. -**הורידו את קובץ ה-compose המפורסם:** +**הורד את קובץ ה-compose שפורסם:** ```bash mkdir -p ./agenteye @@ -56,38 +56,32 @@ curl -fsSL \ cd agenteye ``` -**הגדרו את הסודות שלכם:** +**קבע את הסודות שלך:** -צרו קובץ `.env` כך שההפריסה לא תרוץ עם הרשאות ה-`admin` בברירת המחדל. לפחות הגדרו `ADMIN_KEY` ו-`POSTGRES_PASSWORD`: +צור קובץ `.env` כך שההפריסה לא תפעל על ה-`admin` שקבוע כברירת מחדל. לפחות קבע `ADMIN_KEY` ו-`POSTGRES_PASSWORD`: ```bash POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -כמו כן ייצאו `ADMIN_KEY` בשל שלכם הנוכחי כך ששלבים מאוחרים (למשל ה-`curl` בשלב 3) יוכלו להתייחס אליו ישירות: - -```bash -export ADMIN_KEY=your-admin-secret -``` - -**הפעילו את ה-stack:** +**הפעל את הערימה:** ```bash docker compose up -d ``` -זה מביא את ה-stack המלא, כולל ClickHouse analytics store הנדרש ומטמון Redis אופציונלי, בצד השרת והלוח. ClickHouse צריך להיות בריא כדי שהשרת יתחיל. +זה מעלה את כל הערימה, כולל חנות הניתוחים ClickHouse הנדרשת ומטמון Redis אופציונלי, לצד השרת ולוח הבקרה. ClickHouse חייב להיות בריא כדי שהשרת יתחיל. -השרת מקשיב עכשיו ב-`http://localhost:8080` והלוח ב-`http://localhost:3000`. +השרת כעת מקשיב ב-`http://localhost:8080` ולוח הבקרה ב-`http://localhost:3000`. -לפריסות בייצור (Postgres מותאם, TLS, reverse proxy), ראו [enterprise-docs/deployment.md](/he/agenteye/deployment). +לפריסות ייצור (Postgres מותאם, TLS, reverse proxy), ראה [enterprise-docs/deployment.md](/he/agenteye/deployment). --- -## שלב 3: צרו מפתח API עבור הקולטן +## שלב 3: צור מפתח API עבור המאסף -כל קולטן מאומת עם מפתח API בהיקף. השתמשו ב-`ADMIN_KEY` שהגדרתם בשלב 2 ליצירה של אחד: +כל מאסף מתחייב עם מפתח API בהיקף. השתמש ב-`ADMIN_KEY` שקבעת בשלב 2 ליצירת אחד: ```bash curl -s -X POST http://localhost:8080/keys \ @@ -96,15 +90,15 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -אתם מספקים את ערך `key` בעצמכם; השתמשו בו בתצורת הקולטן בשלב 4. ראו [enterprise-docs/api-keys.md](/he/agenteye/api-keys) לניהול מפתחות מלא. +אתה מספק את ערך `key` בעצמך; השתמש בו בתצורת המאסף בשלב 4. ראה [enterprise-docs/api-keys.md](/he/agenteye/api-keys) לניהול מפתח מלא. --- -## שלב 4: התקנת הקולטן +## שלב 4: התקן את המאסף -על כל מכונה המריצה את הסוכנים בתחום הבינה המלאכותית שלכם, התקינו את daemon הקולטן. +על כל מכונה שמריצה את סוכני ה-AI שלך, התקן את דמון המאסף. -**הורידו את הקובץ הבינארי (Linux x86_64):** +**הורד את הבינארי (Linux x86_64):** ```bash VERSION=0.0.1-beta.13 @@ -115,9 +109,9 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> זה מוריד את הבנייה של **Linux x86_64**. עבור macOS (Apple Silicon או Intel), Linux arm64, או Docker / systemd / launchd setup, ראו [collector-installation.md](/he/agenteye/collector-installation), המוצגת ההורדה עבור כל פלטפורמה — הפקודה לעיל מתקינה קובץ בינארי של Linux שלא יפעל במקום אחר. +> זה מוריד את הבנייה של **Linux x86_64**. עבור macOS (Apple Silicon או Intel), Linux arm64, או Docker / systemd / launchd setup, ראה [collector-installation.md](/he/agenteye/collector-installation), המפרטת את ההורדה לכל פלטפורמה — הפקודה לעיל מתקינה בינארי Linux שלא יעבוד במקומות אחרים. -**הגדירו:** +**קבע תצורה:** ```bash mkdir -p ~/.agenteye @@ -129,25 +123,25 @@ cat > ~/.agenteye/config.json </…`). +עם אירועים זורמים, דפי **ניתוח** הופכים פעילות גולמית לתשובות, כך שתוכל למדוד התנהגות סוכן, לשתף ממצאים עם הצוות, ולקבל עמוד כל פעם שמשהו רוגרס. דפי לוח בקרה הם בהיקף ארגוני, כך שכתובות ה-URL שאתה רואה בסרגל הכתובות מקדימות בקיצור הארגון שלך (`//…`). -- **Queries** (`//queries`): התחלו מספריית שאילתות שמורות וניתנות לשימוש חוזר על ה-events והערכות שלכם (presets מובנים בתוספת שלכם)… +- **חיפושים** (`//queries`): התחל מספרייה של חיפושים שמורים וישימה מחדש על פני האירועים וההערכות שלך (ערכות מובנות בתוספת שלך בעצמך)… -![ספריית השאילתות השמורות: רשת של שאילתות שניתן לשימוש חוזר, גם presets מובנים וגם שאילתות מותאמות אישית](/agenteye/images/queries.png) +![ספרית החיפושים השמורים: רשת של חיפושים ישימה מחדש, גם עם ערכות מובנות וגם מותאמות](/agenteye/images/queries.png) - …לאחר מכן פתחו אחת ב-SQL composer כדי לכוונן אותה והריצו אותה עם תוצאות חיות: + …לאחר מכן פתח אחד בקומפוזר SQL כדי לתקוף אותו והשב עם תוצאות חיות: -![מחברת שאילתות SQL המריצה שאילתה שמורה, עם סרגל צדדי של סכימה וגריד תוצאות חי](/agenteye/images/query-lab.png) +![קומפוזר שאילתה SQL המריץ שאילתה שמורה, עם סרגל צד ערכה וגריד תוצאות חי](/agenteye/images/query-lab.png) -- **Dashboards** (`//dashboards`): קבעו שאילתות כ-line, bar, area, או pie tiles לתוך לוחות מחוונים משותפים בהיקף כל הארגון. +- **לוחות בקרה** (`//dashboards`): סימן חיפושים כרעולים, בר, אזור או עוגה לתוך לוחות בקרה משותפים בהיקף ארגוני. -![לוח מחוונים שנבנה משאילתות שמורות: line של events-per-hour, bar של errors-by-type, area chart של latency ו-tokens-by-model](/agenteye/images/dashboard-fleet.png) +![לוח בקרה שנבנה מחיפושים שמורים: אירועים לשעה קו, שגיאות לפי סוג בר, תרשימי אזור זמן עיכוב וטוקנים לפי מודל](/agenteye/images/dashboard-fleet.png) -- **Alerts** (`//alerts`): קדמו כל סף לתוך כלל עמוד המודיע לפי דוא"ל, Slack, webhook, או בתוך הלוח. ראו [enterprise-docs/alerts.md](/he/agenteye/alerts). +- **התראות** (`//alerts`): קדם כל סף לתוך כלל עמוד המודיע בדוא"ל, Slack, webhook או בלוח בקרה. ראה [enterprise-docs/alerts.md](/he/agenteye/alerts). --- -## שלבים הבאים +## השלבים הבאים -- [Deployment](/he/agenteye/deployment): חסנו עבור בייצור -- [API Keys](/he/agenteye/api-keys): נהלו גישה -- [Troubleshooting](/he/agenteye/troubleshooting): אבחנו בעיות \ No newline at end of file +- [פריסה](/he/agenteye/deployment): התקשה לייצור +- [מפתחות API](/he/agenteye/api-keys): נהל גישה +- [פתרון בעיות](/he/agenteye/troubleshooting): אבחן בעיות \ No newline at end of file diff --git a/docs/he/agenteye/managed-deployment.mdx b/docs/he/agenteye/managed-deployment.mdx index 8601de37..42b4e23d 100644 --- a/docs/he/agenteye/managed-deployment.mdx +++ b/docs/he/agenteye/managed-deployment.mdx @@ -1,158 +1,159 @@ --- +--- title: "פריסה מנוהלת בקלסטר Kubernetes שלך" -description: "תיעוד פריסה מנוהלת של AgentEye בקלסטר Kubernetes שלך." +description: "תיעוד AgentEye Managed Deployment בקלסטר Kubernetes שלך." --- -AgentEye היא פלטפורמת תצפית והערכה בעלות עצמית עבור סוכנים AI ו-LLM. היא תופסת סשנים של סוכנים, קריאות כלים, בקשות מודלים וטעויות, הופכת אותם לניתוחים והערכות ניתנות לחיפוש, ומציגה את התוצאות בדוח מחוונים עם עוזר AI קריאה בלבד אופציונלי. +AgentEye היא פלטפורמת הצפה והערכה עצמאית לסוכנים AI ו-LLM. היא תופסת סשנים של סוכנים, קריאות כלים, בקשות מודל וטעויות, הופכת אותן לניתוח וערכות חיפוש, וחושפת את התוצאות בלוח בקרה עם עוזר AI קריאה-בלבד אופציונלי. -בדגם הפריסה המנוהלת, אתה מספק קלסטר Kubernetes ייעודי ו-Exosphere מפעילה את הפלטפורמה המלאה בתוכו, מפרסת, מוגדרת, מפעילה, מגבה וחידוש כל רכיב מטעמך. הצוות שלך מקבל את ערך הפלטפורמה (נראות סוכנים, ניתוח, הערכה והעוזר האופציונלי) ללא הפעלת מסדי נתונים, תעודות או שדרוגים. כל הנתונים נשארים בתוך חשבון הענן שלך. +במודל הפריסה המנוהלת, אתה מספק קלסטר Kubernetes ייעודי ו-Exosphere מריץ את הפלטפורמה המלאה בתוכו, מפרסת, מגדירה, מפעילה, גורמת גיבוי ומשדרגת כל רכיב בשמך. הצוות שלך מקבל את ערך הפלטפורמה (נראות לסוכנים, ניתוח, הערכה ועוזר אופציונלי) ללא הצורך לתפעל מסדי נתונים, תעודות או שדרוגים. כל הנתונים נשארים בחשבון הענן שלך. --- ## דרישות מקדימות -- **GitHub PAT** למשיכת תמונות קונטיינר והורדת קובצי אחסון (ראה [הגדרת אסימון GitHub](/he/agenteye/github-token)) +- **GitHub PAT** לשליפת תמונות מיכל והורדת עדויות (ראה [enterprise-docs/github-token.md](/he/agenteye/github-token)) - **קלסטר Kubernetes ייעודי** (ראה דרישות להלן) -- **דלי אחסון** לגיבויי מסדי נתונים -- **חיבור רשת**: יציאה 443 כנכנס לאיזן העומס של הקלסטר +- **דלי אחסון** לגיבויי מסד נתונים +- **חיבור רשת**: יציאה 443 נכנסת ל-load balancer של הקלסטר --- -## שלב 1: הצבת קלסטר Kubernetes ייעודי +## שלב 1: הנהל קלסטר Kubernetes ייעודי -צור קלסטר Kubernetes ייעודי עבור AgentEye. הוא לא צריך להיות משותף עם עומסי עבודה אחרים, כך שהפלטפורמה המלאה (שירותי יישום, מסדי נתונים, ניתוח ואחסון זמני) פועלת בבידוד ללא השפעה על התשתית הקיימת שלך. +צור קלסטר Kubernetes שהוא ייעודי ל-AgentEye. לא צריך לשתף אותו עם עומסי עבודה אחרים, כך שהפלטפורמה המלאה (שירותי יישום, מסדי נתונים, ניתוח ועיבוד מטמון) תפעל בבידוד ללא השפעה על התשתית הקיימת שלך. | דרישה | פרטים | |---|---| -| **הפצה** | כל Kubernetes עומד בתנאים: EKS, GKE, AKS, או בניהול עצמי | -| **גרסה** | 1.27 ואילך | -| **מאגר צמתים** | מינימום: **3 צמתים, 4 vCPU / 8 GB RAM לכל אחד** (מופעים סטנדרטיים למטרה כללית) | -| **אחסון** | StorageClass ברירת מחדל המספק כרכים בלוקיים (לדוגמה `gp3` ב-AWS, `pd-ssd` ב-GCP) | -| **איזן עומס** | הקלסטר חייב להיות מסוגל להספיק שירותי LoadBalancer בענן (ברירת מחדל ב-EKS, GKE, AKS) | +| **הפצה** | כל Kubernetes תואם: EKS, GKE, AKS או self-managed | +| **גרסה** | 1.27 ומעלה | +| **בריכת קודי** | מינימום: **3 קודים, 4 vCPU / 8 GB RAM לכל אחד** (instances general-purpose סטנדרטיים) | +| **אחסון** | StorageClass ברירת מחדל המנהל בלוקים (למשל `gp3` ב-AWS, `pd-ssd` ב-GCP) | +| **Load Balancer** | הקלסטר חייב להיות מסוגל לספק שירותי LoadBalancer בענן (ברירת מחדל ב-EKS, GKE, AKS) | -> Exosphere מותקנת וניהול הכל בתוך הקלסטר: בקרי כניסה, תעודות TLS, מסדי נתונים, אחסון זמני, ניטור וכל פריסות היישומים. +> Exosphere מתקינה וניהולה כל דבר אחר בתוך הקלסטר: בקרי ingress, תעודות TLS, מסדי נתונים, עיבוד מטמון, ניטור וכל פריסות יישום. --- -## שלב 2: הענקת גישה לצוות AgentEye +## שלב 2: הענק גישה לצוות AgentEye -Exosphere זקוקה לגישת cluster-admin (או שקיל RBAC רחב שווה) כדי לנהל מרחבי שמות, הגדרות משאבים מותאמות, בקרי כניסה וממספקי אחסון. +Exosphere צריכה גישת cluster-admin (או RBAC רחב שקול) כדי לנהל namespaces, הגדרות משאבים מותאמות אישית, בקרי ingress וספקי אחסון. | דרישה | פרטים | |---|---| -| **שיטת גישה** | תפקיד IAM (מומלץ עבור EKS/GKE), kubeconfig, או גישה מבוססת SSO | -| **VPN / bastion** | אם שרת ה-Kubernetes API פרטי, ספק עדויות VPN או גישה bastion לצוות הפעולות של Exosphere | +| **שיטת גישה** | IAM role (מועדף ל-EKS/GKE), kubeconfig או גישה מבוססת SSO | +| **VPN / bastion** | אם שרת ה-Kubernetes API פרטי, הנח אישורי VPN או גישת bastion לצוות תפעולי Exosphere | --- -## שלב 3: הגדרת חיבור רשת +## שלב 3: הגדר חיבור רשת -צוות הרשת שלך צריך לאפשר תעבורה כנכנסת על **יציאה 443** לאיזני העומס של הקלסטר. הפריסה מפעילה שני איזני עומס נפרדים: אחד להספקת אירוע (מוגן ב-mTLS) ואחד לדוח המחוונים: +צוות הרשת שלך צריך לאפשר תנועה נכנסת ביציאה **443** ל-load balancers של הקלסטר. הפריסה מריצה שני load balancers נפרדים: אחד לספיגת אירועים (מוגן ב-mTLS) ואחד ללוח הבקרה: -| תעבורה | מקור | יעד | ביטחון | +| תנועה | מקור | יעד | אבטחה | |---|---|---|---| -| **הספקת אירוע** | תרגולי אספן בקלסטרים שלך | Ingest LoadBalancer, יציאה 443 | mTLS (תעודת לקוח) + מפתח API | -| **דוח מחוונים** | דפדפני מפתחים | Dashboard LoadBalancer, יציאה 443 | HTTPS בדומיין שלך, כניסה חד-פעמית OTP ללא סיסמה דרך אימייל | +| **ספיגת אירועים** | קודי Collector בקלסטרים שלך | Ingest LoadBalancer, יציאה 443 | mTLS (תעודת לקוח) + מפתח API | +| **לוח בקרה** | דפדפני מפתחים | Dashboard LoadBalancer, יציאה 443 | HTTPS בתחום שלך, כניסה OTP דוא"ל ללא סיסמה | -נקודת הספקה מוגנת ב-TLS הדדי; אספנים חייבים להציג תעודת לקוח תקפה **וגם** מפתח API תקף בכל בקשה. דוח המחוונים פועל על איזן עומס והשם מחשב משלו, עם כניסה מוגבלת לכתובות/דומיינים של אימייל בנושא הרשימה הלבנה שלך. +נקודת הספיגה מוגנת בידי TLS הדדי; collectors חייבים להצגת תעודת לקוח תקפה **וגם** מפתח API תקף בכל בקשה. לוח הבקרה פועל על load balancer והשם מארח משלו, כשהכניסה מוגבלת לכתובות דוא"ל/תחומים שהרשחת. -**רשומות DNS (חד-פעמי):** אתה יוצר שתי רשומות CNAME תחת דומיין שאתה שולט בו — אחת לנקודת הספקה ואחת לדוח המחוונים (לדוגמה `agenteye.your-company.example`) — מצביעות על שמות מחשב של איזן העומס ש-Exosphere מספקת. Exosphere לאחר מכן מספקת תעודות TLS נתונות לציבור עבור שני שמות המחשב באופן אוטומטי, כולל חידושים. +**רשומות DNS (פעם אחת):** אתה יוצר שתי רשומות CNAME תחת תחום שאתה שולט בו — אחת לנקודת הספיגה ואחת ללוח הבקרה (למשל `agenteye.your-company.example`) — מעבר לשמות ה-load balancer hostname שש Exosphere מספקת. Exosphere אז מנהלת תעודות TLS שמוקדשות בציבור עבור שתי hostnames באופן אוטומטי, כולל חידושים. -> **הערת יציאה 80:** אישור תעודה ופיקוח אוטומטי ללא מילה מאמתים דרך HTTP ביציאה 80 של כל איזן עומס. אם עמדת הביטחון שלך דורשת הגבלת עומס דוח המחוונים לטווחי IP תאגידיים, אמור ל-Exosphere קודם — אנחנו עוברים לאימות תעודה לשיטה מבוססת DNS (רשומת DNS נוספת אחת בצד שלך) כך שחידושים ממשיכים לעבוד מאחורי ההגבלה. +> **הערה יציאה 80:** אישור תעודה אוטומטי וחידוש אימות על HTTP ביציאה 80 של כל load balancer. אם העמדה הביטחוני שלך דורשת הגבלת dashboard load balancer לטווחי IP ארגוניים, אמור ל-Exosphere בתחילה — אנחנו מעבירים אימות תעודה לשיטה מבוססת DNS (רשומת DNS אחת נוספת בצדך) כדי שהחידושים ימשיכו לעבוד מאחורי ההגבלה. -> **יציאה:** צמתי קלסטר זקוקים לגישה לאינטרנט כדי למשוך תמונות קונטיינר מ-`ghcr.io`. אם הרשת שלך מגבילה תעבורה יציאה, רשימה לבנה `ghcr.io` או תמונות מראה לרישום הפנימי שלך. +> **יוצא:** קודי הקלסטר צריכים גישת אינטרנט לשליפת תמונות מיכל מ-`ghcr.io`. אם הרשת שלך מגבילה תנועה יוצאת, הרשה `ghcr.io` או שדר תמונות לרישום הפנימי שלך. --- -## שלב 4: ספק דלי אחסון גיבוי +## שלב 4: הנח דלי אחסון לגיבוי -גיבויי מסדי נתונים מאוחסנים בדלי אחסון בענן שאתה בעלך. +גיבויי מסד נתונים מאוחסנים בדלי אחסון בענן שאתה בעלים בו. | דרישה | פרטים | |---|---| -| **שירות** | S3 (AWS), GCS (GCP), או Azure Blob Storage | -| **גישה** | הענק גישת כתיבה לצמתי הקלסטר דרך תפקיד IAM לחשבונות שירות (IRSA ב-EKS, Workload Identity ב-GKE) או ספק עדויות | -| **תעודה** | אתה שולט בנהלי מחזור חיים של הדלי (תקופת השמירה, כללי ארכיון). Exosphere כותבת גיבויים; אתה מחליט כמה זמן לשמור עליהם | +| **שירות** | S3 (AWS), GCS (GCP) או Azure Blob Storage | +| **גישה** | הענק גישת כתיבה לקודי הקלסטר דרך IAM role לחשבוני שירות (IRSA ב-EKS, Workload Identity ב-GKE) או הנח אישורים | +| **עיכול** | אתה שולט בעיכול מחזור חיים של הדלי שלך (תקופת עיכול, כללי ארכיון). Exosphere כותבת גיבויים; אתה מחליט כמה זמן להשאיר אותם | -גיבוי יומי אחד ממלא את PostgreSQL (מצב יחסי) ו-ClickHouse (אירוע והערכות) לתוך ארכיון דחוס אחד ומעלה אותו לדלי שלך. גיבויים גם רצים לפני כל שדרוג. +גיבוי יומי יחיד דוקד ג כel PostgreSQL (מצב יחסוני) וגם ClickHouse (אירועים והערכות) לארכיון דחוס יחיד ועלה אותו לדלי שלך. גיבויים גם פועלים לפני כל שדרוג. --- -## שלב 5: ייעד אנשי קשר +## שלב 5: ציין אדם קשר -ספק אדם אחד או ערוץ Slack/Teams בצד שלך לבעיות ברמת קלסטר: בריאות צמתים, מגבלות חשבון בענן, שינויים ברשת. פעולות יום-יום אינן כרוכות בקשר זה. +הנח אדם אחד או ערוץ Slack/Teams בצדך לבעיות ברמת הקלסטר: בריאות קודים, מגבלות חשבון בענן, שינויים ברשת. פעולות יומיות לא כוללות קשר זה. --- -## מה אנחנו פורסים +## מה אנחנו מפרסמים -ברגע ש-Exosphere יש גישה קלסטר, הרכיבים הבאים מוצבים וניהול עבורך: +לאחר שברא Exosphere יש גישה לקלסטר, הרכיבים הבאים מופרסים ומנוהלים בשבילך: | רכיב | תפקיד | |---|---| -| **AgentEye Server** | HTTP API המקבלת אירוע מאספנים, מפעילה ניתוח וניתנה נתונים לדוח מחוונים | -| **דוח מחוונים** | ממשק אינטרנט להצגת סשנים של סוכנים, קריאות כלים, בקשות מודלים וטעויות; מארח את העוזר AI קריאה בלבד האופציונלי | -| **ClickHouse** | אחסון קנוני נדרש לאירוע שהובא, ניתוח והערכות | -| **PostgreSQL** | חנות יחסית לארגונים, מפתחות API, משתמשים, דוחות מחוונים וסקלים שמורים | -| **Redis** | קיים אחסון זמני משותף אופציונלי וגבול-קצב קצה; הפלטפורמה מתדרדרת בחן אם היא אינה זמינה | -| **עוזר AI (אופציונלי)** | קונטיינר עוזר קריאה בלבד פנימי; נשאר מבוטל עד לתצורת נקודת קצה LLM | -| **בקרי כניסה** | שני איזני עומס (אחד ל-mTLS-protected ingest, אחד לדוח המחוונים) מסיימים TLS עם תעודות נתונות לציבור, חידוש אוטומטי, ובאכיפה mTLS בנקודת הספקה | -| **cert-manager** | מפעילה הספקת תעודה TLS ויצור אסימון לקוח-mTLS בצורה אוטומטית | -| **ניטור תעודה** | עבודה מתוזמנת בודקת פקיעת תעודה וישלח עריכות (לדוגמה ל-Slack) כאשר תעודות מתקרבות לחידוש | - -ההצעה המנוהלת גם מפעילה את צינור הערכה של הפלטפורמה, הדירוג פעילות סוכנים כנגד קריטריונים הערכה שלך. ראה [עוזר](/he/agenteye/assistant) ו-[חבילת הערכה](/he/agenteye/evaluation-suite) לאילו יכולות אלו מספקות. +| **AgentEye Server** | HTTP API שמקבל אירועים מ-collectors, מריץ ניתוח וסירת נתונים ללוח הבקרה | +| **לוח בקרה** | ממשק אינטרנט להצגת סשנים של סוכנים, קריאות כלים, בקשות מודל וטעויות; משדך את העוזר AI קריאה-בלבד אופציונלי | +| **ClickHouse** | חנות קנונית נדרשת לאירועים מובודה, ניתוח והערכות | +| **PostgreSQL** | חנות יחסונית לארגונים, מפתחות API, משתמשים, לוחות בקרה ושאילתות שמורות | +| **Redis** | מטמון משותף אופציונלי וגב שיעור הגבלה; הפלטפורמה דורדרת בנועם אם היא לא זמינה | +| **עוזר AI (אופציונלי)** | מיכל עוזר פנימי קריאה-בלבד; נשאר מנוטרל עד שנקודת קצה LLM מוגדרת | +| **בקרי ingress** | שני load balancers (אחד ל-ingest מוגן ב-mTLS, אחד ללוח בקרה) מסיימים TLS עם תעודות בציבור מהימן, חידוש אוטומטי וכוחית mTLS בנקודת הספיגה | +| **cert-manager** | מעשה מידי של הנהלת תעודות TLS ופרסום תעודות לקוח mTLS | +| **ניטור תעודות** | עבודה מתוזמנת בודקת תפוקת תעודה וקורטיוגרפי התראות (למשל ל-Slack) כתעודות מתקרבות לחידוש | + +ההנהלה שנות גם מפעילה את עקק קו הערכה של הפלטפורמה, אשר משקלל פעילות סוכן מול קריטריונים הערכה שלך. ראה [enterprise-docs/assistant.md](/he/agenteye/assistant) ו-[enterprise-docs/evaluation-suite.md](/he/agenteye/evaluation-suite) לאלו יכולות יעניקו. --- ## מה אנחנו מספקים לך -לאחר שהפריסה הושלמה, אתה מקבל: +לאחר השלמת הפריסה, אתה מקבל: | פריט | פרטים | |---|---| -| **כתובת דוח מחוונים** | שם מחשב תחת הדומיין שלך (לדוגמה `https://agenteye.your-company.example`), מוגש עם תעודה TLS נתונה לציבור, חידוש אוטומטי. אתה יוצר CNAME אחד לשם מחשב של איזן העומס ש-Exosphere מספקת; כניסה היא OTP ללא סיסמה דרך אימייל | -| **נקודת קצה אספן** | נתיב `/events` של שם מחשב הספקה (לדוגמה `https://ingest.your-company.example/events`), mTLS-protected | -| **חבילת תעודת לקוח** | לכל קלסטר: תעודת לקוח, מפתח פרטי ותעודת CA מסופקות כמניפסט סודי Kubernetes. החל אותה פעם אחת לכל קלסטר | -| **GitHub PAT** | להורדת בינריי אספן וחבילות Python SDK | -| **מפתחות API של אספן** | מפתחות בהיקף עם הרשאה `events:add`, אחד לכל פריסת אספן | -| **מדריכי התקנה** | מסמכים שלב-אחר-שלב עבור האספן ו-Python SDK | +| **URL לוח בקרה** | שם מארח תחת תחום שלך (למשל `https://agenteye.your-company.example`), סירת עם תעודת TLS בציבור מהימן, חידוש אוטומטי. אתה יוצר CNAME אחד לשם hostname load balancer שאנחנו מספקים; כניסה היא OTP דוא"ל ללא סיסמה | +| **נקודת קצה Collector** | נקודת הספיגה hostname's `/events` path (למשל `https://ingest.your-company.example/events`), mTLS-protected | +| **חבילת תעודת לקוח** | לכל קלסטר: תעודת לקוח, מפתח פרטי וכ"א תעודה כ-Kubernetes Secret manifest. החל אותו פעם אחת לכל קלסטר | +| **GitHub PAT** | להורדת בינריות collector חבילות Python SDK | +| **מפתחות API Collector** | מפתחות scoped עם `events:add` הרשאה, אחד לכל התפרסות collector | +| **מדריכי התקנה** | סיור דו-שלבי לקולקטור ול-Python SDK | --- -## מה אתה עושה לאחר הגדרה +## מה אתה עושה אחרי הגדרה -העבודה היחידה שלך בעבר היא בקלסטרים של סוכנים משלך, לא זה של AgentEye: +העבודה היומית היחידה שלך היא על מכונות סוכן משלך, לא על קלסטר AgentEye: -1. **התקן את האספן** בכל קלסטר Kubernetes המפעיל סוכנים AI: העלה את תעודת הלקוח והגדר את כתובת נקודת הקצה ומפתח API. ראה [התקנת אספן](/he/agenteye/collector-installation). -2. **שלב את Python SDK** לקוד הסוכן שלך. ראה [Python SDK](/he/agenteye/python-sdk). -3. **פתח את דוח המחוונים** בדפדפן שלך כדי להציג פעילות סוכנים. +1. **התקן את ה-collector** בכל קלסטר Kubernetes המריץ סוכנים AI: טען את תעודת הלקוח וקבע את URL נקודת הקצה ומפתח API. ראה [enterprise-docs/collector-installation.md](/he/agenteye/collector-installation). +2. **שלב את ה-Python SDK** לתוך קוד הסוכן שלך. ראה [enterprise-docs/python-sdk.md](/he/agenteye/python-sdk). +3. **פתח את לוח הבקרה** בדפדפן שלך כדי להצגת פעילות סוכן. -לא פעולות קלסטר, ניהול מסדי נתונים, חידושי תעודות, שדרוגים. +אין פעולות קלסטר, אין ניהול מסד נתונים, אין חידושי תעודות, אין שדרוגים. --- -## ביטחון +## אבטחה -- **הנתונים נשארים בחשבון הענן שלך.** הקלסטר, האחסון, ומסדי הנתונים כולם פועלים בסביבה שלך. לא ממש נתונים עוזבים את הגבול שלך. -- **אתה שולט בגישה.** הקלסטר נמצא בחשבון שלך. אתה יכול לבקר, לעקוב, או לשלול את גישת Exosphere בכל זמן. כל הפעולות עוברות דרך רישום ביקורת של הענן שלך (CloudTrail, GCP Audit Logs, וכו'). -- **mTLS בהספקת אירוע.** כל בקשת אספן דורשת גם תעודת לקוח תקפה וגם מפתח API. מפתח דליפה חסר תועלת ללא התעודה; תעודה גנובה חסרת תועלת ללא מפתח תקף. -- **שליטה בגישה לדוח מחוונים.** דוח המחוונים פועל על איזן עומס משלו, נפרד מהספקת אירוע, וכניסה היא OTP ללא סיסמה דרך אימייל מוגבלת לכתובות/דומיינים שאתה רשימות לבנות. הגבלת טווח מקור IP על איזן העומס זמינה בבקשה; מכיוון שחידוש תעודה אוטומטי חייב להגיע לאיזן העומס, Exosphere משלבת את ההגבלה עם אימות תעודה מבוסס DNS כך שחידושים ממשיכים לעבוד. -- **תעודות לכל קלסטר.** כל אחד מהקלסטרים שלך מקבל תעודת לקוח משלו. אם קלסטר אחד נפגע, התעודה הזו מבוטלת באופן עצמאי ללא השפעה על אחרים. +- **נתונים נשארים בחשבון הענן שלך.** הקלסטר, האחסון ומסדי הנתונים כולם פועלים בסביבה שלך. אין נתונים שעוזבים את הגבול שלך. +- **אתה שולט בגישה.** הקלסטר בחשבון שלך. אתה יכול לבדוק, לנטר או להשהות את הגישה של Exosphere בכל עת. כל הפעולות עוברות דרך יומן ביקורת בענן שלך (CloudTrail, GCP Audit Logs, וכו'). +- **mTLS בספיגת אירועים.** כל בקשת collector דורשת תעודת לקוח תקפה וגם מפתח API. מפתח דורי הוא חסר תועלת ללא התעודה; תעודה גנובה היא חסרת תועלת ללא מפתח תקף. +- **בקרת גישה ללוח בקרה.** לוח הבקרה פועל על load balancer נפרד, מופרד מספיגת אירועים, וכניסה היא OTP דוא"ל ללא סיסמה המוגבלת לכתובות/תחומים דוא"ל שהרשחת. ספירת IP source-range allowlist ב-load balancer זמינה בבקשה; מאחר שחידוש תעודה אוטומטי חייב להגיע ל-load balancer, Exosphere משלבת את ההגבלה עם אימות תעודה מבוסס DNS כדי שהחידושים ימשיכו לעבוד. +- **תעודות לכל קלסטר.** כל אחד מהקלסטרים שלך מקבל תעודת לקוח משלו. אם קלסטר אחד בוויתור, תעודה זו מתבטלת בנפרד ללא השפעה על אחרים. --- -## לוח זמנים פריסה +## ציר וואפו זמן הפריסה -| שלב | משך | שלך מעורבות | +| שלב | משך | השתתפות שלך | |---|---|---| -| **הצבת קלסטר** | 1-2 ימים | הצב את הקלסטר והענק לExosphere גישה | -| **הגדרת פלטפורמה** | יום 1 | כלום; Exosphere מותקנת כל רכיבי תשתית | -| **פריסת יישום** | יום 1 | כלום; Exosphere מוצבת השרת, דוח מחוונים, ויוצרת מפתחות API | -| **הרחקת אספן** | 1-3 ימים | התקן אספנים בקלסטרים שלך (עם הדרכה מ-Exosphere) | -| **שריפה בייצור** | שבוע 1 | כלום; Exosphere משגחת וכיוונון | +| **הנהלת קלסטר** | 1-2 ימים | התקנת הקלסטר והענקת גישה ל-Exosphere | +| **הגדרת פלטפורמה** | יום 1 | אין; Exosphere מתקינה את כל רכיבי התשתית | +| **פריסת יישום** | יום 1 | אין; Exosphere מפרסמת את השרת, לוח הבקרה ויוצרת מפתחות API | +| **הצגת Collector** | 1-3 ימים | התקנת collectors בקלסטרים שלך (עם הנחיה מ-Exosphere) | +| **הבעיר בייצור** | שבוע 1 | אין; Exosphere מנטרת וממיינת | -סך הכל טיפוסי: **~2 שבועות** מהתחלה לערוך-לייצור. +סה"כ אופייני: **~2 שבועות** מה-kickoff למוכנות לייצור. --- @@ -162,10 +163,10 @@ Exosphere זקוקה לגישת cluster-admin (או שקיל RBAC רחב שוו --- -## הצעדים הבאים +## שלבים הבאים -- [תחילת עבודה](/he/agenteye/getting-started): הליכה שלמה מקצה לקצה -- [התקנת אספן](/he/agenteye/collector-installation): התקן והגדר את האספן -- [Python SDK](/he/agenteye/python-sdk): כלי את קוד הסוכן שלך -- [מפתחות API](/he/agenteye/api-keys): נהל גישה והרשאות -- [פתרון בעיות](/he/agenteye/troubleshooting): בעיות נפוצות ותיקונים \ No newline at end of file +- [Getting Started](/he/agenteye/getting-started): הנחיה מקצה לקצה +- [Collector Installation](/he/agenteye/collector-installation): התקנה והגדרת ה-collector +- [Python SDK](/he/agenteye/python-sdk): מכשיר קוד הסוכן שלך +- [API Keys](/he/agenteye/api-keys): ניהול גישה והרשאות +- [Troubleshooting](/he/agenteye/troubleshooting): בעיות נפוצות ותיקונים \ No newline at end of file diff --git a/docs/hi/agenteye/audits.mdx b/docs/hi/agenteye/audits.mdx index 2e8a1f08..96591536 100644 --- a/docs/hi/agenteye/audits.mdx +++ b/docs/hi/agenteye/audits.mdx @@ -1,107 +1,107 @@ --- -title: "ऑडिट्स — एजेंटिक सुधार का पता लगाना" -description: "AgentEye ऑडिट्स — एजेंटिक सुधार का पता लगाना दस्तावेज़।" +--- +title: "ऑडिट — एजेंटिक सुधार पहचान" +description: "AgentEye ऑडिट — एजेंटिक सुधार पहचान दस्तावेज़।" --- -ऑडिट्स आवर्ती कार्य हैं जो आपके एजेंट लॉग्स को **सेशन्स के अंतर्गत** खनन करते हैं सुधार के लिए योग्य चीजों को खोजने के लिए। जहाँ एक अलर्ट एक मीट्रिक को देखता है जिसे आप पहले से जानते हैं लगभग-वास्तविक समय में, एक ऑडिट *जांच करता है*: आपके द्वारा निर्धारित एक शेड्यूल पर, यह विंडो पर एक नियतात्मक नीति पास चलाता है, फिर एक **AI विश्वसनीयता एजेंट** को आपके सेशन्स पर ढीला करता है — एजेंट डेटा को स्वयं क्वेरी करता है, संदिग्ध ट्रांसक्रिप्ट्स को पढ़ता है, और (जब यह मदद करता है) छोटी विश्लेषण स्क्रिप्ट्स चलाता है, फिर **सुधार सिफारिशें** लिखता है प्रत्येक के पीछे सबूत के साथ। +ऑडिट आवर्ती कार्य हैं जो **सेशन के दौरान** आपके एजेंट लॉग को खनन करते हैं ताकि सुधार के लिए महत्वपूर्ण चीजें मिलें। जहाँ एक अलर्ट एक ऐसी मेट्रिक देखता है जिसे आप पहले से जानते हैं रीयल-टाइम के करीब, एक ऑडिट *जांच करता है*: आपके द्वारा निर्धारित शेड्यूल पर, यह विंडो पर एक नियतात्मक नीति पास चलाता है, फिर एक **AI विश्वसनीयता एजेंट** को आपके सेशन पर ढीला छोड़ता है — एजेंट स्वयं डेटा को क्वेरी करता है, संदिग्ध ट्रांसक्रिप्ट पढ़ता है, और (जब यह मदद करता है) छोटी विश्लेषण स्क्रिप्ट चलाता है, फिर **सुधार सिफारिशें** लिखता है जिसमें प्रत्येक के पीछे का सबूत होता है। -ऑडिट्स का उपयोग "मुझे अपने एजेंट्स में क्या ठीक करना या सुधारना चाहिए?" का उत्तर देने के लिए करें — और अलर्ट्स का उपयोग तुरंत पेज किए जाने के लिए जब एक विशिष्ट थ्रेसहोल्ड पार हो। प्रत्येक सुधार सटीक सेशन्स और क्वेरीज़ से जुड़ता है जो इसके पीछे हैं, और एक क्लिक एक पूर्ण-भरी हुई अलर्ट बनाता है पुनरावृत्ति को पकड़ने के लिए। +अपने एजेंट में "मुझे क्या ठीक करना या सुधारना चाहिए?" का उत्तर देने के लिए ऑडिट का उपयोग करें — और किसी विशिष्ट थ्रेशहोल्ड के पार जाते ही पेज पाने के लिए अलर्ट का उपयोग करें। हर सुधार उसके पीछे के सटीक सेशन और क्वेरी से जुड़ा होता है, और एक क्लिक पुनरावृत्तियों को पकड़ने के लिए एक पूर्व-भरे अलर्ट बनाता है। -डैशबोर्ड सतह है **`//audits`** (साइडबार → *analyze* → *audits*), `audits:read` / `audits:write` अनुमतियों द्वारा गेटेड। +डैशबोर्ड सतह **`//audits`** है (साइडबार → *विश्लेषण* → *audits*), `audits:read` / `audits:write` अनुमतियों द्वारा गेटेड। --- ## एक रन कैसे काम करता है -प्रत्येक रन के दो स्तर हैं — एक नियतात्मक आधार और एक एजेंटिक जांच। +प्रत्येक रन के दो परत होते हैं — एक नियतात्मक आधार और एक एजेंटिक जांच। ### 1. नीति पास (नियतात्मक) -किसी भी मॉडल के चलने से पहले, ऑडिट विंडो पर **SQL नीति जांचों** का एक छोटा कैटलॉग निष्पादित करता है: सीमांकित समुच्चय क्वेरीज़ जो ज्ञात-बुरे पैटर्न को फ्लैग करती हैं और रिपोर्ट करती हैं *कितनी* घटनाएं / *कौन से* सेशन्स मेल खाते हैं — कभी मेल खाए गए पाठ को नहीं। कैटलॉग में शामिल हैं: +किसी भी मॉडल के चलने से पहले, ऑडिट विंडो के पार **SQL नीति जांच** के एक छोटे कैटलॉग को निष्पादित करता है: बंधी हुई कुल क्वेरी जो ज्ञात-खराब पैटर्न को फ्लैग करती हैं और *कितने* इवेंट / *कौन से* सेशन मेल खाते हैं - कभी मेल खाए हुए टेक्स्ट को नहीं। कैटलॉग में शामिल हैं: -- इवेंट पेलोड्स में **सीक्रेट / क्रेडेंशियल लीकेज** — AWS एक्सेस कीज़, `sk-…` API कीज़, PEM निजी कीज़, JWT / बेयरर टोकन्स, और `KEY=…` क्रेडेंशियल असाइनमेंट्स। -- **प्रॉम्प्ट-इंजेक्शन मार्कर्स** — "पिछली निर्देशों को अनदेखा करें", "अपना सिस्टम प्रॉम्प्ट प्रकट करें", और समान। -- **PII** — SSN-आकार की संख्याएं (हेयुरिस्टिक)। -- **टूल-अनुमति निषेधाएं** और **भागीदार टूल-कॉल लूप्स**। +- इवेंट पेलोड में **रहस्य / क्रेडेंशियल लीकेज** — AWS एक्सेस कीज, `sk-…` API कीज, PEM निजी कीज, JWT / वाहक टोकन, और `KEY=…` क्रेडेंशियल असाइनमेंट। +- **प्रॉम्प्ट-इंजेक्शन मार्कर** — "पिछली निर्देशों को नज़रअंदाज़ करें", "अपना सिस्टम प्रॉम्प्ट प्रकट करें", और समान। +- **PII** — SSN-आकार की संख्याएं (अनुमानी)। +- **टूल-अनुमति निषेध** और **भागती हुई टूल-कॉल लूप**। -नीति हिट्स निष्कर्षों के रूप में स्थायी होते हैं (तरह `policy`) जो **हमेशा सतह पर आते हैं** (वे प्रति-रन कैप द्वारा कभी ट्रिम नहीं किए जाते), और वे AI एजेंट को शुरुआती संकेत के रूप में सौंपे जाते हैं। क्योंकि इस स्तर को कोई मॉडल की आवश्यकता नहीं है, एक ऑडिट अपने सबसे महत्वपूर्ण सुरक्षा सिग्नल्स का उत्पादन करता है भले ही AI एजेंट अनुपलब्ध हो। +नीति हिट्स को निष्कर्ष (प्रकार `policy`) के रूप में संरक्षित किया जाता है जो **हमेशा सतह पर आते हैं** (वे कभी प्रति-रन कैप द्वारा ट्रिम नहीं होते हैं), और वे AI एजेंट को शुरुआती सुराग के रूप में सौंपे जाते हैं। क्योंकि इस परत को कोई मॉडल की आवश्यकता नहीं है, एक ऑडिट अपने सबसे महत्वपूर्ण सुरक्षा संकेत तब भी उत्पन्न करता है जब AI एजेंट अनुपलब्ध हो। ### 2. एजेंटिक जांच (AI) -ऑडिट फिर एक **स्वायत्त विश्वसनीयता एजेंट** चलाता है (वही Claude Code सेवा जो डैशबोर्ड सहायक को शक्ति देती है, एक ऑडिट-विशिष्ट प्रॉम्प्ट के साथ)। ऑडिट के **स्कोप** (चयनित एजेंट्स × वातावरण) और **समय विंडो** को देखते हुए, एजेंट: +ऑडिट फिर एक **स्वायत्त विश्वसनीयता एजेंट** चलाता है (वही Claude एजेंट SDK सेवा जो डैशबोर्ड सहायक को शक्ति देती है, एक ऑडिट-विशिष्ट प्रॉम्प्ट के साथ)। ऑडिट के **स्कोप** (चयनित एजेंट × वातावरण) और **समय विंडो** को देखते हुए, एजेंट: -- आपकी विश्लेषण तालिकाओं के विरुद्ध केवल-पढ़ने योग्य SQL क्वेरीज़ चलाता है, -- प्रतिनिधि सेशन ट्रांसक्रिप्ट्स की एक मुट्ठी को पढ़ता है, -- वैकल्पिक रूप से छोटी **Python स्क्रिप्ट्स को एक लॉक-डाउन इन-पॉड सैंडबॉक्स में** लिखता और चलाता है (कोई नेटवर्क नहीं, कोई फाइलसिस्टम एक्सेस नहीं, सीक्रेट्स स्क्रब किए गए) विश्लेषण के लिए जो SQL व्यक्त नहीं कर सकता — क्लस्टरिंग त्रुटियां, वितरण की गणना, पेलोड्स को स्वीप करना जो यह पहले से प्राप्त कर चुका है, -- और प्रत्येक अच्छी तरह से सबूत दिए गए **सुधार** को रिकॉर्ड करता है जो यह खोजता है। +- आपकी विश्लेषिकी तालिकाओं के विरुद्ध केवल-पढ़ने योग्य SQL क्वेरी चलाता है, +- प्रतिनिधि सेशन ट्रांसक्रिप्ट की एक मुट्ठी पढ़ता है, +- वैकल्पिक रूप से **SQL व्यक्त नहीं कर सकता** उसके लिए विश्लेषण के लिए एक लॉक-डाउन में-पॉड सैंडबॉक्स में छोटी **Python स्क्रिप्ट** लिखता और चलाता है (कोई नेटवर्क नहीं, कोई फाइलसिस्टम एक्सेस नहीं, रहस्य स्क्रबड) — त्रुटियों को क्लस्टर करना, वितरण की गणना करना, पेलोड को स्वीप करना जिसे यह पहले से प्राप्त कर चुका है, +- और प्रत्येक अच्छी तरह से समर्थित **सुधार** को रिकॉर्ड करता है जो यह पाता है। -यह कई जांच लाइनों के माध्यम से काम करता है — त्रुटि क्लस्टरिंग, एक आधारभूत बनाम ड्रिफ्ट, ट्रांसक्रिप्ट्स में लक्ष्य विफलता, टूल दुरुपयोग, गुणवत्ता/लागत ट्रेड-ऑफ, और कवरेज अंतराल — ऑडिट की **संवेदनशीलता** पर (कम / माध्यम / उच्च)। हर सुधार **सबूत का हवाला देना चाहिए**: सेशन आईडीज़ जो एजेंट वास्तव में निरीक्षण करता है और/या SQL जो यह चलाता है। सर्वर यह सत्यापित करता है कि उद्धृत सेशन्स मौजूद हैं और **किसी भी सुधार को कोई शेष सबूत के साथ छोड़ देता है**, इसलिए एजेंट जांच करता है लेकिन कभी आविष्कार नहीं करता। +यह कई जांच की लाइनों के माध्यम से काम करता है — त्रुटि क्लस्टरिंग, बेसलाइन के विरुद्ध ड्रिफ्ट, ट्रांसक्रिप्ट में लक्ष्य विफलता, टूल दुरुपयोग, गुणवत्ता/लागत व्यापार-ऑफ, और कवरेज अंतराल — ऑडिट की **संवेदनशीलता** (कम / मध्यम / उच्च) पर। हर सुधार **को सबूत का हवाला देना चाहिए**: सेशन आईडी जिसे एजेंट ने वास्तव में निरीक्षण किया और/या SQL जिसे यह चलाया। सर्वर यह सत्यापित करता है कि उद्धृत सेशन मौजूद हैं और **बिना किसी जीवित साक्ष्य के किसी भी सुधार को त्याग देता है**, इसलिए एजेंट जांच करता है लेकन कभी आविष्कार नहीं करता। -प्रत्येक सुधार ले जाता है: +प्रत्येक सुधार वहन करता है: -- एक **सिफारिश** (ठोस परिवर्तन करने के लिए — एक प्रॉम्प्ट ट्वीक, एक टूल-स्कीमा फिक्स, एक रिट्राई नीति, एक गार्ड्रेल, अधिक eval कवरेज), -- एक **अपेक्षित प्रभाव** और एक **प्रयास** अनुमान (कम / माध्यम / उच्च), -- एक **परिमाण** — `big` (एक ऑपरेटर को पेज किया जाना चाहिए), `medium` (रन रिपोर्ट में संबंधित), या `small` (डैशबोर्ड संदर्भ), -- एक स्थिर **फिंगरप्रिंट** (समस्या की श्रेणी + स्कोप से, *इस रन के सेशन्स से नहीं*) ताकि वही समस्या रन-दर-रन ट्रैक की जाए यहां तक कि जब सबूत बदलता है, -- और, जहाँ एक सरल नियतात्मक वॉचर पुनरावृत्ति को पकड़ सकता है, एक **सुझाई गई अलर्ट** जो आप एक क्लिक में बना सकते हैं। +- एक **सिफारिश** (ठोस परिवर्तन करना — एक प्रॉम्प्ट ट्वीक, एक टूल-स्कीमा फिक्स, एक पुनः प्रयास नीति, एक गार्डरेल, अधिक eval कवरेज), +- एक **अपेक्षित प्रभाव** और एक **प्रयास** अनुमान (कम / मध्यम / उच्च), +- एक **परिमाण** — `big` (एक ऑपरेटर को पेज किया जाना चाहिए), `medium` (रन रिपोर्ट में संबंधित है), या `small` (डैशबोर्ड संदर्भ), +- एक स्थिर **फिंगरप्रिंट** (मुद्दे की श्रेणी + स्कोप से, *इस रन के सेशन से नहीं*) ताकि एक ही मुद्दे को रन-ओवर-रन ट्रैक किया जा सके यहां तक कि जब साक्ष्य बदल जाता है, +- और, जहाँ एक सरल नियतात्मक वाचक पुनरावृत्ति को पकड़ सकता है, एक **सुझाया गया अलर्ट** जिसे आप एक क्लिक में बना सकते हैं। -> **AI स्तर वैकल्पिक है लेकिन अनुशंसित है।** यदि ऑडिट पाइपलाइन के लिए कोई AI एजेंट कॉन्फ़िगर नहीं है, तो रन अभी भी निष्पादित होते हैं, नीति निष्कर्षों को स्थायी करते हैं, और ईमानदारी से एजेंटिक स्तर के लिए "विश्लेषण अनुपलब्ध" रिपोर्ट करते हैं बजाय चुप्पी से पास किए जाने के। +> **AI परत वैकल्पिक-लेकिन-अनुशंसित है।** यदि ऑडिट पाइपलाइन के लिए कोई AI एजेंट कॉन्फ़िगर नहीं किया गया है, तब भी रन निष्पादित होते हैं, नीति निष्कर्ष को संरक्षित करते हैं, और ईमानदारी से एजेंटिक परत के लिए "विश्लेषण अनुपलब्ध" रिपोर्ट करते हैं, चुप्पी से पास करने के बजाय। -### विफलता मोड्स +### विफलता मोड -सुधार आपके संगठन के टिकाऊ **विफलता-मोड कैटलॉग** में वर्गीकृत होते हैं (या एक नया मोड प्रस्तावित करते हैं)। मोड्स पैटर्न्स को रन्स के अंतर्गत एक स्थिर पहचान देते हैं और दीर्घ-क्षितिज पुनरावृत्ति ट्रैकिंग। +सुधार आपके संगठन के टिकाऊ **विफलता-मोड कैटलॉग** में वर्गीकृत होते हैं (या एक नया मोड प्रस्तावित करते हैं)। मोड पैटर्न को रन भर में और लंबे-क्षितिज पुनरावृत्ति ट्रैकिंग में एक स्थिर पहचान देते हैं। -## ट्रिएज लाइफसाइकल +## छंटाई जीवनचक्र एक निष्कर्ष पृष्ठ पर (`/audits//findings/`): | कार्रवाई | प्रभाव | |---|---| -| **acknowledge** | निष्कर्ष को दृश्यमान रखता है लेकिन इसकी प्राथमिकता को आधा करता है। | -| **resolve** | इसे ठीक किए गए के रूप में चिह्नित करता है। यदि पैटर्न वास्तव में बाद में वापस आता है, तो यह **new** के रूप में पुनः खुलता है — इसलिए एक प्रतिगमन जोर से होता है, चुप्पी से नहीं। | -| **mute** / **dismiss** | टिकाऊ दमन: पैटर्न की फिंगरप्रिंट को याद रखा जाता है और कभी भी सतह पर नहीं आता है, यहां तक कि रन्स के अंतर्गत। मute का उपयोग "ज्ञात, स्वीकृत" के लिए करें; dismiss का उपयोग "उपयोगी नहीं" के लिए करें। | -| **reopen** | दमन / समाधान को साफ करता है और पैटर्न को फिर से रैंक करता है। | -| **assign** | निष्कर्ष को एक ऑपरेटर (एक संगठन सदस्य) के लिए स्वामित्व के लिए भेजता है। प्राथमिकता और दमन स्थिति अपरिवर्तित हैं। | +| **स्वीकार करना** | निष्कर्ष को दृश्यमान रखता है लेकिन इसकी प्राथमिकता को आधा कर देता है। | +| **हल करना** | इसे ठीक किए गए के रूप में चिह्नित करता है। यदि पैटर्न वास्तव में बाद में वापस आता है, तो यह **नए** के रूप में फिर से खुलता है — इसलिए एक प्रतिगमन जोरदार होता है, चुप्पी से इतिहास में नहीं। | +| **मौन** / **खारिज करना** | टिकाऊ दमन: पैटर्न की फिंगरप्रिंट याद रखी जाती है और कभी सतह पर नहीं आती है, रन भर में भी। "ज्ञात, स्वीकृत" के लिए मौन का उपयोग करें; "उपयोगी नहीं" के लिए खारिज करना। | +| **फिर से खोलना** | दमन / संकल्प को साफ करता है और पैटर्न को फिर से रैंक करता है। | -कम-सिग्नल शोर प्रति-ऑडिट के साथ एजेंटिक सुधारों पर एक प्रति-रन निष्कर्ष कैप (`top_k`) के साथ नियंत्रित होता है। नीति निष्कर्ष कैप को बायपास करते हैं (वे सुरक्षा-प्रासंगिक हैं और हमेशा दिखाए जाते हैं)। कैप द्वारा कट कुछ भी रन के आंकड़ों में गिना जाता है — कुछ भी चुप्पी से ड्रॉप नहीं होता है। +कम-सिग्नल शोर को प्रति ऑडिट एजेंटिक सुधार पर एक प्रति-रन निष्कर्ष कैप (`top_k`) के साथ नियंत्रित किया जाता है। नीति निष्कर्ष कैप को बायपास करते हैं (वे सुरक्षा-प्रासंगिक हैं और हमेशा दिखाए जाते हैं)। कैप द्वारा कुछ भी कट रन के आंकड़ों में गिना जाता है — कुछ भी चुप्पी से ड्रॉप नहीं किया जाता है। ## शेड्यूलिंग -- **Cadence** (`schedule_interval_secs`): प्रति घंटा से साप्ताहिक; **दैनिक डिफ़ॉल्ट है**। ऑडिट्स जानबूझकर अलर्ट्स से मोटे हैं — एक एजेंटिक जांच पूरी विंडोज़ को स्कैन करता है और मिनटों तक चलता है। -- **Window**: या तो एक निश्चित रोलिंग लुकबैक (जैसे "प्रत्येक रन पिछले 7 दिनों को स्कैन करता है") या **since-last-run** (डिफ़ॉल्ट) — प्रत्येक रन वहाँ से शुरू होता है जहाँ पिछला सफल एक समाप्त हुआ था, एक छोटे ओवरलैप के साथ ताकि सीमा घटनाएं कभी न चूकें। -- अगला रन पिछले एक के **समाप्त होने** के बाद एक पूर्ण अंतराल निर्धारित है, इसलिए एक धीमा रन कभी एक ही ऑडिट का एक दूसरा सामयिक रन स्टैक नहीं करता है। -- ऑडिट पृष्ठ पर **Run now** इसे तुरंत देय बनाता है। +- **Cadence** (`schedule_interval_secs`): प्रति घंटा से साप्ताहिक; **दैनिक डिफ़ॉल्ट है**। ऑडिट जानबूझकर अलर्ट की तुलना में मोटे हैं — एक एजेंटिक जांच पूरी विंडो को स्कैन करती है और मिनटों के लिए चलती है। +- **विंडो**: या तो एक निश्चित रोलिंग लुकबैक (उदा. "हर रन पिछले 7 दिन स्कैन करता है") या **since-last-run** (डिफ़ॉल्ट) — प्रत्येक रन पिछले सफल रन से जहाँ रुका था वहीं उठाता है, एक छोटे ओवरलैप के साथ ताकि सीमा इवेंट कभी मिस न हों। +- अगला रन पिछले एक **पूरा होने** के बाद एक पूर्ण अंतराल के लिए शेड्यूल किया जाता है, इसलिए एक धीमा रन कभी एक ही ऑडिट का दूसरा समवर्ती रन ढेर नहीं करता। +- ऑडिट पृष्ठ पर **अभी चलाएं** इसे तुरंत कारण बनाता है। ## मॉडल चयन -एक ऑडिट बनाते समय आप यह चुन सकते हैं कि जांच कौन सा मॉडल उपयोग करता है, **मॉडल्स की सूची से जो आपका ऑपरेटर एजेंट सेवा के लिए कॉन्फ़िगर कर चुका है**। एक एकल मॉडल कॉन्फ़िगर होने के साथ, पिकर इसे एक कैप्शन के रूप में दिखाता है; कई के साथ, आप चुनते हैं। इसे अनसेट रखना कॉन्फ़िगर किए गए डिफ़ॉल्ट का उपयोग करता है। +एक ऑडिट बनाते समय आप जांच के लिए कौन सा मॉडल उपयोग करता है वह चुन सकते हैं, **मॉडल की सूची से जिसे आपके ऑपरेटर ने** एजेंट सेवा के लिए कॉन्फ़िगर किया है। एक एकल मॉडल कॉन्फ़िगर किए जाने पर, पिकर इसे कैप्शन के रूप में दिखाता है; कई होने पर, आप चुनते हैं। इसे सेट न छोड़ने से कॉन्फ़िगर किए गए डिफ़ॉल्ट का उपयोग होता है। -## अधिसूचनाएं +## सूचनाएं -जब एक रन **नए** निष्कर्ष सतह पर लाता है, तो ऑडिट आपके संगठन के कॉन्फ़िगर किए गए चैनलों को सूचित करता है — वही `alerts.enabled_channels` गेट और सेटिंग्स जो अलर्ट्स पाइपलाइन का उपयोग करता है: +जब एक रन **नए** निष्कर्ष सतह पर आते हैं, ऑडिट आपके संगठन के कॉन्फ़िगर किए गए चैनलों को सूचित करता है — वही `alerts.enabled_channels` गेट और सेटिंग्स जो अलर्ट पाइपलाइन का उपयोग करता है: -- **Slack** — महत्वपूर्ण (`big`) नई वस्तुओं का एक सारांश एक गहरी लिंक के साथ। -- **Email** — एक डिज़ाइन किया गया **ऑडिट रिपोर्ट** जो नए सुधार (शीर्ष गंभीरता, प्रति-आइटम सिफारिशें, गहरी लिंक) सूचीबद्ध करता है, जब ऑडिट के पास एक **email** चैनल संलग्न हो और कम से कम एक नया निष्कर्ष हो। +- **Slack** — महत्वपूर्ण (`big`) नए आइटम का एक सारांश एक गहरे लिंक के साथ। +- **Email** — एक डिज़ाइन किया गया **ऑडिट रिपोर्ट** जो नई सुधारें सूचीबद्ध करता है (शीर्ष गंभीरता, प्रति-आइटम सिफारिशें, गहरा लिंक), जब ऑडिट के पास एक **email** चैनल संलग्न होता है और कम से कम एक नया निष्कर्ष होता है। आवर्ती-लेकिन-ज्ञात निष्कर्ष फिर से सूचित नहीं करते हैं। ## कॉन्फ़िगरेशन संदर्भ -ऑडिट परिभाषाएं डैशबोर्ड (`/audits/new`) या API के माध्यम से प्रबंधित की जाती हैं। प्रति-ऑडिट सेटिंग्स में शेड्यूल cadence और विंडो, स्कोप (`{"environments": [...], "agent_ids": [...]}`), संवेदनशीलता (`low` / `medium` / `high`), सूचना चैनल, प्रति-रन निष्कर्ष कैप (`top_k`), और मॉडल (via `llm_budget.model`) शामिल हैं। ऑपरेटर-स्तर सर्वर सेटिंग्स (टाइमआउट्स, सैंडबॉक्स, एजेंट-सेवा URL) [deployment.md](/hi/agenteye/deployment) में दस्तावेज़ित हैं। +ऑडिट परिभाषाएं डैशबोर्ड (`/audits/new`) या API के माध्यम से प्रबंधित की जाती हैं। प्रति-ऑडिट सेटिंग में शेड्यूल cadence और विंडो, स्कोप (`{"environments": [...], "agent_ids": [...]}`) शामिल हैं, संवेदनशीलता (`low` / `medium` / `high`), सूचना चैनल, प्रति-रन निष्कर्ष कैप (`top_k`), और मॉडल (via `llm_budget.model`)। ऑपरेटर-स्तर सर्वर सेटिंग (टाइमआउट, सैंडबॉक्स, एजेंट-सेवा URL) [deployment.md](/hi/agenteye/deployment) में दस्तावेज़ित हैं। ## API -सभी एंडपॉइंट्स संगठन-स्कोप किए गए हैं और मानक वाहक-कुंजी प्रमाणीकरण का पालन करते हैं (देखें [api-keys.md](/hi/agenteye/api-keys))। +सभी एंडपॉइंट संगठन-स्कोप किए गए हैं और मानक वाहक-कुंजी प्रमाणीकरण का पालन करते हैं ([api-keys.md](/hi/agenteye/api-keys) देखें)। | एंडपॉइंट | अनुमति | उद्देश्य | |---|---|---| -| `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | ऑडिट परिभाषाओं को सूचीबद्ध / बनाएं। | -| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | एक ऑडिट का निरीक्षण, संपादन, हटाएं। | -| `POST /audits/:id/run` | `audits:write` | ऑडिट को तुरंत देय बनाएं। | -| `GET /audits/:id/runs` | `audits:read` | रन इतिहास (विंडो, स्थिति, आंकड़े, निष्कर्ष गिनती)। | -| `GET /audits/findings` | `audits:read` | संगठन-व्यापी निष्कर्ष, `audit_id`, `status` से फ़िल्टर योग्य; प्राथमिकता द्वारा सॉर्ट किए गए। | +| `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | ऑडिट परिभाषाएं सूचीबद्ध / बनाएं। | +| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | एक ऑडिट का निरीक्षण, संपादन, हटाना। | +| `POST /audits/:id/run` | `audits:write` | ऑडिट को तुरंत कारण बनाएं। | +| `GET /audits/:id/runs` | `audits:read` | रन इतिहास (विंडो, स्थिति, आंकड़े, निष्कर्ष गणना)। | +| `GET /audits/findings` | `audits:read` | संगठन-व्यापी निष्कर्ष, `audit_id`, `status` द्वारा फ़िल्टर किए जा सकते हैं; प्राथमिकता द्वारा क्रमबद्ध। | | `GET /audits/findings/:fid` | `audits:read` | पूर्ण निष्कर्ष विवरण (सिफारिश, सबूत, प्राथमिकता)। | -| `POST /audits/findings/:fid/status` | `audits:write` | ट्रिएज: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | +| `POST /audits/findings/:fid/status` | `audits:write` | छंटाई: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | -"ऑडिट चला लेकिन कुछ नहीं मिला", "कोड सैंडबॉक्स अक्षम है", और "ऑडिट ईमेल वितरित नहीं किया गया" के लिए, [troubleshooting.md](/hi/agenteye/troubleshooting#audits) देखें। \ No newline at end of file +"ऑडिट चलाया लेकिन कुछ नहीं मिला", "कोड सैंडबॉक्स अक्षम है", और "ऑडिट ईमेल वितरित नहीं किया गया" के लिए, [troubleshooting.md](/hi/agenteye/troubleshooting#audits) देखें। \ No newline at end of file diff --git a/docs/hi/agenteye/cli-recipes.mdx b/docs/hi/agenteye/cli-recipes.mdx index 33aac98d..54964f4c 100644 --- a/docs/hi/agenteye/cli-recipes.mdx +++ b/docs/hi/agenteye/cli-recipes.mdx @@ -1,29 +1,29 @@ --- -title: "एजेंटों के लिए CLI रेसिपीज़" -description: "एजेंटों के लिए AgentEye CLI रेसिपीज़ दस्तावेज़।" +title: "एजेंटों के लिए CLI रेसिपी" +description: "एजेंटों के लिए AgentEye CLI रेसिपी दस्तावेज़।" --- -एक स्क्रिप्ट या कोडिंग एजेंट से सीधे सेशन, इवेंट और मूल्यांकन डेटा (और पुनः-मूल्यांकन ट्रिगर करें), stdout पर क्लीन JSON के साथ जो सीधे `jq` में पाइप होता है। ये रेसिपीज़ AgentEye के ऑब्ज़र्वेबिलिटी डेटा को ऐसी चीज़ में बदलती हैं जिसे एक टर्मिनल उपयोगकर्ता या एक AI कोडिंग एजेंट (Claude Code, Cursor) बिना डैशबोर्ड के क्लिक किए क्वेरी और ऑटोमेट कर सकता है। +सीधे स्क्रिप्ट या कोडिंग एजेंट से सेशन, イベント और मूल्यांकन डेटा खींचें (और पुनः-मूल्यांकन ट्रिगर करें), stdout पर स्वच्छ JSON के साथ जो सीधे `jq` में पाइप करता है। ये रेसिपी AgentEye के अवलोकन योग्य डेटा को कुछ ऐसे में बदलते हैं जिसे टर्मिनल उपयोगकर्ता या AI कोडिंग एजेंट (Claude Code, Cursor) डैशबोर्ड के माध्यम से क्लिक किए बिना क्वेरी और स्वचालित कर सकते हैं। -नीचे दिए गए पैटर्न AgentEye CLI (`agenteye`) के लिए कॉपी-पेस्ट के लिए तैयार हैं। इंस्टॉलेशन, प्रमाणीकरण और पूरी विकल्प सूची के लिए [CLI](/hi/agenteye/cli) देखें; बिल्ट-इन मदद के लिए `agenteye -h` या `agenteye -h` चलाएँ। +नीचे दिए गए पैटर्न AgentEye CLI (`agenteye`) के लिए कॉपी-पेस्ट के लिए तैयार हैं। इंस्टॉलेशन, प्रमाणीकरण और पूर्ण विकल्प सूची के लिए [CLI](/hi/agenteye/cli) देखें; `agenteye -h` या `agenteye -h` चलाएं बिल्ट-इन सहायता के लिए। -## गोल्डन नियम +## स्वर्णिम नियम -1. **ग्लोबल विकल्प कमांड से *पहले* जाते हैं।** `agenteye --json sessions` सही है; `agenteye sessions --json` नहीं है। ग्लोबल्स हैं `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`। -2. **जब भी आप आउटपुट पार्स करें `--json` पास करें।** डेटा **stdout** पर JSON जाता है; मानव स्थिति और त्रुटियां **stderr** पर जाती हैं, इसलिए stdout `jq` में पाइप करने के लिए स्वच्छ रहता है। -3. **stderr टेक्स्ट पर नहीं, exit code पर शाखा दें**: `0` ठीक है · `2` खराब आर्गुमेंट्स · `3` डैशबोर्ड तक नहीं पहुंचा जा सकता · `4` लॉगिन नहीं किया गया या एक्सपायर हो गया · `5` अनुमति की कमी। -4. **`-h` के साथ खोजें।** हर कमांड अपने फिल्टर, वैल्यू फॉर्मेट और JSON आकार को डॉक्यूमेंट करता है। +1. **ग्लोबल विकल्प कमांड से *पहले* आते हैं।** `agenteye --json sessions` सही है; `agenteye sessions --json` नहीं है। ग्लोबल विकल्प हैं `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`। +2. **जब भी आप आउटपुट पार्स करते हैं तो `--json` पास करें।** डेटा **stdout** पर JSON के रूप में जाता है; मानव स्थिति और त्रुटियां **stderr** पर जाती हैं, इसलिए stdout `jq` में पाइपिंग के लिए स्वच्छ रहता है। +3. **stderr टेक्स्ट पर नहीं, exit कोड पर ब्रांच करें**: `0` ठीक है · `2` ख़राब तर्क · `3` डैशबोर्ड तक नहीं पहुंच सकते · `4` लॉगिन नहीं या एक्सपायर्ड · `5` अनुमति नहीं। +4. **`-h` से खोजें।** प्रत्येक कमांड अपने फ़िल्टर, मान प्रारूप और JSON आकार को दस्तावेज़ित करता है। -## एकबारी सेटअप +## एक बार का सेटअप ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # ताकि आप --base-url दोहराएं न -agenteye login --email you@example.com # ईमेल किए गए कोड को पेस्ट करें; ~24h वैलिड +agenteye login --email you@example.com # ईमेल किए गए कोड को पेस्ट करें; ~24h वैध ``` ## काम करने से पहले प्रमाणीकरण की पुष्टि करें -`whoami` कभी भी गायब या एक्सपायर सेशन पर त्रुटि नहीं देता; यह इसके बजाय `logged_in:false` रिपोर्ट करता है, इसलिए एक एजेंट सुरक्षित रूप से प्रमाणीकरण स्थिति की जांच कर सकता है। (यह फिर भी गैर-शून्य exit कर सकता है यदि कोई base URL सेट नहीं है या डैशबोर्ड तक नहीं पहुंचा जा सकता है।) +`whoami` एक लापता या एक्सपायर्ड सेशन पर कभी त्रुटि नहीं देता; यह इसके बजाय `logged_in:false` रिपोर्ट करता है, इसलिए एक एजेंट सुरक्षित रूप से प्रमाणीकरण स्थिति को जांच सकता है। (यदि कोई बेस URL सेट नहीं है या डैशबोर्ड अप्राप्य है तो यह अभी भी गैर-शून्य बाहर निकल सकता है।) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -31,71 +31,71 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## विफल या कम स्कोरिंग वाले सेशन खोजें +## विफल या कम स्कोरिंग सेशन खोजें ```bash -# पिछले 24h में सेशन जिनका मूल्यांकन त्रुटि है +# पिछले 24h में सेशन जिनका मूल्यांकन त्रुटि में हुआ agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# एक एजेंट के लिए helpfulness पर 0.5 तक स्कोर करने वाले मूल्यांकन +# एक एजेंट के लिए सहायकता पर <= 0.5 स्कोरिंग मूल्यांकन agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -स्कोर फिल्टरिंग **`evals`** पर होती है, `sessions` पर नहीं। `--score KEY:MIN..MAX` दोहराने योग्य है और AND-संयुक्त है; कोई भी सीमा वैकल्पिक है (`..0.5` का मतलब ≤ 0.5, `0.9..` का मतलब ≥ 0.9)। आप प्रति अनुरोध 20 तक स्कोर फिल्टर पास कर सकते हैं; अधिक HTTP 400 देता है। `sessions` `evals` के साथ `--env`, `--status`, `--agent-id`, `--session-id`, और समय-रेंज फिल्टर साझा करता है, लेकिन `--score` नहीं है। +स्कोर फ़िल्टरिंग `sessions` पर नहीं, **`evals`** पर रहता है। `--score KEY:MIN..MAX` दोहराया जा सकता है और AND-संयोजित है; कोई भी बाउंड वैकल्पिक है (`..0.5` का मतलब ≤ 0.5 है, `0.9..` का मतलब ≥ 0.9 है)। आप प्रति अनुरोध 20 तक स्कोर फ़िल्टर पास कर सकते हैं; अधिक HTTP 400 लौटाता है। `sessions` `evals` के साथ `--env`, `--status`, `--agent-id`, `--session-id` और समय-श्रेणी फ़िल्टर साझा करता है, लेकिन `--score` नहीं है। -## एक सेशन को शुरू से अंत तक पढ़ें +## एक सेशन को अंत तक पढ़ें -कोई एकल `session show` कमांड नहीं है — इवेंट ट्रेल को सेशन के मूल्यांकन के साथ जोड़ें: +कोई एकल `session show` कमांड नहीं है — इवेंट ट्रेल को सेशन के मूल्यांकन के साथ संयोजित करें: ```bash # सेशन का नवीनतम मूल्यांकन (स्थिति + स्कोर) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# रन में हर इवेंट (पूर्ण स्वीप के लिए --limit बढ़ाएं) +# रन में प्रत्येक इवेंट (पूर्ण स्वीप के लिए --limit बढ़ाएं) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# एक सेशन में सिर्फ टूल कॉल +# सेशन में केवल टूल कॉल agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -## सब कुछ फेच करें (पेजिनेशन) +## सब कुछ प्राप्त करें (पेजिनेशन) -परिणाम सबसे नए-पहले हैं और कर्सर-पेजिनेटेड हैं। +परिणाम सबसे नए-प्रथम और कर्सर-पेजिनेटेड हैं। ```bash -# एक शॉट: 200-पंक्ति के पेजों में 500 पंक्तियों तक फेच करें +# एक शॉट: 200-पंक्ति पृष्ठों में 500 पंक्तियों तक प्राप्त करें agenteye --json events --session-id run-001 --limit 500 --all > events.json -# मैनुअल पेजिंग: अगला cursor वापस फीड करें +# मैनुअल पेजिंग: अगले कर्सर को वापस फीड करें page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## `--fields` के साथ आउटपुट को कम करें +## --fields के साथ आउटपुट को पतला करें -कुंजियों को (टेबल और `--json` दोनों में) प्रतिबंधित करें, एजेंट को जो पढ़ना चाहिए उसे कम करने के लिए। +एजेंट को पढ़ना पड़ने वाले को कम करने के लिए कुंजियों को (टेबल और `--json` दोनों में) प्रतिबंधित करें। ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -अज्ञात फील्ड नाम अस्वीकार किए जाते हैं (exit `2`) वैलिड सूची के साथ, फील्ड नाम खोजने का एक सस्ता तरीका। +अज्ञात फ़ील्ड नाम अस्वीकार किए जाते हैं (exit `2`) वैध सूची के साथ, फ़ील्ड नाम खोजने का एक सस्ता तरीका। -## वैलिड फिल्टर वैल्यूज़ खोजें +## वैध फ़िल्टर मान खोजें ```bash -agenteye --json list envs | jq -r '.values[]' # --env के लिए वैल्यूज़ -agenteye --json list tools | jq -r '.values[]' # टूल नाम; agents, models, event_types भी ... -agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX के लिए वैलिड KEY +agenteye --json list envs | jq -r '.values[]' # --env के लिए मान +agenteye --json list tools | jq -r '.values[]' # टूल नाम; साथ ही एजेंट, मॉडल, event_types, ... +agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX के लिए वैध KEY ``` -## अपना org चुनें (मल्टी-टेनेंट) +## अपना org चुनें (बहु-किरायेदार) -यदि आप एक से अधिक org में हैं, तो लॉगिन पर सक्रिय टेनेंट चुनें (यह सहेजा जाता है): +यदि आप एक से अधिक org के सदस्य हैं, तो लॉगिन पर सक्रिय टेनेंट चुनें (यह सहेजा जाता है): ```bash agenteye login --org acme --email you@corp.com # लॉगिन के समान चरण में टेनेंट सेट करें @@ -103,35 +103,35 @@ agenteye --json orgs list | jq -r '.orgs[].org_slug' agenteye --org globex --json sessions --since 24h # एक कमांड के लिए ओवरराइड करें ``` -मल्टी-org लॉगिन `--org` के बिना गैर-शून्य exit करता है और चुनने के लिए orgs प्रिंट करता है। +`--org` के बिना एक बहु-org लॉगिन गैर-शून्य से बाहर निकलता है और चुनने के लिए org को प्रिंट करता है। -## SDK/collector के लिए एक API key प्रोविजन करें +## SDK/कलेक्टर के लिए API की प्रदान करें ```bash -# सीक्रेट एक बार प्रिंट होता है — --json के साथ यह .key फील्ड है +# गुप्त ONCE प्रिंट किया जाता है — --json के साथ यह .key फ़ील्ड है key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # घुमाएं; रद्द करने के लिए agenteye keys disable ci-bot --yes +agenteye keys regenerate ci-bot --yes # घुमाएं; ci-bot को रद्द करने के लिए agenteye keys disable ci-bot --yes ``` -## एक सहेजी गई या तदर्थ क्वेरी चलाएं +## सहेजी गई या तदर्थ क्वेरी चलाएं ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # एक सहेजी गई क्वेरी + एक positional $1 +agenteye --json query run errs --arg prod | jq '.rows' # एक सहेजी गई क्वेरी + एक स्थितीय $1 ``` -## एक incident को गैर-इंटरैक्टिवली ट्रिएज करें +## गैर-इंटरैक्टिव रूप से एक घटना का विश्लेषण करें ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> Mutations `--json` के तहत या जब stdin एक TTY नहीं है तो अपनी पुष्टि प्रॉम्प्ट को ऑटो-स्किप करते हैं, इसलिए एजेंट कभी हैंग नहीं करते; कहीं और स्पष्ट रूप से इसे स्किप करने के लिए `--yes`/`-y` पास करें। +> म्यूटेशन `--json` के तहत या जब stdin TTY नहीं है तो अपने पुष्टि प्रॉम्प्ट को स्वचालित रूप से छोड़ देते हैं, इसलिए एजेंट कभी हैंग नहीं होते; अन्यत्र स्पष्ट रूप से छोड़ने के लिए `--yes`/`-y` पास करें। -## एक स्क्रिप्ट में Exit-code हैंडलिंग +## स्क्रिप्ट में Exit-code हैंडलिंग ```bash out=$(agenteye --json sessions --since 1h) || code=$? @@ -150,20 +150,20 @@ esac |---|---| | `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` या `{"logged_in": false}` | | `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` | -| `events` | `{"events": [...], "next_cursor": }` | -| `evals` | `{"evaluations": [...], "next_cursor": }` | -| `sessions` | `{"sessions": [...], "next_cursor": }` | -| `errors` | `{"errors": [...], "next_cursor": }` | +| `events` | `{"events": [...], "next_cursor": }` | +| `evals` | `{"evaluations": [...], "next_cursor": }` | +| `sessions` | `{"sessions": [...], "next_cursor": }` | +| `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` एक बार दिखाया जाता है) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` एक बार दिखाया गया) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (कोई भी) | संसाधन ऑब्जेक्ट, या डिलीट के लिए `{"deleted": true, "id"}` | -| विफलता (कोई भी, `--json` के साथ) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` stdout पर | +| create/update/delete (कोई भी) | संसाधन ऑब्जेक्ट, या हटाने के लिए `{"deleted": true, "id"}` | +| विफलता (कोई भी, `--json` के साथ) | stdout पर `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | - प्रत्येक **event** आइटम (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`। - प्रत्येक **evaluation** आइटम (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`। - प्रत्येक **session** आइटम (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`। -प्रत्येक कमांड का `--fields` ठीक अपने स्वयं के आइटम के फील्ड नाम स्वीकार करता है — `sessions` और `evals` के बीच सेट अलग है, इसलिए एक के लिए वैलिड नाम दूसरे द्वारा अस्वीकार किया जा सकता है। \ No newline at end of file +प्रत्येक कमांड की `--fields` बिल्कुल अपने आइटम के फ़ील्ड नामों को स्वीकार करते हैं — सेट `sessions` और `evals` के बीच अलग है, इसलिए एक के लिए वैध नाम दूसरे द्वारा अस्वीकार किया जा सकता है। \ No newline at end of file diff --git a/docs/hi/agenteye/deployment.mdx b/docs/hi/agenteye/deployment.mdx index b409374c..f46fff99 100644 --- a/docs/hi/agenteye/deployment.mdx +++ b/docs/hi/agenteye/deployment.mdx @@ -1,10 +1,10 @@ --- -title: "तैनाती" -description: "AgentEye तैनाती दस्तावेज़।" +title: "परिनियोजन" +description: "AgentEye परिनियोजन दस्तावेज़।" --- -यह गाइड AgentEye सर्वर और डैशबोर्ड को उत्पादन में तैनात करने को कवर करती है। +यह मार्गदर्शिका AgentEye सर्वर और डैशबोर्ड को उत्पादन में परिनियोजित करने को कवर करती है। --- @@ -30,135 +30,134 @@ description: "AgentEye तैनाती दस्तावेज़।" +-----------+ ``` -- **Server**: Rust HTTP सेवा; ईवेंट बैच प्राप्त करता है, उन्हें ClickHouse में लिखता है, और PostgreSQL में संबंधपरक स्थिति बनाए रखता है। -- **Dashboard**: Next.js वेब ऐप; विशेषता के साथ सर्वर API के माध्यम से पढ़ता और लिखता है। -- **agenteye-collector**: सर्वर होस्ट पर नहीं, एजेंट मशीनों पर तैनात किया जाता है। -- **Postgres 15+**: आवश्यक। (मल्टी-टेनेंट रिलीज़ में 14 से बढ़ाया गया; org-membership स्कीमा एक कॉलम-लिस्ट `ON DELETE SET NULL` विदेशी कुंजी का उपयोग करता है, जो Postgres 15+ है। इस संस्करण को तैनात करने से पहले Postgres को अपग्रेड करें।) OLTP स्थिति संग्रहीत करता है: `api_keys`, `users`, `sessions`, `evaluation_jobs` (कतार), `dashboards`, `saved_queries`, `otp_codes`, प्लस मल्टी-टेनेंट तालिकाएं `orgs`, `org_memberships`, `org_settings`। -- **ClickHouse 24+**: आवश्यक। हर एक अंतर्ग्रहण किए गए ईवेंट के लिए विश्लेषण स्टोर। इंजन: `ReplacingMergeTree`, महीने के आधार पर विभाजित, `(session_id, ts, dedup_key)` द्वारा क्रमित। सर्वर `CLICKHOUSE_URL` के माध्यम से जुड़ता है; बंडल किया गया `deploy/base/clickhouse/` एक प्रदर्शन-ट्यून किए गए सिंगल-नोड कॉन्फ़िगरेशन शिप करता है। **मल्टी-टेनेंट आवश्यकता:** बंडल किया गया कॉन्फ़िग SQL एक्सेस प्रबंधन + `users_without_row_policies_can_read_rows=false` सक्षम करता है ताकि सर्वर एक प्रति संगठन पढ़ने-मात्र ClickHouse उपयोगकर्ता + पंक्ति नीति बना सके (SQL संपादक और AI एजेंट के लिए इंजन-प्रवर्तित अलगाव सीमा)। यदि आप अपनी खुद की ClickHouse कॉन्फ़िगरेशन आपूर्ति करते हैं, तो इन सेटिंग्स को आगे ले जाएं (`deploy/base/clickhouse/configmap.yaml` देखें)। -- **Redis 7+**: *वैकल्पिक* साझा कैश + दर-सीमा बैकएंड। सर्वर और डैशबोर्ड दोनों `REDIS_URL` के माध्यम से जुड़ते हैं। यदि अनुपस्थित है, तो दोनों केवल Postgres-पथों तक पहुंचते हैं। नीचे **Redis (वैकल्पिक कैश)** देखें। +- **Server**: Rust HTTP सेवा; ईवेंट बैच प्राप्त करता है, उन्हें ClickHouse में लिखता है, और PostgreSQL में संबंधपरक स्थिति को बनाए रखता है। +- **Dashboard**: Next.js वेब ऐप्लिकेशन; विशेष रूप से सर्वर API के माध्यम से पढ़ता और लिखता है। +- **agenteye-collector**: सर्वर होस्ट पर नहीं, एजेंट मशीनों पर परिनियोजित। +- **Postgres 15+**: आवश्यक। (बहु-किरायेदार रिलीज़ में 14 से बढ़ाया गया; org-membership स्कीमा एक कॉलम-सूची `ON DELETE SET NULL` विदेशी कुंजी का उपयोग करता है, जो Postgres 15+ है। इस संस्करण को तैनात करने से पहले Postgres को अपग्रेड करें।) OLTP स्थिति को संग्रहीत करता है: `api_keys`, `users`, `sessions`, `evaluation_jobs` (कतार), `dashboards`, `saved_queries`, `otp_codes`, साथ ही बहु-किरायेदार तालिकाएं `orgs`, `org_memberships`, `org_settings`। +- **ClickHouse 24+**: आवश्यक। प्रत्येक अंतर्निहित ईवेंट के लिए विश्लेषण स्टोर। इंजन: `ReplacingMergeTree`, महीने द्वारा विभाजित, `(session_id, ts, dedup_key)` द्वारा आदेशित। सर्वर `CLICKHOUSE_URL` के माध्यम से कनेक्ट करता है; बंडल किया गया `deploy/base/clickhouse/` एक प्रदर्शन-ट्यून किया गया सिंगल-नोड कॉन्फ़िगरेशन शिप करता है। **बहु-किरायेदार आवश्यकता:** बंडल किए गए कॉन्फ़िग SQL एक्सेस प्रबंधन + `users_without_row_policies_can_read_rows=false` को सक्षम करते हैं ताकि सर्वर एक केवल-पढ़ने योग्य ClickHouse उपयोगकर्ता + प्रति संगठन पंक्ति नीति बना सकता है (SQL संपादक और AI एजेंट के लिए इंजन-लागू पृथक्करण सीमा)। यदि आप अपनी स्वयं की ClickHouse कॉन्फ़िग प्रदान करते हैं, तो इन सेटिंग्स को ले जाएं (देखें `deploy/base/clickhouse/configmap.yaml`)। +- **Redis 7+**: *वैकल्पिक* साझा कैश + दर-सीमा बैकएंड। सर्वर और डैशबोर्ड दोनों `REDIS_URL` के माध्यम से कनेक्ट करते हैं। यदि अनुपस्थित है, तो दोनों केवल-Postgres पथों में सुंदरता से खराब हो जाते हैं। नीचे **Redis (वैकल्पिक कैश)** देखें। --- ## सर्वर -### इमेज खींचें +### छवि खींचें ```bash echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> वर्तमान निर्माण `beta-latest` के तहत प्रकाशित होते हैं; `latest` केवल स्थिर रिलीज़ को असाइन किया जाता है। उत्पादन के लिए, एक विशिष्ट `:v` टैग पिन करें; [उपलब्ध इमेज टैग](#available-image-tags) देखें। +> वर्तमान बिल्ड `beta-latest` के तहत प्रकाशित होते हैं; `latest` केवल स्थिर रिलीज़ को असाइन किया जाता है। उत्पादन के लिए, एक विशिष्ट `:v` टैग को पिन करें; देखें [Available Image Tags](#available-image-tags)। ### पर्यावरण चर | चर | आवश्यक | डिफ़ॉल्ट | विवरण | |---|---|---|---| -| `DATABASE_URL` | हाँ | कोई नहीं | Postgres DSN। मानक libpq कनेक्शन स्ट्रिंग प्रारूप योजना `postgres://` के साथ। `?sslmode=require` और अन्य libpq पैरामीटर का समर्थन करता है। पासवर्ड में `/`, `+`, या `=` नहीं हो सकते; URL-सुरक्षित पासवर्ड उत्पन्न करने के लिए `openssl rand -hex` का उपयोग करें। | -| `ADMIN_KEY` | नहीं | कोई नहीं | बूटस्ट्रैप एडमिन API कुंजी। हर स्टार्टअप पर सभी अनुमतियों के साथ अपसर्ट किया जाता है। मान को बदलकर और पुनः शुरू करके रोटेट करें। | +| `DATABASE_URL` | हां | कोई नहीं | Postgres DSN। मानक libpq कनेक्शन स्ट्रिंग प्रारूप स्कीम `postgres://` के साथ। `?sslmode=require` और अन्य libpq पैरामीटर का समर्थन करता है। पासवर्ड में `/`, `+`, या `=` नहीं हो सकता; URL-सुरक्षित पासवर्ड उत्पन्न करने के लिए `openssl rand -hex` का उपयोग करें। | +| `ADMIN_KEY` | नहीं | कोई नहीं | बूटस्ट्रैप व्यवस्थापक API कुंजी। हर स्टार्टअप पर सभी अनुमतियों के साथ upsert किया जाता है। मान बदलकर और पुनरारंभ करके घुमाएं। | | `LISTEN_ADDR` | नहीं | `0.0.0.0:8080` | बाइंड करने के लिए TCP पता | -| `MAX_BODY_BYTES` | नहीं | `134217728` (128 MB) | अधिकतम अनुरोध निकाय आकार | -| `ADMIN_EMAIL` | नहीं | कोई नहीं | बूटस्ट्रैप एडमिन उपयोगकर्ता ईमेल। हर स्टार्टअप पर सभी अनुमतियों के साथ अपसर्ट किया जाता है और संरक्षित चिह्नित किया जाता है: डैशबोर्ड/API के माध्यम से अक्षम नहीं किया जा सकता या अनुमतियां संशोधित नहीं की जा सकती। बूटस्ट्रैप एडमिन को रोटेट करने के लिए, `ADMIN_EMAIL` बदलें और पुनः शुरू करें; नया ईमेल संरक्षित के रूप में अपसर्ट किया जाता है, और पिछला अपनी सुरक्षा रखता है जब तक मैन्युअल रूप से डेटाबेस में साफ़ नहीं किया जाता। | -| `ALLOWED_EMAILS` | नहीं | कोई नहीं (सभी अवरुद्ध) | उपयोगकर्ता निर्माण और लॉगिन के लिए अनुमत ईमेल की अल्पविराम-सीमांकित सूची। सटीक पते (`user@example.com`) और डोमेन वाइल्डकार्ड (`*@example.com`) का समर्थन करता है। यदि अनिर्धारित है, तो कोई उपयोगकर्ता बनाए या लॉगिन नहीं कर सकता। **पहली बार बूट सीड केवल**: पहले बूट पर डिफ़ॉल्ट org की allowlist को बीज देता है; उसके बाद प्रत्येक org का [`//settings`](#operational-settings) पेज सच का स्रोत है और इस env var को बदलने का कोई प्रभाव नहीं है। | -| `SMTP_HOST` | नहीं | कोई नहीं | OTP ईमेल भेजने के लिए SMTP सर्वर होस्टनाम। यदि अनिर्धारित है, तो OTP कोड बजाय stdout में लॉग किए जाते हैं। | +| `MAX_BODY_BYTES` | नहीं | `134217728` (128 MB) | अधिकतम अनुरोध बॉडी आकार | +| `ADMIN_EMAIL` | नहीं | कोई नहीं | बूटस्ट्रैप व्यवस्थापक उपयोगकर्ता ईमेल। हर स्टार्टअप पर सभी अनुमतियों के साथ upsert किया जाता है और संरक्षित के रूप में चिह्नित किया जाता है: डैशबोर्ड/API के माध्यम से अक्षम नहीं किया जा सकता या अनुमतियों को संशोधित नहीं किया जा सकता। बूटस्ट्रैप व्यवस्थापक को घुमाने के लिए, `ADMIN_EMAIL` को बदलें और पुनरारंभ करें; नया ईमेल सुरक्षित के रूप में upsert किया जाता है, और पिछला वाला अपनी सुरक्षा को बनाए रखता है जब तक कि डेटाबेस में मैन्युअल रूप से साफ़ नहीं किया जाता। | +| `ALLOWED_EMAILS` | नहीं | कोई नहीं (सभी अवरुद्ध) | उपयोगकर्ता निर्माण और लॉगिन के लिए अनुमत ईमेल की अल्पविराम-विभाजित सूची। सटीक पते (`user@example.com`) और डोमेन वाइल्डकार्ड (`*@example.com`) का समर्थन करता है। यदि सेट नहीं है, तो कोई उपयोगकर्ता बनाया नहीं जा सकता या लॉगिन नहीं कर सकता। **पहली-बूट सीड केवल**: पहली बूट पर डिफ़ॉल्ट org के allowlist को सीड करता है; उसके बाद प्रत्येक org का [`//settings`](#operational-settings) पृष्ठ सत्य का स्रोत है और इस env var को बदलने का कोई प्रभाव नहीं है। | +| `SMTP_HOST` | नहीं | कोई नहीं | OTP ईमेल भेजने के लिए SMTP सर्वर होस्टनाम। यदि सेट नहीं है, तो OTP कोड stdout में लॉग किए जाते हैं। | | `SMTP_PORT` | नहीं | `587` | SMTP सर्वर पोर्ट | | `SMTP_USERNAME` | नहीं | कोई नहीं | SMTP प्रमाणीकरण उपयोगकर्ता नाम | | `SMTP_PASSWORD` | नहीं | कोई नहीं | SMTP प्रमाणीकरण पासवर्ड | | `SMTP_FROM` | नहीं | कोई नहीं | OTP ईमेल के लिए प्रेषक ईमेल पता | -| `SMTP_TLS` | नहीं | STARTTLS | STARTTLS का उपयोग किया जाता है जब तक आप स्पष्ट रूप से इसे बंद नहीं करते: `false` या `0` plaintext भेजता है (कोई TLS नहीं); कोई भी अन्य मान — अनिर्धारित सहित — STARTTLS सक्षम करता है। | -| `DASHBOARD_URL` | नहीं | बिल्ट-इन डिफ़ॉल्ट | OTP-ईमेल जादू लिंक और सतर्कता अधिसूचनाओं में घटना जादू-लिंक दोनों बनाने के लिए उपयोग किया जाने वाला डैशबोर्ड मूल। यदि अनिर्धारित है तो यह एक बिल्ट-इन डिफ़ॉल्ट पर वापस आता है (और, केवल OTP के लिए, डैशबोर्ड-व्युत्पन्न अनुरोध मूल पर)। स्प्लिट-डोमेन सेटअप के लिए इसे सेट करें ताकि ईमेल और Slack/घटना दोनों लिंक आपके डैशबोर्ड पर इंगित हों। **ईमेल जादू-लिंक URL** नीचे देखें; अधिकांश ऑपरेटर को इसे सेट करने की आवश्यकता नहीं है। | -| `SESSION_TTL_SECS` | नहीं | `86400` (24 h) | सेकंड में डैशबोर्ड सत्र अवधि। **पहली बार बूट सीड केवल**: पहली तैनाती के बाद [`//settings`](#operational-settings) के माध्यम से प्रति org संपादित करें। | -| `OTP_TTL_SECS` | नहीं | `600` (10 min) | सेकंड में OTP कोड वैधता अवधि। **पहली बार बूट सीड केवल**: पहली तैनाती के बाद [`//settings`](#operational-settings) के माध्यम से प्रति org संपादित करें। | -| `REDIS_URL` | नहीं | कोई नहीं | वैकल्पिक साझा कैश + दर-सीमा बैकएंड, उदाहरण के लिए `redis://redis:6379/0`। जब सेट किया जाता है, तो सर्वर प्रमाणित API-कुंजी लुकअप, डैशबोर्ड के `/models` एकत्रित, सत्र सूची, और env-list पहलू को कैश करता है; यह भी OTP-अनुरोध दर सीमा को Postgres COUNT से Redis INCR तक स्थानांतरित करता है। यदि अनिर्धारित या अपहुंच योग्य है, तो सर्वर कैश के बिना चलता है (OTP सीमा Postgres तक गिरती है, हर दूसरी कैश कॉल सच के स्रोत में गिरती है)। नीचे **Redis (वैकल्पिक कैश)** देखें। | -| `CLICKHOUSE_URL` | **हाँ** | कोई नहीं | ClickHouse उदाहरण का आधार URL, उदाहरण के लिए `http://clickhouse:8123`। सर्वर हर स्टार्टअप पर इस डेटाबेस पर अपनी ईवेंट स्कीमा लागू करता है और यदि यह ClickHouse तक पहुंच नहीं सकता तो बूट करने से इनकार करता है। नीचे **ClickHouse (आवश्यक विश्लेषण स्टोर)** देखें। | +| `SMTP_TLS` | नहीं | STARTTLS | STARTTLS का उपयोग किया जाता है जब तक आप इसे स्पष्ट रूप से बंद नहीं करते: `false` या `0` सादा पाठ भेजता है (कोई TLS नहीं); कोई अन्य मान — अनसेट सहित — STARTTLS सक्षम करता है। | +| `DASHBOARD_URL` | नहीं | निर्मित-में डिफ़ॉल्ट | OTP-ईमेल मैजिक लिंक और अलर्ट सूचनाओं में घटना मैजिक-लिंक दोनों को बनाने के लिए उपयोग किया जाता है डैशबोर्ड मूल। यदि सेट नहीं है तो यह निर्मित-में डिफ़ॉल्ट में वापस आता है (और केवल OTP के लिए, डैशबोर्ड-व्युत्पन्न अनुरोध मूल को भी)। विभाजन-डोमेन सेटअप के लिए इसे सेट करें ताकि ईमेल और Slack/घटना दोनों लिंक आपके डैशबोर्ड पर इंगित करें। नीचे **Email magic-link URL** देखें; अधिकांश ऑपरेटर को इसे सेट करने की आवश्यकता नहीं है। | +| `SESSION_TTL_SECS` | नहीं | `86400` (24 h) | डैशबोर्ड सत्र अवधि सेकंड में। **पहली-बूट सीड केवल**: [`//settings`](#operational-settings) के माध्यम से पहली तैनाती के बाद प्रति org संपादित करें। | +| `OTP_TTL_SECS` | नहीं | `600` (10 मिनट) | OTP कोड वैधता अवधि सेकंड में। **पहली-बूट सीड केवल**: [`//settings`](#operational-settings) के माध्यम से पहली तैनाती के बाद प्रति org संपादित करें। | +| `REDIS_URL` | नहीं | कोई नहीं | वैकल्पिक साझा कैश + दर-सीमा बैकएंड, उदाहरण `redis://redis:6379/0`। जब सेट किया जाता है, तो सर्वर प्रमाणित API-कुंजी लुकअप, डैशबोर्ड के `/models` एकत्रित, सत्र सूची, और env-list पहलू को कैश करता है; यह OTP-अनुरोध दर सीमा को Postgres COUNT से Redis INCR में भी स्थानांतरित करता है। यदि सेट नहीं है या अप्राप्य है, तो सर्वर कैश के बिना चलता है (OTP सीमा Postgres में वापस आती है, हर दूसरे कैश कॉल सत्य के स्रोत में पड़ता है)। नीचे **Redis (वैकल्पिक कैश)** देखें। | +| `CLICKHOUSE_URL` | **हां** | कोई नहीं | ClickHouse उदाहरण का आधार URL, उदाहरण `http://clickhouse:8123`। सर्वर हर स्टार्टअप पर इस डेटाबेस पर अपनी ईवेंट स्कीमा लागू करता है और यदि यह ClickHouse तक नहीं पहुंच सकता तो बूट करने से इंकार करता है। नीचे **ClickHouse (आवश्यक विश्लेषण स्टोर)** देखें। | | `CLICKHOUSE_DATABASE` | नहीं | `agenteye` | ClickHouse डेटाबेस (स्कीमा) नाम। सर्वर स्टार्टअप पर इसे बनाता है यदि यह मौजूद नहीं है। | -| `ORG_CH_SECRET` | नहीं (सिंगल-टेनेंट) / **हाँ (मल्टी-org)** | dev डिफ़ॉल्ट | HMAC कुंजी जिससे प्रत्येक संगठन के प्रति-टेनेंट ClickHouse पासवर्ड प्राप्त किए जाते हैं। SQL संपादक और AI एजेंट के `run_query` org के अपने पढ़ने-मात्र ClickHouse उपयोगकर्ता के रूप में निष्पादित होते हैं, जिसकी पंक्ति नीति इंजन में टेनेंट अलगाव को लागू करती है। सिंगल-टेनेंट तैनाती बिल्ट-इन dev डिफ़ॉल्ट पर ठीक बूट करती है; **दूसरा org प्रदान करने से पहले आपको एक मजबूत, स्थिर मान सेट करना होगा**, क्योंकि `agenteye-orgctl org create` CLI बिल्ट-इन dev डिफ़ॉल्ट पर चलने से इनकार करता है। इसे रोटेट करने से हर org का ClickHouse उपयोगकर्ता अगले स्टार्टअप तक अनाथ हो जाता है पुनः-प्रावधान (बूट-समय सामंजस्य स्वचालित रूप से इसे ठीक करता है)। इसे रहस्य रखें और प्रतिकृतियों में अपरिवर्तित रखें। Org प्रावधान स्वयं केवल ऑपरेटर है; नीचे **Organizations (multi-tenancy)** देखें। | -| `DEFAULT_ORG_NAME` | नहीं | `Default` | बिल्ट-इन डिफ़ॉल्ट org के लिए बीज किया गया प्रदर्शन नाम। **पहली बार बूट सीड केवल**, और केवल जब org अभी भी अपनी ताज़ा-प्रवासित सामान्य पहचान रखता है, स्टार्टअप पर लागू, फिर अनदेखा किया जाता है। एक बार जब आप org का नाम बदलते हैं (`agenteye-orgctl org rename`) तो नाम परिवर्तन प्राधिकार है और इस env var का कोई और प्रभाव नहीं है। | -| `DEFAULT_ORG_SLUG` | नहीं | `default` | बिल्ट-इन डिफ़ॉल्ट org के लिए URL स्लग, डैशबोर्ड पथ यह रहता है (`//…`)। `DEFAULT_ORG_NAME` के समान पहली-बूट-केवल / pristine-केवल सिमेंटिक्स। 1-40 लोअरकेस अलфान्यूमेरिक्स होना चाहिए एकल आंतरिक हाइफन के साथ और [आरक्षित शब्द](#organizations-multi-tenancy) नहीं; एक अमान्य मान अनदेखा किया जाता है (org `default` रखता है)। सिंगल-टेनेंट इंस्टॉल को बिना किसी पोस्ट-तैनाती CLI कदम के `/acme` के रूप में प्रस्तुत करने देता है। | -| `RUST_LOG` | नहीं | `info` | लॉग विस्तार (`debug`, `warn`, `error`, `agenteye_server=trace`) | -| `EVALUATOR_ENDPOINT` | नहीं | कोई नहीं | आपकी मूल्यांकनकर्ता सेवा का आधार URL (उदाहरण के लिए `http://evaluator:9000`)। जब अनिर्धारित है तो संपूर्ण मूल्यांकन पाइपलाइन एक नो-ऑप है; कोई कतार पंक्ति नहीं लिखी जाती, कोई कार्यकर्ता नहीं चलते। [मूल्यांकन सूट](/hi/agenteye/evaluation-suite) देखें। | -| `EVALUATOR_TOKEN` | नहीं | कोई नहीं | मूल्यांकनकर्ता के रूप में भेजा गया `Authorization: Bearer `। **मूल्यांकनकर्ता सेवा के साथ कॉन्फ़िगर किए गए समान मान के बराबर होना चाहिए।** केवल वैकल्पिक यदि आपका मूल्यांकनकर्ता कोई टोकन के साथ कॉन्फ़िगर किया गया है। | -| `EVALUATOR_WORKERS` | नहीं | `2` | समवर्तिता: मूल्यांकन भेजने वाले प्रति सर्वर उदाहरण कार्यकर्ता कार्यों की संख्या। क्षैतिज रूप से स्केल किए गए कई सर्वरों में चलाने के लिए सुरक्षित। | -| `EVALUATOR_CLAIM_BATCH` | नहीं | `4` | अधिकतम संख्या में मूल्यांकन जो एक एकल कार्यकर्ता प्रति टिक दावा करता है। बैच **समवर्ती** रूप से भेजे जाते हैं, इसलिए आपके मूल्यांकनकर्ता एंडपॉइंट पर कुल समवर्तिता `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` है। | -| `EVALUATOR_POLL_IDLE_SECS` | नहीं | `2` | कार्यकर्ता कितने समय तक सो जाता है जब कुछ भी होना नहीं है तो भेजने का प्रयास करने के बीच। | -| `EVALUATOR_POLLING_INTERVAL_SECS` | नहीं | `10` | `GET /evaluate/{id}` पोल के लिए अंतिम फॉलबैक गति (सेकंड) जब मूल्यांकनकर्ता प्रति-प्रतिक्रिया `next_poll_secs` नहीं लौटाता है और `GET /config` से `default_poll_interval_secs` की विज्ञापन नहीं करता है। | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | नहीं | `30000` | मूल्यांकनकर्ता के विरुद्ध प्रति-HTTP-अनुरोध टाइमआउट (मिलीसेकंड)। | -| `EVALUATOR_MAX_ATTEMPTS` | नहीं | `5` | इस कई विफल प्रयासों के बाद एक मूल्यांकन टर्मिनल `error` (या विफलताएं अनुरोध टाइमआउट थीं तो `timeout`) के रूप में रिकॉर्ड किया जाता है। | -| `EVALUATOR_CONFIG_REFRESH_SECS` | नहीं | `300` (5 min) | सर्वर कितनी बार `GET /config` को मूल्यांकनकर्ता से पुनः-प्राप्त करता है। | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | नहीं | `3600` (1 h) | अधिकतम wallclock समय एक सत्र पोलिंग कतार में रह सकता है इससे पहले AgentEye इसे `timeout` के रूप में समाप्त कर देता है। एक मूल्यांकनकर्ता से रक्षा करता है जो `pending` को हमेशा के लिए लौटाता है। | -| `ALERT_WORKERS` | नहीं | `1` | समवर्तिता: प्रति सर्वर उदाहरण सतर्कता नियमों का मूल्यांकन करने वाले कार्यकर्ता कार्यों की संख्या। [सतर्कताएं](/hi/agenteye/alerts) देखें। | -| `ALERT_CLAIM_BATCH` | नहीं | `16` | अधिकतम संख्या में सतर्कताएं जो एक एकल कार्यकर्ता प्रति टिक दावा करता है। | -| `ALERT_POLL_IDLE_SECS` | नहीं | `5` | कतार खाली होने पर सतर्कता कार्यकर्ता कितने समय तक सो जाता है। | -| `ALERT_REQUEST_TIMEOUT_MS` | नहीं | `15000` | प्रति-ट्रिगर मूल्यांकन टाइमआउट (ClickHouse क्वेरीज़ + आउटबाउंड चैनल HTTP)। | -| `ALERT_MAX_ATTEMPTS` | नहीं | `5` | लगातार क्षणिक विफलताएं इससे पहले एक सतर्कता अपने सामान्य गति के बजाय घातीय बैकऑफ पर पुनः-शेड्यूल करती है। | -| `AUDIT_WORKERS` | नहीं | `1` | समवर्तिता: प्रति सर्वर उदाहरण ऑडिट निष्पादित करने वाले कार्यकर्ता कार्यों की संख्या। [ऑडिट्स](/hi/agenteye/audits) देखें। | -| `AUDIT_CLAIM_BATCH` | नहीं | `1` | अधिकतम संख्या में होने वाले ऑडिट जो एक एकल कार्यकर्ता प्रति टिक दावा करता है। एक एजेंटिक जांच एक लंबा लूप है, इसलिए डिफ़ॉल्ट 1 है। | -| `AUDIT_POLL_IDLE_SECS` | नहीं | `30` | कोई ऑडिट होने पर ऑडिट कार्यकर्ता कितने समय तक सो जाता है। | -| `AUDIT_REQUEST_TIMEOUT_MS` | नहीं | `30000` | ClickHouse के विरुद्ध प्रति-नीति-क्वेरी टाइमआउट (मिलीसेकंड)। | -| `AUDIT_LLM_TIMEOUT_MS` | नहीं | `1440000` | AI सहायक सेवा के लिए एजेंटिक जांच कॉल के लिए टाइमआउट। एक पूर्ण एजेंट लूप मिनटों के लिए चलता है; इसे एजेंट के अपने `AGENTEYE_AUDIT_TIMEOUT_MS` से ऊपर रखें ताकि एजेंट सर्वर हार मानने से पहले अपने आंशिक निष्कर्ष लौटाए। | -| `AUDIT_MAX_ATTEMPTS` | नहीं | `5` | लगातार क्षणिक विफलताएं इससे पहले एक ऑडिट अपने सामान्य गति के बजाय घातीय बैकऑफ पर पुनः-शेड्यूल करता है। | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | नहीं | — | ऑडिट की एजेंटिक जांच AI-सहायक `agent` सेवा को कॉल करती है, **सहायक के रूप में एक ही कनेक्शन का पुनः उपयोग** — तो **सर्वर** पर भी ये दोनों सेट करें (बंडल किए गए manifests/compose करते हैं)। दोनों सेट ⇒ ऑडिट AI जांच चलाते हैं; या तो अनिर्धारित ⇒ ऑडिट **केवल-नीति** चलाते हैं (नियतात्मक SQL नीति पास अभी भी चलता है), प्रति-ऑडिट `llm_enabled` झंडे की परवाह किए बिना। एजेंट के पास भी एक LLM कॉन्फ़िगर होना चाहिए — [assistant.md](/hi/agenteye/assistant) देखें। | - -**AI सहायक सेवा — ऑडिट + सैंडबॉक्स सेटिंग्स।** एजेंटिक जांच और इसका इन-पॉड Python सैंडबॉक्स **एजेंट सेवा** पर ट्यून किए जाते हैं (सर्वर पर नहीं), सभी `AGENTEYE_AUDIT_*` प्रीफिक्स पर और सभी वैकल्पिक: - -| चर | डिफ़ॉल्ट | मतलब | +| `ORG_CH_SECRET` | नहीं (एकल-किरायेदार) / **हां (बहु-org)** | dev डिफ़ॉल्ट | HMAC कुंजी जिससे प्रत्येक संगठन की प्रति-किरायेदार ClickHouse पासवर्ड व्युत्पन्न होता है। SQL संपादक और AI एजेंट के `run_query` org की अपनी केवल-पढ़ने योग्य ClickHouse उपयोगकर्ता के रूप में निष्पादित होते हैं, जिसकी पंक्ति नीति इंजन में किरायेदार अलगाव को लागू करती है। एकल-किरायेदार परिनियोजन निर्मित-में dev डिफ़ॉल्ट पर ठीक बूट करते हैं; **दूसरा org प्रदान करने से पहले आपको एक मजबूत, स्थिर मान सेट करना होगा**, क्योंकि `agenteye-orgctl org create` CLI निर्मित-में dev डिफ़ॉल्ट पर चलने से इंकार करता है। इसे घुमाना हर org के ClickHouse उपयोगकर्ता को तब तक अनाथ कर देता है जब तक अगली स्टार्टअप उन्हें पुनः प्रावधान न करे (बूट-समय समेटना इसे स्वचालित रूप से ठीक करता है)। इसे गुप्त रखें और प्रतिकृतियों में अपरिवर्तित रखें। Org प्रावधान ही ऑपरेटर-केवल है; नीचे **Organizations (multi-tenancy)** देखें। | +| `DEFAULT_ORG_NAME` | नहीं | `Default` | निर्मित-में डिफ़ॉल्ट org के लिए seeded प्रदर्शन नाम। **पहली-बूट सीड केवल**, और केवल जबकि org अभी भी इसे ताज़ा-माइग्रेट किए गए सामान्य पहचान से संभाले, स्टार्टअप पर लागू, फिर अनदेखा किया जाता है। एक बार जब आप org का नाम बदल देते हैं (`agenteye-orgctl org rename`) नाम बदलना सत्तामूलक हो जाता है और इस env var का आगे कोई प्रभाव नहीं है। | +| `DEFAULT_ORG_SLUG` | नहीं | `default` | निर्मित-में डिफ़ॉल्ट org के लिए URL slug, डैशबोर्ड पथ यह रहता है (`//…`)। `DEFAULT_ORG_NAME` के समान पहली-बूट-केवल / कौवारी-केवल शब्दार्थ। 1-40 लोअरकेस अल्फान्यूमेरिक्स एकल आंतरिक हाइफन और [आरक्षित शब्द](#organizations-multi-tenancy) नहीं होना चाहिए; एक अमान्य मान अनदेखा किया जाता है (org `default` को रखता है)। एकल-किरायेदार स्थापना को कोई पोस्ट-तैनात CLI चरण के बिना `/default` के बजाय उदाहरण के लिए `/acme` के रूप में प्रस्तुत करने देता है। | +| `RUST_LOG` | नहीं | `info` | लॉग verbosity (`debug`, `warn`, `error`, `agenteye_server=trace`) | +| `EVALUATOR_ENDPOINT` | नहीं | कोई नहीं | आपकी मूल्यांकन सेवा का आधार URL (उदाहरण `http://evaluator:9000`)। जब सेट न हो तो संपूर्ण मूल्यांकन पाइपलाइन एक no-op है; कोई कतार पंक्तियां लिखी नहीं जाती, कोई कार्यकर्ता नहीं चलते। देखें [Evaluation Suite](/hi/agenteye/evaluation-suite)। | +| `EVALUATOR_TOKEN` | नहीं | कोई नहीं | मूल्यांकक को `Authorization: Bearer ` के रूप में भेजा जाता है। **मूल्यांकक सेवा के साथ समान मान के बराबर होना चाहिए।** केवल वैकल्पिक यदि आपका मूल्यांकक कोई टोकन के साथ कॉन्फ़िगर नहीं है। | +| `EVALUATOR_WORKERS` | नहीं | `2` | Concurrency: प्रति सर्वर उदाहरण worker कार्यों की संख्या जो मूल्यांकन dispatch करते हैं। क्षैतिज रूप से स्केल किए गए कई सर्वरों में चलाने के लिए सुरक्षित। | +| `EVALUATOR_CLAIM_BATCH` | नहीं | `4` | अधिकतम संख्या मूल्यांकन एक एकल worker प्रति टिक दावा करता है। बैच **concurrently** dispatch किए जाते हैं, इसलिए आपके मूल्यांकक endpoint पर कुल concurrency `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` है। | +| `EVALUATOR_POLL_IDLE_SECS` | नहीं | `2` | जब कुछ भी कारण न हो तो worker कितने समय सोते हैं dispatch प्रयासों के बीच। | +| `EVALUATOR_POLLING_INTERVAL_SECS` | नहीं | `10` | अंतिम fallback cadence (सेकंड) `GET /evaluate/{id}` के लिए जब मूल्यांकक प्रति-प्रतिक्रिया `next_poll_secs` नहीं लौटाता और `GET /config` से `default_poll_interval_secs` का विज्ञापन नहीं करता। | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | नहीं | `30000` | मूल्यांकक के विरुद्ध प्रति-HTTP-अनुरोध timeout (मिलीसेकंड)। | +| `EVALUATOR_MAX_ATTEMPTS` | नहीं | `5` | इस कई विफल प्रयासों के बाद एक मूल्यांकन टर्मिनल `error` (या `timeout` यदि विफलताएं request timeouts थीं) के रूप में दर्ज किया जाता है। | +| `EVALUATOR_CONFIG_REFRESH_SECS` | नहीं | `300` (5 मिनट) | सर्वर कितनी बार मूल्यांकक से `GET /config` को पुनः प्राप्त करता है। | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | नहीं | `3600` (1 h) | अधिकतम wallclock समय एक सत्र पोलिंग कतार में रह सकता है इससे पहले कि AgentEye इसे `timeout` के रूप में समाप्त कर दे। एक मूल्यांकक के खिलाफ सुरक्षा जो `pending` को forever वापस लौटाता है। | +| `ALERT_WORKERS` | नहीं | `1` | Concurrency: प्रति सर्वर उदाहरण worker कार्यों की संख्या जो अलर्ट नियमों का मूल्यांकन करते हैं। देखें [Alerts](/hi/agenteye/alerts)। | +| `ALERT_CLAIM_BATCH` | नहीं | `16` | अधिकतम संख्या अलर्ट एक एकल worker प्रति टिक दावा करता है। | +| `ALERT_POLL_IDLE_SECS` | नहीं | `5` | कितने समय एक alerts worker सोते हैं जब कतार खाली है। | +| `ALERT_REQUEST_TIMEOUT_MS` | नहीं | `15000` | प्रति-trigger मूल्यांकन timeout (ClickHouse queries + आउटबाउंड चैनल HTTP)। | +| `ALERT_MAX_ATTEMPTS` | नहीं | `5` | क्रमिक transient विफलताएं इससे पहले कि एक अलर्ट अपने सामान्य cadence पर reschedule करे exponential backoff के बजाय। | +| `AUDIT_WORKERS` | नहीं | `1` | Concurrency: प्रति सर्वर उदाहरण worker कार्यों की संख्या जो audits को निष्पादित करते हैं। देखें [Audits](/hi/agenteye/audits)। | +| `AUDIT_CLAIM_BATCH` | नहीं | `1` | अधिकतम संख्या due audits एक एकल worker प्रति टिक दावा करता है। एक agentic जांच एक लंबा लूप है, इसलिए डिफ़ॉल्ट 1 है। | +| `AUDIT_POLL_IDLE_SECS` | नहीं | `30` | कितने समय एक audits worker सोते हैं जब कोई audit due नहीं है। | +| `AUDIT_REQUEST_TIMEOUT_MS` | नहीं | `30000` | ClickHouse के विरुद्ध प्रति-policy-query timeout (मिलीसेकंड)। | +| `AUDIT_LLM_TIMEOUT_MS` | नहीं | `1440000` | AI सहायक सेवा के लिए agentic जांच कॉल के लिए timeout। एक पूर्ण agent लूप मिनटों के लिए चलता है; इसे agent के अपने `AGENTEYE_AUDIT_TIMEOUT_MS` के ऊपर रखें ताकि agent सर्वर देने से पहले अपनी आंशिक निष्कर्ष वापस लौटाए। | +| `AUDIT_MAX_ATTEMPTS` | नहीं | `5` | क्रमिक transient विफलताएं इससे पहले कि एक audit अपने सामान्य cadence पर reschedule करे exponential backoff के बजाय। | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | नहीं | — | audit की agentic जांच AI-सहायक `agent` सेवा को कॉल करती है, **सहायक के समान कनेक्शन का पुनः उपयोग करते हुए** — इसलिए इन दोनों को **सर्वर** पर भी सेट करें (बंडल किए गए manifests/compose करते हैं)। दोनों सेट ⇒ audits AI जांच चलाते हैं; कोई भी सेट न हो ⇒ audits **policy-only** चलाते हैं (deterministic SQL policy pass अभी भी चलता है), प्रति-audit `llm_enabled` फ़्लैग की परवाह किए बिना। एजेंट के पास भी एक LLM कॉन्फ़िगर किया होना चाहिए — देखें [assistant.md](/hi/agenteye/assistant)। | + +**AI सहायक सेवा — audit + sandbox सेटिंग्स।** agentic जांच और इसके in-pod Python sandbox **एजेंट सेवा** पर ट्यून किए जाते हैं (सर्वर पर नहीं), सभी `AGENTEYE_AUDIT_*` उपसर्ग पर और सभी वैकल्पिक: + +| चर | डिफ़ॉल्ट | अर्थ | |---|---|---| -| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | प्रति जांच अधिकतम एजेंट मोड़। | -| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | एक जांच के लिए दीवार-घड़ी (20 min)। सर्वर के `AUDIT_LLM_TIMEOUT_MS` **नीचे** रहना चाहिए। | -| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | एजेंट पॉड प्रति समवर्ती जांचें (चैट सहायक के बजट से अलग)। | -| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | बुलबुलेरैप सैंडबॉक्स के लिए प्रति-स्क्रिप्ट सीमाएं। | +| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | प्रति जांच max agent turns। | +| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | एक जांच के लिए Wall-clock (20 मिनट)। सर्वर के `AUDIT_LLM_TIMEOUT_MS` के **नीचे** रहना चाहिए। | +| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | एजेंट pod के साथ concurrent जांच (chat सहायक के बजट से अलग)। | +| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | bubblewrap sandbox के लिए प्रति-स्क्रिप्ट सीमाएं। | -**सैंडबॉक्स प्लेटफॉर्म आवश्यकता।** ऑडिट कोड सैंडबॉक्स मॉडल के Python को एक bubblewrap जेल में चलाता है, जिसे **अप्रविष्ट उपयोगकर्ता नेमस्पेस** की आवश्यकता है। एजेंट पॉड को `clone()` झंडों की अनुमति देनी चाहिए — k8s पर `seccompProfile: Unconfined` सेट करें या compose पर `security_opt: [seccomp:unconfined]`। जहां नोड कर्नल अप्रविष्ट उपयोगकर्ता नेमस्पेस को अक्षम करता है (उदाहरण के लिए कुछ GKE COS छवियां), सैंडबॉक्स **प्रीफ्लाइट विफल हो जाता है और ऑडिटर स्वचालित रूप से केवल-SQL में घट जाता है** — कोई त्रुटि नहीं, बस एजेंट के `/health` पर `sandbox_available: false`। +**Sandbox platform आवश्यकता।** audit code sandbox model के Python को एक bubblewrap जेल में चलाता है, जिसे **unprivileged user namespaces** की आवश्यकता है। एजेंट pod को `clone()` फ़्लैग की अनुमति देनी चाहिए — `seccompProfile: Unconfined` (k8s) या `security_opt: [seccomp:unconfined]` (compose) को agent पर सेट करें। जहां node kernel unprivileged user namespaces को अक्षम करता है (उदाहरण कुछ GKE COS छवियां), sandbox **preflight विफल हो जाता है और auditor स्वचालित रूप से SQL-only में downgrade हो जाता है** — कोई त्रुटि नहीं, केवल agent के `/health` पर `sandbox_available: false`। ### चलाएं -अपने पर्यावरण में `DATABASE_URL` और `CLICKHOUSE_URL` सेट करें (सर्वर ClickHouse के बिना बूट करने से इनकार करता है), फिर उन्हें कंटेनर तक पास करें: +अपने वातावरण में `DATABASE_URL` सेट करें, फिर इसे कंटेनर में पास करें: ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest ``` -सर्वर स्टार्टअप पर स्वचालित रूप से डेटाबेस प्रवास चलाता है; कोई अलग प्रवास कदम आवश्यक नहीं है। +सर्वर स्टार्टअप पर स्वचालित रूप से डेटाबेस माइग्रेशन चलाता है; कोई अलग migration चरण आवश्यक नहीं है। ### स्वास्थ्य जांच ``` -GET /health # liveness - हमेशा {"status":"ok"} एक बार प्रक्रिया ऊपर हो जाती है -GET /ready # readiness - 200 जब Postgres + ClickHouse पहुंचने योग्य हों, अन्यथा 503 +GET /health # liveness - हमेशा {"status":"ok"} एक बार प्रक्रिया ऊपर है +GET /ready # readiness - 200 जब Postgres + ClickHouse पहुंचने योग्य हैं, अन्यथा 503 ``` -कोई प्रमाणीकरण आवश्यक नहीं है। **liveness** प्रोब के लिए `/health` का उपयोग करें और **readiness** / लोड-बैलेंसर प्रोब के लिए `/ready` का उपयोग करें। `/ready` कठोर निर्भरताओं की जांच करता है जो सर्वर बिना सेवा नहीं कर सकता (Postgres + ClickHouse), तो एक सर्वर जो चल रहा है लेकिन अपने डेटाबेस तक नहीं पहुंच सकता, रोटेशन से बाहर निकाल दिया जाता है और `NotReady` के रूप में दिखाया जाता है; Redis की रिपोर्ट की जाती है लेकिन कभी readiness विफल नहीं करता। बंडल किए गए Kubernetes manifests पर readiness प्रोब पहले से `/ready` पर इंगित करता है और liveness `/health` पर रहता है। पूरी तस्वीर के लिए [enterprise-docs/health-monitoring.md](/hi/agenteye/health-monitoring) देखें, जिसमें Slack के लिए opt-in Kubernetes-मूल पॉड-विफलता सतर्कता शामिल है। +कोई प्रमाणीकरण आवश्यक नहीं है। **liveness** probes के लिए `/health` और **readiness** / load-balancer probes के लिए `/ready` का उपयोग करें। `/ready` उन कठोर निर्भरताओं की जांच करता है जो सर्वर बिना सेवा नहीं कर सकता (Postgres + ClickHouse), इसलिए एक सर्वर जो चल रहा है लेकिन अपने डेटाबेस तक नहीं पहुंच सकता है rotation से बाहर निकाला जाता है और `NotReady` के रूप में दिखाया जाता है; Redis रिपोर्ट किया जाता है लेकिन कभी readiness विफल नहीं करता। बंडल किए गए Kubernetes manifests पर readiness probe पहले से ही `/ready` की ओर इंगित करता है और liveness `/health` पर रहता है। पूर्ण चित्र के लिए देखें [enterprise-docs/health-monitoring.md](/hi/agenteye/health-monitoring), Slack को opt-in Kubernetes-native pod-failure अलर्टिंग सहित। -### ईमेल जादू-लिंक URL +### ईमेल magic-link URL -OTP लॉगिन ईमेल में एक एक-टैप **डैशबोर्ड खोलें** बटन होता है। इसे क्लिक करने से उपयोगकर्ता को `/login?token=&email=
` पर ले जाता है; डैशबोर्ड उस जोड़ी को एक सत्र के लिए विनिमय करता है और ऐप पर पुनः निर्देशित करता है, बिना किसी मैन्युअल कोड पुनः-प्रविष्टि के। सर्वर तीन स्तरों में डैशबोर्ड मूल का समाधान करता है: +OTP लॉगिन ईमेल में एक one-tap **डैशबोर्ड खोलें** बटन होता है। इस पर क्लिक करने से उपयोगकर्ता `/login?token=&email=
` पर आते हैं; डैशबोर्ड उस जोड़ी को एक सत्र के लिए विनिमय करता है और ऐप में पुनर्निर्देशित करता है, कोई manual code re-entry के साथ नहीं। सर्वर तीन स्तरों में लिंक बनाने के लिए उपयोग किए जाने वाले डैशबोर्ड मूल को हल करता है: -1. **`X-AgentEye-Dashboard-Url` हेडर**: डैशबोर्ड के `/api/auth/otp/request` प्रॉक्सी द्वारा अपने स्वयं के सार्वजनिक मूल से स्वचालित रूप से सेट। एक समान-मूल तैनाती में (सर्वर और डैशबोर्ड एक होस्ट साझा करते हैं एक इनग्रेस के पीछे जो प्रॉक्सी हेडर अग्रेषित करते हैं), **कोई कॉन्फ़िगरेशन आवश्यक नहीं है**। -2. **`DASHBOARD_URL` env var**: यदि आपका डैशबोर्ड सर्वर के OTP अनुरोध एंडपॉइंट से एक भिन्न मूल पर पहुंचने योग्य है (विभाजित `api.example.com` / `app.example.com`), या यदि आपका इनग्रेस डैशबोर्ड पॉड में सार्वजनिक होस्ट को प्रचार नहीं करता है (तो `request.nextUrl.origin` अन्यथा एक वाइल्डकार्ड बाइंड जैसे `0.0.0.0:3000` को हल करेगा)। उदाहरण: `DASHBOARD_URL=https://app.example.com`। -3. **डिफ़ॉल्ट**: `https://app.befailproof.ai`, केवल यदि उपरोक्त में से कोई भी मौजूद नहीं है तो उपयोग किया जाता है। +1. **`X-AgentEye-Dashboard-Url` हेडर**: डैशबोर्ड के अपने `/api/auth/otp/request` proxy द्वारा अपने स्वयं के सार्वजनिक मूल से स्वचालित रूप से सेट किया जाता है। एक same-origin परिनियोजन में (सर्वर और डैशबोर्ड एक होस्ट को साझा करते हैं जो proxy हेडर को forward करता है), **कोई कॉन्फ़िगरेशन आवश्यक नहीं है**। +2. **`DASHBOARD_URL` env var**: यदि आपका डैशबोर्ड एक अलग मूल पर पहुंचने योग्य है (विभाजन `api.example.com` / `app.example.com`), या यदि आपका ingress सार्वजनिक होस्ट को डैशबोर्ड pod में propagate नहीं करता (ताकि `request.nextUrl.origin` अन्यथा एक wildcard bind जैसे `0.0.0.0:3000` में हल करेगा)। उदाहरण: `DASHBOARD_URL=https://app.example.com`। +3. **Default**: `https://app.befailproof.ai`, केवल यदि उपरोक्त में से कोई भी मौजूद नहीं है। -हेडर मान सत्यापित किया जाता है: केवल `https://*` और loopback (`http://localhost*`, `http://127.0.0.1*`) मूल स्वीकृत हैं, और वाइल्डकार्ड बाइंड पते (`0.0.0.0`, `[::]`) `https://` स्कीम के साथ भी अस्वीकार किए जाते हैं। कुछ और स्तर 2 तक गिरता है। +हेडर मान सत्यापित किया जाता है: केवल `https://*` और loopback (`http://localhost*`, `http://127.0.0.1*`) मूल स्वीकार किए जाते हैं, और wildcard bind पते (`0.0.0.0`, `[::]`) को `https://` स्कीम के साथ भी अस्वीकार किया जाता है। कुछ और भी टियर 2 में पड़ता है। -एक चलंत क्लस्टर पर एक-लाइनर के साथ सेट करें; कोई फाइल नहीं, कोई kustomize पुनर्निर्माण नहीं: +एक-लाइनर के साथ एक चल रहे क्लस्टर पर इसे सेट करें; कोई फ़ाइल नहीं, कोई kustomize पुनर्निर्माण नहीं: ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -यह एक रोलआउट को ट्रिगर करता है; नए पॉड पहले अनुरोध पर मान को उठाते हैं। ध्यान दें कि ओवरराइड केवल Deployment पर रहता है; ओवरले के विरुद्ध `kustomize build | kubectl apply` का एक बाद का समन्वय इसे पोंछ देगा जब तक आप अपने ओवरले के `server-env.yaml` पैच में समान env var नहीं जोड़ते। +यह एक rollout ट्रिगर करता है; नई pods पहली अनुरोध पर मान उठाते हैं। ध्यान दें कि override केवल Deployment पर रहता है; `kustomize build | kubectl apply` के बाद के खिलाफ overlay को लागू करने से इसे मिटा दिया जाएगा जब तक आप अपने overlay के `server-env.yaml` patch को समान env var जोड़ते हैं। --- ## डैशबोर्ड -### इमेज खींचें +### छवि खींचें ```bash docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest @@ -168,14 +167,14 @@ docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest | चर | आवश्यक | डिफ़ॉल्ट | विवरण | |---|---|---|---| -| `AGENTEYE_SERVER_URL` | हाँ | कोई नहीं | सर्वर का आधार URL, उदाहरण के लिए `http://localhost:8080` | -| `AGENTEYE_API_KEY` | हाँ | कोई नहीं | API कुंजी डैशबोर्ड सर्वर के लिए प्रमाणीकृत करने के लिए उपयोग करता है। सभी अनुमतियों की आवश्यकता है (एडमिन कुंजी अनुशंसित)। | -| `AE_LOG_LEVEL` | नहीं | `info` | सर्वर-पक्ष लॉग विस्तार: `debug`, `info`, `warn`, `error`। मुद्दों का निदान करते समय अपस्ट्रीम-अनुरोध/प्रतिक्रिया लाइनें और सत्र-सत्यापन ट्रेस देखने के लिए `debug` पर सेट करें। | -| `AE_LOG_JSON` | नहीं | auto | `1` JSON-प्रति-लाइन आउटपुट को मजबूर करता है; `0` मानव-पठनीय आउटपुट को मजबूर करता है। जब अनिर्धारित है, तो `NODE_ENV=production` होने पर JSON स्वचालित रूप से सक्षम होता है। उत्पादन में JSON अनुशंसित है ताकि लॉग `jq` या लॉग एकत्रीकरण के साथ स्पष्ट रूप से पार्स हों। | -| `AE_ANALYTICS_DISABLED` | नहीं | कोई नहीं | डैशबोर्ड के गुमनाम उत्पाद-उपयोग टेलीमेट्री को अक्षम करने के लिए `1`/`true` पर सेट करें। नीचे [Telemetry & privacy](#telemetry--privacy) देखें। | -| `REDIS_URL` | नहीं | कोई नहीं | वैकल्पिक साझा कैश बैकएंड, उदाहरण के लिए `redis://redis:6379/0`। जब सेट किया जाता है, तो डैशबोर्ड प्रतिकृतियों में `validateSession()` परिणाम कैश करता है और latency-एकत्रित / env-list प्रॉक्सी मार्गों के लिए Next.js fetch कैश साझा करता है। Edge-side OTP अनुरोध और सत्यापन दर सीमाएं भी Redis का उपयोग करती हैं जब मौजूद हों (Redis अपहुंच योग्य होने पर खुली विफल; सर्वर-पक्ष सीमा सुरक्षा backstop है)। नीचे **Redis (वैकल्पिक कैश)** देखें। | -| `AGENTEYE_AGENT_URL` | नहीं | कोई नहीं | वैकल्पिक AI-सहायक `agent` सेवा का आधार URL, उदाहरण के लिए `http://agent:9100`। **इसे अनिर्धारित छोड़ें एजेंट को पूरी तरह से छिपाने के लिए**: कोई सहायक बुलबुला डैशबोर्ड में दिखाई नहीं देता। [enterprise-docs/assistant.md](/hi/agenteye/assistant) देखें। | -| `AGENTEYE_AGENT_TOKEN` | नहीं | कोई नहीं | साझा गुप्त डैशबोर्ड `agent` सेवा को प्रस्तुत करता है। एजेंट पर कॉन्फ़िगर किए गए `AGENTEYE_AGENT_TOKEN` से मेल खाना चाहिए। [enterprise-docs/assistant.md](/hi/agenteye/assistant) देखें। | +| `AGENTEYE_SERVER_URL` | हां | कोई नहीं | सर्वर का आधार URL, उदाहरण `http://localhost:8080` | +| `AGENTEYE_API_KEY` | हां | कोई नहीं | API कुंजी डैशबोर्ड सर्वर के लिए प्रमाणीकरण के लिए उपयोग करता है। सभी अनुमतियों की आवश्यकता है (admin key अनुशंसित)। | +| `AE_LOG_LEVEL` | नहीं | `info` | सर्वर-साइड लॉग verbosity: `debug`, `info`, `warn`, `error`। समस्याओं के निदान में upstream-request/response लाइनों और सत्र-validation ट्रेस को देखने के लिए `debug` पर सेट करें। | +| `AE_LOG_JSON` | नहीं | auto | `1` JSON-प्रति-लाइन आउटपुट को बाध्य करता है; `0` मानव-पठनीय आउटपुट को बाध्य करता है। जब सेट न हो, तो JSON स्वचालित रूप से सक्षम होता है यदि `NODE_ENV=production`। JSON उत्पादन में अनुशंसित है इसलिए लॉग `jq` या लॉग एकत्रक के साथ स्वच्छ रूप से parse करते हैं। | +| `AE_ANALYTICS_DISABLED` | नहीं | कोई नहीं | डैशबोर्ड के anonymous product-usage telemetry को अक्षम करने के लिए `1`/`true` पर सेट करें। नीचे [Telemetry & privacy](#telemetry--privacy) देखें। | +| `REDIS_URL` | नहीं | कोई नहीं | वैकल्पिक साझा कैश बैकएंड, उदाहरण `redis://redis:6379/0`। जब सेट किया जाता है, तो डैशबोर्ड प्रतिकृतियों में `validateSession()` परिणामों को कैश करता है और latency-aggregate / env-list proxy routes के लिए Next.js fetch cache को साझा करता है। Edge-साइड OTP अनुरोध और verify rate limits मौजूद होने पर भी Redis का उपयोग करते हैं (यदि Redis अप्राप्य है तो खुले में विफल; सर्वर-साइड सीमा security backstop है)। नीचे **Redis (वैकल्पिक कैश)** देखें। | +| `AGENTEYE_AGENT_URL` | नहीं | कोई नहीं | वैकल्पिक AI-सहायक `agent` सेवा का आधार URL, उदाहरण `http://agent:9100`। **इसे सहायक को पूरी तरह छिपाने के लिए सेट न करें**: डैशबोर्ड में कोई सहायक बुलबुला दिखाई नहीं देता। देखें [enterprise-docs/assistant.md](/hi/agenteye/assistant)। | +| `AGENTEYE_AGENT_TOKEN` | नहीं | कोई नहीं | साझा गुप्त डैशबोर्ड `agent` सेवा को प्रस्तुत करता है। एजेंट पर कॉन्फ़िगर किए गए `AGENTEYE_AGENT_TOKEN` से मेल खाना चाहिए। देखें [enterprise-docs/assistant.md](/hi/agenteye/assistant)। | ### चलाएं @@ -188,58 +187,146 @@ docker run -d --restart unless-stopped \ ghcr.io/agenteye-enterprise/dashboard:beta-latest ``` -### टेलीमेट्री और गोपनीयता +### Telemetry & privacy -डैशबोर्ड **गुमनाम उत्पाद-उपयोग विश्लेषण** Exosphere की विश्लेषण सेवा (PostHog) को भेजता है: कौन सी डैशबोर्ड पृष्ठ देखी जाती हैं और UI क्रियाओं की एक मुट्ठी जैसे API कुंजी बनाना या सत्र का पुनः मूल्यांकन करना। यह उपयोग संकेत सूचित करता है कि कौन सी विशेषताएं प्राथमिकता दी जाती हैं। +डैशबोर्ड **anonymous product-usage analytics** Exosphere की analytics सेवा (PostHog) को भेजता है: कौन से डैशबोर्ड पेज देखे जाते हैं और UI actions की एक मुट्ठी जैसे एक API key बनाना या एक सत्र का पुनः मूल्यांकन करना। यह उपयोग सिग्नल सूचित करता है कि कौन से features को प्राथमिकता दी जाती है। -- **कोई एजेंट, सत्र, या ईवेंट डेटा कभी आपके बुनियादी ढांचे को नहीं छोड़ता है।** केवल डैशबोर्ड UI उपयोग की रिपोर्ट की जाती है। पृष्ठ URL भेजने से पहले पहचानकर्ताओं को छीन लिया जाता है, और ऑपरेटरों को केवल एक अपारदर्शी आंतरिक id द्वारा पहचाना जाता है, कभी ईमेल द्वारा नहीं। -- टेलीमेट्री **डिफ़ॉल्ट रूप से सक्षम है**। इसे पूरी तरह से बंद करने के लिए, डैशबोर्ड कंटेनर पर `AE_ANALYTICS_DISABLED=1` सेट करें और पुनः शुरू करें। -- विश्लेषण डैशबोर्ड के अपने `/ingest` पथ पर भेजे जाते हैं, जो डैशबोर्ड PostHog (`https://us.i.posthog.com`) को रिवर्स-प्रॉक्सी करता है। अनुरोधों को प्रथम-पक्ष रखने का मतलब है ब्राउज़र विज्ञापन-अवरोधक उन्हें नहीं गिराते हैं। **डैशबोर्ड कंटेनर** को PostHog के लिए आउटबाउंड एक्सेस की आवश्यकता है; यदि यह अवरुद्ध है, तो टेलीमेट्री चुप से कुछ नहीं करता है और डैशबोर्ड प्रभावित नहीं होता है। +- **कोई एजेंट, सत्र, या ईवेंट डेटा कभी आपके infrastructure को नहीं छोड़ता।** केवल डैशबोर्ड UI उपयोग रिपोर्ट किया जाता है। पेज URLs भेजने से पहले identifiers से छीन दिए जाते हैं, और ऑपरेटरों को केवल एक opaque internal id द्वारा पहचाना जाता है, कभी ईमेल द्वारा नहीं। +- Telemetry **डिफ़ॉल्ट रूप से सक्षम है**। इसे पूरी तरह बंद करने के लिए, डैशबोर्ड कंटेनर पर `AE_ANALYTICS_DISABLED=1` सेट करें और पुनरारंभ करें। +- Analytics डैशबोर्ड के अपने `/ingest` पथ को भेजे जाते हैं, जो डैशबोर्ड PostHog को reverse-proxy करता है (`https://us.i.posthog.com`)। अनुरोधों को first-party रखना मतलब ब्राउज़र ad-blockers उन्हें नहीं छोड़ते। **डैशबोर्ड कंटेनर** को PostHog के लिए आउटबाउंड एक्सेस की आवश्यकता है; यदि यह अवरुद्ध है, तो telemetry चुप रहकर कुछ नहीं करता है और डैशबोर्ड अप्रभावित है। --- ## AI सहायक (वैकल्पिक) -एक इन-डैशबोर्ड AI सहायक आपकी टीम को उनके एजेंट डेटा के बारे में सादे भाषा में प्रश्न पूछने देता है (सत्रों को सारांशित करना, `/queries` संपादक के लिए SQL का मसौदा तैयार करना, और बचाए गए प्रश्नों को डैशबोर्ड टाइल में बदलना) डैशबोर्ड छोड़े बिना। यह Claude Agent SDK पर एक अलग आंतरिक `agent` कंटेनर के रूप में चलता है जो केवल डैशबोर्ड तक पहुंच सकता है, और **तब तक अक्षम रहता है जब तक आप एक LLM एंडपॉइंट कॉन्फ़िगर नहीं करते**। +एक in-dashboard AI सहायक आपकी टीम को उनके एजेंट डेटा को साधारण भाषा में (सत्र summarizing, `/queries` संपादक के लिए SQL का मसौदा तैयार करना, और सहेजे गए queries को डैशबोर्ड tiles में बदलना) डैशबोर्ड को छोड़े बिना सवाल पूछने देता है। यह एक अलग internal `agent` कंटेनर (Claude Agent SDK पर) के रूप में चलता है जो केवल डैशबोर्ड तक पहुंच सकता है, और **तब तक अक्षम रहता है जब तक आप एक LLM endpoint कॉन्फ़िगर नहीं करते**। -इसे सक्षम करने के लिए आप `agent` सेवा पर सेट करते हैं, एक LLM कनेक्शन (**Portkey** via `PORTKEY_API_KEY` + एक मॉडल-कैटलॉग स्लग `AGENTEYE_AGENT_MODEL=@/`, सीधे Anthropic via `ANTHROPIC_API_KEY`, दूसरा gateway via `ANTHROPIC_BASE_URL`, या Bedrock/Vertex), एक **समर्पित** डेटा कुंजी, और एक साझा `AGENTEYE_AGENT_TOKEN` डैशबोर्ड से मेल खाता है। डैशबोर्ड उपयोगकर्ताओं को अतिरिक्त रूप से `agent:use` अनुमति की आवश्यकता है। +इसे सक्षम करने के लिए आप `agent` सेवा पर, एक LLM कनेक्शन (**Portkey** via `PORTKEY_API_KEY` + एक model-catalog slug `AGENTEYE_AGENT_MODEL=@/`, direct Anthropic via `ANTHROPIC_API_KEY`, दूसरा gateway via `ANTHROPIC_BASE_URL`, या Bedrock/Vertex), एक **dedicated** डेटा key, और एक साझा `AGENTEYE_AGENT_TOKEN` मिलान डैशबोर्ड सेट करते हैं। डैशबोर्ड उपयोगकर्ताओं को अतिरिक्त रूप से `agent:use` अनुमति की आवश्यकता है। -सहायक की डेटा कुंजी के लिए आप किसी चीज़ को हाथ से टकसाल नहीं करते: एक यादृच्छिक गुप्त चुनें, इसे `AGENTEYE_API_KEY` के रूप में `agent` पर और `AGENT_API_KEY` के रूप में `server` पर सेट करें, और सर्वर स्टार्टअप पर एक निश्चित अनुमति सेट के साथ इसे बीज देता है। इसका डेटा पहुंच केवल-पढ़ने के लिए है (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), और यह अतिरिक्त रूप से अनुमोदन-गेटेड लेखन स्कोप धारण करता है (`dashboards:write`, `queries:write`, `queries:run`) इसलिए यह उपयोगकर्ता की ओर से बचाए गए प्रश्नों का मसौदा तैयार कर सकता है और डैशबोर्ड टाइल बना सकता है; सभी SQL अभी भी org के पढ़ने-मात्र ClickHouse भूमिका के माध्यम से चलता है, तो यह क्या सहायक लेख कर सकता है को चौड़ा करता है, डेटा तक पहुंच नहीं है। स्कोप कोड में निश्चित हैं और कॉन्फ़िगरेशन द्वारा चौड़ा नहीं किए जा सकते हैं। वह कुंजी संरक्षित है; इसे API के माध्यम से अक्षम या पुनः उत्पन्न नहीं किया जा सकता, केवल मान बदलकर और पुनः शुरू करके रोटेट किया जा सकता है। कभी इसके लिए admin/dashboard कुंजी का पुनः उपयोग न करें। +सहायक के डेटा key के लिए आप हाथ से कुछ भी mint नहीं करते: एक random secret चुनें, इसे `agent` पर `AGENTEYE_API_KEY` के रूप में और `server` पर `AGENT_API_KEY` के रूप में सेट करें, और सर्वर स्टार्टअप पर fixed permission set के साथ इसे seed करता है। इसका डेटा एक्सेस read-only है (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), और इसके अतिरिक्त approval-gated authoring scopes (`dashboards:write`, `queries:write`, `queries:run`) को होल्ड करता है ताकि यह उपयोगकर्ता की ओर से सहेजे गए queries का मसौदा तैयार और validate कर सकता है और डैशबोर्ड tiles बना सकता है; सभी SQL अभी भी org के read-only ClickHouse role के माध्यम से चलते हैं, इसलिए यह सहायक को क्या डेटा तक पहुंच सकता है, न कि क्या डेटा तक पहुंच सकता है, को चौड़ा करता है। scopes code में fixed हैं और configuration द्वारा चौड़ा नहीं किया जा सकता। वह key संरक्षित है; इसे API के माध्यम से अक्षम या regenerate नहीं किया जा सकता, केवल मान बदलकर और पुनरारंभ करके rotated किया जा सकता है। कभी admin/dashboard key को इसके लिए reuse न करें। -पूर्ण सेटअप, पूर्ण पर्यावरण-चर संदर्भ, टेलीमेट्री विकल्प, और सुरक्षा मॉडल **[enterprise-docs/assistant.md](/hi/agenteye/assistant)** में हैं। +पूर्ण सेटअप, पूर्ण environment-variable reference, telemetry विकल्प, और security model **[enterprise-docs/assistant.md](/hi/agenteye/assistant)** में हैं। --- ## ClickHouse (आवश्यक विश्लेषण स्टोर) -ClickHouse आपके डैशबोर्ड को उच्च ईवेंट मात्रा पर प्रतिक्रियाशील रखता है और `/queries` SQL संपादक को एक एकल स्टोर में ईवेंट, मूल्यांकन, और सत्रों में शामिल होने देता है। यह हर एक अंतर्ग्रहण किए गए ईवेंट, हर टर्मिनल मूल्यांकन परिणाम, और प्रति-सत्र एकत्रित के लिए आवश्यक प्रामाणिक स्टोर है। PostgreSQL संबंधपरक / परिवर्तनशील-स्थिति तालिकाएं धारण करता है (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); विश्लेषणात्मक सतह ClickHouse में रहती है ताकि डैशबोर्ड के रोलअप्स और आपके स्वयं के SQL प्रश्न इसे मूल रूप से स्कैन और शामिल कर सकें, बिना क्रॉस-डेटाबेस राउंड-ट्रिप के। सर्वर `CLICKHOUSE_URL` के बिना बूट करने से इनकार करता है। +ClickHouse आपके डैशबोर्ड को उच्च ईवेंट volume पर responsive रखता है और `/queries` SQL संपादक को events, evaluations, और sessions के across join करने देता है एक एकल store में। यह प्रत्येक ingested event, प्रत्येक terminal evaluation outcome, और derived per-session aggregates के लिए आवश्यक canonical store है। PostgreSQL relational / mutable-state tables को रखता है (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); analytical surface ClickHouse में रहता है ताकि डैशबोर्ड के rollups और आपके स्वयं के SQL queries बिना cross-database round-trips के नेटिवली स्कैन और join कर सकें। सर्वर `CLICKHOUSE_URL` के बिना बूट करने से इंकार करता है। ### स्कीमा -तीन ClickHouse ऑब्जेक्ट सर्वर स्टार्टअप पर बनाए जाते हैं, सभी idempotent (`CREATE IF NOT EXISTS`): +तीन ClickHouse objects सर्वर स्टार्टअप पर बनाए जाते हैं, सभी idempotent (`CREATE IF NOT EXISTS`): -- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, `toYYYYMM(ts)` द्वारा विभाजित, `(session_id, ts, dedup_key)` द्वारा क्रमित। नकली इनपुट (कलेक्टर पुनः प्रयास) मर्ज समय पर एक एकल पंक्ति में ढह जाते हैं; सर्वर हर ईवेंट के लिए एक निर्धारक SHA-256 `dedup_key` की गणना करता है इसलिए पुनः प्रयास सुरक्षित हैं। -- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, `toYYYYMM(finished_at)` द्वारा विभाजित, `(session_id, finished_at, dedup_key)` द्वारा क्रमित। मूल्यांकनकर्ता पाइपलाइन द्वारा प्रति टर्मिनल मूल्यांकन परिणाम एक बार लिखा गया। `events` के समान dedup-key मॉडल। -- **`agenteye.agent_sessions`**: `agenteye.events` पर एक **VIEW**, भौतिक तालिका नहीं। हर कॉलम व्युत्पन्न है (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, आदि)। कोई प्रति-ईवेंट अपसर्ट और कोई अलग बैकफिल नहीं; दृश्य स्वचालित रूप से जो कुछ भी `events` में प्रतिबिंबित होता है उसे प्रतिबिंबित करता है। +- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, `toYYYYMM(ts)` द्वारा विभाजित, `(session_id, ts, dedup_key)` द्वारा आदेशित। Duplicate inserts (collector retries) merge समय पर एक पंक्ति में collapse हो जाते हैं; सर्वर हर ईवेंट के लिए एक deterministic SHA-256 `dedup_key` computes करता है इसलिए retries सुरक्षित हैं। +- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, `toYYYYMM(finished_at)` द्वारा विभाजित, `(session_id, finished_at, dedup_key)` द्वारा आदेशित। प्रति terminal evaluation outcome evaluator pipeline द्वारा एक बार लिखा गया। `events` के समान dedup-key model। +- **`agenteye.agent_sessions`**: एक **VIEW** `agenteye.events` के over, एक भौतिक table नहीं। हर स्तंभ व्युत्पन्न है (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, आदि)। कोई per-event upsert और कोई अलग backfill नहीं; view auto-reflects जो कुछ भी `events` में है। -पुरानी संगतता के लिए बचाए गए प्रश्नों के साथ जो `analytics.evaluations` / `analytics.sessions` का संदर्भ देते हैं, सर्वर भी एक `analytics` ClickHouse डेटाबेस बनाता है `agenteye.*` तालिकाओं के दृश्य के साथ; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` सभी सही तरीके से समाधान करते हैं। +saved queries के साथ backwards-compat के लिए जो `analytics.evaluations` / `analytics.sessions` को reference करते हैं, सर्वर एक `analytics` ClickHouse database भी बनाता है `agenteye.*` tables के over views के साथ; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` सभी सही तरीके से resolve करते हैं। ### कॉन्फ़िगरेशन -बंडल किए गए docker-compose और `deploy/base/clickhouse/` एक ClickHouse सेवा के साथ AgentEye के कार्य के लिए ट्यून किए गए: +बंडल किया गया docker-compose और `deploy/base/clickhouse/` AgentEye के workload के लिए ट्यून किए गए एक ClickHouse सेवा को शिप करते हैं: -- 2 GiB अनुरोधित / 4 GiB सीमा मेमोरी शिप किए गए बेस ओवरले में (छोटे POC/staging नोड्स में फिट करने के आकार की); उत्पादन ग्राहकों को ओवरले करना चाहिए — अनुशंसित फर्श 2c / 4Gi अनुरोध, 6c / 8Gi सीमा है। `max_server_memory_usage_to_ram_ratio=0.9` -- 5 GiB मार्क कैश + 8 GiB असंपीड़ित कैश +- 2 GiB requested / 4 GiB limit memory shipped base overlay में (छोटे POC/staging nodes को fit करने के आकार का); production customers को overlay up करना चाहिए — recommended floor 2c / 4Gi request, 6c / 8Gi limit है। `max_server_memory_usage_to_ram_ratio=0.9` +- 5 GiB mark cache + 8 GiB uncompressed cache - `background_pool_size=16`, `background_merges_mutations_concurrency_ratio=2` - MergeTree: `parts_to_throw_insert=3000`, `parts_to_delay_insert=1500`, `non_replicated_deduplication_window=1000` -- `local_io_method=auto` (समर्थित कर्नेल पर io_uring) -- `fsync_metadata=0`: कम से कम-एक बार अंतर्ग्रहण + ReplacingMergeTree dedup के कारण स्वीकार्य -- `query_log` 30-दिन TTL के साथ सक्षम; `query_thread_log` हटाया गया (उच्च QPS पर महंगा) -- `max_execution_time=30` उपयोगकर्ता-पक्ष प्रश्नों के लिए -- StatefulSet टेम्पलेट पर 100 GiB PVC (ग्राहक ओवरले उत्पादन के लिए एक तेज़ SSD स्टोरेज क्लास को ओवरराइड करना चाहिए) +- `local_io_method=auto` (supported kernels पर io_uring) +- `fsync_metadata=0`: at-least-once ingest + ReplacingMergeTree dedup के कारण स्वीकार्य +- `query_log` enabled 30-day TTL के साथ; `query_thread_log` removed (high QPS पर महंगा) +- `max_execution_time=30` user-साइड queries के लिए +- StatefulSet template पर 100 GiB PVC (customer overlays को production के लिए fast SSD storage class में override करना चाहिए) ### बैकअप -आपका संपूर्ण डेटासेट रात भर एक एकल पुनर्स्थापन योग्य संग्रह में कैप्चर किया जाता है, इसलिए एक क्लस्टर या स्टोरेज नुकसान पुनर्प्राप्त होता है। ClickHouse स्वचालित रूप से दैनिक `agenteye-backup` CronJob द्वारा बैक किया जाता है, जो एक पास में PostgreSQL और ClickHouse दोनों को डंप करता है। ClickHouse इसके HTTP API पर पढ़ा जाता है: `agenteye.events` और `agenteye.evaluations` ClickHouse-मूल प्रारूप में डंप किए जाते हैं (दृश्य और पंक्ति नीतियां सर्वर द्वारा स्टार्टअप पर पुनः बनाई जाती हैं, इसलिए तालिका डेटा पूरी तस्वीर है) और Postgres डंप के साथ एक एकल संपीड़ित संग्रह में बंडल किया जाता है आपके ऑब्जेक्ट स्टोरेज में अपलोड किया गया। +आपकी पूरी dataset एक एकल restorable archive में nightly कैप्चर की जाती है, इसलिए एक cluster या storage loss recoverable है। ClickHouse को स्वचालित रूप से daily `agenteye-backup` CronJob द्वारा backed up किया जाता है, जो एक pass में PostgreSQL और ClickHouse दोनों को dumps करता है। ClickHouse को इसके HTTP API के over पढ़ा जाता है: `agenteye.events` और `agenteye.evaluations` ClickHouse-native format में dumped होते हैं (views और row policies सर्वर स्टार्टअप पर recreate किए जाते हैं, इसलिए table data पूरी तस्वीर है) और Postgres dump के साथ एक एकल compressed archive में bundled आपकी object storage में uploaded। -गंतव्य बाल्टी और क्लाउड क्रेडेंशियल ओवरले के अनुसार कॉन्फ़िगर किए जा \ No newline at end of file +गंतव्य bucket और cloud credentials प्रति overlay कॉन्फ़िगर किए जाते हैं। upload configuration और restore steps के लिए देखें [enterprise-docs/kubernetes-deployment.md](/hi/agenteye/kubernetes-deployment) की **Backups** section। + +--- + +## Redis (वैकल्पिक कैश) + +Redis एक **वैकल्पिक** साझा कैश + दर-सीमा बैकएंड है जो सर्वर और डैशबोर्ड द्वारा उपयोग किया जाता है। Redis deployed और दोनों सेवाओं पर `REDIS_URL` सेट के साथ: + +- **सर्वर** authenticated API-key lookups, `/events/environments` + `/evaluations/environments` lists, `/events/latency_aggregate` rollup (सबसे भारी query डैशबोर्ड polls करता है), `/sessions` list को कैश करता है, और OTP-request rate limiting को Postgres `COUNT(*)` से Redis `INCR + EXPIRE` में स्विच करता है। +- **डैशबोर्ड** `validateSession()` परिणामों को कैश करता है ताकि एक typical page load जो 10-20 authed API calls issues करता है वह सभी एक upstream सत्र जांच साझा करते हैं। यह Dashboard edge पर OTP-request और OTP-verify को भी rate-limit करता है। + +**दोनों सेवाएं gracefully downgrade करते हैं यदि Redis अप्राप्य है।** हर कैश कॉल एक bounded timeout के भीतर `Err` लौटाता है और caller सत्य के स्रोत में fallback करता है (सर्वर पर Postgres, डैशबोर्ड पर upstream Rust server)। OTP rate limiting सर्वर पर Postgres `COUNT(*)` पथ में fallback करता है (security property संरक्षित है); डैशबोर्ड का edge OTP limit जबकि सर्वर-साइड limit अभी भी holds fail open करता है। Redis down होना latency को downgrade करता है, correctness को नहीं। + +### कॉन्फ़िगरेशन + +docker-compose bundle पहले से ही एक Redis सेवा को शामिल करता है और `REDIS_URL=redis://redis:6379/0` को सर्वर और डैशबोर्ड में wires करता है। एक external Redis का उपयोग करने के लिए, `REDIS_URL` को अपने endpoint में सेट करें और compose file से `redis` service को हटा दें। + +### मेमोरी + persistence + +बंडल किया गया Redis image `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru` के साथ चलता है। AOF persistence मतलब cache container restarts से survive करता है; `everysec` सही durability/perf balance है क्योंकि cache writes के last second को खोना harmless है। LRU eviction मेमोरी growth को cap करता है। + +### कब Redis को deploy न करें + +- Single-instance dev/QA। सर्वर पर in-process caches अकेले per-replica benefit के अधिकांश को deliver करते हैं; Redis एक cross-replica sharing जोड़ता है जो single-instance setups को नहीं चाहिए। +- Air-gapped installs जहां एक service अधिक चलाने का operational cost latency win से outweigh करता है। + +--- + +## Docker Compose (अनुशंसित) + +एक `docker-compose.yml` `agenteye-enterprise/releases` repo में उपलब्ध है। यह एक एकल कमांड के साथ Postgres, सर्वर, और डैशबोर्ड को up करता है। + +```bash +GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ + --repo agenteye-enterprise/releases \ + --pattern 'docker-compose.yml' \ + --dir ./agenteye +cd agenteye +``` + +**`.env` के माध्यम से defaults को override करें:** + +``` +# URL-safe पासवर्ड का उपयोग करें (कोई /, +, या = characters नहीं)। +# Generate करें: openssl rand -hex 24 +POSTGRES_PASSWORD=your-db-password +ADMIN_KEY=your-admin-secret + +# डैशबोर्ड प्रमाणीकरण +ADMIN_EMAIL=admin@yourcompany.com +ALLOWED_EMAILS=*@yourcompany.com + +# OTP emails के लिए SMTP (OTP codes को stdout में log करने के लिए omit करें) +# SMTP_HOST=smtp.yourprovider.com +# SMTP_PORT=587 +# SMTP_USERNAME=your-smtp-user +# SMTP_PASSWORD=your-smtp-password +# SMTP_FROM=noreply@yourcompany.com + +RUST_LOG=info +``` + +```bash +docker compose up -d +``` + +**रोकें (डेटा volume को रखता है):** + +```bash +docker compose down +``` + +**रोकें और सभी डेटा को wipe करें:** + +```bash +docker compose down -v +``` + +--- + +## ऑपरेशनल सेटिंग्स + +एक छोटा सेट operational knobs जो env vars द्वारा pinned हुआ करते थे अब dashboard के **`//settings`** पृष्ठ से प्रति organization संपादन योग्य हैं; प्रत्येक org अपनी configure करता है। परिवर्तन कुछ सेकंड के भीतर effect लेते हैं, restart और redeploy के बिना। + +| सेटिंग | Bootstrap env var | इसे क्या नियंत्रित करता है | +|---|---|---| +| Allowed साइन-इन | `ALLOWED_EMAILS` | ईमेल (या `*@domain.com` wildcards) OTP प्राप्त करने और उपयोगकर्ताओं के रूप में जोड़े जाने की अनुमति | +| Default user अनुमतियां | `DEFAULT_USER_PERMISSIONS` | जब एक admin **+ new user** खोलता है तो Comma-separated permission tokens प्रीसिलेक्ट किए जाते हैं। प्रत्येक token [API key permissions](/hi/agenteye/api-keys) के तहत listed strings में से एक होना चाहिए। डिफ़ॉल्ट `standard` preset: read-only access plus everyday on-call actions (trigger re-evaluations, run queries, ack incidents, use the assistant)। | +| Session जीवनकाल | `SESSION_TTL_SECS` | डैशबोर्ड login कितने समय valid रहता है इससे पहले re-auth। डैशबोर्ड हर 5 सेकंड upstream session को फिर से जांचता है, इस \ No newline at end of file diff --git a/docs/hi/agenteye/getting-started.mdx b/docs/hi/agenteye/getting-started.mdx index 19a4cc28..1f9c2dd5 100644 --- a/docs/hi/agenteye/getting-started.mdx +++ b/docs/hi/agenteye/getting-started.mdx @@ -1,35 +1,36 @@ --- +--- title: "AgentEye के साथ शुरुआत करें" -description: "AgentEye के साथ शुरुआत करने का दस्तावेज़।" +description: "AgentEye के साथ शुरुआत करें — AgentEye दस्तावेज़।" --- -यह गाइड आपको एक संपूर्ण AgentEye सेटअप के माध्यम से ले जाता है: सर्वर और डैशबोर्ड को तैनात करना, एजेंट मशीन पर कलेक्टर स्थापित करना, और अपने Python एजेंट कोड को उपकरण से सुसज्जित करना। +यह गाइड आपको एक पूर्ण AgentEye सेटअप के माध्यम से ले जाती है: सर्वर और डैशबोर्ड को तैनात करना, एजेंट मशीन पर कलेक्टर इंस्टॉल करना, और आपके Python एजेंट कोड को स्ट्रूमेंट करना। --- ## AgentEye क्या है? -AgentEye एक **AI एजेंट्स के लिए स्व-होस्टेड अवलोकनशीलता और मूल्यांकन प्लेटफॉर्म** है। यह रिकॉर्ड करता है कि आपके एजेंट्स क्या करते हैं — एक रन का हर चरण — और स्वचालित रूप से प्रत्येक पूर्ण रन की गुणवत्ता को स्कोर करता है, ताकि आप देख सकें कि आपके एजेंट्स प्रोडक्शन में कैसे व्यवहार करते हैं और अपने उपयोगकर्ताओं से पहले रिग्रेशन पकड़ सकें। +AgentEye एक **AI एजेंट्स के लिए स्व-होस्टेड ऑब्जर्वेबिलिटी और मूल्यांकन प्लेटफॉर्म** है। यह रिकॉर्ड करता है कि आपके एजेंट्स क्या करते हैं — एक रन का प्रत्येक कदम — और पूर्ण रन की गुणवत्ता को स्वचालित रूप से स्कोर करता है, ताकि आप देख सकें कि आपके एजेंट्स प्रोडक्शन में कैसे व्यवहार करते हैं और आपके उपयोगकर्ताओं से पहले रिग्रेशन को पकड़ सकें। -डेटा एक दिशा में बहता है: आपका एजेंट कोड **Python SDK** के माध्यम से **ईवेंट्स** उत्सर्जित करता है → एक हल्का **कलेक्टर** डेमन उन्हें बैच करता है और **सर्वर** को भेजता है → ईवेंट्स और विश्लेषण **ClickHouse** में संग्रहीत होते हैं (संगठन, उपयोगकर्ता, API कुंजी, डैशबोर्ड और सहेजी गई क्वेरीज़ जैसी परिचालन स्थिति **Postgres** में रहती है) → आप **डैशबोर्ड** में सब कुछ खोजते हैं। +डेटा एक दिशा में प्रवाहित होता है: आपका एजेंट कोड **Python SDK** के माध्यम से **events** उत्सर्जित करता है → एक हल्का **collector** डेमॉन उन्हें बैच करता है और **server** को भेजता है → events और विश्लेषण **ClickHouse** में संग्रहीत होते हैं (संगठन, उपयोगकर्ता, API कुंजियाँ, डैशबोर्ड, और सहेजी गई क्वेरीज़ जैसी संचालनात्मक स्थिति **Postgres** में रहती है) → आप **dashboard** में सब कुछ explore करते हैं। -आप क्या पाते हैं: +आपको क्या मिलता है: -- **ईवेंट्स** — हर एजेंट रन का कच्चा, प्रति-चरण ट्रेल (टूल कॉल्स, मॉडल कॉल्स, हुक्स, त्रुटियां)। -- **सेशन्स** — वे ईवेंट्स एक पंक्ति में रोल किए गए, प्रत्येक **स्वचालित रूप से मूल्यांकित** और स्कोर किया गया। -- **मूल्यांकन** — आपकी अपनी मूल्यांकनकर्ता सेवाओं द्वारा उत्पादित गुणवत्ता स्कोर, ताकि गुणवत्ता में गिरावट मैनुअल समीक्षा के बिना सामने आए। -- **क्वेरीज़ और डैशबोर्ड्स** — आपके डेटा पर सहेजी गई ClickHouse SQL, साझा, संगठन-स्कोप्ड डैशबोर्ड्स में चार्ट किए गए। -- **अलर्ट्स और इंसिडेंट्स** — थ्रेसहोल्ड नियम जो आपको पेज करते हैं (ईमेल, Slack, वेबहुक, डैशबोर्ड-इन) साथ ही उन्हें ट्रायएज करने के लिए एक इंसिडेंट वर्कफ़्लो। -- **CLI और AI असिस्टेंट** — एक टर्मिनल क्लाइंट (`agenteye`) और एक डैशबोर्ड-इन असिस्टेंट सादे अंग्रेजी में प्रश्न पूछने के लिए। +- **Events** — हर एजेंट रन का कच्चा, प्रति-कदम ट्रेल (टूल कॉल्स, मॉडल कॉल्स, हुक्स, एरर्स)। +- **Sessions** — वे events एक रो में रोल अप किए गए, प्रत्येक **स्वचालित रूप से मूल्यांकित** और स्कोर किया गया। +- **Evaluations** — आपकी अपनी मूल्यांकनकर्ता सेवाओं द्वारा उत्पादित गुणवत्ता के स्कोर, ताकि गुणवत्ता में गिरावट मैनुअल रिव्यू के बिना सामने आए। +- **Queries & dashboards** — आपके डेटा पर सहेजी गई ClickHouse SQL, साझा, संगठन-स्कोपड डैशबोर्ड में चार्ट किया गया। +- **Alerts & incidents** — थ्रेशहोल्ड नियम जो आपको पेज करते हैं (ईमेल, Slack, webhook, इन-डैशबोर्ड) साथ ही उन्हें ट्रिएज करने के लिए एक incident वर्कफ़्लो। +- **CLI & AI assistant** — एक टर्मिनल क्लायंट (`agenteye`) और एक इन-डैशबोर्ड असिस्टेंट सादा अंग्रेजी में प्रश्न पूछने के लिए। -आप इसे अपने स्वयं के बुनियादी ढांचे में चलाते हैं, एक एकल Docker Compose स्टैक के रूप में (यह गाइड), एक प्रोडक्शन Kubernetes इंस्टॉल, या एक एकल सह-स्थित पॉड। इस गाइड का बाकी हिस्सा Compose स्टैक को अंत तक सेट अप करता है। +आप इसे सब अपने स्वयं के इन्फ्रास्ट्रक्चर में चलाते हैं, एक एकल Docker Compose स्टैक (यह गाइड), एक प्रोडक्शन Kubernetes इंस्टॉल, या एक एकल सह-स्थित पॉड के रूप में। इस गाइड का बाकी हिस्सा Compose स्टैक को end-to-end सेट अप करता है। --- ## चरण 1: प्रमाणीकरण करें -सभी AgentEye कलाकृतियां `agenteye-enterprise` GitHub संगठन से वितरित की जाती हैं। एक एंटरप्राइज़ डेवलपर के रूप में आप अपनी स्वयं की GitHub PAT उत्पन्न कर सकते हैं। सटीक चरणों और आवश्यक अनुमतियों के लिए [enterprise-docs/github-token.md](/hi/agenteye/github-token) फॉलो करें। +सभी AgentEye artifacts `agenteye-enterprise` GitHub संगठन से वितरित किए जाते हैं। एक enterprise developer के रूप में आप अपना स्वयं का GitHub PAT बना सकते हैं। सटीक चरणों और आवश्यक अनुमतियों के लिए [enterprise-docs/github-token.md](/hi/agenteye/github-token) का अनुसरण करें। ```bash export AGENTEYE_TOKEN= @@ -40,11 +41,11 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin --- -## चरण 2: सर्वर और डैशबोर्ड को तैनात करें +## चरण 2: सर्वर और डैशबोर्ड तैनात करें -सर्वर कलेक्टर्स से ईवेंट्स प्राप्त करता है और उन्हें क्वेरीयोग्य बनाता है; डैशबोर्ड वह जगह है जहां आप उन्हें खोजते हैं। अंतर्ग्रहित ईवेंट्स और विश्लेषण ClickHouse में रहते हैं (आवश्यक विश्लेषण स्टोर), जबकि Postgres संगठन, उपयोगकर्ता, API कुंजी, डैशबोर्ड और सहेजी गई क्वेरीज़ जैसी परिचालन स्थिति रखता है। +सर्वर कलेक्टर से events प्राप्त करता है और उन्हें query योग्य बनाता है; डैशबोर्ड वह जगह है जहाँ आप उन्हें explore करते हैं। Ingested events और विश्लेषण ClickHouse (आवश्यक विश्लेषण स्टोर) में रहते हैं, जबकि Postgres संगठन, उपयोगकर्ता, API कुंजियाँ, डैशबोर्ड, और सहेजी गई क्वेरीज़ जैसी संचालनात्मक स्थिति रखता है। -**प्रकाशित कंपोज़ फ़ाइल डाउनलोड करें:** +**प्रकाशित compose फ़ाइल डाउनलोड करें:** ```bash mkdir -p ./agenteye @@ -55,38 +56,32 @@ curl -fsSL \ cd agenteye ``` -**अपने रहस्य सेट करें:** +**अपने secrets सेट करें:** -एक `.env` फ़ाइल बनाएं ताकि डिप्लॉयमेंट डिफॉल्ट `admin` क्रेडेंशियल पर न चले। कम से कम `ADMIN_KEY` और `POSTGRES_PASSWORD` सेट करें: +एक `.env` फ़ाइल बनाएँ ताकि तैनाती डिफ़ॉल्ट `admin` क्रेडेंशियल पर न चले। कम से कम `ADMIN_KEY` और `POSTGRES_PASSWORD` सेट करें: ```bash POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -अपनी वर्तमान शेल में `ADMIN_KEY` को भी एक्सपोर्ट करें ताकि बाद के चरण (उदाहरण के लिए स्टेप 3 `curl`) इसे सीधे संदर्भित कर सकें: - -```bash -export ADMIN_KEY=your-admin-secret -``` - **स्टैक शुरू करें:** ```bash docker compose up -d ``` -यह पूरे स्टैक को ऊपर लाता है, जिसमें आवश्यक ClickHouse विश्लेषण स्टोर और एक वैकल्पिक Redis कैश शामिल है, सर्वर और डैशबोर्ड के साथ। ClickHouse को स्वस्थ होना चाहिए ताकि सर्वर शुरू हो सके। +यह पूर्ण स्टैक लाता है, जिसमें आवश्यक ClickHouse विश्लेषण स्टोर और एक वैकल्पिक Redis कैश भी शामिल है, सर्वर और डैशबोर्ड के साथ। ClickHouse को स्वस्थ होना चाहिए ताकि सर्वर शुरू हो सके। सर्वर अब `http://localhost:8080` पर सुन रहा है और डैशबोर्ड `http://localhost:3000` पर है। -प्रोडक्शन डिप्लॉयमेंट के लिए (कस्टम Postgres, TLS, रिवर्स प्रॉक्सी), [enterprise-docs/deployment.md](/hi/agenteye/deployment) देखें। +प्रोडक्शन तैनातियों के लिए (कस्टम Postgres, TLS, reverse proxy), [enterprise-docs/deployment.md](/hi/agenteye/deployment) देखें। --- -## चरण 3: कलेक्टर के लिए API कुंजी बनाएं +## चरण 3: कलेक्टर के लिए एक API Key बनाएँ -प्रत्येक कलेक्टर एक स्कोप्ड API कुंजी के साथ प्रमाणित करता है। स्टेप 2 में सेट की गई `ADMIN_KEY` का उपयोग करके एक बनाएं: +प्रत्येक कलेक्टर एक scoped API key के साथ प्रमाणीकरण करता है। चरण 2 में सेट करें `ADMIN_KEY` का उपयोग करके एक बनाएँ: ```bash curl -s -X POST http://localhost:8080/keys \ @@ -95,15 +90,15 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -आप `key` मान को स्वयं प्रदान करते हैं; स्टेप 4 में कलेक्टर कॉन्फ़िग में इसका उपयोग करें। पूर्ण कुंजी प्रबंधन के लिए [enterprise-docs/api-keys.md](/hi/agenteye/api-keys) देखें। +आप `key` value स्वयं प्रदान करते हैं; चरण 4 में कलेक्टर कॉन्फ़िग में इसका उपयोग करें। पूर्ण key प्रबंधन के लिए [enterprise-docs/api-keys.md](/hi/agenteye/api-keys) देखें। --- -## चरण 4: कलेक्टर स्थापित करें +## चरण 4: कलेक्टर इंस्टॉल करें -हर मशीन पर जो आपके AI एजेंट्स को चलाती है, कलेक्टर डेमन स्थापित करें। +आपके AI एजेंट्स चलाने वाली हर मशीन पर कलेक्टर डेमॉन इंस्टॉल करें। -**बाइनरी डाउनलोड करें (Linux x86_64):** +**बायनरी डाउनलोड करें (Linux x86_64):** ```bash VERSION=0.0.1-beta.13 @@ -114,7 +109,7 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> यह **Linux x86_64** बिल्ड डाउनलोड करता है। macOS (Apple Silicon या Intel), Linux arm64, या Docker/systemd/launchd सेटअप के लिए, [collector-installation.md](/hi/agenteye/collector-installation) देखें, जो प्रत्येक प्लेटफॉर्म के लिए डाउनलोड की सूची देता है — ऊपर दिया गया कमांड एक Linux बाइनरी स्थापित करता है जो अन्य जगहों पर नहीं चलेगा। +> यह **Linux x86_64** बिल्ड डाउनलोड करता है। macOS (Apple Silicon या Intel), Linux arm64, या Docker / systemd / launchd सेटअप के लिए, [collector-installation.md](/hi/agenteye/collector-installation) देखें, जो प्रत्येक प्लेटफॉर्म के लिए डाउनलोड सूचीबद्ध करता है — ऊपर दिया गया कमांड एक Linux बायनरी इंस्टॉल करता है जो कहीं और नहीं चलेगी। **कॉन्फ़िगर करें:** @@ -128,25 +123,25 @@ cat > ~/.agenteye/config.json </…`)। +Events के साथ flowing, **analyze** पृष्ठ कच्ची activity को answers में बदलते हैं, ताकि आप एजेंट व्यवहार मापें, पूरी टीम में निष्कर्ष साझा करें, और क्षण भर कुछ regresses होने पर paged हों। Dashboard पृष्ठ organization-scoped हैं, इसलिए जो URLs आप address bar में देखते हैं वह आपके org slug (`//…`) के साथ prefixed हैं। -- **क्वेरीज़** (`//queries`): अपनी ईवेंट्स और मूल्यांकन पर सहेजी गई, पुनः उपयोग योग्य क्वेरीज़ की एक लाइब्रेरी से शुरू करें (बिल्ट-इन प्रीसेट्स साथ ही आपकी अपनी)… +- **Queries** (`//queries`): saved, reusable queries के एक library से शुरू करें अपने events और evaluations के ऊपर (built-in presets प्लस आपके अपने)… -![सहेजी गई-क्वेरीज़ लाइब्रेरी: पुनः उपयोग योग्य क्वेरीज़ का एक ग्रिड, बिल्ट-इन प्रीसेट्स और कस्टम दोनों](/agenteye/images/queries.png) +![saved-queries library: reusable queries का एक grid, built-in presets और custom दोनों](/agenteye/images/queries.png) - …फिर एक को SQL कम्पोजर में खोलें इसे ट्वीक करने और लाइव परिणामों के साथ चलाने के लिए: + …फिर एक को SQL composer में खोलें इसे tweak करने और live results के साथ चलाने के लिए: -![SQL क्वेरी कम्पोजर एक सहेजी गई क्वेरी चला रहा है, स्कीमा साइडबार और एक लाइव परिणाम ग्रिड के साथ](/agenteye/images/query-lab.png) +![SQL query composer एक saved query चला रहा है, एक schema sidebar और एक live result grid के साथ](/agenteye/images/query-lab.png) -- **डैशबोर्ड्स** (`//dashboards`): क्वेरीज़ को लाइन, बार, एरिया या पाई टाइल्स के रूप में साझा, संगठन-व्यापी डैशबोर्ड्स में पिन करें। +- **Dashboards** (`//dashboards`): queries को line, bar, area, या pie tiles के रूप में shared, org-wide dashboards में pin करें। -![एक डैशबोर्ड सहेजी गई क्वेरीज़ से बनाया गया: एक प्रति-घंटा लाइन, एक त्रुटि-दर-प्रकार बार, एक लेटेंसी एरिया चार्ट और टोकन-प्रति-मॉडल](/agenteye/images/dashboard-fleet.png) +![एक dashboard saved queries से बनाया गया: एक events-per-hour line, एक errors-by-type bar, एक latency area chart, और tokens-by-model](/agenteye/images/dashboard-fleet.png) -- **अलर्ट्स** (`//alerts`): किसी भी थ्रेसहोल्ड को एक पेजिंग नियम में प्रोन्नत करें जो ईमेल, Slack, वेबहुक या डैशबोर्ड-इन द्वारा सूचित करता है। [enterprise-docs/alerts.md](/hi/agenteye/alerts) देखें। +- **Alerts** (`//alerts`): किसी भी threshold को एक paging rule में promote करें जो email, Slack, webhook, या in-dashboard द्वारा notify करती है। [enterprise-docs/alerts.md](/hi/agenteye/alerts) देखें। --- -## अगले चरण +## अगले कदम -- [डिप्लॉयमेंट](/hi/agenteye/deployment): प्रोडक्शन के लिए कठोर करें -- [API कुंजियां](/hi/agenteye/api-keys): एक्सेस प्रबंधित करें -- [समस्या निवारण](/hi/agenteye/troubleshooting): समस्याओं का निदान करें \ No newline at end of file +- [Deployment](/hi/agenteye/deployment): प्रोडक्शन के लिए harden करें +- [API Keys](/hi/agenteye/api-keys): access प्रबंधित करें +- [Troubleshooting](/hi/agenteye/troubleshooting): issues diagnose करें \ No newline at end of file diff --git a/docs/hi/agenteye/managed-deployment.mdx b/docs/hi/agenteye/managed-deployment.mdx index a0ad07b5..80145574 100644 --- a/docs/hi/agenteye/managed-deployment.mdx +++ b/docs/hi/agenteye/managed-deployment.mdx @@ -1,19 +1,18 @@ --- ---- -title: "आपके Kubernetes क्लस्टर पर प्रबंधित परिनियोजन" -description: "आपके Kubernetes क्लस्टर पर AgentEye प्रबंधित परिनियोजन दस्तावेज़।" +title: "आपके Kubernetes क्लस्टर पर प्रबंधित स्थापना" +description: "आपके Kubernetes क्लस्टर पर AgentEye प्रबंधित स्थापना दस्तावेज़।" --- -AgentEye एक स्व-होस्ट किया गया अवलोकनशीलता और मूल्यांकन मंच है AI और LLM एजेंट्स के लिए। यह एजेंट सेशन, टूल कॉल, मॉडल अनुरोध और त्रुटियों को कैप्चर करता है, उन्हें खोजने योग्य विश्लेषण और मूल्यांकन में बदल देता है, और परिणामों को एक डैशबोर्ड में प्रदर्शित करता है जिसमें एक वैकल्पिक केवल-पढ़ने के लिए AI सहायक होता है। +AgentEye एक self-hosted अवलोकनीयता और मूल्यांकन प्लेटफॉर्म है जो AI और LLM एजेंटों के लिए डिज़ाइन किया गया है। यह एजेंट सेशन, टूल कॉल, मॉडल अनुरोध और त्रुटियों को कैप्चर करता है, उन्हें खोजने योग्य विश्लेषण और मूल्यांकन में परिवर्तित करता है, और परिणामों को एक डैशबोर्ड में प्रदर्शित करता है जिसमें एक वैकल्पिक read-only AI सहायक है। -प्रबंधित परिनियोजन मॉडल में, आप एक समर्पित Kubernetes क्लस्टर प्रदान करते हैं और Exosphere इसके अंदर पूरा मंच चलाता है, आपकी ओर से हर घटक को परिनियोजित, कॉन्फ़िगर, संचालित, बैकअप और अपग्रेड करता है। आपकी टीम को प्लेटफॉर्म का मूल्य मिलता है (एजेंट दृश्यता, विश्लेषण, मूल्यांकन, और वैकल्पिक सहायक) डेटाबेस, प्रमाणपत्र या अपग्रेड संचालित किए बिना। सभी डेटा आपके क्लाउड खाते के भीतर रहता है। +प्रबंधित स्थापना मॉडल में, आप एक समर्पित Kubernetes क्लस्टर प्रदान करते हैं और Exosphere पूरे प्लेटफॉर्म को इसके अंदर चलाता है, आपकी ओर से हर घटक को स्थापित करता है, कॉन्फ़िगर करता है, संचालित करता है, बैकअप लेता है और अपग्रेड करता है। आपकी टीम को प्लेटफॉर्म का मूल्य (एजेंट दृश्यता, विश्लेषण, मूल्यांकन और वैकल्पिक सहायक) मिलता है बिना डेटाबेस, प्रमाणपत्र या अपग्रेड का संचालन किए। सभी डेटा आपके क्लाउड खाते में रहता है। --- -## पूर्वापेक्षाएं +## आवश्यक शर्तें -- एक **GitHub PAT** कंटेनर इमेज खींचने और आर्टिफैक्ट डाउनलोड करने के लिए ([GitHub Token सेटअप](/hi/agenteye/github-token) देखें) +- कंटेनर इमेज खींचने और आर्टिफैक्ट डाउनलोड करने के लिए एक **GitHub PAT** (देखें [enterprise-docs/github-token.md](/hi/agenteye/github-token)) - एक **समर्पित Kubernetes क्लस्टर** (नीचे आवश्यकताएं देखें) - डेटाबेस बैकअप के लिए एक **स्टोरेज बकेट** - **नेटवर्क कनेक्टिविटी**: क्लस्टर के लोड बैलेंसर के लिए पोर्ट 443 इनबाउंड @@ -22,151 +21,151 @@ AgentEye एक स्व-होस्ट किया गया अवलोक ## चरण 1: एक समर्पित Kubernetes क्लस्टर प्रदान करें -AgentEye के लिए एक समर्पित Kubernetes क्लस्टर बनाएं। इसे अन्य कार्यभार के साथ साझा नहीं किया जाना चाहिए, ताकि पूरा प्लेटफॉर्म (एप्लिकेशन सेवाएं, डेटाबेस, विश्लेषण और कैशिंग) अलगाव में चले और आपके मौजूदा बुनियादी ढांचे को प्रभावित न करे। +AgentEye के लिए एक Kubernetes क्लस्टर बनाएं जो अन्य workloads के साथ साझा न हो। पूरा प्लेटफॉर्म (एप्लिकेशन सेवाएं, डेटाबेस, विश्लेषण और कैशिंग) अलगाव में चलता है जिससे आपके मौजूदा बुनियादी ढांचे को प्रभावित न करे। | आवश्यकता | विवरण | |---|---| -| **वितरण** | कोई भी अनुरूप Kubernetes: EKS, GKE, AKS, या स्व-प्रबंधित | +| **वितरण** | कोई भी conformant Kubernetes: EKS, GKE, AKS, या self-managed | | **संस्करण** | 1.27 या बाद में | -| **नोड पूल** | न्यूनतम: **3 नोड्स, प्रत्येक 4 vCPU / 8 GB RAM** (मानक सामान्य प्रयोजन इंस्टेंस) | -| **स्टोरेज** | एक डिफ़ॉल्ट StorageClass जो ब्लॉक वॉल्यूम प्रदान करता है (AWS पर `gp3`, GCP पर `pd-ssd`) | -| **लोड बैलेंसर** | क्लस्टर को क्लाउड LoadBalancer सेवाएं प्रदान करने में सक्षम होना चाहिए (EKS, GKE, AKS पर डिफ़ॉल्ट) | +| **नोड पूल** | न्यूनतम: **3 नोड्स, 4 vCPU / 8 GB RAM प्रत्येक** (standard general-purpose instances) | +| **स्टोरेज** | एक default StorageClass जो ब्लॉक वॉल्यूम प्रदान करता है (जैसे AWS पर `gp3`, GCP पर `pd-ssd`) | +| **लोड बैलेंसर** | क्लस्टर को cloud LoadBalancer सेवाएं प्रदान करने में सक्षम होना चाहिए (EKS, GKE, AKS पर default) | -> Exosphere क्लस्टर के अंदर सब कुछ इंस्टॉल और प्रबंधित करता है: इनग्रेस कंट्रोलर, TLS प्रमाणपत्र, डेटाबेस, कैशिंग, निगरानी, और सभी एप्लिकेशन परिनियोजन। +> Exosphere क्लस्टर के अंदर सब कुछ स्थापित और प्रबंधित करता है: ingress controllers, TLS प्रमाणपत्र, डेटाबेस, कैशिंग, निगरानी और सभी एप्लिकेशन स्थापन। --- -## चरण 2: AgentEye टीम को पहुंच प्रदान करें +## चरण 2: AgentEye टीम को एक्सेस प्रदान करें -Exosphere को cluster-admin पहुंच (या समतुल्य व्यापक RBAC) की आवश्यकता है नेमस्पेस, कस्टम रिसोर्स परिभाषा, इनग्रेस कंट्रोलर और स्टोरेज provisioners प्रबंधित करने के लिए। +Exosphere को cluster-admin एक्सेस (या समतुल्य व्यापक RBAC) की आवश्यकता है namespaces, custom resource definitions, ingress controllers और storage provisioners को प्रबंधित करने के लिए। | आवश्यकता | विवरण | |---|---| -| **पहुंच विधि** | IAM भूमिका (EKS/GKE के लिए पसंदीदा), kubeconfig, या SSO-आधारित पहुंच | -| **VPN / बेस्टियन** | यदि Kubernetes API सर्वर निजी है, तो Exosphere संचालन टीम के लिए VPN क्रेडेंशियल या बेस्टियन पहुंच प्रदान करें | +| **एक्सेस विधि** | IAM role (EKS/GKE के लिए पसंदीदा), kubeconfig, या SSO-आधारित एक्सेस | +| **VPN / bastion** | यदि Kubernetes API सर्वर निजी है, तो Exosphere ऑपरेशन टीम के लिए VPN क्रेडेंशियल या bastion एक्सेस प्रदान करें | --- ## चरण 3: नेटवर्क कनेक्टिविटी कॉन्फ़िगर करें -आपकी नेटवर्क टीम को क्लस्टर के लोड बैलेंसर में **पोर्ट 443** पर इनबाउंड ट्रैफिक की अनुमति देनी चाहिए। परिनियोजन दो अलग-अलग लोड बैलेंसर चलाता है: एक इवेंट इनजेस्शन के लिए (mTLS-सुरक्षित) और एक डैशबोर्ड के लिए: +आपकी नेटवर्क टीम को क्लस्टर के लोड बैलेंसर के लिए **पोर्ट 443** पर इनबाउंड ट्रैफिक की अनुमति देनी चाहिए। स्थापना दो अलग-अलग लोड बैलेंसर चलाता है: एक इवेंट ingestion के लिए (mTLS-सुरक्षित) और एक डैशबोर्ड के लिए: | ट्रैफिक | स्रोत | गंतव्य | सुरक्षा | |---|---|---|---| -| **इवेंट इनजेस्शन** | आपके क्लस्टर में कलेक्टर पॉड्स | Ingest LoadBalancer, पोर्ट 443 | mTLS (क्लाइंट प्रमाणपत्र) + API कुंजी | -| **डैशबोर्ड** | डेवलपर ब्राउज़र | Dashboard LoadBalancer, पोर्ट 443 | आपके डोमेन पर HTTPS, पासवर्ड-रहित ईमेल OTP साइन-इन | +| **इवेंट ingestion** | आपके क्लस्टर में Collector pods | Ingest LoadBalancer, पोर्ट 443 | mTLS (client certificate) + API key | +| **डैशबोर्ड** | डेवलपर ब्राउज़र | Dashboard LoadBalancer, पोर्ट 443 | आपके डोमेन पर HTTPS, passwordless email OTP sign-in | -ingest एंडपॉइंट पारस्परिक TLS द्वारा सुरक्षित है; कलेक्टर को हर अनुरोध पर एक वैध क्लाइंट प्रमाणपत्र **और** एक वैध API कुंजी प्रस्तुत करनी चाहिए। डैशबोर्ड अपने स्वयं के लोड बैलेंसर और होस्टनाम पर चलता है, साइन-इन आपके अनुमति सूची में डाले गए ईमेल पते/डोमेन तक सीमित है। +Ingest एंडपॉइंट mutual TLS द्वारा सुरक्षित है; collectors को हर अनुरोध पर एक valid client certificate **और** एक valid API key प्रस्तुत करना चाहिए। डैशबोर्ड अपने स्वयं के लोड बैलेंसर और होस्टनाम पर चलता है, जिसमें sign-in आपके allowlisted ईमेल पते/डोमेन तक सीमित है। -**DNS रिकॉर्ड (एक बार):** आप अपने नियंत्रण वाले एक डोमेन के तहत दो CNAME रिकॉर्ड बनाते हैं — एक ingest एंडपॉइंट के लिए और एक डैशबोर्ड के लिए (जैसे `agenteye.your-company.example`) — Exosphere द्वारा प्रदान किए गए लोड बैलेंसर होस्टनाम की ओर इशारा करते हुए। Exosphere फिर दोनों होस्टनाम के लिए सार्वजनिक रूप से विश्वस्त TLS प्रमाणपत्र स्वचालित रूप से प्रदान करता है, नवीकरण सहित। +**DNS रिकॉर्ड (एक बार):** आप अपने द्वारा नियंत्रित डोमेन के तहत दो CNAME रिकॉर्ड बनाते हैं — ingest एंडपॉइंट के लिए एक और डैशबोर्ड के लिए एक (जैसे `agenteye.your-company.example`) — लोड बैलेंसर होस्टनाम की ओर जो Exosphere प्रदान करता है। Exosphere फिर दोनों होस्टनाम के लिए publicly-trusted TLS प्रमाणपत्र स्वचालित रूप से प्रदान करता है, renewals सहित। -> **पोर्ट 80 नोट:** स्वचालित प्रमाणपत्र जारी करना और नवीकरण प्रत्येक लोड बैलेंसर के पोर्ट 80 पर HTTP पर सत्यापित करते हैं। यदि आपकी सुरक्षा स्थिति के लिए डैशबोर्ड लोड बैलेंसर को कॉर्पोरेट IP श्रेणियों तक सीमित करने की आवश्यकता है, तो पहले Exosphere को बताएं — हम प्रमाणपत्र सत्यापन को एक DNS-आधारित विधि में स्विच करते हैं (आपकी ओर से एक अतिरिक्त DNS रिकॉर्ड) ताकि नवीकरण प्रतिबंध के पीछे काम करते रहें। +> **पोर्ट 80 नोट:** स्वचालित प्रमाणपत्र issuance और renewal प्रत्येक लोड बैलेंसर के पोर्ट 80 पर HTTP पर validate करते हैं। यदि आपकी सुरक्षा नीति को डैशबोर्ड लोड बैलेंसर को corporate IP ranges तक सीमित करने की आवश्यकता है, तो पहले Exosphere को बताएं — हम प्रमाणपत्र validation को DNS-आधारित विधि में स्विच करते हैं (आपकी ओर से एक अतिरिक्त DNS रिकॉर्ड) ताकि प्रतिबंध के पीछे renewals काम करती रहें। -> **आउटबाउंड:** क्लस्टर नोड्स को `ghcr.io` से कंटेनर इमेज खींचने के लिए इंटरनेट पहुंच की आवश्यकता है। यदि आपका नेटवर्क आउटबाउंड ट्रैफिक को प्रतिबंधित करता है, तो `ghcr.io` को अनुमति दें या इमेज को अपने आंतरिक रजिस्ट्री में मिरर करें। +> **आउटबाउंड:** क्लस्टर नोड्स को `ghcr.io` से कंटेनर इमेज खींचने के लिए इंटरनेट एक्सेस की आवश्यकता है। यदि आपका नेटवर्क आउटबाउंड ट्रैफिक को प्रतिबंधित करता है, तो `ghcr.io` को allowlist करें या इमेज को अपने आंतरिक registry में mirror करें। --- ## चरण 4: एक बैकअप स्टोरेज बकेट प्रदान करें -डेटाबेस बैकअप एक क्लाउड स्टोरेज बकेट में संग्रहीत होते हैं जिसके आप मालिक हैं। +डेटाबेस बैकअप एक क्लाउड स्टोरेज बकेट में संग्रहीत होते हैं जो आप स्वामित्व रखते हैं। | आवश्यकता | विवरण | |---|---| | **सेवा** | S3 (AWS), GCS (GCP), या Azure Blob Storage | -| **पहुंच** | IAM भूमिका (EKS पर IRSA, GKE पर Workload Identity) या क्रेडेंशियल के माध्यम से क्लस्टर के नोड्स को लिखने के लिए पहुंच प्रदान करें | -| **प्रतिधारण** | आप बकेट की जीवनचक्र नीति को नियंत्रित करते हैं (प्रतिधारण अवधि, संग्रह नियम)। Exosphere बैकअप लिखता है; आप तय करते हैं कि उन्हें कितने समय तक रखना है | +| **एक्सेस** | IAM role के माध्यम से क्लस्टर के नोड्स को write एक्सेस प्रदान करें service accounts के लिए (EKS पर IRSA, GKE पर Workload Identity) या क्रेडेंशियल प्रदान करें | +| **Retention** | आप बकेट की lifecycle policy को नियंत्रित करते हैं (retention period, archival rules)। Exosphere बैकअप लिखता है; आप तय करते हैं कि उन्हें कितने समय तक रखना है | -एक एकल दैनिक बैकअप PostgreSQL (संबंधपरक स्थिति) और ClickHouse (इवेंट और मूल्यांकन) दोनों को एक संपीड़ित संग्रह में डंप करता है और इसे आपके बकेट में अपलोड करता है। बैकअप हर अपग्रेड से पहले भी चलते हैं। +एक दैनिक बैकअप PostgreSQL (relational state) और ClickHouse (events और evaluations) दोनों को एक compressed archive में डंप करता है और इसे आपके बकेट में अपलोड करता है। हर upgrade से पहले बैकअप भी चलते हैं। --- -## चरण 5: एक संपर्क व्यक्ति नामित करें +## चरण 5: एक संपर्क बिंदु नामित करें -क्लस्टर-स्तरीय समस्याओं के लिए आपकी ओर से एक व्यक्ति या Slack/Teams चैनल प्रदान करें: नोड स्वास्थ्य, क्लाउड खाता सीमा, नेटवर्क परिवर्तन। दिन-प्रतिदिन की संचालन में इस संपर्क को शामिल नहीं किया जाता है। +cluster-level समस्याओं के लिए अपनी ओर से एक व्यक्ति या Slack/Teams चैनल प्रदान करें: नोड स्वास्थ्य, क्लाउड खाता सीमाएं, नेटवर्क परिवर्तन। दिन-प्रतिदिन के ऑपरेशन में इस संपर्क को शामिल नहीं किया जाता है। --- -## हम क्या परिनियोजित करते हैं +## हम क्या स्थापित करते हैं -एक बार Exosphere को क्लस्टर पहुंच मिलने के बाद, निम्नलिखित घटकों को परिनियोजित और आपके लिए प्रबंधित किया जाता है: +एक बार Exosphere को क्लस्टर एक्सेस हो जाने के बाद, निम्नलिखित घटक आपके लिए स्थापित और प्रबंधित किए जाते हैं: | घटक | भूमिका | |---|---| -| **AgentEye सर्वर** | HTTP API जो कलेक्टर से इवेंट प्राप्त करता है, विश्लेषण चलाता है, और डैशबोर्ड को डेटा परोसता है | -| **डैशबोर्ड** | एजेंट सेशन, टूल कॉल, मॉडल अनुरोध और त्रुटियों को देखने के लिए वेब इंटरफेस; वैकल्पिक केवल-पढ़ने के लिए सहायक को होस्ट करता है | -| **ClickHouse** | Ingested इवेंट, विश्लेषण और मूल्यांकन के लिए आवश्यक विहित स्टोर | -| **PostgreSQL** | संगठन, API कुंजी, उपयोगकर्ता, डैशबोर्ड और सहेजे गए क्वेरी के लिए संबंधपरक स्टोर | -| **Redis** | वैकल्पिक साझा कैश और दर-सीमा बैकएंड; प्लेटफॉर्म सुंदरता से गिरावट करता है यदि यह उपलब्ध नहीं है | -| **AI सहायक (वैकल्पिक)** | आंतरिक केवल-पढ़ने के लिए सहायक कंटेनर; एक LLM एंडपॉइंट कॉन्फ़िगर किए जाने तक अक्षम रहता है | -| **Ingress कंट्रोलर** | दो लोड बैलेंसर (एक mTLS-सुरक्षित ingest के लिए, एक डैशबोर्ड के लिए) सार्वजनिक रूप से विश्वस्त, स्वचालित रूप से नवीनीकृत प्रमाणपत्र के साथ TLS को समाप्त करते हैं और ingest एंडपॉइंट पर mTLS लागू करते हैं | -| **cert-manager** | TLS प्रमाणपत्र प्रदान और mTLS क्लाइंट-प्रमाणपत्र जारी को स्वचालित करता है | -| **प्रमाणपत्र निगरानी** | एक निर्धारित कार्य प्रमाणपत्र समाप्ति जांचता है और जैसे-जैसे प्रमाणपत्र नवीकरण के करीब आते हैं सतर्कताएं भेजता है (जैसे Slack के लिए) | - -प्रबंधित प्रस्ताव प्लेटफॉर्म के मूल्यांकन पाइपलाइन को भी संचालित करता है, जो एजेंट गतिविधि को आपके मूल्यांकन मानदंड के विरुद्ध स्कोर करता है। ये क्षमताएं क्या प्रदान करती हैं यह जानने के लिए [सहायक](/hi/agenteye/assistant) और [मूल्यांकन सूट](/hi/agenteye/evaluation-suite) देखें। +| **AgentEye Server** | HTTP API जो collectors से events प्राप्त करता है, विश्लेषण चलाता है और डैशबोर्ड को डेटा प्रदान करता है | +| **Dashboard** | एजेंट सेशन, टूल कॉल, मॉडल अनुरोध और त्रुटियां देखने के लिए web interface; वैकल्पिक read-only AI सहायक को होस्ट करता है | +| **ClickHouse** | Ingested events, विश्लेषण और evaluations के लिए आवश्यक canonical store | +| **PostgreSQL** | संगठन, API keys, users, dashboards और saved queries के लिए relational store | +| **Redis** | वैकल्पिक shared cache और rate-limit backend; यदि यह उपलब्ध नहीं है तो प्लेटफॉर्म gracefully degrade होता है | +| **AI सहायक (वैकल्पिक)** | Internal read-only assistant container; जब तक कोई LLM एंडपॉइंट configured न हो तब तक disabled रहता है | +| **Ingress controllers** | दो लोड बैलेंसर (एक mTLS-सुरक्षित ingest के लिए, एक डैशबोर्ड के लिए) TLS को terminate करते हुए publicly-trusted, auto-renewed प्रमाणपत्र के साथ और ingest एंडपॉइंट पर mTLS लागू करते हैं | +| **cert-manager** | TLS प्रमाणपत्र provisioning और mTLS client-certificate issuance को स्वचालित करता है | +| **प्रमाणपत्र निगरानी** | एक scheduled job प्रमाणपत्र की expiry की जांच करता है और जब प्रमाणपत्र renewal के करीब हों तो alerts भेजता है (जैसे Slack को) | + +प्रबंधित offering प्लेटफॉर्म की evaluation pipeline को भी संचालित करता है, जो agent activity को आपके evaluation criteria के विरुद्ध स्कोर करता है। ये capabilities क्या देती हैं, इसके लिए [enterprise-docs/assistant.md](/hi/agenteye/assistant) और [enterprise-docs/evaluation-suite.md](/hi/agenteye/evaluation-suite) देखें। --- ## हम आपको क्या प्रदान करते हैं -परिनियोजन पूरा होने के बाद, आप प्राप्त करते हैं: +स्थापना के बाद, आपको निम्नलिखित प्राप्त होते हैं: | आइटम | विवरण | |---|---| -| **डैशबोर्ड URL** | आपके डोमेन के तहत एक होस्टनाम (जैसे `https://agenteye.your-company.example`), सार्वजनिक रूप से विश्वस्त, स्वचालित रूप से नवीनीकृत TLS प्रमाणपत्र के साथ परोसा जाता है। आप हमारे द्वारा प्रदान किए गए लोड बैलेंसर होस्टनाम के लिए एक CNAME बनाते हैं; साइन-इन पासवर्ड-रहित ईमेल OTP है | -| **कलेक्टर एंडपॉइंट** | ingest होस्टनाम का `/events` पाथ (जैसे `https://ingest.your-company.example/events`), mTLS-सुरक्षित | -| **क्लाइंट प्रमाणपत्र बंडल** | प्रति-क्लस्टर: क्लाइंट प्रमाणपत्र, निजी कुंजी, और CA प्रमाणपत्र एक Kubernetes Secret मैनिफेस्ट के रूप में वितरित। इसे प्रति क्लस्टर एक बार लागू करें | -| **GitHub PAT** | कलेक्टर बाइनरी और Python SDK पैकेज डाउनलोड करने के लिए | -| **कलेक्टर API कुंजी** | `events:add` अनुमति के साथ स्कोप की गई कुंजी, प्रत्येक कलेक्टर परिनियोजन के लिए एक | -| **स्थापना गाइड** | कलेक्टर और Python SDK के लिए चरण-दर-चरण दस्तावेज़ | +| **Dashboard URL** | आपके डोमेन के तहत एक होस्टनाम (जैसे `https://agenteye.your-company.example`), publicly-trusted, auto-renewed TLS प्रमाणपत्र के साथ served। आप हम द्वारा प्रदान किए गए लोड बैलेंसर होस्टनाम के लिए एक CNAME बनाते हैं; sign-in passwordless email OTP है | +| **Collector endpoint** | Ingest होस्टनाम का `/events` path (जैसे `https://ingest.your-company.example/events`), mTLS-सुरक्षित | +| **Client certificate bundle** | प्रति-क्लस्टर: client cert, private key, और CA cert एक Kubernetes Secret manifest के रूप में delivered। इसे एक बार प्रति क्लस्टर लागू करें | +| **GitHub PAT** | Collector binaries और Python SDK packages डाउनलोड करने के लिए | +| **Collector API keys** | `events:add` permission के साथ scoped keys, प्रत्येक collector deployment के लिए एक | +| **Installation guides** | Collector और Python SDK के लिए step-by-step दस्तावेज़ | --- ## सेटअप के बाद आप क्या करते हैं -आपका एकमात्र चल रहा काम आपनी अपनी एजेंट मशीनों पर है, AgentEye क्लस्टर पर नहीं: +आपका एकमात्र चल रहा काम आपनी अपनी agent machines पर है, AgentEye क्लस्टर पर नहीं: -1. **कलेक्टर स्थापित करें** AI एजेंट चलाने वाले प्रत्येक Kubernetes क्लस्टर में: क्लाइंट प्रमाणपत्र माउंट करें और एंडपॉइंट URL और API कुंजी कॉन्फ़िगर करें। [कलेक्टर स्थापना](/hi/agenteye/collector-installation) देखें। -2. **Python SDK को एकीकृत करें** अपने एजेंट कोड में। [Python SDK](/hi/agenteye/python-sdk) देखें। -3. **डैशबोर्ड खोलें** अपने ब्राउज़र में एजेंट गतिविधि देखने के लिए। +1. **Collector स्थापित करें** हर Kubernetes क्लस्टर में जो AI agents चलाता है: client certificate को mount करें और endpoint URL और API key को configure करें। देखें [enterprise-docs/collector-installation.md](/hi/agenteye/collector-installation)। +2. **Python SDK को एकीकृत करें** अपने agent code में। देखें [enterprise-docs/python-sdk.md](/hi/agenteye/python-sdk)। +3. **Dashboard खोलें** अपने ब्राउज़र में agent activity को देखने के लिए। -कोई क्लस्टर संचालन नहीं, कोई डेटाबेस प्रबंधन नहीं, कोई प्रमाणपत्र नवीकरण नहीं, कोई अपग्रेड नहीं। +कोई cluster ऑपरेशन नहीं, कोई database प्रबंधन नहीं, कोई प्रमाणपत्र renewal नहीं, कोई upgrade नहीं। --- ## सुरक्षा -- **डेटा आपके क्लाउड खाते में रहता है।** क्लस्टर, स्टोरेज, और डेटाबेस सभी आपके वातावरण में चलते हैं। कोई डेटा आपकी सीमा से बाहर नहीं जाता है। -- **आप पहुंच को नियंत्रित करते हैं।** क्लस्टर आपके खाते में है। आप किसी भी समय Exosphere की पहुंच को ऑडिट, निगरानी, या रद्द कर सकते हैं। सभी संचालन आपके क्लाउड की ऑडिट लॉग (CloudTrail, GCP Audit Logs, आदि) के माध्यम से जाते हैं। -- **इवेंट ingest पर mTLS।** हर कलेक्टर अनुरोध को एक वैध क्लाइंट प्रमाणपत्र और एक API कुंजी दोनों की आवश्यकता है। एक रिसाव हुई कुंजी प्रमाणपत्र के बिना बेकार है; एक चोरी किया गया प्रमाणपत्र एक वैध कुंजी के बिना बेकार है। -- **डैशबोर्ड पहुंच नियंत्रण।** डैशबोर्ड अपने स्वयं के लोड बैलेंसर पर चलता है, इवेंट ingest से अलग, और साइन-इन पासवर्ड-रहित ईमेल OTP है जो आपके द्वारा अनुमति सूची में डाले गए ईमेल पते/डोमेन तक सीमित है। लोड बैलेंसर पर एक IP स्रोत-श्रेणी अनुमति सूची अनुरोध पर उपलब्ध है; चूंकि स्वचालित प्रमाणपत्र नवीकरण को लोड बैलेंसर तक पहुंचना चाहिए, Exosphere प्रतिबंध को DNS-आधारित प्रमाणपत्र सत्यापन के साथ जोड़ता है ताकि नवीकरण काम करते रहें। -- **प्रति-क्लस्टर प्रमाणपत्र।** आपके प्रत्येक क्लस्टर को अपना क्लाइंट प्रमाणपत्र प्राप्त होता है। यदि एक क्लस्टर से समझौता होता है, तो वह प्रमाणपत्र स्वतंत्र रूप से रद्द किया जाता है दूसरों को प्रभावित किए बिना। +- **डेटा आपके क्लाउड खाते में रहता है।** क्लस्टर, स्टोरेज और डेटाबेस सभी आपके environment में चलते हैं। कोई डेटा आपकी boundary को नहीं छोड़ता। +- **आप एक्सेस को नियंत्रित करते हैं।** क्लस्टर आपके खाते में है। आप किसी भी समय Exosphere के एक्सेस को audit, monitor या revoke कर सकते हैं। सभी ऑपरेशन आपके क्लाउड के audit log (CloudTrail, GCP Audit Logs, आदि) के माध्यम से जाते हैं। +- **Event ingestion पर mTLS।** हर collector अनुरोध को एक valid client certificate **और** एक API key दोनों की आवश्यकता है। एक leaked key प्रमाणपत्र के बिना बेकार है; एक stolen cert एक valid key के बिना बेकार है। +- **Dashboard एक्सेस नियंत्रण।** Dashboard अपने स्वयं के लोड बैलेंसर पर चलता है, event ingestion से अलग, और sign-in passwordless email OTP है जो आपके द्वारा allowlist किए गए ईमेल पते/डोमेन तक सीमित है। लोड बैलेंसर पर IP source-range allowlist अनुरोध पर उपलब्ध है; क्योंकि स्वचालित प्रमाणपत्र renewal को लोड बैलेंसर तक पहुंचना चाहिए, Exosphere प्रतिबंध को DNS-based प्रमाणपत्र validation के साथ जोड़ता है ताकि renewals काम करती रहें। +- **प्रति-क्लस्टर प्रमाणपत्र।** आपके प्रत्येक क्लस्टर को अपना client certificate मिलता है। यदि एक क्लस्टर compromised है, तो वह प्रमाणपत्र स्वतंत्र रूप से revoke किया जाता है अन्य को प्रभावित किए बिना। --- -## परिनियोजन समयरेखा +## स्थापना समयरेखा -| चरण | अवधि | आपकी संलिप्तता | +| चरण | अवधि | आपकी involvement | |---|---|---| -| **क्लस्टर provisioning** | 1-2 दिन | क्लस्टर प्रदान करें और Exosphere को पहुंच प्रदान करें | -| **प्लेटफॉर्म सेटअप** | 1 दिन | कोई नहीं; Exosphere सभी बुनियादी ढांचा घटकों को स्थापित करता है | -| **एप्लिकेशन परिनियोजन** | 1 दिन | कोई नहीं; Exosphere सर्वर, डैशबोर्ड को परिनियोजित करता है और API कुंजी बनाता है | -| **कलेक्टर रोलआउट** | 1-3 दिन | अपने क्लस्टर में कलेक्टर स्थापित करें (Exosphere से मार्गदर्शन के साथ) | -| **उत्पादन burn-in** | 1 सप्ताह | कोई नहीं; Exosphere निगरानी करता है और समायोजन करता है | +| **क्लस्टर provisioning** | 1-2 दिन | क्लस्टर को provision करें और Exosphere को एक्सेस दें | +| **प्लेटफॉर्म सेटअप** | 1 दिन | कोई नहीं; Exosphere सभी बुनियादी ढांचे के घटक स्थापित करता है | +| **एप्लिकेशन स्थापना** | 1 दिन | कोई नहीं; Exosphere server, dashboard को स्थापित करता है और API keys बनाता है | +| **Collector rollout** | 1-3 दिन | अपने क्लस्टर में collectors स्थापित करें (Exosphere के मार्गदर्शन के साथ) | +| **उत्पादन burn-in** | 1 सप्ताह | कोई नहीं; Exosphere निगरानी और tuning करता है | -विशिष्ट कुल: **~2 सप्ताह** किकऑफ से उत्पादन-तैयार तक। +विशिष्ट कुल: **~2 सप्ताह** kickoff से production-ready तक। --- ## समर्थन -प्रश्नों या समस्याओं के लिए, Exosphere से `support@exosphere.host` पर संपर्क करें। +प्रश्नों या समस्याओं के लिए, Exosphere को `support@exosphere.host` पर संपर्क करें। --- -## अगले कदम +## अगले चरण -- [शुरुआत करें](/hi/agenteye/getting-started): end-to-end walkthrough -- [कलेक्टर स्थापना](/hi/agenteye/collector-installation): कलेक्टर स्थापित और कॉन्फ़िगर करें -- [Python SDK](/hi/agenteye/python-sdk): अपने एजेंट कोड को उपकरण करें -- [API कुंजी](/hi/agenteye/api-keys): पहुंच और अनुमति प्रबंधित करें -- [समस्या निवारण](/hi/agenteye/troubleshooting): सामान्य समस्याएं और समाधान \ No newline at end of file +- [Getting Started](/hi/agenteye/getting-started): end-to-end walkthrough +- [Collector Installation](/hi/agenteye/collector-installation): collector को स्थापित और कॉन्फ़िगर करें +- [Python SDK](/hi/agenteye/python-sdk): अपने agent code को instrument करें +- [API Keys](/hi/agenteye/api-keys): एक्सेस और permissions को manage करें +- [Troubleshooting](/hi/agenteye/troubleshooting): सामान्य समस्याएं और fixes \ No newline at end of file diff --git a/docs/it/agenteye/audits.mdx b/docs/it/agenteye/audits.mdx index 70be54bc..d6bc3351 100644 --- a/docs/it/agenteye/audits.mdx +++ b/docs/it/agenteye/audits.mdx @@ -1,107 +1,106 @@ --- -title: "Audits — agentic improvement detection" -description: "AgentEye Audits — agentic improvement detection documentation." +title: "Audit — rilevamento di miglioramenti agentici" +description: "AgentEye Audit — documentazione del rilevamento di miglioramenti agentici." --- -Gli audit sono job ricorrenti che analizzano i tuoi log degli agenti **tra le sessioni** per trovare aree di miglioramento. Mentre un alert monitora una metrica specifica che conosci già in tempo quasi reale, un audit *indaga*: secondo una pianificazione che tu imposti, esegue una verifica di policy deterministica sulla finestra, quindi libera un **agente AI per l'affidabilità** sulle tue sessioni — l'agente interroga i dati stesso, legge transcript sospetti, ed (quando utile) esegue piccoli script di analisi, quindi redige **raccomandazioni di miglioramento** con le prove dietro ognuna. +Gli audit sono job ricorrenti che analizzano i tuoi log degli agenti **tra sessioni** per trovare aree di miglioramento. Mentre un avviso monitora una metrica specifica che conosci già in quasi tempo reale, un audit *indaga*: secondo una pianificazione che stabilisci, esegue un passaggio deterministico delle policy sulla finestra temporale, quindi invia un **agente di affidabilità basato su IA** sulle tue sessioni — l'agente interroga direttamente i dati, legge i transcript sospetti, e (quando utile) esegue piccoli script di analisi, quindi redige **raccomandazioni di miglioramento** con le prove dietro ciascuna. -Usa gli audit per rispondere a "cosa dovrei correggere o migliorare nei miei agenti?" — e gli alert per essere avvisato nel momento esatto in cui una soglia specifica viene superata. Ogni miglioramento si collega alle sessioni e alle query esatte dietro di esso, e un solo clic crea un alert precompilato per catturare ricorrenze. +Usa gli audit per rispondere a "cosa dovrei risolvere o migliorare nei miei agenti?" — e gli avvisi per ricevere una notifica istantanea quando una soglia specifica viene superata. Ogni miglioramento è collegato alle sessioni e alle query esatte dietro di esso, e un clic crea un avviso precompilato per rilevare ricorrenze. -La superficie del dashboard è **`//audits`** (sidebar → *analyze* → *audits*), protetta dalle autorizzazioni `audits:read` / `audits:write`. +La superficie del dashboard è **`//audits`** (sidebar → *analyze* → *audits*), controllata dai permessi `audits:read` / `audits:write`. --- -## Come funziona una esecuzione +## Come funziona un'esecuzione -Ogni esecuzione ha due livelli — una base deterministica e un'indagine agentica. +Ogni esecuzione ha due livelli — una base deterministica e un'indagine agentia. -### 1. La verifica di policy (deterministica) +### 1. Il passaggio della policy (deterministico) -Prima che qualsiasi modello venga eseguito, l'audit esegue un piccolo catalogo di **verifiche di policy SQL** sulla finestra: query aggregate delimitate che evidenziano schemi noti come problematici e segnalano *quanti* eventi / *quali* sessioni li hanno generati — mai il testo dei risultati. Il catalogo include: +Prima che qualsiasi modello venga eseguito, l'audit esegue un piccolo catalogo di **controlli delle policy SQL** sulla finestra temporale: query aggregate delimitate che segnalano pattern noti come problematici e riportano *quanti* eventi / *quali* sessioni corrisponden — mai il testo corrispondente stesso. Il catalogo include: -- **Leakage di secret / credenziali** nei payload degli eventi — chiavi di accesso AWS, chiavi API `sk-…`, chiavi private PEM, token JWT / bearer, e assegnazioni di credenziali `KEY=…`. +- **Perdita di segreti / credenziali** nei payload degli eventi — chiavi di accesso AWS, chiavi API `sk-…`, chiavi private PEM, token JWT / bearer, e assegnamenti di credenziali `KEY=…`. - **Marcatori di prompt injection** — "ignora le istruzioni precedenti", "rivela il tuo system prompt", e simili. -- **PII** — numeri simili a SSN (euristico). -- **Negazioni di autorizzazione degli strumenti** e **loop di tool-call in fuga**. +- **PII** — numeri a forma di SSN (euristico). +- **Negazioni di permessi degli strumenti** e **loop di chiamate di strumenti in fuga**. -I risultati della policy vengono persistiti come finding (tipo `policy`) che **affiorano sempre** (non vengono mai eliminati dal limite per-esecuzione), e vengono passati all'agente AI come piste iniziali. Poiché questo livello non necessita del modello, un audit produce comunque i suoi segnali di sicurezza più importanti anche se l'agente AI è non disponibile. +I risultati della policy vengono memorizzati come finding (tipo `policy`) che **emergono sempre** (non vengono mai ridotti dal limite per esecuzione), e vengono consegnati all'agente IA come piste iniziali. Poiché questo livello non richiede nessun modello, un audit produce comunque i suoi segnali di sicurezza più importanti anche se l'agente IA è indisponibile. -### 2. L'indagine agentica (AI) +### 2. L'indagine agentia (IA) -L'audit quindi esegue un **agente di affidabilità autonomo** (lo stesso servizio Agents SDK di Claude che alimenta l'assistente dashboard, con un prompt specifico per l'audit). Data la **portata** dell'audit (agenti selezionati × ambienti) e la **finestra temporale**, l'agente: +L'audit quindi esegue un **agente autonomo di affidabilità** (lo stesso servizio Agents SDK di Claude che alimenta l'assistente del dashboard, con un prompt specifico per l'audit). Dato lo **scope** dell'audit (agenti selezionati × ambienti) e la **finestra temporale**, l'agente: -- esegue query SQL di sola lettura sulle tue tabelle di analytics, -- legge un certo numero di transcript di sessioni rappresentative, -- facoltativamente scrive ed esegue brevi **script Python in una sandbox in-pod blindata** (nessuna rete, nessun accesso al filesystem, secret eliminati) per analisi che SQL non può esprimere — clustering di errori, calcolo di distribuzioni, scansione di payload già recuperati, -- e registra ogni **miglioramento** ben comprovato che trova. +- esegue query SQL di sola lettura rispetto alle tue tabelle di analytics, +- legge una manciata di transcript di sessioni rappresentativi, +- facoltativamente scrive ed esegue brevi **script Python in una sandbox chiusa in-pod** (nessuna rete, nessun accesso al filesystem, segreti scrubati) per analisi che SQL non può esprimere — clustering di errori, calcolo di distribuzioni, sweep di payload già recuperati, +- e registra ogni **miglioramento** ben provato che trova. -Lavora attraverso diverse linee investigative — clustering di errori, drift rispetto a una baseline, fallimento dell'obiettivo negli transcript, abuso di strumenti, compromessi qualità/costo, e gap di copertura — secondo la **sensibilità** dell'audit (bassa / media / alta). Ogni miglioramento **deve citare prove**: gli id di sessione che l'agente ha effettivamente ispezionato e/o l'SQL che ha eseguito. Il server valida che le sessioni citate esistano e **scarta qualsiasi miglioramento senza prove sopravvissute**, quindi l'agente indaga ma non inventa mai. +Lavora attraverso diverse linee investigative — clustering di errori, drift rispetto a un baseline, fallimento degli obiettivi nei transcript, uso improprio degli strumenti, compromessi qualità/costo, e lacune di copertura — alla **sensibilità** dell'audit (bassa / media / alta). Ogni miglioramento **deve citare prove**: gli id di sessione che l'agente ha effettivamente ispezionato e/o la SQL che ha eseguito. Il server convalida che le sessioni citate esistono e **scarta qualsiasi miglioramento senza prove sopravvissute**, quindi l'agente indaga ma non inventa mai. -Ogni miglioramento comporta: +Ogni miglioramento include: -- una **raccomandazione** (il cambio concreto da apportare — una modifica di prompt, una correzione di schema tool, una politica di retry, una guardrail, più copertura eval), -- una stima di **impatto atteso** e **sforzo** (basso / medio / alto), -- una **magnitudine** — `big` (un operatore dovrebbe essere avvisato), `medium` (appartiene alla relazione di esecuzione), o `small` (contesto dashboard), -- un'**impronta** stabile (dalla categoria del problema + portata, *non* dalle sessioni di questa esecuzione) così lo stesso problema viene tracciato da esecuzione a esecuzione anche mentre le prove cambiano, -- e, dove un semplice watcher deterministico potrebbe catturare ricorrenza, un **alert suggerito** che puoi creare con un solo clic. +- una **raccomandazione** (il cambiamento concreto da fare — un aggiustamento del prompt, una correzione dello schema dello strumento, una policy di ripetizione, una guardrail, copertura eval maggiore), +- un **impatto previsto** e una stima dello **sforzo** (basso / medio / alto), +- una **magnitudine** — `big` (un operatore dovrebbe ricevere una notifica), `medium` (appartiene alla relazione della esecuzione), o `small` (contesto del dashboard), +- un **fingerprint** stabile (dalla categoria del problema + scope, *non* dalle sessioni di questa esecuzione) così lo stesso problema viene tracciato da esecuzione a esecuzione mentre le prove cambiano, +- e, dove un semplice osservatore deterministico potrebbe catturare ricorrenze, un **avviso suggerito** che puoi creare in un clic. -> **Il livello AI è opzionale ma consigliato.** Se nessun agente AI è configurato per la pipeline audit, le esecuzioni comunque si eseguono, persistono i finding di policy, e onestamente riportano "analisi non disponibile" per il livello agentico piuttosto che passare silenziosamente. +> **Il livello IA è facoltativo ma consigliato.** Se nessun agente IA è configurato per la pipeline di audit, le esecuzioni ancora si eseguono, persistono i finding della policy, e onestamente riportano "analisi non disponibile" per il livello agentia anziché passare silenziosamente. ### Modalità di fallimento -I miglioramenti si classificano nel tuo catalogo durabile di **modalità di fallimento** (o propongono una nuova modalità). Le modalità danno ai pattern un'identità stabile tra le esecuzioni e il tracciamento di ricorrenza a lungo termine. +I miglioramenti vengono classificati nel tuo catalogo di **modalità di fallimento** durevole dell'organizzazione (o propongono una nuova modalità). Le modalità danno ai pattern un'identità stabile tra le esecuzioni e il tracciamento della ricorrenza a lungo raggio. -## Ciclo di vita della triaging +## Ciclo di vita della triage -In una pagina di finding (`/audits//findings/`): +Su una pagina di finding (`/audits//findings/`): | Azione | Effetto | |---|---| | **acknowledge** | Mantiene il finding visibile ma dimezza la sua priorità. | -| **resolve** | Lo contrassegna come risolto. Se il pattern ritorna genuinamente in seguito, si riapre come **new** — quindi una regressione è evidente, non silenziosamente incorporata nella storia. | -| **mute** / **dismiss** | Soppressione duratura: l'impronta del pattern viene ricordata e non affiora mai più, anche tra le esecuzioni. Usa mute per "noto, accettato"; dismiss per "non utile". | -| **reopen** | Cancella la soppressione / risoluzione e riclassifica il pattern. | -| **assign** | Instrada il finding a un operatore (un membro dell'org) per la proprietà. Priorità e stato di soppressione rimangono invariati. | +| **resolve** | Lo marca come risolto. Se il pattern genuinamente ritorna più tardi, si riapre come **new** — quindi una regressione è evidente, non silenziosamente incorporata nella storia. | +| **mute** / **dismiss** | Soppressione durevole: il fingerprint del pattern viene ricordato e non emerge mai più, anche tra le esecuzioni. Usa mute per "noto, accettato"; dismiss per "non utile". | +| **reopen** | Cancella soppressione / risoluzione e classifica di nuovo il pattern. | -Il rumore di basso segnale è controllato per audit con un limite di finding per-esecuzione (`top_k`) sui miglioramenti agentici. I finding di policy bypassano il limite (sono rilevanti per la sicurezza e sempre mostrati). Qualsiasi cosa tagliata dal limite è contata nelle statistiche dell'esecuzione — nulla viene silenziosamente eliminato. +Il rumore a basso segnale è controllato per audit con un limite di finding per esecuzione (`top_k`) sui miglioramenti agentici. I finding della policy bypassano il limite (sono rilevanti per la sicurezza e sempre mostrati). Qualsiasi cosa tagliata dal limite viene conteggiata nelle statistiche della esecuzione — nulla viene silenziosamente eliminato. ## Pianificazione -- **Cadenza** (`schedule_interval_secs`): ogni ora fino a settimanale; **giornaliero è il default**. Gli audit sono deliberatamente più grossolani degli alert — un'indagine agentica scansiona intere finestre ed esegue per minuti. -- **Finestra**: o una lookback rolling fissa (ad es. "ogni esecuzione scansiona gli ultimi 7 giorni") o **since-last-run** (il default) — ogni esecuzione riprende da dove è finita la precedente esecuzione riuscita, con una piccola sovrapposizione così gli eventi al confine non vengono mai persi. -- L'esecuzione successiva è pianificata un intervallo completo dopo il completamento della precedente **completes**, quindi un'esecuzione lenta non mette mai in coda una seconda esecuzione concorrente dello stesso audit. -- **Run now** nella pagina audit la rende dovuta immediatamente. +- **Cadenza** (`schedule_interval_secs`): oraria a settimanale; **giornaliera è la predefinita**. Gli audit sono deliberatamente più rudi degli avvisi — un'indagine agentia scansiona intere finestre e viene eseguita per minuti. +- **Finestra**: o un lookback rolling fisso (ad es. "ogni esecuzione scansiona gli ultimi 7 giorni") o **since-last-run** (la predefinita) — ogni esecuzione riprende da dove si è fermata l'esecuzione precedente riuscita, con un piccolo overlap così gli eventi di confine non vengono mai persi. +- L'esecuzione successiva viene pianificata un intervallo completo dopo che la precedente si **completa**, così un'esecuzione lenta non ammassa mai una seconda esecuzione concorrente dello stesso audit. +- **Run now** sulla pagina dell'audit lo rende dovuto immediatamente. ## Selezione del modello -Quando crei un audit puoi scegliere quale modello l'indagine usa, dalla **lista di modelli che il tuo operatore ha configurato** per il servizio agenti. Con un singolo modello configurato, il picker lo mostra come caption; con più, tu scegli. Lasciarlo non impostato usa il default configurato. +Quando crei un audit puoi scegliere quale modello l'indagine usa, dall'**elenco di modelli che il tuo operatore ha configurato** per il servizio agent. Con un singolo modello configurato, il picker lo mostra come didascalia; con diversi, scegli. Lasciarlo non impostato usa il default configurato. ## Notifiche -Quando un'esecuzione affiora finding **nuovi**, l'audit notifica i canali configurati della tua organizzazione — la stessa porta `alerts.enabled_channels` e le impostazioni che la pipeline di alert usa: +Quando un'esecuzione emerge **nuovi** finding, l'audit notifica ai canali configurati della tua organizzazione — lo stesso gate `alerts.enabled_channels` e le impostazioni che la pipeline degli avvisi usa: -- **Slack** — un riepilogo degli elementi nuovi significativi (`big`) con un deep link. -- **Email** — una **relazione di audit** progettata che elenca i nuovi miglioramenti (top severity, raccomandazioni per-item, deep link), inviata quando l'audit ha un canale **email** allegato ed esiste almeno un finding nuovo. +- **Slack** — un riassunto degli elementi significativi (`big`) nuovi con un deep link. +- **Email** — un **report di audit** progettato che elenca i nuovi miglioramenti (principale per gravità, raccomandazioni per elemento, deep link), inviato quando l'audit ha un canale **email** allegato e c'è almeno un finding nuovo. -I finding ricorrenti ma noti non ri-notificano. +I finding ricorrenti ma noti non notificano di nuovo. ## Riferimento di configurazione -Le definizioni di audit sono gestite nel dashboard (`/audits/new`) o via API. Le impostazioni per-audit includono la cadenza di pianificazione e la finestra, la portata (`{"environments": [...], "agent_ids": [...]}`), la sensibilità (`low` / `medium` / `high`), i canali di notifica, il limite di finding per-esecuzione (`top_k`), e il modello (via `llm_budget.model`). Le impostazioni server a livello operatore (timeout, sandbox, l'URL del servizio agenti) sono documentate in [deployment.md](/it/agenteye/deployment). +Le definizioni di audit vengono gestite nel dashboard (`/audits/new`) o tramite l'API. Le impostazioni per audit includono la cadenza e la finestra della pianificazione, lo scope (`{"environments": [...], "agent_ids": [...]}`), la sensibilità (`low` / `medium` / `high`), i canali di notifica, il limite di finding per esecuzione (`top_k`), e il modello (tramite `llm_budget.model`). Le impostazioni del server a livello di operatore (timeout, sandbox, l'URL del servizio agent) sono documentate in [deployment.md](/it/agenteye/deployment). ## API -Tutti gli endpoint sono org-scoped e seguono l'auth standard bearer-key (vedi [api-keys.md](/it/agenteye/api-keys)). +Tutti gli endpoint hanno scope org e seguono l'autenticazione standard bearer-key (vedi [api-keys.md](/it/agenteye/api-keys)). -| Endpoint | Autorizzazione | Scopo | +| Endpoint | Permesso | Scopo | |---|---|---| | `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | Elenca / crea definizioni di audit. | | `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Ispeziona, modifica, elimina un audit. | | `POST /audits/:id/run` | `audits:write` | Rendi l'audit dovuto immediatamente. | -| `GET /audits/:id/runs` | `audits:read` | Cronologia di esecuzione (finestra, status, statistiche, conteggi di finding). | -| `GET /audits/findings` | `audits:read` | Finding a livello org, filtrabili per `audit_id`, `status`; ordinati per priorità. | -| `GET /audits/findings/:fid` | `audits:read` | Dettaglio completo di finding (raccomandazione, prova, priorità). | -| `POST /audits/findings/:fid/status` | `audits:write` | Triaging: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | +| `GET /audits/:id/runs` | `audits:read` | Cronologia della esecuzione (finestra, stato, statistiche, conteggi di finding). | +| `GET /audits/findings` | `audits:read` | Finding a livello di organizzazione, filtrabili per `audit_id`, `status`; ordinati per priorità. | +| `GET /audits/findings/:fid` | `audits:read` | Dettaglio completo del finding (raccomandazione, prove, priorità). | +| `POST /audits/findings/:fid/status` | `audits:write` | Triage: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | -Per "audit eseguito ma non ha trovato nulla", "la sandbox del codice è disabilitata", e "email dell'audit non consegnata", vedi [troubleshooting.md](/it/agenteye/troubleshooting#audits). \ No newline at end of file +Per "audit eseguito ma non ha trovato nulla", "la sandbox di codice è disabilitata", e "email di audit non consegnata", vedi [troubleshooting.md](/it/agenteye/troubleshooting#audits). \ No newline at end of file diff --git a/docs/it/agenteye/cli-recipes.mdx b/docs/it/agenteye/cli-recipes.mdx index fdbad359..6b16d361 100644 --- a/docs/it/agenteye/cli-recipes.mdx +++ b/docs/it/agenteye/cli-recipes.mdx @@ -3,27 +3,27 @@ title: "Ricette CLI per agenti" description: "Documentazione delle ricette CLI di AgentEye per agenti." --- -Estrai dati di sessione, evento e valutazione (e attiva rivalutazioni) direttamente da uno script o da un agente di codifica, con JSON pulito su stdout che si collega direttamente a `jq`. Queste ricette trasformano i dati di osservabilità di AgentEye in qualcosa che un utente di terminale o un agente di codifica AI (Claude Code, Cursor) può interrogare e automatizzare, senza fare clic sulla dashboard. +Estrai dati di sessione, evento e valutazione (e attiva rivalutazioni) direttamente da uno script o da un agente di codifica, con JSON pulito su stdout che si collega direttamente a `jq`. Queste ricette trasformano i dati di osservabilità di AgentEye in qualcosa che un utente di terminale o un agente di codifica AI (Claude Code, Cursor) può interrogare e automatizzare, senza cliccare sulla dashboard. -I modelli sottostanti sono pronti per copia-incolla per AgentEye CLI (`agenteye`). Per l'installazione, l'autenticazione e l'elenco completo delle opzioni consulta [CLI](/it/agenteye/cli); esegui `agenteye -h` o `agenteye -h` per la guida integrata. +I modelli seguenti sono pronti per il copia-incolla sulla CLI di AgentEye (`agenteye`). Per l'installazione, l'autenticazione e l'elenco completo delle opzioni, vedi [CLI](/it/agenteye/cli); esegui `agenteye -h` o `agenteye -h` per l'aiuto integrato. ## Regole d'oro -1. **Le opzioni globali vanno *prima* del comando.** `agenteye --json sessions` è corretto; `agenteye sessions --json` non lo è. Le globali sono `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Passa `--json` ogni volta che analizzi l'output.** I dati vanno su **stdout** come JSON; lo stato umano e gli errori vanno su **stderr**, quindi stdout rimane pulito per collegarsi a `jq`. -3. **Crea un ramo in base al codice di uscita**, non al testo di stderr: `0` ok · `2` argomenti non validi · `3` impossibile raggiungere la dashboard · `4` non connesso o scaduto · `5` autorizzazione mancante. +1. **Le opzioni globali vanno *prima* del comando.** `agenteye --json sessions` è corretto; `agenteye sessions --json` non lo è. Le opzioni globali sono `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **Passa `--json` ogni volta che analizzi l'output.** I dati vanno su **stdout** come JSON; i messaggi di stato umani e gli errori vanno su **stderr**, quindi stdout rimane pulito per collegarsi a `jq`. +3. **Ramifica in base al codice di uscita**, non al testo di stderr: `0` ok · `2` argomenti errati · `3` impossibile raggiungere la dashboard · `4` non connesso o sessione scaduta · `5` permesso mancante. 4. **Scopri con `-h`.** Ogni comando documenta i suoi filtri, i formati di valore e la forma JSON. ## Configurazione una tantum ```bash export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # così non ripeti --base-url -agenteye login --email you@example.com # incolla il codice inviato; valido ~24h +agenteye login --email you@example.com # incolla il codice inviato per email; valido ~24h ``` -## Conferma l'autenticazione prima di fare il lavoro +## Conferma autenticazione prima di lavorare -`whoami` non genera mai errori su una sessione mancante o scaduta; invece segnala `logged_in:false`, così un agente può controllare lo stato di autenticazione in sicurezza. (Può comunque uscire con un codice diverso da zero se nessun URL di base è impostato o la dashboard non è raggiungibile.) +`whoami` non genera mai errori per una sessione mancante o scaduta; invece riporta `logged_in:false`, quindi un agente può sondare lo stato di autenticazione in sicurezza. (Può comunque uscire con codice diverso da zero se nessun URL di base è impostato o la dashboard è irraggiungibile.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -31,41 +31,41 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## Trova sessioni fallite o con punteggio basso +## Trova sessioni con fallimento o punteggio basso ```bash -# sessioni nelle ultime 24h la cui valutazione ha generato errore +# sessioni nelle ultime 24h la cui valutazione ha errore agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# valutazioni con punteggio <= 0.5 su helpfulness, per un agente +# valutazioni con punteggio <= 0.5 su utilità, per un agente agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -Il filtro dei punteggi vive su **`evals`**, non su `sessions`. `--score KEY:MIN..MAX` è ripetibile e AND-combinato; entrambi i limiti sono opzionali (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Puoi passare fino a 20 filtri di punteggio per richiesta; più di questo restituisce HTTP 400. `sessions` condivide i filtri `--env`, `--status`, `--agent-id`, `--session-id` e intervallo di tempo con `evals`, ma non ha `--score`. +Il filtro dei punteggi si trova su **`evals`**, non su `sessions`. `--score KEY:MIN..MAX` è ripetibile e combinato con AND; entrambi i limiti sono opzionali (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Puoi passare fino a 20 filtri di punteggio per richiesta; più di questo restituisce HTTP 400. `sessions` condivide i filtri `--env`, `--status`, `--agent-id`, `--session-id` e intervallo di tempo con `evals`, ma non ha `--score`. ## Leggi una sessione da capo a fondo -Non esiste un singolo comando `session show` — combina il trail di eventi con la valutazione della sessione: +Non c'è un singolo comando `session show` — combina la traccia di eventi con la valutazione della sessione: ```bash -# la valutazione più recente della sessione (status + scores) +# l'ultima valutazione della sessione (stato + punteggi) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' # ogni evento nell'esecuzione (aumenta --limit per una scansione completa) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# solo le tool call in una sessione +# solo le chiamate tool in una sessione agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -## Estrai tutto (paginazione) +## Recupera tutto (paginazione) -I risultati sono più recenti per primi e paginati con cursore. +I risultati sono in ordine più recente prima e impaginati con cursore. ```bash -# in una sola volta: estrai fino a 500 righe in pagine di 200 righe +# una sola volta: recupera fino a 500 righe in pagine di 200 righe agenteye --json events --session-id run-001 --limit 500 --all > events.json # paginazione manuale: reinserisci next_cursor @@ -74,9 +74,9 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## Semplifica l'output con --fields +## Riduci l'output con --fields -Limita le chiavi (sia nella tabella che in `--json`) per ridurre quello che un agente deve leggere. +Limita le chiavi (sia nella tabella che in `--json`) per ridurre ciò che un agente deve leggere. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' @@ -85,11 +85,11 @@ agenteye --json events --session-id run-001 --fields ts,event_type --all I nomi di campo sconosciuti vengono rifiutati (uscita `2`) con l'elenco valido, un modo economico per scoprire i nomi dei campi. -## Scopri i valori di filtro validi +## Scopri valori di filtro validi ```bash agenteye --json list envs | jq -r '.values[]' # valori per --env -agenteye --json list tools | jq -r '.values[]' # nomi degli strumenti; anche agents, models, event_types, … +agenteye --json list tools | jq -r '.values[]' # nomi tool; anche agenti, modelli, event_types, … agenteye --json list score_filters | jq -r '.values[]' # KEY valido per --score KEY:MIN..MAX ``` @@ -103,33 +103,33 @@ agenteye --json orgs list | jq -r '.orgs[].org_slug' agenteye --org globex --json sessions --since 24h # sostituisci per un comando ``` -Un login multi-org senza `--org` esce con un codice diverso da zero e stampa le organizzazioni tra cui scegliere. +Un login multi-org senza `--org` esce con codice diverso da zero e stampa le organizzazioni tra cui scegliere. -## Fornisci una chiave API per SDK/collector +## Provisioning di una chiave API per SDK/collector ```bash -# il segreto viene stampato UNA SOLA VOLTA — con --json è il campo .key +# il segreto è stampato UNA VOLTA — con --json è il campo .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # ruota; agenteye keys disable ci-bot --yes per revocare ``` -## Esegui una query salvata o ad-hoc +## Esegui una query salvata o ad hoc ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' agenteye --json query run errs --arg prod | jq '.rows' # una query salvata + un $1 posizionale ``` -## Esamina un incidente in modo non interattivo +## Triage di un incident non interattivamente ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> Le mutazioni saltano automaticamente il prompt di conferma sotto `--json` o quando stdin non è un TTY, quindi gli agenti non si bloccano mai; passa `--yes`/`-y` per saltarlo esplicitamente altrove. +> Le mutazioni saltano automaticamente il prompt di conferma con `--json` o quando stdin non è un TTY, quindi gli agenti non si bloccano mai; passa `--yes`/`-y` per saltarlo esplicitamente altrove. ## Gestione del codice di uscita in uno script @@ -146,7 +146,7 @@ esac ## Forme di output JSON -| Comando | stdout JSON (con `--json`) | +| Comando | JSON stdout (con `--json`) | |---|---| | `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` o `{"logged_in": false}` | | `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` | @@ -155,15 +155,15 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` mostrato una sola volta) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` mostrato una volta) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (qualsiasi) | l'oggetto risorsa, o `{"deleted": true, "id"}` per le eliminazioni | +| create/update/delete (qualsiasi) | l'oggetto risorsa, o `{"deleted": true, "id"}` per eliminazioni | | failure (qualsiasi, con `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` su stdout | - Ogni elemento **event** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. - Ogni elemento **evaluation** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. - Ogni elemento **session** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -`--fields` di ogni comando accetta esattamente i nomi dei campi del suo elemento — l'insieme differisce tra `sessions` e `evals`, quindi un nome valido per uno potrebbe essere rifiutato dall'altro. \ No newline at end of file +Ogni `--fields` del comando accetta esattamente i nomi dei campi del suo elemento — l'insieme è diverso tra `sessions` e `evals`, quindi un nome valido per uno può essere rifiutato dall'altro. \ No newline at end of file diff --git a/docs/it/agenteye/deployment.mdx b/docs/it/agenteye/deployment.mdx index c123297e..1b206c21 100644 --- a/docs/it/agenteye/deployment.mdx +++ b/docs/it/agenteye/deployment.mdx @@ -1,16 +1,17 @@ --- title: "Deployment" -description: "Documentazione del Deployment di AgentEye." +description: "Documentazione di AgentEye Deployment." --- -Questa guida copre il deployment del server AgentEye e della dashboard in produzione. + +Questa guida copre il deployment del server AgentEye e del dashboard in produzione. --- ## Panoramica dell'architettura ``` - [ Macchine agenti AI ] [ Infrastruttura personale ] + [ macchine agenti AI ] [ Tua infrastruttura ] Python SDK | scrive JSONL +----------------------+ @@ -20,104 +21,103 @@ Questa guida copre il deployment del server AgentEye e della dashboard in produz v | +--------+ | +----------------------+ | Server |<------+--->| ClickHouse 24+ | - +--------+ | | (eventi / analitiche)| + +--------+ | | (eventi / analytics) | ^ | +----------------------+ API | | | | +----------------------+ - +-----------+ +- - >| Redis 7+ (facoltativo)| - | Dashboard | +----------------------+ + +-----------+ +- - >| Redis 7+ (opzionale) | + | Dashboard | +----------------------+ +-----------+ ``` -- **Server**: servizio HTTP Rust; riceve batch di eventi, li scrive su ClickHouse e mantiene lo stato relazionale in PostgreSQL. -- **Dashboard**: app Next.js; legge e scrive esclusivamente attraverso l'API del server. +- **Server**: servizio HTTP in Rust; riceve batch di eventi, li scrive in ClickHouse e mantiene lo stato relazionale in PostgreSQL. +- **Dashboard**: app web Next.js; legge e scrive esclusivamente tramite l'API del server. - **agenteye-collector**: deployato su macchine agenti, non sull'host del server. -- **Postgres 15+**: OBBLIGATORIO. (Aggiornato dalla versione 14 nel rilascio multi-tenant; lo schema dell'appartenenza organizzativa utilizza una chiave esterna `ON DELETE SET NULL` con elenco di colonne, che è disponibile solo in Postgres 15+. Aggiornare Postgres prima di eseguire il deployment di questa versione.) Archivia lo stato OLTP: `api_keys`, `users`, `sessions`, `evaluation_jobs` (coda), `dashboards`, `saved_queries`, `otp_codes`, più le tabelle multi-tenant `orgs`, `org_memberships`, `org_settings`. -- **ClickHouse 24+**: OBBLIGATORIO. L'archivio di analitiche per ogni evento acquisito. Engine: `ReplacingMergeTree`, partizionato per mese, ordinato per `(session_id, ts, dedup_key)`. Il server si connette tramite `CLICKHOUSE_URL`; il bundle `deploy/base/clickhouse/` fornisce una configurazione single-node ottimizzata per le prestazioni. **Requisito multi-tenant:** la configurazione bundled abilita la gestione dell'accesso SQL + `users_without_row_policies_can_read_rows=false` in modo che il server possa creare un utente e una politica di riga ClickHouse di sola lettura per organizzazione (il confine di isolamento imposto dal motore per l'editor SQL e l'agente AI). Se fornisci la tua configurazione ClickHouse, trasferisci queste impostazioni (vedi `deploy/base/clickhouse/configmap.yaml`). -- **Redis 7+**: *facoltativo* cache condiviso + backend per rate-limit. Il server e la dashboard si connettono entrambi tramite `REDIS_URL`. Se assente, entrambi degradano elegantemente a percorsi solo Postgres. Vedi **Redis (cache facoltativo)** di seguito. +- **Postgres 15+**: OBBLIGATORIO. (Aumentato dalla versione 14 nel rilascio multi-tenant; lo schema delle appartenenze all'organizzazione utilizza una chiave esterna con lista di colonne `ON DELETE SET NULL`, che richiede Postgres 15+. Aggiorna Postgres prima di deployare questa versione.) Memorizza lo stato OLTP: `api_keys`, `users`, `sessions`, `evaluation_jobs` (coda), `dashboards`, `saved_queries`, `otp_codes`, più le tabelle multi-tenant `orgs`, `org_memberships`, `org_settings`. +- **ClickHouse 24+**: OBBLIGATORIO. L'archivio di analytics per ogni evento ingestionato. Engine: `ReplacingMergeTree`, partizionato per mese, ordinato per `(session_id, ts, dedup_key)`. Il server si connette tramite `CLICKHOUSE_URL`; il `deploy/base/clickhouse/` incluso fornisce una configurazione single-node ottimizzata per le prestazioni. **Requisito multi-tenant:** la configurazione inclusa abilita la gestione dell'accesso SQL + `users_without_row_policies_can_read_rows=false` affinché il server possa creare un utente ClickHouse di sola lettura + politica di riga per organizzazione (il limite di isolamento applicato dal motore per l'editor SQL e l'agente AI). Se fornisci la tua configurazione ClickHouse, riporta queste impostazioni (vedi `deploy/base/clickhouse/configmap.yaml`). +- **Redis 7+**: *opzionale* cache condivisa + backend per il rate-limiting. Sia il server che il dashboard si connettono tramite `REDIS_URL`. Se assente, entrambi si degradano elegantemente a percorsi solo Postgres. Vedi **Redis (cache opzionale)** di seguito. --- ## Server -### Estrai l'immagine +### Scarica l'immagine ```bash echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> Le build attuali vengono pubblicate con `beta-latest`; `latest` viene assegnato solo ai rilasci stabili. Per la produzione, fissa un tag specifico `:v`; vedi [Tag immagine disponibili](#available-image-tags). +> I build attuali sono pubblicati sotto `beta-latest`; `latest` è assegnato solo ai rilasci stabili. Per la produzione, usa un tag specifico `:v`; vedi [Tag di immagine disponibili](#available-image-tags). ### Variabili di ambiente | Variabile | Obbligatoria | Default | Descrizione | |---|---|---|---| -| `DATABASE_URL` | Sì | nessuna | DSN Postgres. Stringa di connessione libpq standard con schema `postgres://`. Supporta `?sslmode=require` e altri parametri libpq. La password non deve contenere `/`, `+`, o `=`; usa `openssl rand -hex` per generare password sicure per URL. | -| `ADMIN_KEY` | No | nessuna | Chiave API amministratore bootstrap. Eseguita con tutti i permessi ad ogni avvio. Ruota cambiando il valore e riavviando. | -| `LISTEN_ADDR` | No | `0.0.0.0:8080` | Indirizzo TCP su cui fare il bind | +| `DATABASE_URL` | Sì | nessuno | DSN PostgreSQL. Stringa di connessione libpq standard con schema `postgres://`. Supporta `?sslmode=require` e altri parametri libpq. La password non deve contenere `/`, `+` o `=`; usa `openssl rand -hex` per generare password sicure per gli URL. | +| `ADMIN_KEY` | No | nessuno | Chiave API admin di bootstrap. Effettuato un upsert con tutti i permessi ad ogni avvio. Ruota modificando il valore e riavviando. | +| `LISTEN_ADDR` | No | `0.0.0.0:8080` | Indirizzo TCP da assegnare | | `MAX_BODY_BYTES` | No | `134217728` (128 MB) | Dimensione massima del corpo della richiesta | -| `ADMIN_EMAIL` | No | nessuna | Email dell'utente amministratore bootstrap. Eseguita con tutti i permessi ad ogni avvio e contrassegnata come protetta: non può essere disabilitata o avere i permessi modificati tramite la dashboard/API. Per ruotare l'amministratore bootstrap, cambia `ADMIN_EMAIL` e riavvia; la nuova email viene eseguita come protetta, e la precedente mantiene la sua protezione fino a quando non viene manualmente cancellata dal database. | -| `ALLOWED_EMAILS` | No | nessuna (tutti bloccati) | Elenco separato da virgole di email consentite per la creazione e l'accesso degli utenti. Supporta indirizzi esatti (`user@example.com`) e wildcard di dominio (`*@example.com`). Se non impostato, nessun utente può essere creato o accedere. **Solo seed al primo avvio**: popola la lista consentita dell'organizzazione predefinita al primo avvio; successivamente la pagina [`//settings`](#operational-settings) di ogni organizzazione è la fonte della verità e cambiare questa variabile di ambiente non ha effetto. | -| `SMTP_HOST` | No | nessuna | Nome host del server SMTP per l'invio di email OTP. Se non impostato, i codici OTP vengono registrati su stdout. | +| `ADMIN_EMAIL` | No | nessuno | Email utente admin di bootstrap. Effettuato un upsert con tutti i permessi ad ogni avvio e contrassegnato come protetto: non può essere disabilitato o avere i permessi modificati tramite dashboard/API. Per ruotare l'admin di bootstrap, modifica `ADMIN_EMAIL` e riavvia; il nuovo email viene effettuato come upsert protetto, e il precedente mantiene la protezione finché non viene manualmente cancellata nel database. | +| `ALLOWED_EMAILS` | No | nessuno (tutti bloccati) | Lista separata da virgole di email consentite per la creazione e l'accesso degli utenti. Supporta indirizzi esatti (`user@example.com`) e wildcard di dominio (`*@example.com`). Se non impostato, nessun utente può essere creato o effettuare l'accesso. **Solo seed di primo avvio**: popola la lista consentita dell'organizzazione predefinita al primo avvio; in seguito la pagina [`//settings`](#operational-settings) di ogni organizzazione è la fonte di verità e modificare questa variabile di ambiente non ha effetto. | +| `SMTP_HOST` | No | nessuno | Hostname del server SMTP per l'invio di email OTP. Se non impostato, i codici OTP vengono registrati a stdout. | | `SMTP_PORT` | No | `587` | Porta del server SMTP | -| `SMTP_USERNAME` | No | nessuna | Nome utente di autenticazione SMTP | -| `SMTP_PASSWORD` | No | nessuna | Password di autenticazione SMTP | -| `SMTP_FROM` | No | nessuna | Indirizzo email del mittente per le email OTP | -| `SMTP_TLS` | No | STARTTLS | STARTTLS viene utilizzato a meno che tu non lo disabiliti esplicitamente: `false` o `0` invia testo semplice (nessun TLS); qualsiasi altro valore — incluso non impostato — abilita STARTTLS. | -| `DASHBOARD_URL` | No | default incorporato | Origine della dashboard utilizzata per creare sia il collegamento magico dell'email OTP che i collegamenti magici dell'incidente nelle notifiche di avviso. Se non impostato, torna al default incorporato (e, solo per OTP, all'origine della dashboard derivata dalla richiesta). Impostalo per configurazioni con dominio diviso in modo che sia i collegamenti email che Slack/incidente puntino alla tua dashboard. Vedi **URL collegamento magico email** di seguito; la maggior parte degli operatori non ha bisogno di impostarlo. | -| `SESSION_TTL_SECS` | No | `86400` (24 h) | Durata della sessione della dashboard in secondi. **Solo seed al primo avvio**: modifica per organizzazione tramite [`//settings`](#operational-settings) dopo il primo deployment. | -| `OTP_TTL_SECS` | No | `600` (10 min) | Periodo di validità del codice OTP in secondi. **Solo seed al primo avvio**: modifica per organizzazione tramite [`//settings`](#operational-settings) dopo il primo deployment. | -| `REDIS_URL` | No | nessuna | Backend cache condiviso facoltativo + rate-limit, ad es. `redis://redis:6379/0`. Quando impostato, il server memorizza nella cache le ricerche di chiavi API autenticate, l'aggregato `/models` della dashboard, l'elenco delle sessioni e il facet dell'elenco env; sposta anche il rate limiting della richiesta OTP da Postgres COUNT a Redis INCR. Se non impostato o non raggiungibile, il server funziona senza cache (il limite OTP torna a Postgres, ogni altra chiamata di cache cade alla fonte della verità). Vedi **Redis (cache facoltativo)** di seguito. | -| `CLICKHOUSE_URL` | **Sì** | nessuna | URL di base dell'istanza ClickHouse, ad es. `http://clickhouse:8123`. Il server applica il suo schema di eventi a questo database ad ogni avvio e si rifiuta di avviarsi se non riesce a raggiungere ClickHouse. Vedi **ClickHouse (archivio di analitiche richiesto)** di seguito. | -| `CLICKHOUSE_DATABASE` | No | `agenteye` | Nome database (schema) di ClickHouse. Il server lo crea all'avvio se non esiste. | -| `ORG_CH_SECRET` | No (single-tenant) / **Sì (multi-org)** | default dev | Chiave HMAC da cui viene derivata la password ClickHouse per tenant di ogni organizzazione. L'editor SQL e `run_query` dell'agente AI vengono eseguiti come utente ClickHouse di sola lettura dell'organizzazione, la cui politica di riga impone l'isolamento dei tenant nel motore. I deployment single-tenant si avviano bene con il default dev incorporato; **prima di eseguire il provisioning di una seconda organizzazione DEVI impostare un valore forte e stabile**, perché la CLI `agenteye-orgctl org create` si rifiuta di eseguire il default dev incorporato. Ruotarlo rende orfano ogni utente ClickHouse dell'organizzazione fino al successivo avvio che li riprovvigiona (la riconciliazione al tempo di avvio ripara questo automaticamente). Mantienilo segreto e invariato tra le repliche. Il provisioning dell'organizzazione è solo operatore; vedi **Organizzazioni (multi-tenancy)** di seguito. | -| `DEFAULT_ORG_NAME` | No | `Default` | Nome visualizzato sottoposto a seed per l'organizzazione predefinita incorporata. **Solo seed al primo avvio**, e solo mentre l'organizzazione mantiene ancora la sua identità generica appena migrata, applicata all'avvio, quindi ignorata. Una volta che rinomini l'organizzazione (`agenteye-orgctl org rename`) il rinomina è autorevole e questa variabile di ambiente non ha ulteriore effetto. | -| `DEFAULT_ORG_SLUG` | No | `default` | Slug URL per l'organizzazione predefinita incorporata, il percorso della dashboard su cui si trova (`//…`). Stessa semantica di primo-avvio-solo / pristino-solo di `DEFAULT_ORG_NAME`. Deve essere 1-40 caratteri alfanumerici minuscoli con singoli trattini interni e non essere una [parola riservata](#organizations-multi-tenancy); un valore non valido viene ignorato (l'organizzazione mantiene `default`). Consente a un'installazione single-tenant di presentarsi come ad es. `/acme` invece di `/default` senza alcun passaggio CLI post-deploy. | -| `RUST_LOG` | No | `info` | Verbosità del registro (`debug`, `warn`, `error`, `agenteye_server=trace`) | -| `EVALUATOR_ENDPOINT` | No | nessuna | URL di base del tuo servizio valutatore (ad es. `http://evaluator:9000`). Quando non impostato l'intera pipeline di valutazione è un no-op; non vengono scritte righe di coda, nessun worker viene eseguito. Vedi [Evaluation Suite](/it/agenteye/evaluation-suite). | -| `EVALUATOR_TOKEN` | No | nessuna | Inviato come `Authorization: Bearer ` al valutatore. **Deve essere uguale allo stesso valore con cui è configurato il servizio valutatore.** Facoltativo solo se il tuo valutatore è configurato senza token. | -| `EVALUATOR_WORKERS` | No | `2` | Concorrenza: numero di attività di lavoro per istanza di server che inviano valutazioni. Sicuro per l'esecuzione su più server con scalabilità orizzontale. | +| `SMTP_USERNAME` | No | nessuno | Username di autenticazione SMTP | +| `SMTP_PASSWORD` | No | nessuno | Password di autenticazione SMTP | +| `SMTP_FROM` | No | nessuno | Indirizzo email del mittente per le email OTP | +| `SMTP_TLS` | No | STARTTLS | STARTTLS è utilizzato a meno che non lo disabiliti esplicitamente: `false` o `0` invia in chiaro (senza TLS); qualsiasi altro valore — incluso non impostato — abilita STARTTLS. | +| `DASHBOARD_URL` | No | default integrato | Origine del dashboard utilizzata per costruire sia il link magico dell'email OTP che i link magici negli incidenti nelle notifiche di alert. Se non impostato, torna a un default integrato (e, solo per OTP, all'origine derivata dal dashboard per prima). Imposta questo per configurazioni con domini separati affinché sia le email che i link Slack/incidenti puntino al tuo dashboard. Vedi **URL link magico email** di seguito; la maggior parte degli operatori non ha bisogno di impostare questo. | +| `SESSION_TTL_SECS` | No | `86400` (24 h) | Durata della sessione dashboard in secondi. **Solo seed di primo avvio**: modifica per organizzazione tramite [`//settings`](#operational-settings) dopo il primo deploy. | +| `OTP_TTL_SECS` | No | `600` (10 min) | Periodo di validità del codice OTP in secondi. **Solo seed di primo avvio**: modifica per organizzazione tramite [`//settings`](#operational-settings) dopo il primo deploy. | +| `REDIS_URL` | No | nessuno | Cache condivisa opzionale + backend per il rate-limiting, ad esempio `redis://redis:6379/0`. Se impostato, il server memorizza in cache le ricerche di chiavi API autenticate, l'aggregato `/models` del dashboard, l'elenco delle sessioni e la faccia dell'elenco env; sposta anche il rate-limiting delle richieste OTP da PostgreSQL COUNT a Redis INCR. Se non impostato o irraggiungibile, il server funziona senza cache (il limite OTP torna a PostgreSQL, ogni altra chiamata di cache cade attraverso alla fonte di verità). Vedi **Redis (cache opzionale)** di seguito. | +| `CLICKHOUSE_URL` | **Sì** | nessuno | URL di base dell'istanza ClickHouse, ad esempio `http://clickhouse:8123`. Il server applica il suo schema di eventi a questo database ad ogni avvio e rifiuta di avviarsi se non riesce a raggiungere ClickHouse. Vedi **ClickHouse (archivio analytics obbligatorio)** di seguito. | +| `CLICKHOUSE_DATABASE` | No | `agenteye` | Nome del database (schema) ClickHouse. Il server lo crea all'avvio se non esiste. | +| `ORG_CH_SECRET` | No (single-tenant) / **Sì (multi-org)** | default di sviluppo | Chiave HMAC da cui è derivata la password ClickHouse per tenant di ogni organizzazione. L'editor SQL e la `run_query` dell'agente AI vengono eseguiti come l'utente ClickHouse di sola lettura dell'organizzazione, la cui politica di riga applica l'isolamento del tenant nel motore. I deployment single-tenant si avviano correttamente con il default di sviluppo integrato; **prima di provisioning di una seconda organizzazione DEVI impostare un valore forte e stabile**, poiché il CLI `agenteye-orgctl org create` rifiuta di funzionare con il default di sviluppo integrato. Ruotarlo orfana ogni utente ClickHouse dell'organizzazione fino al prossimo avvio che li re-provisiona (la riconciliazione al momento dell'avvio guarisce questo automaticamente). Mantienilo segreto e invariato attraverso le repliche. Il provisioning dell'organizzazione stesso è solo per operatori; vedi **Organizzazioni (multi-tenancy)** di seguito. | +| `DEFAULT_ORG_NAME` | No | `Default` | Nome visualizzato seminato per l'organizzazione predefinita integrata. **Solo seed di primo avvio**, e solo mentre l'organizzazione mantiene ancora la sua identità generica appena migrata, applicato all'avvio, quindi ignorato. Una volta rinominata l'organizzazione (`agenteye-orgctl org rename`) il cambio di nome è autorevole e questa variabile di ambiente non ha ulteriori effetti. | +| `DEFAULT_ORG_SLUG` | No | `default` | Slug URL per l'organizzazione predefinita integrata, il percorso dashboard in cui vive (`//…`). Stessa semantica di solo primo avvio / pristino come `DEFAULT_ORG_NAME`. Deve essere 1-40 caratteri alfanumerici minuscoli con singoli trattini interni e non una [parola riservata](#organizations-multi-tenancy); un valore non valido viene ignorato (l'organizzazione mantiene `default`). Permette a un'installazione single-tenant di presentarsi come ad esempio `/acme` invece di `/default` senza alcun passaggio CLI post-deploy. | +| `RUST_LOG` | No | `info` | Verbosità del log (`debug`, `warn`, `error`, `agenteye_server=trace`) | +| `EVALUATOR_ENDPOINT` | No | nessuno | URL di base del tuo servizio valutatore (ad esempio `http://evaluator:9000`). Se non impostato l'intera pipeline di valutazione è un no-op; nessuna riga di coda viene scritta, nessun worker viene eseguito. Vedi [Suite di valutazione](/it/agenteye/evaluation-suite). | +| `EVALUATOR_TOKEN` | No | nessuno | Inviato come `Authorization: Bearer ` al valutatore. **Deve uguagliare lo stesso valore con cui è configurato il servizio valutatore.** Opzionale solo se il tuo valutatore è configurato senza token. | +| `EVALUATOR_WORKERS` | No | `2` | Concorrenza: numero di task worker per istanza server che inviano valutazioni. Sicuro da eseguire su più server scalati orizzontalmente. | | `EVALUATOR_CLAIM_BATCH` | No | `4` | Numero massimo di valutazioni che un singolo worker rivendica per tick. I batch vengono inviati **concorrentemente**, quindi la concorrenza totale sul tuo endpoint valutatore è `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | | `EVALUATOR_POLL_IDLE_SECS` | No | `2` | Quanto tempo un worker dorme tra i tentativi di invio quando nulla è dovuto. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | No | `10` | Cadenza di fallback finale (secondi) per i poll `GET /evaluate/{id}` quando il valutatore non restituisce un `next_poll_secs` per risposta e non annuncia un `default_poll_interval_secs` da `GET /config`. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | No | `30000` | Timeout per richiesta HTTP al valutatore (millisecondi). | -| `EVALUATOR_MAX_ATTEMPTS` | No | `5` | Dopo questo numero di tentativi falliti una valutazione viene registrata come terminale `error` (o `timeout` se i fallimenti erano timeout di richiesta). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | No | `300` (5 min) | Con quale frequenza il server recupera nuovamente `GET /config` dal valutatore. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | No | `3600` (1 h) | Tempo di wallclock massimo che una sessione può rimanere nella coda di polling prima che AgentEye la termini come `timeout`. Protegge da un valutatore che restituisce `pending` per sempre. | -| `ALERT_WORKERS` | No | `1` | Concorrenza: numero di attività di lavoro per istanza di server che valutano le regole di avviso. Vedi [Alerts](/it/agenteye/alerts). | -| `ALERT_CLAIM_BATCH` | No | `16` | Numero massimo di avvisi che un singolo worker rivendica per tick. | -| `ALERT_POLL_IDLE_SECS` | No | `5` | Quanto tempo un worker di avvisi dorme quando la coda è vuota. | -| `ALERT_REQUEST_TIMEOUT_MS` | No | `15000` | Timeout di valutazione per trigger (query ClickHouse + HTTP del canale in uscita). | -| `ALERT_MAX_ATTEMPTS` | No | `5` | Fallimenti transienti consecutivi prima che un avviso si riprogrammi al suo ritmo normale invece del backoff esponenziale. | -| `AUDIT_WORKERS` | No | `1` | Concorrenza: numero di attività di lavoro per istanza di server che eseguono gli audit. Vedi [Audits](/it/agenteye/audits). | -| `AUDIT_CLAIM_BATCH` | No | `1` | Numero massimo di audit dovuti che un singolo worker rivendica per tick. Un'indagine agentica è un lungo loop, quindi il default è 1. | +| `EVALUATOR_POLLING_INTERVAL_SECS` | No | `10` | Cadenza di fallback finale (secondi) per i poll `GET /evaluate/{id}` quando il valutatore non ritorna un `next_poll_secs` per risposta e non pubblicizza un `default_poll_interval_secs` da `GET /config`. | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | No | `30000` | Timeout per richiesta HTTP verso il valutatore (millisecondi). | +| `EVALUATOR_MAX_ATTEMPTS` | No | `5` | Dopo questo numero di tentativi falliti una valutazione viene registrata come terminale `error` (o `timeout` se i fallimenti erano timeout di richieste). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | No | `300` (5 min) | Con quale frequenza il server ri-raccoglie `GET /config` dal valutatore. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | No | `3600` (1 h) | Massimo tempo wallclock una sessione può rimanere nella coda di polling prima che AgentEye la termini come `timeout`. Protegge da un valutatore che ritorna `pending` per sempre. | +| `ALERT_WORKERS` | No | `1` | Concorrenza: numero di task worker per istanza server che valutano le regole di alert. Vedi [Alert](/it/agenteye/alerts). | +| `ALERT_CLAIM_BATCH` | No | `16` | Numero massimo di alert che un singolo worker rivendica per tick. | +| `ALERT_POLL_IDLE_SECS` | No | `5` | Quanto tempo un worker di alert dorme quando la coda è vuota. | +| `ALERT_REQUEST_TIMEOUT_MS` | No | `15000` | Timeout di valutazione per trigger (query ClickHouse + HTTP canale in uscita). | +| `ALERT_MAX_ATTEMPTS` | No | `5` | Fallimenti transienti consecutivi prima che un alert si riprogrammi alla sua cadenza normale invece del backoff esponenziale. | +| `AUDIT_WORKERS` | No | `1` | Concorrenza: numero di task worker per istanza server che eseguono gli audit. Vedi [Audit](/it/agenteye/audits). | +| `AUDIT_CLAIM_BATCH` | No | `1` | Numero massimo di audit dovuti che un singolo worker rivendica per tick. Un'indagine agenticità è un lungo ciclo, quindi il default è 1. | | `AUDIT_POLL_IDLE_SECS` | No | `30` | Quanto tempo un worker di audit dorme quando nessun audit è dovuto. | -| `AUDIT_REQUEST_TIMEOUT_MS` | No | `30000` | Timeout per query di politica su ClickHouse (millisecondi). | -| `AUDIT_LLM_TIMEOUT_MS` | No | `1440000` | Timeout per la chiamata di investigazione agentica al servizio assistente AI. Un loop agente completo funziona per minuti; mantienilo SOPRA il `AGENTEYE_AUDIT_TIMEOUT_MS` dell'agente stesso in modo che l'agente restituisca i suoi risultati parziali prima che il server rinunci. | -| `AUDIT_MAX_ATTEMPTS` | No | `5` | Fallimenti transienti consecutivi prima che un audit si riprogrammi al suo ritmo normale invece del backoff esponenziale. | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | No | — | L'indagine agentica dell'audit chiama il servizio `agent` dell'assistente AI, **riutilizzando la stessa connessione dell'assistente** — quindi impostali entrambi anche su **server** (i manifesti/compose bundled lo fanno). Entrambi impostati ⇒ gli audit eseguono l'investigazione AI; uno qualsiasi non impostato ⇒ gli audit eseguono **solo politica** (il passaggio di politica SQL deterministico viene comunque eseguito), indipendentemente dal flag `llm_enabled` per audit. L'agente deve avere anche un LLM configurato — vedi [assistant.md](/it/agenteye/assistant). | +| `AUDIT_REQUEST_TIMEOUT_MS` | No | `30000` | Timeout per query di politica per query contro ClickHouse (millisecondi). | +| `AUDIT_LLM_TIMEOUT_MS` | No | `1440000` | Timeout per la chiamata di indagine agenticità al servizio assistente AI. Un ciclo di agente completo funziona per minuti; tieni questo SOPRA il `AGENTEYE_AUDIT_TIMEOUT_MS` dell'agente stesso affinché l'agente ritorni i suoi risultati parziali prima che il server rinunci. | +| `AUDIT_MAX_ATTEMPTS` | No | `5` | Fallimenti transienti consecutivi prima che un audit si riprogrammi alla sua cadenza normale invece del backoff esponenziale. | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | No | — | L'indagine agenticità dell'audit chiama il servizio `agent` dell'assistente AI, **riutilizzando la stessa connessione dell'assistente** — quindi imposta anche questi due sul **server** (i manifesti/compose inclusi lo fanno). Entrambi impostati ⇒ gli audit eseguono l'indagine AI; uno qualsiasi non impostato ⇒ gli audit eseguono **solo politica** (il pass di politica SQL deterministico ancora funziona), indipendentemente dal flag `llm_enabled` per audit. L'agente deve anche avere un LLM configurato — vedi [assistant.md](/it/agenteye/assistant). | -**Servizio assistente AI — impostazioni di audit e sandbox.** L'indagine agentica e il suo sandbox Python in-pod sono sintonizzati sul **servizio agente** (non sul server), tutti con prefisso `AGENTEYE_AUDIT_*` e tutti facoltativi: +**Servizio assistente AI — impostazioni audit e sandbox.** L'indagine agenticità e il suo sandbox Python in-pod sono sintonizzati sul **servizio agente** (non il server), tutti con il prefisso `AGENTEYE_AUDIT_*` e tutti opzionali: | Variabile | Default | Significato | |---|---|---| -| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Turni agente max per indagine. | -| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Wallclock per un'indagine (20 min). Deve rimanere **sotto** il `AUDIT_LLM_TIMEOUT_MS` del server. | -| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Indagini concorrenti per pod agente (separato dal budget dell'assistente di chat). | -| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Limiti per-script per la jail bubblewrap. | +| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Massimi turni agente per indagine. | +| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Wallclock per un'indagine (20 min). Deve stare **sotto** il `AUDIT_LLM_TIMEOUT_MS` del server. | +| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Indagini concorrenti per pod agente (separate dal budget dell'assistente di chat). | +| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Limiti per script per il sandbox bubblewrap. | -**Requisito della piattaforma sandbox.** La sandbox del codice di audit esegue il Python del modello dentro una jail bubblewrap, che ha bisogno di **spazi dei nomi utente non privilegiati**. Il pod agente deve consentire i flag `clone()` — imposta `seccompProfile: Unconfined` (k8s) o `security_opt: [seccomp:unconfined]` (compose) sull'agente. Dove il kernel del nodo disabilita gli spazi dei nomi utente non privilegiati (ad es. alcune immagini GKE COS), il sandbox **il precheck fallisce e l'auditor degrada automaticamente a solo SQL** — nessun errore, solo un `sandbox_available: false` su `/health` dell'agente. +**Requisito della piattaforma sandbox.** Il sandbox di codice audit esegue il Python del modello all'interno di un jail bubblewrap, che ha bisogno di **namespace utente senza privilegi**. Il pod agente deve consentire i flag `clone()` — imposta `seccompProfile: Unconfined` (k8s) o `security_opt: [seccomp:unconfined]` (compose) sull'agente. Dove il kernel del nodo disabilita i namespace utente senza privilegi (ad esempio alcune immagini GKE COS), il sandbox **fallisce il preflight e l'auditor si degrada a solo SQL automaticamente** — nessun errore, solo un `sandbox_available: false` su `/health` dell'agente. -### Esecuzione +### Esegui -Imposta `DATABASE_URL` e `CLICKHOUSE_URL` nel tuo ambiente (il server si rifiuta di avviarsi senza ClickHouse), quindi passali al container: +Imposta `DATABASE_URL` nel tuo ambiente, quindi passalo al contenitore: ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest @@ -128,36 +128,36 @@ Il server esegue automaticamente le migrazioni del database all'avvio; nessun pa ### Health check ``` -GET /health # liveness - sempre {"status":"ok"} una volta che il processo è in su +GET /health # liveness - sempre {"status":"ok"} una volta che il processo è attivo GET /ready # readiness - 200 quando Postgres + ClickHouse sono raggiungibili, altrimenti 503 ``` -Nessuna autenticazione richiesta. Usa `/health` per i probe **liveness** e `/ready` per i probe **readiness** / load-balancer. `/ready` controlla le dipendenze hard che il server non può servire senza (Postgres + ClickHouse), quindi un server che è in esecuzione ma non può raggiungere il suo database viene tolto dalla rotazione e mostrato come `NotReady`; Redis viene segnalato ma non fallisce mai la readiness. Sui manifesti Kubernetes bundled il probe di readiness già punta a `/ready` e la liveness rimane su `/health`. Vedi [enterprise-docs/health-monitoring.md](/it/agenteye/health-monitoring) per il quadro completo, incluso l'alerting opzionale nativo di Kubernetes per il fallimento del pod a Slack. +Nessuna autenticazione richiesta. Usa `/health` per probe di **liveness** e `/ready` per probe di **readiness** / load-balancer. `/ready` controlla le dipendenze hard che il server non può servire senza (Postgres + ClickHouse), quindi un server che è in esecuzione ma non può raggiungere il suo database viene tolto dalla rotazione e appare come `NotReady`; Redis è segnalato ma non fallisce mai la readiness. Nei manifesti Kubernetes inclusi il probe di readiness punta già a `/ready` e la liveness rimane su `/health`. Vedi [enterprise-docs/health-monitoring.md](/it/agenteye/health-monitoring) per il quadro completo, incluso il pod-failure alerting nativo di Kubernetes opt-in a Slack. -### URL collegamento magico email +### URL link magico email -Le email di accesso OTP contengono un pulsante **apri la dashboard** one-tap. Cliccandolo l'utente arriva su `/login?token=&email=
`; la dashboard scambia quella coppia per una sessione e reindirizza all'app, senza re-immissione manuale del codice. Il server risolve l'origine della dashboard utilizzata per costruire il collegamento in tre livelli: +Le email OTP login contengono un pulsante **apri il dashboard** one-tap. Cliccarlo atterra l'utente su `/login?token=&email=
`; il dashboard scambia quella coppia per una sessione e reindirizza all'app, senza re-entry manuale del codice. Il server risolve l'origine del dashboard utilizzata per costruire il link in tre livelli: -1. **Header `X-AgentEye-Dashboard-Url`**: impostato automaticamente dal proxy `/api/auth/otp/request` della dashboard dalla sua stessa origine pubblica. In un deployment same-origin (server e dashboard condividono un host dietro un ingress che inoltra gli header proxy), **nessuna configurazione è richiesta**. -2. **Variabile di ambiente `DASHBOARD_URL`**: impostalo se la tua dashboard è raggiungibile su un'origine diversa da quella che l'endpoint della richiesta OTP del server vede (split `api.example.com` / `app.example.com`), o se il tuo ingress non propaga l'host pubblico nel pod della dashboard (quindi `request.nextUrl.origin` altrimenti si risolverebbe in un bind wildcard come `0.0.0.0:3000`). Esempio: `DASHBOARD_URL=https://app.example.com`. -3. **Default**: `https://app.befailproof.ai`, usato solo se nessuno dei precedenti è presente. +1. **Header `X-AgentEye-Dashboard-Url`**: impostato automaticamente dal proxy `/api/auth/otp/request` del dashboard dalla sua stessa origine pubblica. In un deployment same-origin (server e dashboard condividono un host dietro un ingress che inoltra i proxy header), **nessuna configurazione è richiesta**. +2. **Variabile di ambiente `DASHBOARD_URL`**: imposta questo se il tuo dashboard è raggiungibile su un'origine diversa da quella che l'endpoint OTP request del server vede (dividi `api.example.com` / `app.example.com`), o se il tuo ingress non propaga l'host pubblico nel pod dashboard (così `request.nextUrl.origin` altrimenti si risolverebbe in un bind wildcard come `0.0.0.0:3000`). Esempio: `DASHBOARD_URL=https://app.example.com`. +3. **Default**: `https://app.befailproof.ai`, utilizzato solo se nessuno dei precedenti è presente. -Il valore dell'header viene validato: solo le origini `https://*` e loopback (`http://localhost*`, `http://127.0.0.1*`) vengono accettate, e gli indirizzi di bind wildcard (`0.0.0.0`, `[::]`) vengono rifiutati anche con lo schema `https://`. Tutto il resto cade al livello 2. +Il valore dell'header è validato: solo origini `https://*` e loopback (`http://localhost*`, `http://127.0.0.1*`) sono accettate, e gli indirizzi di bind wildcard (`0.0.0.0`, `[::]`) sono rifiutati anche con lo schema `https://`. Tutto il resto cade attraverso al livello 2. -Impostalo su un cluster in esecuzione con un one-liner; nessun file, nessuna ricostruzione di kustomize: +Impostalo su un cluster in esecuzione con un one-liner; nessun file, nessuna ricostruzione kustomize: ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -Questo attiva un rollout; i nuovi pod raccolgono il valore alla prima richiesta. Nota che l'override vive solo sulla Deployment; un successivo `kustomize build | kubectl apply` rispetto all'overlay lo cancellerà a meno che tu non aggiunga la stessa variabile di ambiente al patch `server-env.yaml` del tuo overlay. +Questo attiva un rollout; i nuovi pod raccolgono il valore alla prima richiesta. Nota che l'override vive solo su Deployment; un successivo `kustomize build | kubectl apply` verso l'overlay lo cancellerà a meno che tu non aggiunga la stessa variabile di ambiente alla patch `server-env.yaml` del tuo overlay. --- ## Dashboard -### Estrai l'immagine +### Scarica l'immagine ```bash docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest @@ -167,16 +167,16 @@ docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest | Variabile | Obbligatoria | Default | Descrizione | |---|---|---|---| -| `AGENTEYE_SERVER_URL` | Sì | nessuna | URL di base del server, ad es. `http://localhost:8080` | -| `AGENTEYE_API_KEY` | Sì | nessuna | Chiave API che la dashboard utilizza per autenticarsi al server. Ha bisogno di tutti i permessi (chiave admin consigliata). | -| `AE_LOG_LEVEL` | No | `info` | Verbosità del registro lato server: `debug`, `info`, `warn`, `error`. Impostalo su `debug` per vedere le linee di richiesta/risposta upstream e le tracce di validazione della sessione quando diagnostichi i problemi. | -| `AE_LOG_JSON` | No | auto | `1` forza l'output JSON-per-riga; `0` forza l'output leggibile dall'uomo. Se non impostato, JSON è abilitato automaticamente se `NODE_ENV=production`. JSON è consigliato in produzione in modo che i registri si analizzino in modo ordinato con `jq` o un aggregatore di registri. | -| `AE_ANALYTICS_DISABLED` | No | nessuna | Impostalo su `1`/`true` per disabilitare la telemetria di utilizzo del prodotto anonima della dashboard. Vedi [Telemetry & privacy](#telemetry--privacy) di seguito. | -| `REDIS_URL` | No | nessuna | Backend cache condiviso facoltativo, ad es. `redis://redis:6379/0`. Quando impostato, la dashboard memorizza nella cache i risultati di `validateSession()` tra le repliche e condivide la cache di recupero di Next.js per le rotte proxy aggregate di latenza / elenco env. I limiti di rate OTP di richiesta e verifica edge-side utilizzano anche Redis quando presente (che si aprono se Redis non è raggiungibile; il limite lato server è la difesa di sicurezza). Vedi **Redis (cache facoltativo)** di seguito. | -| `AGENTEYE_AGENT_URL` | No | nessuna | URL di base del servizio `agent` assistente AI opzionale, ad es. `http://agent:9100`. **Lascialo non impostato per nascondere completamente l'assistente**: nessuna bolla dell'assistente appare nella dashboard. Vedi [enterprise-docs/assistant.md](/it/agenteye/assistant). | -| `AGENTEYE_AGENT_TOKEN` | No | nessuna | Segreto condiviso che la dashboard presenta al servizio `agent`. Deve corrispondere al `AGENTEYE_AGENT_TOKEN` configurato sull'agente. Vedi [enterprise-docs/assistant.md](/it/agenteye/assistant). | +| `AGENTEYE_SERVER_URL` | Sì | nessuno | URL di base del server, ad esempio `http://localhost:8080` | +| `AGENTEYE_API_KEY` | Sì | nessuno | Chiave API che il dashboard utilizza per autenticarsi al server. Ha bisogno di tutti i permessi (chiave admin consigliata). | +| `AE_LOG_LEVEL` | No | `info` | Verbosità del log lato server: `debug`, `info`, `warn`, `error`. Imposta a `debug` per vedere linee di richiesta/risposta upstream e tracce di validazione della sessione quando si diagnosticano i problemi. | +| `AE_LOG_JSON` | No | auto | `1` forza output JSON per linea; `0` forza output leggibile dall'uomo. Se non impostato, JSON è abilitato automaticamente se `NODE_ENV=production`. JSON è consigliato in produzione affinché i log si analizzino correttamente con `jq` o un aggregatore di log. | +| `AE_ANALYTICS_DISABLED` | No | nessuno | Imposta a `1`/`true` per disabilitare la telemetria di utilizzo del prodotto anonima del dashboard. Vedi [Telemetria & privacy](#telemetry--privacy) di seguito. | +| `REDIS_URL` | No | nessuno | Backend cache condiviso opzionale, ad esempio `redis://redis:6379/0`. Se impostato, il dashboard memorizza in cache i risultati di `validateSession()` attraverso le repliche e condivide la cache fetch di Next.js per le route proxy dei rollup latenza / lista env. I limiti di rate OTP di richiesta e verifica anche lato edge utilizzano Redis quando presente (fallendo aperto se Redis è irraggiungibile; il limite lato server è il backstop di sicurezza). Vedi **Redis (cache opzionale)** di seguito. | +| `AGENTEYE_AGENT_URL` | No | nessuno | URL di base del servizio `agent` assistente AI opzionale, ad esempio `http://agent:9100`. **Lascialo non impostato per nascondere completamente l'assistente**: nessuna bolla assistente appare nel dashboard. Vedi [enterprise-docs/assistant.md](/it/agenteye/assistant). | +| `AGENTEYE_AGENT_TOKEN` | No | nessuno | Segreto condiviso che il dashboard presenta al servizio `agent`. Deve corrispondere al `AGENTEYE_AGENT_TOKEN` configurato sull'agente. Vedi [enterprise-docs/assistant.md](/it/agenteye/assistant). | -### Esecuzione +### Esegui ```bash docker run -d --restart unless-stopped \ @@ -187,91 +187,91 @@ docker run -d --restart unless-stopped \ ghcr.io/agenteye-enterprise/dashboard:beta-latest ``` -### Telemetria e privacy +### Telemetria & privacy -La dashboard invia **analitiche di utilizzo del prodotto anonimo** al servizio di analitiche di Exosphere (PostHog): quali pagine della dashboard vengono visualizzate e una manciata di azioni dell'interfaccia utente come la creazione di una chiave API o la rivalutazione di una sessione. Questo segnale di utilizzo informa quali funzioni sono prioritarie. +Il dashboard invia **telemetria di utilizzo del prodotto anonima** al servizio di analytics di Exosphere (PostHog): quali pagine del dashboard sono visualizzate e una manciata di azioni UI come la creazione di una chiave API o la rivalutazione di una sessione. Questo segnale di utilizzo informa quali funzionalità hanno la priorità. -- **Nessun dato di agente, sessione o evento esce mai dalla tua infrastruttura.** Solo l'utilizzo dell'interfaccia utente della dashboard viene segnalato. Gli URL delle pagine vengono spogliati degli identificatori prima dell'invio, e gli operatori vengono identificati solo da un id interno opaco, mai per email. -- La telemetria è **abilitata per impostazione predefinita**. Per disattivarla completamente, imposta `AE_ANALYTICS_DISABLED=1` nel container della dashboard e riavvia. -- Le analitiche vengono inviate al percorso `/ingest` della dashboard stessa, che la dashboard inoltra tramite proxy a PostHog (`https://us.i.posthog.com`). Mantenere le richieste first-party significa che i blocchi degli annunci del browser non le riducono. Il **container della dashboard** ha bisogno dell'accesso in uscita a PostHog; se è bloccato, la telemetria non fa silenziosamente nulla e la dashboard è inalterata. +- **Nessun dato di agente, sessione o evento lascia mai la tua infrastruttura.** Solo l'utilizzo dell'interfaccia utente del dashboard è segnalato. Gli URL delle pagine vengono spogliati degli identificatori prima dell'invio, e gli operatori sono identificati solo da un id opaco interno, mai per email. +- La telemetria è **abilitata per default**. Per disabilitarla completamente, imposta `AE_ANALYTICS_DISABLED=1` sul contenitore dashboard e riavvia. +- Gli analytics vengono inviati al percorso `/ingest` del dashboard, che il dashboard rimanda tramite proxy a PostHog (`https://us.i.posthog.com`). Mantenere le richieste first-party significa che gli ad-blocker del browser non le eliminano. Il **contenitore dashboard** ha bisogno di accesso in uscita a PostHog; se è bloccato, la telemetria silenziosamente non fa nulla e il dashboard non è interessato. --- -## Assistente AI (facoltativo) +## Assistente AI (opzionale) -Un assistente AI in-dashboard consente al tuo team di porre domande sui dati del loro agente in linguaggio naturale (riassumendo le sessioni, elaborando SQL per l'editor `/queries` e trasformando le query salvate in tile della dashboard) senza lasciare la dashboard. Funziona come un container `agent` interno separato (su Claude Agent SDK) che solo la dashboard può raggiungere, e rimane **disabilitato fino a quando non configuri un endpoint LLM**. +Un assistente AI in-dashboard consente al tuo team di porre domande sui dati del loro agente in linguaggio naturale (riassumendo sessioni, bozze SQL per l'editor `/queries`, e trasformando query salvate in tile dashboard) senza lasciare il dashboard. Funziona come un contenitore `agent` interno separato (su Claude Agent SDK) che solo il dashboard può raggiungere, e rimane **disabilitato finché non configuri un endpoint LLM**. -Per abilitarlo, imposta, sul servizio `agent`, una connessione LLM (**Portkey** tramite `PORTKEY_API_KEY` + uno slug del catalogo modelli `AGENTEYE_AGENT_MODEL=@/`, Anthropic diretto tramite `ANTHROPIC_API_KEY`, un altro gateway tramite `ANTHROPIC_BASE_URL`, o Bedrock/Vertex), una chiave di dati **dedicata**, e un `AGENTEYE_AGENT_TOKEN` condiviso che corrisponde alla dashboard. Gli utenti della dashboard hanno inoltre bisogno del permesso `agent:use`. +Per abilitarlo imposta, sul servizio `agent`, una connessione LLM (**Portkey** tramite `PORTKEY_API_KEY` + uno slug di catalogo modello `AGENTEYE_AGENT_MODEL=@/`, Anthropic diretto tramite `ANTHROPIC_API_KEY`, un altro gateway tramite `ANTHROPIC_BASE_URL`, o Bedrock/Vertex), una chiave dati **dedicata**, e un `AGENTEYE_AGENT_TOKEN` condiviso che corrisponde al dashboard. Gli utenti del dashboard hanno inoltre bisogno del permesso `agent:use`. -Per la chiave di dati dell'assistente non conia nulla a mano: scegli un segreto casuale, impostalo come `AGENTEYE_API_KEY` su `agent` **e** come `AGENT_API_KEY` su `server`, e il server lo propaga all'avvio con un set di permessi fisso. Il suo accesso ai dati è di sola lettura (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), e inoltre contiene scope di authoring con controllo di approvazione (`dashboards:write`, `queries:write`, `queries:run`) in modo che possa elaborare e convalidare le query salvate e costruire tile della dashboard per conto dell'utente; tutto SQL viene comunque eseguito attraverso il ruolo ClickHouse di sola lettura dell'organizzazione, quindi questo amplia ciò che l'assistente può creare, non i dati che può raggiungere. Gli scope sono fissi nel codice e non possono essere ampliati per configurazione. Quella chiave è protetta; non può essere disabilitata o rigenerata tramite l'API, solo ruotata cambiando il valore e riavviando. Non riutilizzare mai la chiave admin/dashboard per questo. +Per la chiave dati dell'assistente non coni nulla a mano: scegli un segreto casuale, impostalo come `AGENTEYE_API_KEY` sull'agente **e** come `AGENT_API_KEY` sul server, e il server lo popola all'avvio con un insieme di permessi fisso. Il suo accesso ai dati è di sola lettura (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), e inoltre contiene ambiti di authoring gestiti da approvazione (`dashboards:write`, `queries:write`, `queries:run`) affinché possa abbozzare e convalidare query salvate e costruire tile dashboard per conto dell'utente; tutto l'SQL ancora viene eseguito tramite il ruolo ClickHouse di sola lettura dell'organizzazione, quindi questo amplia ciò che l'assistente può creare, non che dati può raggiungere. Gli ambiti sono fissi nel codice e non possono essere ampliati dalla configurazione. Quella chiave è protetta; non può essere disabilitata o rigenerata tramite l'API, solo ruotata modificando il valore e riavviando. Non riutilizzare mai la chiave admin/dashboard per questo. -Setup completo, il riferimento completo alle variabili di ambiente, opzioni di telemetria e il modello di sicurezza sono in **[enterprise-docs/assistant.md](/it/agenteye/assistant)**. +Setup completo, il riferimento completo delle variabili di ambiente, le opzioni di telemetria, e il modello di sicurezza sono in **[enterprise-docs/assistant.md](/it/agenteye/assistant)**. --- -## ClickHouse (archivio di analitiche richiesto) +## ClickHouse (archivio analytics obbligatorio) -ClickHouse mantiene le tue dashboard responsabili ad alti volumi di eventi e consente all'editor SQL `/queries` di unire tra loro eventi, valutazioni e sessioni in un singolo archivio. È l'archivio canonico richiesto per ogni evento acquisito, ogni risultato di valutazione terminale e gli aggregati derivati per-sessione. PostgreSQL contiene le tabelle di stato relazionale / mutabile (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); la superficie analitica vive in ClickHouse in modo che i rollup della dashboard e le tue query SQL possono scansionare e unirle in modo nativo, senza round-trip tra database. Il server si rifiuta di avviarsi senza `CLICKHOUSE_URL`. +ClickHouse mantiene i tuoi dashboard reattivi a volumi di evento elevati e consente all'editor SQL `/queries` di unire tra eventi, valutazioni e sessioni in un unico archivio. È l'archivio canonico obbligatorio per ogni evento ingestionato, ogni risultato di valutazione terminale, e gli aggregati derivati per sessione. PostgreSQL contiene le tabelle relazionali / stato mutevole (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); la superficie analitica vive in ClickHouse affinché i rollup del dashboard e le tue query SQL possano scansionarlo e unirlo nativamente, senza round-trip cross-database. Il server rifiuta di avviarsi senza `CLICKHOUSE_URL`. ### Schema -Tre oggetti ClickHouse vengono creati all'avvio del server, tutti idempotenti (`CREATE IF NOT EXISTS`): +Tre oggetti ClickHouse vengono creati all'avvio del server, tutto idempotente (`CREATE IF NOT EXISTS`): -- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, partizionato per `toYYYYMM(ts)`, ordinato per `(session_id, ts, dedup_key)`. Gli inserti duplicati (i retry del collettore) collassano in una singola riga al momento della fusione; il server calcola una chiave di dedup SHA-256 deterministica `dedup_key` per ogni evento in modo che i retry siano sicuri. -- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, partizionato per `toYYYYMM(finished_at)`, ordinato per `(session_id, finished_at, dedup_key)`. Scritto una volta per ogni risultato di valutazione terminale dalla pipeline del valutatore. Lo stesso modello di chiave di dedup di `events`. -- **`agenteye.agent_sessions`**: una **VIEW** su `agenteye.events`, non una tabella fisica. Ogni colonna è derivata (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, ecc.). Nessun upsert per evento e nessun backfill separato; la view riflette automaticamente qualsiasi cosa sia in `events`. +- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, partizionato per `toYYYYMM(ts)`, ordinato per `(session_id, ts, dedup_key)`. Gli inserti duplicati (tentativi di raccoglitore) collassano a una singola riga al momento del merge; il server calcola un `dedup_key` SHA-256 deterministico per ogni evento affinché i tentativi siano sicuri. +- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, partizionato per `toYYYYMM(finished_at)`, ordinato per `(session_id, finished_at, dedup_key)`. Scritto una volta per risultato di valutazione terminale dalla pipeline di valutatore. Stesso modello di dedup-key come `events`. +- **`agenteye.agent_sessions`**: una **VIEW** su `agenteye.events`, non una tabella fisica. Ogni colonna è derivata (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, ecc.). Nessun upsert per evento e nessun backfill separato; la view si riflette automaticamente in qualunque cosa sia in `events`. -Per la compatibilità all'indietro con le query salvate che fanno riferimento a `analytics.evaluations` / `analytics.sessions`, il server crea anche un database `analytics` di ClickHouse con view sui table `agenteye.*`; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` si risolvono tutti correttamente. +Per la compatibilità all'indietro con query salvate che fanno riferimento a `analytics.evaluations` / `analytics.sessions`, il server crea anche un database `analytics` ClickHouse con view sopra le tabelle `agenteye.*`; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` si risolvono tutti correttamente. ### Configurazione -Il docker-compose bundled e `deploy/base/clickhouse/` forniscono un servizio ClickHouse sintonizzato per il carico di lavoro di AgentEye: +Il docker-compose incluso e il `deploy/base/clickhouse/` forniscono un servizio ClickHouse sintonizzato per il carico di lavoro di AgentEye: -- Memoria richiesta 2 GiB / limite 4 GiB nell'overlay di base fornito (dimensionato per adattarsi ai piccoli nodi POC/staging); i clienti di produzione dovrebbero sovrapporre — il floor consigliato è 2c / 4Gi richiesta, 6c / 8Gi limite. `max_server_memory_usage_to_ram_ratio=0.9` +- 2 GiB richiesto / 4 GiB limite di memoria nell'overlay base fornito (dimensionato per adattarsi a piccoli nodi POC/staging); i clienti di produzione dovrebbero sovrapporre verso l'alto — il minimo consigliato è 2c / 4Gi richiesta, 6c / 8Gi limite. `max_server_memory_usage_to_ram_ratio=0.9` - 5 GiB mark cache + 8 GiB cache non compressa - `background_pool_size=16`, `background_merges_mutations_concurrency_ratio=2` - MergeTree: `parts_to_throw_insert=3000`, `parts_to_delay_insert=1500`, `non_replicated_deduplication_window=1000` -- `local_io_method=auto` (io_uring sui kernel supportati) -- `fsync_metadata=0`: accettabile per inserimento at-least-once + dedup ReplacingMergeTree -- `query_log` abilitato con TTL di 30 giorni; `query_thread_log` rimosso (costoso ad alto QPS) -- `max_execution_time=30` per le query lato utente -- 100 GiB PVC nel template StatefulSet (gli overlay dei clienti DOVREBBERO eseguire l'override con una classe di archiviazione SSD veloce per la produzione) +- `local_io_method=auto` (io_uring su kernel supportati) +- `fsync_metadata=0`: accettabile per l'ingest almeno una volta + dedup ReplacingMergeTree +- `query_log` abilitato con TTL di 30 giorni; `query_thread_log` rimosso (costoso a QPS elevato) +- `max_execution_time=30` per query lato utente +- 100 GiB PVC al template StatefulSet (gli overlay dei clienti DOVREBBERO sovraporre a una classe di archiviazione SSD veloce per la produzione) ### Backup -L'intero set di dati viene acquisito nightly in un singolo archivio ripristinabile, quindi una perdita di cluster o archiviazione è recuperabile. ClickHouse viene sottoposto a backup automaticamente dal CronJob `agenteye-backup` giornaliero, che scarica sia PostgreSQL che ClickHouse in un unico passaggio. ClickHouse viene letto sulla sua API HTTP: `agenteye.events` e `agenteye.evaluations` vengono scaricati nel formato nativo di ClickHouse (le view e le politiche di riga vengono ricreate dal server all'avvio, quindi i dati della tabella sono il quadro completo) e raggruppati con il dump Postgres in un singolo archivio compresso caricato sul tuo archivio di oggetti. +Il tuo set di dati completo è catturato ogni notte in un singolo archivio ripristinabile, quindi una perdita di cluster o archiviazione è recuperabile. ClickHouse viene sottoposto automaticamente a backup dal CronJob giornaliero `agenteye-backup`, che scarica sia PostgreSQL che ClickHouse in un unico passaggio. ClickHouse viene letto tramite la sua API HTTP: `agenteye.events` e `agenteye.evaluations` vengono scaricati nel formato nativo ClickHouse (le view e le politiche di riga vengono ricreate dal server all'avvio, quindi i dati della tabella sono l'immagine completa) e raggruppati con lo scarico Postgres in un unico archivio compresso caricato nel tuo object storage. -Il bucket di destinazione e le credenziali cloud vengono configurati per overlay. Vedi la sezione **Backups** di [enterprise-docs/kubernetes-deployment.md](/it/agenteye/kubernetes-deployment) per la configurazione del caricamento e i passaggi di ripristino. +Il bucket di destinazione e le credenziali cloud sono configurati per overlay. Vedi la sezione **Backup** di [enterprise-docs/kubernetes-deployment.md](/it/agenteye/kubernetes-deployment) per la configurazione dell'upload e i passaggi di ripristino. --- -## Redis (cache facoltativo) +## Redis (cache opzionale) -Redis è un backend cache condiviso **facoltativo** + rate-limit utilizzato dal server e dalla dashboard. Con Redis deployato e `REDIS_URL` impostato su entrambi i servizi: +Redis è un **opzionale** cache condiviso + backend per il rate-limiting utilizzato dal server e dal dashboard. Con Redis deployato e `REDIS_URL` impostato su entrambi i servizi: -- **Server** memorizza nella cache le ricerche di chiavi API autenticate, gli elenchi `/events/environments` + `/evaluations/environments`, il rollup `/events/latency_aggregate` (la query più pesante che la dashboard esegue il polling), l'elenco `/sessions`, e cambia il rate limiting della richiesta OTP da un `COUNT(*)` Postgres a un `INCR + EXPIRE` Redis. -- **Dashboard** memorizza nella cache i risultati di `validateSession()` in modo che le 10-20 chiamate API autenticate che un tipico caricamento di pagina emette condividano tutte un singolo controllo di sessione upstream. Inoltre limita la velocità di richiesta e verifica OTP al bordo della dashboard. +- **Server** memorizza in cache le ricerche di chiavi API autenticate, gli elenchi `/events/environments` + `/evaluations/environments`, il rollup `/events/latency_aggregate` (la query più pesante che il dashboard polling), l'elenco `/sessions`, e passa il rate-limiting delle richieste OTP da un `COUNT(*)` di Postgres a un `INCR + EXPIRE` di Redis. +- **Dashboard** memorizza in cache i risultati di `validateSession()` così le 10-20 chiamate API autenticate che un tipico caricamento di pagina emette condividono tutti una singola verifica di sessione upstream. Limita anche le richieste OTP-request e OTP-verify nel lato edge del dashboard. -**Entrambi i servizi degradano elegantemente se Redis non è raggiungibile.** Ogni chiamata di cache restituisce `Err` entro un timeout limitato e il chiamante torna alla fonte della verità (Postgres sul server, il server Rust a monte sulla dashboard). Il rate limiting OTP torna al percorso `COUNT(*)` Postgres sul server (la proprietà di sicurezza è preservata); il limite OTP edge della dashboard non ha successo mentre il limite lato server continua a valere. Redis essere inattivo degrada la latenza, non la correttezza. +**Entrambi i servizi si degradano elegantemente se Redis è irraggiungibile.** Ogni chiamata di cache ritorna `Err` entro un timeout limitato e il chiamante torna alla fonte di verità (Postgres sul server, il server Rust upstream sul dashboard). Il rate-limiting OTP torna al percorso `COUNT(*)` di Postgres sul server (la proprietà di sicurezza è preservata); il limite OTP edge del dashboard fallisce aperto mentre il limite lato server ancora regge. Redis essere giù degrada la latenza, non la correttezza. ### Configurazione -Il bundle docker-compose include già un servizio Redis e cablagna `REDIS_URL=redis://redis:6379/0` nel server e nella dashboard. Per utilizzare un Redis esterno, imposta `REDIS_URL` sul tuo endpoint e rimuovi il servizio `redis` dal file compose. +Il bundle docker-compose include già un servizio Redis e cablaggio di `REDIS_URL=redis://redis:6379/0` nel server e dashboard. Per utilizzare un Redis esterno, imposta `REDIS_URL` al tuo endpoint e rimuovi il servizio `redis` dal file compose. ### Memoria + persistenza -L'immagine Redis bundled si esegue con `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. La persistenza AOF significa che la cache sopravvive ai riavvii del container; `everysec` è il giusto equilibrio di durabilità/perf perché perdere l'ultimo secondo di scritture di cache è innocuo. L'evizione LRU limita la crescita della memoria. +L'immagine Redis inclusa funziona con `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. La persistenza AOF significa che la cache sopravvive ai riavvii del contenitore; `everysec` è il bilancio corretto di durabilità/perf perché perdere l'ultimo secondo di scritture della cache è innocuo. L'evizione LRU limita la crescita della memoria. ### Quando NON deployare Redis -- Dev/QA single-instance. Le cache in-process sul server da solo forniscono la maggior parte del beneficio per-replica; Redis aggiunge la condivisione tra-replica che i setup single-instance non hanno. +- Single-instance dev/QA. Le cache in-process sul server solo forniscono la maggior parte del beneficio per replica; Redis aggiunge la condivisione cross-replica che i setup single-instance non hanno bisogno. - Installazioni air-gapped dove il costo operazionale di eseguire un servizio in più supera il guadagno di latenza. --- ## Docker Compose (consigliato) -Un `docker-compose.yml` è disponibile nel repo `agenteye-enterprise/releases`. Avvia Postgres, ClickHouse, Redis, il server e la dashboard con un singolo comando. +Un `docker-compose.yml` è disponibile nel repo `agenteye-enterprise/releases`. Porta su Postgres, il server, e il dashboard con un singolo comando. ```bash GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ @@ -281,10 +281,10 @@ GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ cd agenteye ``` -**Esegui l'override dei default tramite `.env`:** +**Sovrascrivi i default tramite `.env`:** ``` -# Usa password sicure per URL (nessun /, +, o = caratteri). +# Usa password sicure per URL (senza /, +, o = caratteri). # Genera con: openssl rand -hex 24 POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret @@ -293,7 +293,7 @@ ADMIN_KEY=your-admin-secret ADMIN_EMAIL=admin@yourcompany.com ALLOWED_EMAILS=*@yourcompany.com -# SMTP per email OTP (ometti per registrare i codici OTP su stdout) +# SMTP per email OTP (ometti per registrare i codici OTP a stdout) # SMTP_HOST=smtp.yourprovider.com # SMTP_PORT=587 # SMTP_USERNAME=your-smtp-user @@ -307,13 +307,13 @@ RUST_LOG=info docker compose up -d ``` -**Arresta (mantiene il volume dati):** +**Ferma (mantiene il volume dati):** ```bash docker compose down ``` -**Arresta e cancella tutti i dati:** +**Ferma e cancella tutti i dati:** ```bash docker compose down -v @@ -323,76 +323,76 @@ docker compose down -v ## Impostazioni operative -Un piccolo set di manopole operative che erano precedentemente fissate dalle variabili di ambiente sono ora modificabili per organizzazione dalla pagina **`//settings`** della dashboard; ogni organizzazione configura la propria. Le modifiche hanno effetto entro secondi, senza riavvio e senza redistribuzione. +Un piccolo set di manopole operative che usavano stare fissate da variabili di ambiente sono ora modificabili per organizzazione dalla pagina **`//settings`** del dashboard; ogni organizzazione configura la propria. Le modifiche hanno effetto entro pochi secondi, senza riavvio e senza redeploy. -| Impostazione | Variabile env bootstrap | Cosa controlla | +| Impostazione | Variabile di ambiente bootstrap | Cosa controlla | |---|---|---| | Accessi consentiti | `ALLOWED_EMAILS` | Email (o wildcard `*@domain.com`) autorizzate a ricevere un OTP ed essere aggiunte come utenti | -| Permessi utente predefiniti | `DEFAULT_USER_PERMISSIONS` | Token di autorizzazione separati da virgole preselezionati quando un admin apre **+ nuovo utente**. Ogni token deve essere una delle stringhe elencate sotto [API key permissions](/it/agenteye/api-keys). Predefinito al preset `standard`: accesso di sola lettura più le azioni quotidiane on-call (attiva rivalutazioni, esegui query, riconosci incidenti, usa l'assistente). | -| Durata della sessione | `SESSION_TTL_SECS` | Quanto tempo un accesso alla dashboard rimane valido prima della riautenticazione. La dashboard ricontrolla la sessione a monte ogni 5 secondi, quindi un aggiornamento delle autorizzazioni su `//users` ha effetto sulla richiesta successiva dell'utente interessato, senza riaccesso. | -| Durata del codice monouso | `OTP_TTL_SECS` | Quanto tempo un OTP / collegamento magico rimane utilizzabile | -| Canali di notifica di avviso | `ALERTS_ENABLED_CHANNELS` | Elenco separato da virgole di tipi di canale che il dispatcher di avviso è autorizzato a utilizzare: `email`, `slack`, `webhook`. La configurazione per-avviso viene comunque creata su `//alerts/`, ma il dispatcher filtra ogni consegna in uscita attraverso questo set; un canale disabilitato qui cortocircuita con una riga di audit `skipped_disabled`. Il canale `dashboard` (l'inserimento dell'audit locale) è sempre consentito. Predefinito a tutti e tre su. | +| Permessi utente predefiniti | `DEFAULT_USER_PERMISSIONS` | Token di autorizzazione separati da virgole preselezionati quando un admin apre **+ nuovo utente**. Ogni token deve essere una delle stringhe elencate sotto [Permessi chiave API](/it/agenteye/api-keys). Impostazione predefinita al preset `standard`: accesso di sola lettura più le azioni quotidiane on-call (attivare rivalutazioni, eseguire query, riconoscere incidenti, usare l'assistente). | +| Durata della sessione | `SESSION_TTL_SECS` | Quanto tempo un accesso al dashboard rimane valido prima della ri-auth. Il dashboard ri-controlla la sessione upstream ogni 5 secondi, quindi un aggiornamento del permesso su `//users` ha effetto sulla richiesta successiva dell'utente interessato, senza riaccesso. | +| Durata del codice una tantum | `OTP_TTL_SECS` | Quanto tempo un OTP / link magico rimane utilizzabile | +| Canali di notifica degli alert | `ALERTS_ENABLED_CHANNELS` | Lista separata da virgole di tipi di canale che il dispatcher di alert è autorizzato a usare: `email`, `slack`, `webhook`. La configurazione per-alert è ancora creata su `//alerts/`, ma il dispatcher filtra ogni consegna in uscita attraverso questo set; un canale disabilitato qui cortocircuita con una riga di audit `skipped_disabled`. Il canale `dashboard` (l'inserimento di audit locale) è sempre consentito. Impostazione predefinita a tutti e tre. | ### Come funziona il bootstrap -Le impostazioni vengono archiviate per organizzazione in `org_settings`. Al primo avvio, il server propaga le righe mancanti dell'organizzazione predefinita dalla variabile di ambiente corrispondente (o un default ragionevole se la variabile di ambiente non è impostata). Dopo ciò, **il valore archiviato è la fonte della verità e la variabile di ambiente viene ignorata**; cambiare la variabile di ambiente su un riavvio successivo non influenzerà il valore di un'organizzazione live, e le organizzazioni aggiuntive iniziano dai default e configurano le proprie. +Le impostazioni sono memorizzate per organizzazione in `org_settings`. Al primo avvio, il server popola le righe mancanti dell'organizzazione predefinita dalla variabile di ambiente corrispondente (o un sensato default se la variabile di ambiente non è impostata). In seguito, **il valore memorizzato è la fonte di verità e la variabile di ambiente viene ignorata**; modificare la variabile di ambiente su un riavvio successivo non interesserà il valore di un'organizzazione viva, e le organizzazioni aggiuntive iniziano da default e configurano le loro. Questo significa: -- Per un deployment fresco, imposta le variabili di ambiente come mostrato sopra e l'organizzazione predefinita le legge al primo avvio. -- Per cambiare un valore in seguito, accedi alla dashboard e modificalo sotto `//settings`. La modifica si applica entro secondi tra tutte le repliche del server; nessun riavvio necessario. -- Una riga di registro all'avvio registra cosa è stato sottoposto a seed rispetto a cosa era già presente, quindi puoi confermare che il bootstrap ha avuto effetto: +- Per un deploy fresco, imposta le variabili di ambiente come mostrato sopra e l'organizzazione predefinita le legge al primo avvio. +- Per modificare un valore successivamente, accedi al dashboard e modificalo sotto `//settings`. La modifica si applica entro pochi secondi su tutte le repliche del server; nessun riavvio necessario. +- Una linea di log all'avvio registra cosa è stato seminato vs. cosa era già presente, così puoi confermare che il bootstrap ha avuto effetto: ```text INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true ``` -#### Semantica di accesso tra le organizzazioni +#### Semantica di accesso attraverso le organizzazioni -Una sessione e un OTP sono globali all'utente, non a una singola organizzazione, quindi due regole riconciliano le impostazioni per-organizzazione al momento dell'accesso: +Una sessione e un OTP sono globali all'utente, non a una singola organizzazione, quindi due regole riconciliano le impostazioni per organizzazione al momento dell'accesso: -- **Durata della sessione / OTP**: la durata più severa (più breve) tra le organizzazioni a cui l'utente appartiene vince. -- **Accessi consentiti**: il gate combina logicamente (OR) ogni elenco consentito dell'organizzazione con l'appartenenza all'organizzazione: un utente può richiedere un OTP se l'elenco consentito di qualsiasi organizzazione ammette la sua email **o** è già membro di qualsiasi organizzazione. +- **Durata sessione / OTP**: il più rigoroso (più breve) il tempo di vita tra le organizzazioni di cui l'utente è membro vince. +- **Accessi consentiti**: il gate ORs ogni lista di consentiti dell'organizzazione insieme all'appartenenza all'organizzazione: un utente può richiedere un OTP se la lista consentiti di qualunque organizzazione ammette la sua email **o** sono già membri di qualunque organizzazione. -### Autorizzazioni +### Permessi -L'accesso a una pagina `//settings` è controllato da due autorizzazioni: +L'accesso a una pagina `//settings` è gestito da due permessi: - `settings:read`: vedi la pagina e i valori attuali. - `settings:write`: salva le modifiche. -L'utente admin bootstrap (propagato da `ADMIN_EMAIL`) ottiene entrambi automaticamente insieme a ogni altra autorizzazione. Concedili ad altri utenti da `//users` come necessario. +L'utente admin di bootstrap (seminato da `ADMIN_EMAIL`) li ottiene automaticamente insieme a tutti gli altri permessi. Concedili ad altri utenti da `//users` secondo necessità. --- ## Organizzazioni (multi-tenancy) -Un singolo deployment può servire più **organizzazioni** isolate (tenant); ogni riga di dati appartiene a esattamente un'organizzazione e l'isolamento è imposto nel motore del database. Un'installazione single-tenant non ha bisogno di nulla qui; tutti i dati vivono in un'organizzazione `default` incorporata. (Puoi dare a quell'organizzazione un nome più amichevole e un slug URL, in modo che viva a es. `/acme` invece di `/default`, impostando `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` prima del primo avvio, o rinominandola in qualsiasi momento con `agenteye-orgctl org rename`.) +Un singolo deployment può servire molteplici **organizzazioni** isolate (tenant); ogni riga di dati appartiene esattamente a un'organizzazione e l'isolamento è applicato nel motore del database. Un'installazione single-tenant non ha bisogno di nulla qui; tutti i dati vivono in un'organizzazione `default` integrata. (Puoi dare a quell'organizzazione un nome più amichevole e uno slug URL, così vive a es. `/acme` invece di `/default`, impostando `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` prima del primo avvio, o rinominandola in qualsiasi momento con `agenteye-orgctl org rename`.) -**Il provisioning del tenant è solo operatore.** Le organizzazioni e le loro appartenenze vengono create e gestite con la CLI **`agenteye-orgctl`**, che viene fornita **all'interno dell'immagine del server** (insieme a `agenteye-server`) e viene eseguita **all'interno del pod del server esistente**; non c'è **pod/Job separato, nessuna API HTTP, e nessun pulsante dashboard**. Riusa `DATABASE_URL`, `CLICKHOUSE_URL` e `ORG_CH_SECRET` del server. +**Il provisioning del tenant è solo per operatori.** Le organizzazioni e le loro appartenenze sono create e gestite con il CLI **`agenteye-orgctl`**, che viene fornito **dentro l'immagine del server** (insieme a `agenteye-server`) e viene eseguito **dentro il pod del server esistente**; non c'è **nessun pod/Job separato, nessuna API HTTP, e nessun pulsante dashboard**. Riutilizza il `DATABASE_URL` del server, `CLICKHOUSE_URL`, e `ORG_CH_SECRET`. ```bash # Docker Compose - exec nel servizio server in esecuzione: docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp" docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin -# Kubernetes - exec nella Deployment del server in esecuzione: +# Kubernetes - exec nel Deployment server in esecuzione: kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list ``` -Verbi disponibili: `org create | list | rename | delete | purge` e `member add | list | update | remove`, con set di autorizzazioni incorporati `admin`, `standard`, e `read-only`. I membri aggiunti ricevono un OTP al primo accesso alla dashboard. +Verbi disponibili: `org create | list | rename | delete | purge` e `member add | list | update | remove`, con set di permessi integrati `admin`, `standard`, e `read-only`. I membri aggiunti ricevono un OTP al primo accesso al dashboard. -**Prima di creare una seconda organizzazione:** imposta un `ORG_CH_SECRET` forte e stabile (il comando `org create` si rifiuta di eseguire il default dev incorporato) e assicurati che Postgres sia **15+**. **Invariato:** le chiavi API per-organizzazione vengono comunque coniate nella dashboard/API dai membri dell'organizzazione; solo il ciclo di vita org + member si è spostato sulla CLI. Riferimento del comando completo e un esempio pratico: **[enterprise-docs/tenant-management.md](/it/agenteye/tenant-management)**. +**Prima di creare una seconda organizzazione:** imposta un forte, stabile `ORG_CH_SECRET` (il comando `org create` rifiuta di funzionare sul built-in dev default) e assicurati che Postgres sia **15+**. **Invariato:** le chiavi API per organizzazione sono ancora coniate nel dashboard/API dai membri dell'organizzazione; solo il ciclo di vita dell'organizzazione + membro è passato al CLI. Riferimento completo del comando e un esempio lavorato: **[enterprise-docs/tenant-management.md](/it/agenteye/tenant-management)**. --- ## Riempimento della finestra di contesto -Ogni evento `model_response` mostra una **pillola di riempimento del contesto** — token di input più output come percentuale della finestra di contesto di quel modello. Le bande sono `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%), e `reset context` (75–100%). AgentEye risolve gli ID dei modelli comuni automaticamente, quindi nessuna configurazione iniziale è richiesta. +Ogni evento `model_response` mostra una **pillola di riempimento contesto** — token di input più output come percentuale della finestra di contesto di quel modello. Le bande sono `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%), e `reset context` (75–100%). AgentEye risolve gli ID modello comuni automaticamente, quindi nessuna configurazione iniziale è richiesta. -Ogni modello che un'organizzazione invia appare sotto **Settings → model context windows**. Gli utenti con `settings:write` possono eseguire l'override della sua finestra o aggiungere un modello privato/proxy (0–1.000.000 token); `0` significa "sconosciuto" e sopprime la pillola. Le modifiche si applicano agli eventi appena acquisiti. Gli utenti con `settings:read` possono visualizzare l'elenco. +Ogni modello che un'organizzazione invia appare sotto **Impostazioni → finestre di contesto modello**. Gli utenti con `settings:write` possono sovrastare la sua finestra o aggiungere un modello privato/proxy (0–1.000.000 token); `0` significa sconosciuto e sopprima la pillola. Le modifiche si applicano agli eventi appena ingestionati. Gli utenti con `settings:read` possono visualizzare l'elenco. -I nuovi eventi ricevono il riempimento dal momento in cui esegui l'upgrade. Per anche popolare gli eventi **storici** (e l'elenco per-modello) per un deployment esistente, esegui il backfill una tantum — viene fornito all'interno dell'immagine del server (come `agenteye-orgctl`) e si esegue nel pod del server esistente: +I nuovi eventi ottengono il riempimento dal momento in cui aggiorni. Per popolare anche gli eventi **storici** (e la lista per modello) per un deployment esistente, esegui il backfill unico — viene fornito dentro l'immagine del server (come `agenteye-orgctl`) e funziona nel pod server esistente: ```bash # anteprima (stampa la mutazione per-organizzazione, non cambia nulla): @@ -403,25 +403,25 @@ kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window docker compose exec server agenteye-backfill-context-window ``` -È idempotente (sicuro di eseguire di nuovo) e riusa `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` dal pod. Rieseguilo dopo aver modificato le finestre dei modelli se vuoi che gli eventi esistenti vengano ricalcolati. +È idempotente (sicuro di eseguire di nuovo) e riutilizza `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` dal pod. Esegui di nuovo dopo aver modificato le finestre del modello se vuoi che gli eventi esistenti siano ricalcolati. --- ## Considerazioni sulla produzione -- **Postgres**: utilizza un servizio Postgres gestito o un'istanza dedicata con backup regolari. `DATABASE_URL` supporta tutti i parametri libpq standard, incluso `sslmode=require` per le connessioni crittografate. -- **TLS**: metti il server e la dashboard dietro un proxy inverso (nginx, Caddy, Traefik) che termina TLS. -- **Firewall**: la porta del server (default 8080) dovrebbe essere raggiungibile solo dalle macchine collettore e dall'host della dashboard, non da internet pubblico. -- **Chiave admin**: imposta `ADMIN_KEY` su un segreto casuale forte. Dopo il bootstrap, crea chiavi dedicate con scope per collettori e dashboard piuttosto che usare la chiave admin ovunque. -- **Tag immagine**: fissa alla versione nei tuoi manifesti di release (ad es. `server:v0.0.1-beta.48`) in produzione piuttosto che un tag mobile per evitare upgrade indesiderati. Le build beta attuali vengono pubblicate su `beta-latest`; `latest` viene assegnato solo ai rilasci stabili. -- **Monitoraggio della salute**: su Kubernetes il probe di readiness usa `/ready` (raggiungibilità Postgres + ClickHouse) mentre la liveness rimane su `/health`. Per l'alerting a livello di flotta "AgentEye stesso è in su?" a Slack, abilita l'add-on Robusta opzionale; vedi [enterprise-docs/health-monitoring.md](/it/agenteye/health-monitoring). +- **Postgres**: Usa un servizio Postgres gestito o un'istanza dedicata con backup regolari. Il `DATABASE_URL` supporta tutti i parametri libpq standard, incluso `sslmode=require` per le connessioni criptate. +- **TLS**: Metti il server e il dashboard dietro un reverse proxy (nginx, Caddy, Traefik) che termina TLS. +- **Firewall**: La porta del server (default 8080) dovrebbe essere raggiungibile solo da macchine di raccoltore e dall'host del dashboard, non da internet pubblico. +- **Chiave admin**: Imposta `ADMIN_KEY` su un segreto casuale forte. Dopo il bootstrap, crea chiavi scoped dedicate per i raccoglitori e il dashboard piuttosto che usare la chiave admin ovunque. +- **Tag di immagine**: Fissa alla versione nei tuoi manifesti di release (ad esempio, `server:v0.0.1-beta.48`) in produzione piuttosto che un tag fluttuante per evitare aggiornamenti non intenzionali. I build beta attuali vengono pubblicati sotto `beta-latest`; `latest` è assegnato solo ai rilasci stabili. +- **Monitoraggio della salute**: Su Kubernetes il probe di readiness utilizza `/ready` (raggiungibilità Postgres + ClickHouse) mentre la liveness rimane su `/health`. Per il "AgentEye stesso è su?" alerting a livello di flotta a Slack, abilita il complemento Robusta opt-in; vedi [enterprise-docs/health-monitoring.md](/it/agenteye/health-monitoring). --- -## Tag immagine disponibili +## Tag di immagine disponibili | Tag | Descrizione | |-----|-------------| | `latest` | Ultimo rilascio stabile | | `beta-latest` | Ultimo pre-rilascio (beta) | -| `v` | Versione fissata, ad es. `v0.0.1-beta.48` (consigliato per la produzione) | \ No newline at end of file +| `v` | Versione fissa, es. `v0.0.1-beta.48` (consigliato per la produzione) | \ No newline at end of file diff --git a/docs/it/agenteye/getting-started.mdx b/docs/it/agenteye/getting-started.mdx index ed4853bd..529e23c9 100644 --- a/docs/it/agenteye/getting-started.mdx +++ b/docs/it/agenteye/getting-started.mdx @@ -1,35 +1,36 @@ --- -title: "Guida introduttiva ad AgentEye" -description: "Documentazione di AgentEye - Guida introduttiva ad AgentEye." +--- +title: "Iniziare con AgentEye" +description: "Documentazione per iniziare con AgentEye." --- -Questa guida ti accompagna attraverso una configurazione completa di AgentEye: distribuire il server e il dashboard, installare il collector su una macchina agente e strumentare il codice dell'agente Python. +Questa guida ti accompagna attraverso una configurazione completa di AgentEye: distribuire il server e il dashboard, installare il collector su una macchina agente e strumentare il codice del tuo agente Python. --- -## Che cos'è AgentEye? +## Cos'è AgentEye? -AgentEye è una **piattaforma di osservabilità e valutazione auto-hosted per agenti AI**. Registra tutto ciò che fanno i tuoi agenti — ogni fase di un'esecuzione — e valuta automaticamente la qualità di ogni esecuzione completata, così puoi vedere come si comportano i tuoi agenti in produzione e rilevare le regressioni prima che lo facciano i tuoi utenti. +AgentEye è una **piattaforma self-hosted di osservabilità e valutazione per agenti AI**. Registra cosa fanno i tuoi agenti — ogni fase di un'esecuzione — e valuta automaticamente la qualità di ogni esecuzione completata, in modo da poter vedere come si comportano i tuoi agenti in produzione e rilevare le regressioni prima che lo facciano i tuoi utenti. -Il flusso dei dati va in una sola direzione: il codice dell'agente emette **eventi** attraverso l'**SDK Python** → un daemon **collector** leggero raggruppa e li invia al **server** → gli eventi e l'analytics vengono archiviati in **ClickHouse** (lo stato operativo come organizzazioni, utenti, chiavi API, dashboard e query salvate risiede in **Postgres**) → esplori tutto nel **dashboard**. +Il flusso dei dati procede in una sola direzione: il codice del tuo agente emette **eventi** attraverso l'**SDK Python** → un daemon **collector** leggero li raggruppa e li invia al **server** → gli eventi e le analitiche vengono archiviati in **ClickHouse** (lo stato operativo come organizzazioni, utenti, chiavi API, dashboard e query salvate risiede in **Postgres**) → tu esplori tutto nel **dashboard**. Quello che ottieni: -- **Eventi** — la traccia grezza e per-fase di ogni esecuzione di agente (tool call, model call, hook, errori). -- **Sessioni** — quegli eventi aggregati in una riga per esecuzione, ciascuno **automaticamente valutato** e punteggiato. -- **Valutazioni** — punteggi di qualità prodotti dai tuoi servizi di valutazione, così i cali di qualità emergono senza revisione manuale. -- **Query e dashboard** — SQL ClickHouse salvato sui tuoi dati, rappresentato in grafici in dashboard condivisi a livello di organizzazione. -- **Avvisi e incident** — regole di soglia che ti notificano (email, Slack, webhook, in-dashboard) più un flusso di lavoro incident per triaging. -- **CLI e assistente AI** — un client terminal (`agenteye`) e un assistente in-dashboard per fare domande in linguaggio naturale. +- **Eventi** — la traccia grezza, passo dopo passo, di ogni esecuzione dell'agente (tool call, model call, hook, errori). +- **Sessioni** — questi eventi raggruppati in una riga per esecuzione, ciascuno **automaticamente valutato** e assegnato un punteggio. +- **Valutazioni** — punteggi di qualità prodotti dai tuoi servizi di valutazione, in modo che i cali di qualità emergano senza revisione manuale. +- **Query e dashboard** — SQL ClickHouse salvato sui tuoi dati, visualizzati in dashboard condivisi a livello organizzativo. +- **Avvisi e incidenti** — regole soglia che ti notificano (email, Slack, webhook, in-dashboard) più un flusso di lavoro per gli incidenti per triagiarli. +- **CLI e assistente AI** — un client terminale (`agenteye`) e un assistente in-dashboard per fare domande in linguaggio naturale. -Esegui tutto nella tua infrastruttura, come un singolo stack Docker Compose (questa guida), un'installazione Kubernetes in produzione, o un singolo pod co-locato. Il resto di questa guida configura lo stack Compose da capo a fondo. +Esegui tutto nella tua infrastruttura, come uno stack Docker Compose singolo (questa guida), un'installazione Kubernetes di produzione, o un pod co-locato singolo. Il resto di questa guida configura lo stack Compose end to end. --- -## Passaggio 1: Autenticazione +## Passaggio 1: Autenticati -Tutti gli artefatti di AgentEye sono distribuiti dall'organizzazione GitHub `agenteye-enterprise`. Come sviluppatore enterprise puoi generare il tuo GitHub PAT. Segui [enterprise-docs/github-token.md](/it/agenteye/github-token) per i passaggi esatti e le autorizzazioni richieste. +Tutti gli artefatti di AgentEye sono distribuiti dall'organizzazione GitHub `agenteye-enterprise`. Come sviluppatore enterprise puoi generare il tuo GitHub PAT. Segui [enterprise-docs/github-token.md](/it/agenteye/github-token) per i passaggi esatti e i permessi richiesti. ```bash export AGENTEYE_TOKEN= @@ -40,9 +41,9 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin --- -## Passaggio 2: Distribuire il Server e il Dashboard +## Passaggio 2: Distribuisci il Server e il Dashboard -Il server riceve gli eventi dai collector e li rende interrogabili; il dashboard è il luogo in cui li esplori. Gli eventi ingeriti e l'analytics risiedono in ClickHouse (lo store di analytics richiesto), mentre Postgres contiene lo stato operativo come organizzazioni, utenti, chiavi API, dashboard e query salvate. +Il server riceve eventi dai collector e li rende interrogabili; il dashboard è dove li esplori. Gli eventi e le analitiche acquisiti risiedono in ClickHouse (l'analytics store richiesto), mentre Postgres contiene lo stato operativo come organizzazioni, utenti, chiavi API, dashboard e query salvate. **Scarica il file compose pubblicato:** @@ -55,7 +56,7 @@ curl -fsSL \ cd agenteye ``` -**Imposta i tuoi segreti:** +**Imposta i tuoi secret:** Crea un file `.env` in modo che la distribuzione non venga eseguita con le credenziali predefinite `admin`. Come minimo imposta `ADMIN_KEY` e `POSTGRES_PASSWORD`: @@ -64,29 +65,23 @@ POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -Esporta anche `ADMIN_KEY` nella tua shell attuale in modo che i passaggi successivi (ad es. il `curl` del Passaggio 3) possano farvi riferimento direttamente: - -```bash -export ADMIN_KEY=your-admin-secret -``` - **Avvia lo stack:** ```bash docker compose up -d ``` -Questo avvia lo stack completo, incluso lo store di analytics ClickHouse richiesto e una cache Redis opzionale, insieme al server e al dashboard. ClickHouse deve essere healthy affinché il server si avvii. +Questo avvia lo stack completo, incluso l'analytics store ClickHouse richiesto e una cache Redis opzionale, insieme al server e al dashboard. ClickHouse deve essere sano affinché il server si avvii. -Il server è ora in ascolto su `http://localhost:8080` e il dashboard su `http://localhost:3000`. +Il server ora è in ascolto su `http://localhost:8080` e il dashboard su `http://localhost:3000`. -Per le distribuzioni in produzione (Postgres personalizzato, TLS, reverse proxy), vedi [enterprise-docs/deployment.md](/it/agenteye/deployment). +Per distribuzioni di produzione (Postgres personalizzato, TLS, reverse proxy), vedi [enterprise-docs/deployment.md](/it/agenteye/deployment). --- -## Passaggio 3: Creare una Chiave API per il Collector +## Passaggio 3: Crea una Chiave API per il Collector -Ogni collector si autentica con una chiave API scoped. Usa l'`ADMIN_KEY` che hai impostato al Passaggio 2 per crearne una: +Ogni collector si autentica con una chiave API con scope. Utilizza l'`ADMIN_KEY` che hai impostato nel Passaggio 2 per crearne una: ```bash curl -s -X POST http://localhost:8080/keys \ @@ -95,11 +90,11 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -Tu fornisci il valore `key` stesso; usalo nella configurazione del collector al Passaggio 4. Vedi [enterprise-docs/api-keys.md](/it/agenteye/api-keys) per la gestione completa delle chiavi. +Fornisci tu stesso il valore `key`; usalo nella configurazione del collector nel Passaggio 4. Vedi [enterprise-docs/api-keys.md](/it/agenteye/api-keys) per la gestione completa delle chiavi. --- -## Passaggio 4: Installare il Collector +## Passaggio 4: Installa il Collector Su ogni macchina che esegue i tuoi agenti AI, installa il daemon collector. @@ -114,7 +109,7 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> Questo scarica il build **Linux x86_64**. Per macOS (Apple Silicon o Intel), Linux arm64, o setup Docker / systemd / launchd, vedi [collector-installation.md](/it/agenteye/collector-installation), che elenca il download per ogni piattaforma — il comando sopra installa un binario Linux che non funzionerà altrove. +> Questo scarica il build **Linux x86_64**. Per macOS (Apple Silicon o Intel), Linux arm64, o setup Docker / systemd / launchd, vedi [collector-installation.md](/it/agenteye/collector-installation), che elenca il download per ogni piattaforma — il comando qui sopra installa un binario Linux che non funzionerà altrove. **Configura:** @@ -134,7 +129,7 @@ EOF agenteye-collector start ``` -Verifica la connettività con uno flush one-shot (esce dopo aver drenato eventuali eventi in sospeso): +Verifica la connettività con uno svuotamento una tantum (esce dopo aver drenato eventuali eventi in sospeso): ```bash agenteye-collector flush @@ -144,9 +139,9 @@ Per setup Docker, systemd e launchd vedi [enterprise-docs/collector-installation --- -## Passaggio 5: Installare l'SDK Python +## Passaggio 5: Installa l'SDK Python -Su ogni macchina in cui vuoi strumentare il codice dell'agente, installa il wheel da GitHub Releases. +Su ogni macchina dove vuoi strumentare il codice dell'agente, installa il wheel da GitHub Releases. ```bash VERSION=0.0.1b9 @@ -180,56 +175,56 @@ agenteye.event.agent_end( ) ``` -Gli eventi vengono bufferizzati e flushed a `$AGENTEYE_HOME/events/` (o `~/.agenteye/events/` se `AGENTEYE_HOME` non è impostato) ogni 500 ms. Il collector li preleva automaticamente. +Gli eventi vengono messi in buffer e svuotati a `$AGENTEYE_HOME/events/` (o `~/.agenteye/events/` se `AGENTEYE_HOME` non è impostato) ogni 500 ms. Il collector li raccoglie automaticamente. -Vedi [enterprise-docs/python-sdk.md](/it/agenteye/python-sdk) per l'API completa degli eventi. +Vedi [enterprise-docs/python-sdk.md](/it/agenteye/python-sdk) per l'API di evento completa. --- ## Passaggio 7: Visualizza gli Eventi nel Dashboard -Apri `http://your-dashboard-host:3000` e accedi. AgentEye ti invia un codice monouso (o un link magic one-click), quindi non c'è password da gestire. +Apri `http://your-dashboard-host:3000` ed effettua l'accesso. AgentEye ti invia un codice monouso (o un link magic one-click), quindi non c'è una password da gestire. -![The AgentEye sign-in screen, which sends a single-use code to your email](/agenteye/images/login.png) +![La schermata di accesso di AgentEye, che invia un codice monouso alla tua email](/agenteye/images/login.png) -Una volta dentro, la pagina **Events** mostra una traccia live di tutti gli eventi ingeriti. Filtra per `session_id` o `agent_id` per approfondire un'esecuzione specifica. +Una volta dentro, la pagina **Events** mostra una traccia live di tutti gli eventi acquisiti. Filtra per `session_id` o `agent_id` per approfondire un'esecuzione specifica. -![The live Events stream, colour-coded by event type and filterable by environment, agent, and session](/agenteye/images/events-stream.png) +![Il flusso di eventi live, codificato a colori per tipo di evento e filtrabile per ambiente, agente e sessione](/agenteye/images/events-stream.png) -La pagina **Sessions** aggrega quegli eventi in una riga per esecuzione. AgentEye valuta automaticamente le sessioni completate, quindi ogni esecuzione è punteggiata e le regressioni di qualità emergono senza revisione manuale; il punteggio di valutazione più recente appare su ogni riga a colpo d'occhio: +La pagina **Sessions** raggruppa questi eventi in una riga per esecuzione. AgentEye valuta automaticamente le sessioni completate, quindi ogni esecuzione viene assegnata un punteggio e le regressioni di qualità emergono senza revisione manuale; il punteggio di valutazione più recente appare su ogni riga a colpo d'occhio: -![The Sessions list, one row per run, with status pills and evaluation score badges](/agenteye/images/sessions-list.png) +![L'elenco delle sessioni, una riga per esecuzione, con badge di stato e punteggi di valutazione](/agenteye/images/sessions-list.png) -Per configurare come vengono punteggiati le sessioni, vedi [enterprise-docs/evaluation-suite.md](/it/agenteye/evaluation-suite). +Per configurare come vengono valutate le sessioni, vedi [enterprise-docs/evaluation-suite.md](/it/agenteye/evaluation-suite). -Fai clic su qualsiasi sessione per aprire il suo **execution graph**, una vista in stile git di come agenti, tool, hook e model call si sono sviluppati nel tempo, con sub-agenti paralleli sulle loro corsie e una suddivisione per-esecuzione nel pannello destro: +Fai clic su qualsiasi sessione per aprire il suo **execution graph**, una vista nello stile di git di come agenti, tool, hook e model call si sono svolti nel tempo, con sotto-agenti paralleli sulle loro corsie e un breakdown per esecuzione nella barra destra: -![A session's git-style execution graph beside its event timeline, with the tool/model/hook breakdown panel](/agenteye/images/session-detail.png) +![Un execution graph nello stile di git della sessione accanto alla sua timeline di eventi, con il pannello di breakdown tool/model/hook](/agenteye/images/session-detail.png) --- -## Passaggio 8: Esplora, rappresenta in grafici e avvisa +## Passaggio 8: Esplora, crea grafici e configura avvisi -Con gli eventi che fluiscono, le pagine **analyze** trasformano l'attività grezza in risposte, così puoi misurare il comportamento dell'agente, condividere i risultati con il team e ricevere una notifica nel momento in cui qualcosa regredisce. Le pagine del dashboard hanno scope a livello di organizzazione, quindi gli URL che vedi nella barra degli indirizzi sono preceduti dal tuo slug org (`//…`). +Con gli eventi in flusso, le pagine **analyze** trasformano l'attività grezza in risposte, in modo da poter misurare il comportamento dell'agente, condividere i risultati con il team e ricevere una notifica nel momento in cui qualcosa regredisce. Le pagine del dashboard hanno scope organizzativo, quindi gli URL che vedi nella barra degli indirizzi hanno il prefisso del tuo slug org (`//…`). -- **Queries** (`//queries`): inizia da una libreria di query salvate e riutilizzabili sui tuoi eventi e valutazioni (preset built-in più i tuoi)… +- **Queries** (`//queries`): inizia da una libreria di query salvate e riutilizzabili sui tuoi eventi e valutazioni (preset incorporati più i tuoi)… -![The saved-queries library: a grid of reusable queries, both built-in presets and custom ones](/agenteye/images/queries.png) +![La libreria di query salvate: una griglia di query riutilizzabili, sia preset incorporati che personalizzati](/agenteye/images/queries.png) - …quindi aprine una nel compositore SQL per modificarla ed eseguirla con risultati live: + …quindi aprine una nel SQL composer per modificarla ed eseguirla con risultati live: -![The SQL query composer running a saved query, with a schema sidebar and a live result grid](/agenteye/images/query-lab.png) +![Il SQL query composer che esegue una query salvata, con una barra laterale dello schema e una griglia di risultati live](/agenteye/images/query-lab.png) -- **Dashboards** (`//dashboards`): fissa le query come tile di linea, barra, area o torta in dashboard condivisi a livello di organizzazione. +- **Dashboards** (`//dashboards`): fissa le query come tile di linea, barra, area o torta in dashboard condivisi a livello organizzativo. -![A dashboard built from saved queries: an events-per-hour line, an errors-by-type bar, a latency area chart, and tokens-by-model](/agenteye/images/dashboard-fleet.png) +![Un dashboard costruito da query salvate: una linea di eventi per ora, un istogramma di errori per tipo, un grafico di area di latenza e token per modello](/agenteye/images/dashboard-fleet.png) -- **Alerts** (`//alerts`): promuovi qualsiasi soglia in una regola di paging che notifica per email, Slack, webhook o in-dashboard. Vedi [enterprise-docs/alerts.md](/it/agenteye/alerts). +- **Alerts** (`//alerts`): promuovi qualsiasi soglia in una regola di paging che notifica via email, Slack, webhook o in-dashboard. Vedi [enterprise-docs/alerts.md](/it/agenteye/alerts). --- ## Passaggi Successivi -- [Deployment](/it/agenteye/deployment): irrigidisci per la produzione -- [API Keys](/it/agenteye/api-keys): gestisci l'accesso -- [Troubleshooting](/it/agenteye/troubleshooting): diagnostica i problemi \ No newline at end of file +- [Deployment](/it/agenteye/deployment): indurire per la produzione +- [API Keys](/it/agenteye/api-keys): gestire l'accesso +- [Troubleshooting](/it/agenteye/troubleshooting): diagnosticare i problemi \ No newline at end of file diff --git a/docs/it/agenteye/managed-deployment.mdx b/docs/it/agenteye/managed-deployment.mdx index f48d19dd..6fc29a86 100644 --- a/docs/it/agenteye/managed-deployment.mdx +++ b/docs/it/agenteye/managed-deployment.mdx @@ -1,172 +1,171 @@ --- ---- -title: "Distribuzione Gestita nel Vostro Cluster Kubernetes" -description: "Documentazione della distribuzione gestita di AgentEye nel vostro cluster Kubernetes." +title: "Distribuzione gestita nel tuo cluster Kubernetes" +description: "Documentazione della distribuzione gestita di AgentEye nel tuo cluster Kubernetes." --- -AgentEye è una piattaforma di osservabilità e valutazione auto-ospitata per agenti AI e LLM. Cattura sessioni di agenti, chiamate di strumenti, richieste di modelli ed errori, li trasforma in analytics e valutazioni ricercabili, e presenta i risultati in un dashboard con un assistente AI facoltativo in sola lettura. +AgentEye è una piattaforma di osservabilità e valutazione self-hosted per agenti AI e LLM. Cattura sessioni di agenti, chiamate di strumenti, richieste di modelli ed errori, li trasforma in analitiche ricercabili e valutazioni, e presenta i risultati in un dashboard con un assistente AI opzionale di sola lettura. -Nel modello di distribuzione gestita, voi fornite un cluster Kubernetes dedicato ed Exosphere esegue l'intera piattaforma al suo interno, distribuendo, configurando, operando, eseguendo il backup e aggiornando ogni componente per vostro conto. Il vostro team ottiene il valore della piattaforma (visibilità degli agenti, analytics, valutazione e l'assistente facoltativo) senza gestire database, certificati o aggiornamenti. Tutti i dati rimangono all'interno del vostro account cloud. +Nel modello di distribuzione gestita, fornisci un cluster Kubernetes dedicato ed Exosphere esegue l'intera piattaforma al suo interno, distribuendo, configurando, operando, effettuando backup e aggiornando ogni componente per tuo conto. Il tuo team ottiene il valore della piattaforma (visibilità degli agenti, analitiche, valutazione e l'assistente opzionale) senza operare database, certificati o aggiornamenti. Tutti i dati rimangono all'interno del tuo account cloud. --- ## Prerequisiti -- Un **GitHub PAT** per scaricare immagini di container e artefatti (vedere [Configurazione del Token GitHub](/it/agenteye/github-token)) -- Un **cluster Kubernetes dedicato** (vedere i requisiti di seguito) -- Un **bucket di storage** per i backup del database +- Un **GitHub PAT** per il pull delle immagini container e il download degli artefatti (vedi [enterprise-docs/github-token.md](/it/agenteye/github-token)) +- Un **cluster Kubernetes dedicato** (vedi i requisiti di seguito) +- Un **bucket di archiviazione** per i backup del database - **Connettività di rete**: porta 443 in ingresso al load balancer del cluster --- -## Fase 1: Provisioning di un Cluster Kubernetes Dedicato +## Step 1: Provisioning di un cluster Kubernetes dedicato -Creare un cluster Kubernetes dedicato ad AgentEye. Non deve essere condiviso con altri carichi di lavoro, in modo che l'intera piattaforma (servizi applicativi, database, analytics e caching) funzioni in isolamento senza impattare l'infrastruttura esistente. +Crea un cluster Kubernetes dedicato a AgentEye. Non dovrebbe essere condiviso con altri carichi di lavoro, in modo che l'intera piattaforma (servizi applicativi, database, analitiche e caching) venga eseguita in isolamento senza impattare l'infrastruttura esistente. | Requisito | Dettagli | |---|---| -| **Distribuzione** | Qualsiasi Kubernetes conforme: EKS, GKE, AKS, o auto-gestito | +| **Distribuzione** | Qualsiasi Kubernetes conforme: EKS, GKE, AKS o self-managed | | **Versione** | 1.27 o successiva | | **Pool di nodi** | Minimo: **3 nodi, 4 vCPU / 8 GB RAM ciascuno** (istanze general-purpose standard) | -| **Storage** | Una StorageClass predefinita che provisioning di volumi a blocchi (es. `gp3` su AWS, `pd-ssd` su GCP) | -| **Load Balancer** | Il cluster deve essere in grado di effettuare il provisioning di servizi LoadBalancer nel cloud (predefinito su EKS, GKE, AKS) | +| **Archiviazione** | Una StorageClass predefinita che provisioning dei volumi a blocchi (ad es. `gp3` su AWS, `pd-ssd` su GCP) | +| **Load Balancer** | Il cluster deve essere in grado di provisioning i servizi LoadBalancer cloud (predefinito su EKS, GKE, AKS) | -> Exosphere installa e gestisce tutto il resto all'interno del cluster: controller di ingress, certificati TLS, database, caching, monitoraggio e tutte le distribuzioni di applicazioni. +> Exosphere installa e gestisce tutto il resto nel cluster: ingress controller, certificati TLS, database, caching, monitoraggio e tutti i deployment dell'applicazione. --- -## Fase 2: Concedere Accesso al Team di AgentEye +## Step 2: Concedi accesso al team di AgentEye -Exosphere ha bisogno di accesso cluster-admin (o RBAC ampio equivalente) per gestire namespace, definizioni di risorse personalizzate, controller di ingress e provisioner di storage. +Exosphere ha bisogno dell'accesso cluster-admin (o equivalente ampio RBAC) per gestire namespace, custom resource definition, ingress controller e provisioner di archiviazione. | Requisito | Dettagli | |---|---| -| **Metodo di accesso** | Ruolo IAM (preferito per EKS/GKE), kubeconfig, o accesso basato su SSO | -| **VPN / bastion** | Se il server API Kubernetes è privato, fornire credenziali VPN o accesso bastion per il team delle operazioni Exosphere | +| **Metodo di accesso** | Ruolo IAM (preferito per EKS/GKE), kubeconfig o accesso basato su SSO | +| **VPN / bastion** | Se il server API di Kubernetes è privato, fornisci credenziali VPN o accesso bastion per il team delle operazioni di Exosphere | --- -## Fase 3: Configurare la Connettività di Rete +## Step 3: Configura la connettività di rete -Il vostro team di rete deve permettere il traffico in ingresso sulla **porta 443** ai load balancer del cluster. La distribuzione esegue due load balancer separati: uno per l'acquisizione di eventi (protetto da mTLS) e uno per il dashboard: +Il tuo team di rete deve consentire il traffico in ingresso sulla **porta 443** ai load balancer del cluster. La distribuzione esegue due load balancer separati: uno per l'acquisizione degli eventi (protetto da mTLS) e uno per il dashboard: -| Traffico | Sorgente | Destinazione | Sicurezza | +| Traffico | Origine | Destinazione | Sicurezza | |---|---|---|---| -| **Acquisizione di eventi** | Pod di raccolta nei vostri cluster | LoadBalancer di acquisizione, porta 443 | mTLS (certificato client) + chiave API | -| **Dashboard** | Browser degli sviluppatori | Dashboard LoadBalancer, porta 443 | HTTPS nel vostro dominio, accesso OTP email senza password | +| **Acquisizione degli eventi** | Pod collector nei tuoi cluster | Ingest LoadBalancer, porta 443 | mTLS (certificato client) + chiave API | +| **Dashboard** | Browser degli sviluppatori | Dashboard LoadBalancer, porta 443 | HTTPS nel tuo dominio, accesso passwordless via OTP email | -L'endpoint di acquisizione è protetto da TLS reciproco; i raccoglitori devono presentare un certificato client valido **e** una chiave API valida ad ogni richiesta. Il dashboard funziona nel suo load balancer e hostname separati, con l'accesso limitato agli indirizzi email/domini che avete consentito. +L'endpoint di acquisizione è protetto da mutual TLS; i collector devono presentare un certificato client valido **e** una chiave API valida in ogni richiesta. Il dashboard viene eseguito sul suo load balancer e hostname separati, con accesso limitato agli indirizzi email/domini in whitelist. -**Record DNS (una tantum):** voi create due record CNAME in un dominio che controllate — uno per l'endpoint di acquisizione e uno per il dashboard (es. `agenteye.your-company.example`) — puntando ai nomi host del load balancer che Exosphere fornisce. Exosphere provisioning automaticamente certificati TLS pubblicamente affidabili per entrambi i nomi host, inclusi i rinnovi. +**Record DNS (una tantum):** crei due record CNAME in un dominio che controlli — uno per l'endpoint di acquisizione e uno per il dashboard (ad es. `agenteye.your-company.example`) — puntando ai nomi host del load balancer che Exosphere fornisce. Exosphere quindi effettua il provisioning automatico di certificati TLS pubblicamente attendibili per entrambi gli hostname, inclusi i rinnovi. -> **Nota porta 80:** il rilascio automatico dei certificati e il rinnovo si validano sulla porta 80 di ogni load balancer tramite HTTP. Se la vostra postura di sicurezza richiede di limitare il dashboard load balancer a intervalli IP aziendali, comunicatelo a Exosphere — passiamo alla convalida dei certificati basata su DNS (un record DNS extra dal vostro lato) in modo che i rinnovi continuino a funzionare dietro la restrizione. +> **Nota porta 80:** la convalida e il rinnovo del certificato automatizzati si convalidano sulla porta 80 di ogni load balancer. Se il tuo profilo di sicurezza richiede di limitare il load balancer del dashboard a intervalli IP aziendali, comunica prima a Exosphere — commutiam la convalida del certificato a un metodo basato su DNS (un record DNS aggiuntivo dal tuo lato) in modo che i rinnovi continuino a funzionare dietro la restrizione. -> **In uscita:** I nodi del cluster hanno bisogno di accesso a Internet per scaricare immagini di container da `ghcr.io`. Se la vostra rete limita il traffico in uscita, consentite `ghcr.io` o specchiate le immagini nel vostro registro interno. +> **In uscita:** I nodi del cluster hanno bisogno dell'accesso a internet per eseguire il pull delle immagini container da `ghcr.io`. Se la tua rete limita il traffico in uscita, inserisci in whitelist `ghcr.io` o specchia le immagini nel tuo registro interno. --- -## Fase 4: Fornire un Bucket di Storage per il Backup +## Step 4: Fornisci un bucket di archiviazione per i backup -I backup del database sono archiviati in un bucket di cloud storage che voi possedete. +I backup del database sono archiviati in un bucket di archiviazione cloud che possiedi. | Requisito | Dettagli | |---|---| -| **Servizio** | S3 (AWS), GCS (GCP), o Azure Blob Storage | -| **Accesso** | Concedere accesso in scrittura ai nodi del cluster tramite ruolo IAM per account di servizio (IRSA su EKS, Workload Identity su GKE) o fornire credenziali | -| **Conservazione** | Voi controllate la politica del ciclo di vita del bucket (periodo di conservazione, regole di archiviazione). Exosphere scrive i backup; voi decidete quanto tempo conservarli | +| **Servizio** | S3 (AWS), GCS (GCP) o Azure Blob Storage | +| **Accesso** | Concedi accesso in scrittura ai nodi del cluster tramite ruolo IAM per account di servizio (IRSA su EKS, Workload Identity su GKE) o fornisci credenziali | +| **Retention** | Tu controlli la policy del ciclo di vita del bucket (periodo di retention, regole di archiviazione). Exosphere scrive i backup; tu decidi quanto tempo conservarli | -Un singolo backup giornaliero esegue il dump sia di PostgreSQL (stato relazionale) che di ClickHouse (eventi e valutazioni) in un singolo archivio compresso e lo carica nel vostro bucket. I backup vengono eseguiti anche prima di ogni aggiornamento. +Un singolo backup giornaliero scarica sia PostgreSQL (stato relazionale) che ClickHouse (eventi e valutazioni) in un singolo archivio compresso e lo carica nel tuo bucket. I backup vengono eseguiti anche prima di ogni aggiornamento. --- -## Fase 5: Designare un Punto di Contatto +## Step 5: Designa un punto di contatto -Fornite una persona o un canale Slack/Teams dal vostro lato per i problemi a livello di cluster: salute dei nodi, limiti dell'account cloud, modifiche di rete. Le operazioni quotidiane non coinvolgono questo contatto. +Fornisci una persona o un canale Slack/Teams dal tuo lato per i problemi a livello di cluster: salute dei nodi, limiti dell'account cloud, modifiche di rete. Le operazioni quotidiane non coinvolgono questo contatto. --- -## Cosa Distribuiamo +## Cosa distribuiamo -Una volta che Exosphere ha accesso al cluster, i seguenti componenti vengono distribuiti e gestiti per voi: +Una volta che Exosphere ha accesso al cluster, vengono distribuiti e gestiti i seguenti componenti: | Componente | Ruolo | |---|---| -| **Server AgentEye** | API HTTP che riceve eventi dai raccoglitori, esegue analytics e fornisce dati al dashboard | -| **Dashboard** | Interfaccia web per visualizzare sessioni di agenti, chiamate di strumenti, richieste di modelli ed errori; ospita l'assistente AI facoltativo in sola lettura | -| **ClickHouse** | Archivio canonico obbligatorio per eventi acquisiti, analytics e valutazioni | -| **PostgreSQL** | Archivio relazionale per organizzazioni, chiavi API, utenti, dashboard e query salvate | -| **Redis** | Cache condivisa facoltativa e backend per limitare la frequenza; la piattaforma si degrada elegantemente se non disponibile | -| **Assistente AI (facoltativo)** | Container assistente interno in sola lettura; rimane disabilitato fino a quando non viene configurato un endpoint LLM | -| **Controller di ingress** | Due load balancer (uno per acquisizione protetta da mTLS, uno per il dashboard) che terminano TLS con certificati pubblicamente affidabili e auto-rinnovati e applicano mTLS nell'endpoint di acquisizione | -| **cert-manager** | Automatizza il provisioning di certificati TLS e il rilascio di certificati client mTLS | -| **Monitoraggio certificati** | Un lavoro pianificato verifica la scadenza dei certificati e invia avvisi (es. a Slack) quando i certificati si avvicinano al rinnovo | - -L'offerta gestita opera anche la pipeline di valutazione della piattaforma, che valuta l'attività dell'agente rispetto ai vostri criteri di valutazione. Vedere [Assistant](/it/agenteye/assistant) e [Evaluation Suite](/it/agenteye/evaluation-suite) per cosa queste funzionalità forniscono. +| **AgentEye Server** | API HTTP che riceve gli eventi dai collector, esegue analitiche e serve i dati al dashboard | +| **Dashboard** | Interfaccia web per visualizzare sessioni di agenti, chiamate di strumenti, richieste di modelli ed errori; ospita l'assistente AI opzionale di sola lettura | +| **ClickHouse** | Store canonico richiesto per gli eventi acquisiti, le analitiche e le valutazioni | +| **PostgreSQL** | Store relazionale per organizzazioni, chiavi API, utenti, dashboard e query salvate | +| **Redis** | Cache condivisa opzionale e backend di rate-limit; la piattaforma degrada elegantemente se non disponibile | +| **Assistente AI (opzionale)** | Container assistente interno di sola lettura; rimane disabilitato fino a quando non viene configurato un endpoint LLM | +| **Controller Ingress** | Due load balancer (uno per l'acquisizione protetta da mTLS, uno per il dashboard) che terminano TLS con certificati pubblicamente attendibili e auto-rinnovati e applicano mTLS all'endpoint di acquisizione | +| **cert-manager** | Automatizza il provisioning di certificati TLS e l'issuance di certificati client mTLS | +| **Monitoraggio dei certificati** | Un job programmato controlla la scadenza dei certificati e invia avvisi (ad es. a Slack) quando i certificati si avvicinano al rinnovo | + +L'offerta gestita gestisce anche la pipeline di valutazione della piattaforma, che valuta l'attività degli agenti in base ai tuoi criteri di valutazione. Vedi [enterprise-docs/assistant.md](/it/agenteye/assistant) e [enterprise-docs/evaluation-suite.md](/it/agenteye/evaluation-suite) per quello che queste capacità forniscono. --- -## Cosa Vi Forniamo +## Cosa ti forniamo -Dopo il completamento della distribuzione, ricevete: +Dopo il completamento della distribuzione, ricevi: | Elemento | Dettagli | |---|---| -| **URL del Dashboard** | Un nome host sotto il vostro dominio (es. `https://agenteye.your-company.example`), fornito con un certificato TLS pubblicamente affidabile e auto-rinnovato. Voi create un CNAME al nome host del load balancer che forniamo; l'accesso è passwordless OTP email | -| **Endpoint di raccolta** | Il percorso `/events` del nome host di acquisizione (es. `https://ingest.your-company.example/events`), protetto da mTLS | -| **Bundle certificato client** | Per cluster: certificato client, chiave privata e certificato CA consegnati come manifesto Kubernetes Secret. Applicateli una volta per cluster | -| **GitHub PAT** | Per scaricare i binari del raccoglitore e i pacchetti Python SDK | -| **Chiavi API del raccoglitore** | Chiavi ambite con permesso `events:add`, una per distribuzione di raccoglitore | -| **Guide di installazione** | Documentazione passo passo per il raccoglitore e Python SDK | +| **URL Dashboard** | Un hostname sotto il tuo dominio (ad es. `https://agenteye.your-company.example`), servito con un certificato TLS pubblicamente attendibile e auto-rinnovato. Crei un CNAME al nome host del load balancer che forniamo; l'accesso è passwordless via OTP email | +| **Endpoint collector** | Il percorso `/events` dell'hostname di acquisizione (ad es. `https://ingest.your-company.example/events`), protetto da mTLS | +| **Bundle certificato client** | Per cluster: certificato client, chiave privata e certificato CA forniti come manifesto Kubernetes Secret. Applicare una volta per cluster | +| **GitHub PAT** | Per il download dei binari del collector e dei pacchetti SDK Python | +| **Chiavi API collector** | Chiavi scoped con permesso `events:add`, una per distribuzione di collector | +| **Guide di installazione** | Documentazione passo-passo per il collector e l'SDK Python | --- -## Cosa Fate Dopo la Configurazione +## Cosa fai dopo la configurazione -Il vostro unico lavoro in corso è sulle vostre proprie macchine di agenti, non sul cluster AgentEye: +Il tuo unico lavoro continuativo è sulle tue macchine di agenti, non sul cluster AgentEye: -1. **Installare il raccoglitore** in ogni cluster Kubernetes che esegue agenti AI: montare il certificato client e configurare l'URL dell'endpoint e la chiave API. Vedere [Installazione del Raccoglitore](/it/agenteye/collector-installation). -2. **Integrare Python SDK** nel vostro codice di agente. Vedere [Python SDK](/it/agenteye/python-sdk). -3. **Aprire il dashboard** nel vostro browser per visualizzare l'attività dell'agente. +1. **Installa il collector** in ogni cluster Kubernetes che esegue agenti AI: monta il certificato client e configura l'URL dell'endpoint e la chiave API. Vedi [enterprise-docs/collector-installation.md](/it/agenteye/collector-installation). +2. **Integra l'SDK Python** nel codice del tuo agente. Vedi [enterprise-docs/python-sdk.md](/it/agenteye/python-sdk). +3. **Apri il dashboard** nel tuo browser per visualizzare l'attività degli agenti. -Nessuna operazione di cluster, nessuna gestione di database, nessun rinnovo di certificati, nessun aggiornamento. +Nessuna operazione di cluster, nessuna gestione del database, nessun rinnovo di certificati, nessun aggiornamento. --- ## Sicurezza -- **I dati rimangono nel vostro account cloud.** Il cluster, lo storage e i database vengono tutti eseguiti nel vostro ambiente. Nessun dato esce dal vostro confine. -- **Voi controllate l'accesso.** Il cluster è nel vostro account. Potete controllare, monitorare o revocare l'accesso di Exosphere in qualsiasi momento. Tutte le operazioni passano attraverso il registro di audit del vostro cloud (CloudTrail, GCP Audit Logs, ecc.). -- **mTLS su acquisizione di eventi.** Ogni richiesta del raccoglitore richiede sia un certificato client valido che una chiave API. Una chiave trapelata è inutile senza il certificato; un certificato rubato è inutile senza una chiave valida. -- **Controllo dell'accesso al dashboard.** Il dashboard funziona nel suo load balancer separato, distinto dall'acquisizione di eventi, e l'accesso è passwordless OTP email limitato agli indirizzi email/domini che consentite. Un elenco di intervalli IP sorgente nel load balancer è disponibile su richiesta; poiché il rinnovo automatico del certificato deve raggiungere il load balancer, Exosphere accoppia la restrizione alla convalida del certificato basata su DNS in modo che i rinnovi continuino a funzionare. -- **Certificati per cluster.** Ognuno dei vostri cluster riceve il suo certificato client. Se un cluster viene compromesso, quel certificato viene revocato indipendentemente senza influire sugli altri. +- **I dati rimangono nel tuo account cloud.** Il cluster, l'archiviazione e i database vengono tutti eseguiti nel tuo ambiente. Nessun dato esce dal tuo confine. +- **Tu controlli l'accesso.** Il cluster è nel tuo account. Puoi controllare, monitorare o revocare l'accesso di Exosphere in qualsiasi momento. Tutte le operazioni passano attraverso il registro di audit del tuo cloud (CloudTrail, GCP Audit Logs, ecc.). +- **mTLS nell'acquisizione degli eventi.** Ogni richiesta del collector richiede sia un certificato client valido che una chiave API. Una chiave persa è inutile senza il certificato; un certificato rubato è inutile senza una chiave valida. +- **Controllo dell'accesso al dashboard.** Il dashboard viene eseguito sul suo load balancer separato, separato dall'acquisizione degli eventi, e l'accesso è passwordless via OTP email limitato agli indirizzi email/domini in whitelist. Una whitelist di intervalli di origine IP sul load balancer è disponibile su richiesta; poiché il rinnovo del certificato automatizzato deve raggiungere il load balancer, Exosphere accoppia la restrizione con la convalida del certificato basata su DNS in modo che i rinnovi continuino a funzionare. +- **Certificati per cluster.** Ogni tuo cluster riceve il suo certificato client. Se un cluster viene compromesso, quel certificato viene revocato indipendentemente senza influire sugli altri. --- -## Timeline di Distribuzione +## Timeline di distribuzione -| Fase | Durata | Vostro coinvolgimento | +| Fase | Durata | Tuo coinvolgimento | |---|---|---| -| **Provisioning del cluster** | 1-2 giorni | Effettuare il provisioning del cluster e concedere accesso a Exosphere | -| **Configurazione della piattaforma** | 1 giorno | Nessuno; Exosphere installa tutti i componenti infrastrutturali | -| **Distribuzione dell'applicazione** | 1 giorno | Nessuno; Exosphere distribuisce il server, il dashboard e crea chiavi API | -| **Rollout del raccoglitore** | 1-3 giorni | Installare i raccoglitori nei vostri cluster (con guida da Exosphere) | -| **Rodaggio in produzione** | 1 settimana | Nessuno; Exosphere monitora e ottimizza | +| **Provisioning del cluster** | 1-2 giorni | Provisioning del cluster e concessione dell'accesso a Exosphere | +| **Configurazione della piattaforma** | 1 giorno | Nessuno; Exosphere installa tutti i componenti dell'infrastruttura | +| **Distribuzione dell'applicazione** | 1 giorno | Nessuno; Exosphere distribuisce il server, il dashboard e crea le chiavi API | +| **Rollout del collector** | 1-3 giorni | Installa i collector nei tuoi cluster (con guida da Exosphere) | +| **Burn-in in produzione** | 1 settimana | Nessuno; Exosphere monitora e effettua l'ottimizzazione | -Totale tipico: **~2 settimane** dal via ai ready per la produzione. +Totale tipico: **~2 settimane** dal kickoff al pronto per la produzione. --- ## Supporto -Per domande o problemi, contattate Exosphere a `support@exosphere.host`. +Per domande o problemi, contatta Exosphere all'indirizzo `support@exosphere.host`. --- -## Passaggi Successivi +## Prossimi passi -- [Guida Introduttiva](/it/agenteye/getting-started): procedura dettagliata end-to-end -- [Installazione del Raccoglitore](/it/agenteye/collector-installation): installa e configura il raccoglitore -- [Python SDK](/it/agenteye/python-sdk): strumenta il tuo codice di agente -- [Chiavi API](/it/agenteye/api-keys): gestisci accesso e permessi -- [Risoluzione dei Problemi](/it/agenteye/troubleshooting): problemi comuni e soluzioni \ No newline at end of file +- [Getting Started](/it/agenteye/getting-started): procedura dettagliata end-to-end +- [Collector Installation](/it/agenteye/collector-installation): installa e configura il collector +- [Python SDK](/it/agenteye/python-sdk): strumenta il codice del tuo agente +- [API Keys](/it/agenteye/api-keys): gestisci accesso e permessi +- [Troubleshooting](/it/agenteye/troubleshooting): problemi comuni e fix \ No newline at end of file diff --git a/docs/ja/agenteye/audits.mdx b/docs/ja/agenteye/audits.mdx index f00fce28..084d5d6d 100644 --- a/docs/ja/agenteye/audits.mdx +++ b/docs/ja/agenteye/audits.mdx @@ -1,107 +1,106 @@ --- -title: "監査 — エージェント的な改善検出" -description: "AgentEye 監査 — エージェント的な改善検出のドキュメント。" +title: "監査 — エージェント的改善検出" +description: "AgentEye 監査 — エージェント的改善検出のドキュメント。" --- -監査は、**セッションをまたいで**エージェントのログを分析し、改善すべき点を発見する定期ジョブです。アラートが既知の指標をほぼリアルタイムで監視するのに対し、監査は*調査*を行います。設定したスケジュールで、ウィンドウ全体に対して決定論的なポリシーパスを実行し、続いて**AI信頼性エージェント**をセッションに対して動かします。エージェントはデータに対してクエリを実行し、疑わしいトランスクリプトを読み込み、必要に応じて小規模な分析スクリプトを実行したうえで、各発見の根拠とともに**改善提案**をまとめます。 +監査は、**セッションをまたいで**エージェントログを分析し、改善すべき点を見つけ出す定期実行ジョブです。アラートが既知のメトリクスをほぼリアルタイムで監視するのに対し、監査は*調査*を行います。設定したスケジュールに従い、対象ウィンドウに対して決定論的なポリシーチェックを実行した後、**AI信頼性エージェント**をセッションに対して投入します。エージェントはデータ自体にクエリを発行し、不審なトランスクリプトを読み込み、（必要に応じて）小規模な分析スクリプトを実行し、各発見の根拠を添えた**改善提案**をまとめます。 -「エージェントの何を修正・改善すべきか」という問いへの回答には監査を、特定の閾値を超えた瞬間に通知を受け取るにはアラートを使い分けてください。すべての改善提案は背後のセッションとクエリに直接リンクされており、ワンクリックで再発を検知するためのアラートを事前入力済みの状態で作成できます。 +「エージェントの何を修正・改善すべきか」という問いへの答えには監査を使い、特定のしきい値を超えた瞬間に通知を受け取るにはアラートを使ってください。すべての改善提案はその根拠となった正確なセッションとクエリにリンクされており、ワンクリックで再発検知用のアラートをあらかじめ入力済みの状態で作成できます。 -ダッシュボードの画面は **`//audits`**（サイドバー → *analyze* → *audits*）で、`audits:read` / `audits:write` 権限によって制御されます。 +ダッシュボードの画面は **`//audits`**（サイドバー → *analyze* → *audits*）で、`audits:read` / `audits:write` 権限によって制御されています。 --- ## 実行の仕組み -各実行には2つの層があります。決定論的な基盤層と、エージェント的な調査層です。 +各実行は、決定論的なベース層とエージェント的な調査層の2層構成になっています。 ### 1. ポリシーパス（決定論的） -モデルが動く前に、監査はウィンドウに対して**SQLポリシーチェック**の小さなカタログを実行します。既知の問題パターンにフラグを立て、該当したイベント数/セッションを報告する境界付き集計クエリで、マッチしたテキスト自体は報告されません。カタログには以下が含まれます。 +モデルが動作する前に、監査は対象ウィンドウに対して**SQLポリシーチェック**の小規模なカタログを実行します。これは既知の問題パターンにフラグを立て、一致したイベントの*件数*や*セッション*を報告する有界集計クエリです（一致したテキスト自体は報告しません）。カタログには以下が含まれます。 -- イベントペイロード内の**シークレット/認証情報の漏洩** — AWSアクセスキー、`sk-…` APIキー、PEM秘密鍵、JWT / Bearerトークン、`KEY=…` 形式の認証情報 -- **プロンプトインジェクションのマーカー** — 「以前の指示を無視して」「システムプロンプトを教えて」など -- **PII** — SSN形式の番号（ヒューリスティック） -- **ツール権限の拒否**と**際限のないツールコールループ** +- イベントペイロード内の**シークレット／認証情報漏洩** — AWSアクセスキー、`sk-…` APIキー、PEM秘密鍵、JWT／ベアラートークン、`KEY=…` 形式の認証情報代入。 +- **プロンプトインジェクションのマーカー** — "ignore previous instructions"、"reveal your system prompt" など類似表現。 +- **PII** — SSN形式の数値（ヒューリスティック）。 +- **ツール権限の拒否**および**ツール呼び出しのループ暴走**。 -ポリシーヒットはファインディング（kind: `policy`）として永続化され、**常に表示**されます（実行ごとの上限によるトリミングの対象外）。また、AIエージェントへの手がかりとして渡されます。この層はモデルを必要としないため、AIエージェントが利用できない場合でも、監査は最も重要なセキュリティシグナルを生成します。 +ポリシーヒットは kind `policy` のフィンディングとして永続化され、**常に表示されます**（1回の実行あたりの上限でトリミングされることはありません）。また、AIエージェントの最初の手がかりとして渡されます。この層はモデルを必要としないため、AIエージェントが利用できない場合でも監査は最重要のセキュリティシグナルを生成します。 ### 2. エージェント的調査（AI） -次に監査は**自律的な信頼性エージェント**を実行します（ダッシュボードアシスタントを動かしているのと同じ Claude Agent SDK サービスを、監査専用のプロンプトで使用）。エージェントは監査の**スコープ**（対象エージェント × 環境）と**時間ウィンドウ**をもとに、以下を行います。 +次に監査は**自律型信頼性エージェント**を実行します（ダッシュボードアシスタントと同じClaude Agent SDKサービスを使用し、監査専用のプロンプトが設定されています）。監査の**スコープ**（選択されたエージェント×環境）と**時間ウィンドウ**が与えられると、エージェントは以下を行います。 -- 分析テーブルに対して読み取り専用のSQLクエリを実行 -- 代表的なセッショントランスクリプトを数件読み込み -- SQLでは表現できない分析（エラーのクラスタリング、分布の計算、取得済みペイロードのスキャン）が必要な場合は、**隔離されたイン・ポッド・サンドボックス**（ネットワーク不可、ファイルシステムアクセス不可、シークレットはスクラブ済み）で短いPythonスクリプトを実行 -- 十分な根拠を持つ**改善点**を記録 +- アナリティクステーブルに対して読み取り専用のSQLクエリを実行する。 +- 代表的なセッショントランスクリプトをいくつか読み込む。 +- 必要に応じて、SQLでは表現できない分析（エラーのクラスタリング、分布の計算、取得済みペイロードの精査など）のために、**ネットワークアクセス・ファイルシステムアクセスなし、シークレットスクラブ済みの隔離されたインPodサンドボックス**内で短いPythonスクリプトを作成して実行する。 +- 証拠のある**改善点**を記録する。 -エラーのクラスタリング、ベースラインとのドリフト、トランスクリプト上のゴール失敗、ツールの誤用、品質/コストのトレードオフ、カバレッジギャップなど、複数の調査ラインを監査の**感度**（low / medium / high）に従って検討します。すべての改善提案は**証拠の引用が必須**です。エージェントが実際に検査したセッションIDか、実行したSQLのいずれか（または両方）を引用する必要があります。サーバーは引用されたセッションの存在を検証し、**生き残った証拠のない改善提案は破棄**します。つまりエージェントは調査するだけで、事実を創作しません。 +エージェントは監査の**感度**（低 / 中 / 高）に基づき、エラークラスタリング、ベースラインとの差異、トランスクリプト内のゴール失敗、ツールの誤用、品質/コストのトレードオフ、カバレッジのギャップなど、複数の調査軸から調査を行います。すべての改善提案は**証拠を引用しなければなりません**。エージェントが実際に調査したセッションIDや実行したSQLが根拠として必要です。サーバーは引用されたセッションの存在を検証し、**存在する証拠がない改善提案は破棄します**。エージェントは調査しますが、捏造はしません。 各改善提案には以下が含まれます。 - **推奨事項**（具体的な変更内容 — プロンプトの調整、ツールスキーマの修正、リトライポリシー、ガードレール、評価カバレッジの拡充など） -- **期待される効果**と**工数**の見積もり（low / medium / high） -- **重大度** — `big`（オペレーターへの即時通知が必要）、`medium`（実行レポートに記載）、`small`（ダッシュボードのコンテキスト情報） -- 安定した**フィンガープリント**（問題のカテゴリ + スコープに基づき、今回の実行セッションには依存しない）により、証拠が変わっても同じ問題を実行をまたいで追跡可能 -- 決定論的な監視で再発を検知できる場合は、ワンクリックで作成できる**アラートの提案** +- **期待される効果**と**工数**の見積もり（低 / 中 / 高） +- **重大度** — `big`（オペレーターへの通知が必要）、`medium`（実行レポートに含める）、`small`（ダッシュボードのコンテキスト） +- 安定した**フィンガープリント**（問題のカテゴリ＋スコープから生成され、今回の実行のセッションには依存しない）。これにより、証拠が変わっても同一の問題が実行をまたいで追跡される。 +- 単純な決定論的監視で再発を検知できる場合は、ワンクリックで作成できる**アラートの提案**。 -> **AIレイヤーは任意ですが推奨されます。** 監査パイプラインにAIエージェントが設定されていない場合も、実行は行われ、ポリシーファインディングは永続化されます。エージェント層については「分析利用不可」と正直にレポートし、静かにパスすることはありません。 +> **AIレイヤーはオプションですが推奨されます。** 監査パイプラインにAIエージェントが設定されていない場合でも、実行は行われ、ポリシーフィンディングは永続化されます。エージェント層については、黙って合格とするのではなく、「分析利用不可」と正直に報告します。 ### 障害モード -改善提案は組織の永続的な**障害モードカタログ**に分類されます（または新しいモードを提案します）。モードにより、実行をまたいだパターンの安定したID管理と長期的な再発追跡が可能になります。 +改善提案は組織の持続的な**障害モードカタログ**に分類されます（新しいモードの提案も可能）。モードによりパターンに実行をまたいだ安定したIDが付与され、長期的な再発追跡が可能になります。 ## トリアージのライフサイクル -ファインディングページ（`/audits//findings/`）での操作： +フィンディングページ（`/audits//findings/`）では： | アクション | 効果 | |---|---| -| **acknowledge** | ファインディングを表示したまま優先度を半減させます。 | -| **resolve** | 修正済みとしてマークします。パターンが後日再発した場合、**new** として再オープン — 退行は静かに歴史に埋もれることなく、明示的に通知されます。 | -| **mute** / **dismiss** | 永続的な抑制：パターンのフィンガープリントが記憶され、実行をまたいで二度と表示されません。muteは「既知・許容済み」、dismissは「有用でない」場合に使用します。 | -| **reopen** | 抑制・解決をクリアし、パターンを再度ランク付けします。 | -| **assign** | ファインディングをオーナーとして組織メンバーのオペレーターに割り当てます。優先度と抑制状態は変わりません。 | +| **acknowledge（確認）** | フィンディングを表示したまま優先度を半分にする。 | +| **resolve（解決）** | 修正済みとしてマークする。パターンが後日実際に再発した場合は**new**として再オープンされる — リグレッションは目立つ形で通知され、静かに履歴に埋もれることはない。 | +| **mute（ミュート）** / **dismiss（却下）** | 永続的な抑制：パターンのフィンガープリントが記録され、実行をまたいでも二度と表示されない。mute は「既知・許容済み」に、dismiss は「有用でない」場合に使用する。 | +| **reopen（再オープン）** | 抑制／解決をクリアし、パターンを再度ランキング対象にする。 | -低シグナルのノイズは、エージェント的な改善に対する実行ごとのファインディング上限（`top_k`）で監査ごとに制御されます。ポリシーファインディングはセキュリティ上重要なため上限をバイパスし、常に表示されます。上限によって除外されたものは実行の統計に計上されます — 何も静かに破棄されません。 +低シグナルのノイズは、エージェント的改善に対する1実行あたりのフィンディング上限（`top_k`）で監査ごとに制御されます。ポリシーフィンディングはセキュリティ上重要であるため上限をバイパスし、常に表示されます。上限によって除外されたものは実行の統計にカウントされます — 静かに破棄されるものはありません。 ## スケジューリング -- **ケイデンス**（`schedule_interval_secs`）：1時間ごと〜週1回。**デフォルトは1日1回**。監査はアラートよりも粗い粒度で設計されています。エージェント的な調査はウィンドウ全体をスキャンし、実行に数分かかります。 -- **ウィンドウ**：固定のローリングルックバック（例：「各実行は直近7日間をスキャン」）または**前回実行以降**（デフォルト）— 各実行は前回成功した実行が終了した時点から開始し、境界イベントを見逃さないように小さなオーバーラップを設けます。 -- 次の実行は、前の実行が**完了**してから1インターバル後にスケジュールされます。これにより、実行が遅延しても同じ監査の2回目の実行が同時に重なることはありません。 -- 監査ページの**今すぐ実行**をクリックすると、即座に実行対象となります。 +- **頻度**（`schedule_interval_secs`）：1時間ごとから1週間ごと。**デフォルトは毎日**。監査はアラートよりも意図的に粗い粒度になっています — エージェント的調査はウィンドウ全体をスキャンし、実行に数分かかります。 +- **ウィンドウ**：固定のローリングルックバック（例：「各実行で過去7日間をスキャン」）または**前回実行以降**（デフォルト）のいずれか。後者は前回の成功実行が終了した時点から引き継ぎ、境界イベントを取りこぼさないよう小さなオーバーラップがあります。 +- 次の実行は前回実行が**完了**してから1インターバル後にスケジュールされるため、実行が遅くなっても同じ監査が並行して実行されることはありません。 +- 監査ページの**今すぐ実行**ボタンで即時実行をキューに入れられます。 -## モデル選択 +## モデルの選択 -監査作成時に、エージェントサービス用に**オペレーターが設定したモデルリスト**から調査に使用するモデルを選択できます。モデルが1つだけ設定されている場合はキャプションとして表示され、複数ある場合は選択できます。未設定の場合は設定済みのデフォルトが使用されます。 +監査を作成する際に、**オペレーターがエージェントサービス用に設定したモデルの一覧**から調査に使用するモデルを選択できます。モデルが1つだけ設定されている場合はキャプションとして表示され、複数ある場合は選択できます。未設定の場合は設定済みのデフォルトが使用されます。 ## 通知 -実行で**新規**ファインディングが検出された場合、監査は組織の設定済みチャネルに通知します。アラートパイプラインが使用するものと同じ `alerts.enabled_channels` ゲートと設定を使用します。 +実行によって**新しい**フィンディングが見つかると、監査は組織に設定されたチャンネルに通知します。アラートパイプラインと同じ `alerts.enabled_channels` ゲートと設定を使用します。 -- **Slack** — 重要（`big`）な新規項目のサマリーとディープリンク -- **Email** — 新規改善提案（最高重大度、項目ごとの推奨事項、ディープリンク）をリストアップした**監査レポート**。監査に**email**チャネルが設定されており、新規ファインディングが1件以上ある場合に送信されます。 +- **Slack** — 重要な（`big`）新規アイテムの概要とディープリンク。 +- **Email** — 新しい改善提案（重大度上位、各アイテムの推奨事項、ディープリンク）を一覧にした**監査レポート**。監査に**email**チャンネルが設定されており、新規フィンディングが1件以上ある場合に送信される。 -繰り返し検出されているが既知のファインディングは再通知されません。 +再発しているが既知のフィンディングについては再通知しません。 ## 設定リファレンス -監査の定義はダッシュボード（`/audits/new`）またはAPIで管理します。監査ごとの設定には、スケジュールのケイデンスとウィンドウ、スコープ（`{"environments": [...], "agent_ids": [...]}`）、感度（`low` / `medium` / `high`）、通知チャネル、実行ごとのファインディング上限（`top_k`）、モデル（`llm_budget.model`）が含まれます。オペレーターレベルのサーバー設定（タイムアウト、サンドボックス、エージェントサービスのURL）は [deployment.md](/ja/agenteye/deployment) に記載されています。 +監査定義はダッシュボード（`/audits/new`）またはAPIで管理します。監査ごとの設定には、スケジュールの頻度とウィンドウ、スコープ（`{"environments": [...], "agent_ids": [...]}`）、感度（`low` / `medium` / `high`）、通知チャンネル、1実行あたりのフィンディング上限（`top_k`）、モデル（`llm_budget.model` 経由）が含まれます。オペレーターレベルのサーバー設定（タイムアウト、サンドボックス、エージェントサービスURL）は [deployment.md](/ja/agenteye/deployment) に記載されています。 ## API -すべてのエンドポイントは組織スコープで、標準のBearerキー認証を使用します（[api-keys.md](/ja/agenteye/api-keys) を参照）。 +すべてのエンドポイントは組織スコープで、標準のベアラーキー認証を使用します（[api-keys.md](/ja/agenteye/api-keys) を参照）。 | エンドポイント | 権限 | 目的 | |---|---|---| -| `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | 監査定義の一覧取得 / 作成 | -| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | 監査の参照、編集、削除 | -| `POST /audits/:id/run` | `audits:write` | 監査を即座に実行対象にする | -| `GET /audits/:id/runs` | `audits:read` | 実行履歴（ウィンドウ、ステータス、統計、ファインディング数） | -| `GET /audits/findings` | `audits:read` | 組織全体のファインディング。`audit_id`、`status` でフィルタリング可能。優先度順に並べ替え済み | -| `GET /audits/findings/:fid` | `audits:read` | ファインディングの全詳細（推奨事項、証拠、優先度） | -| `POST /audits/findings/:fid/status` | `audits:write` | トリアージ: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}` | - -「監査を実行したが何も検出されなかった」「コードサンドボックスが無効」「監査メールが届かない」については、[troubleshooting.md](/ja/agenteye/troubleshooting#audits) を参照してください。 \ No newline at end of file +| `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | 監査定義の一覧取得 / 作成。 | +| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | 監査の参照、編集、削除。 | +| `POST /audits/:id/run` | `audits:write` | 監査を即時実行キューに入れる。 | +| `GET /audits/:id/runs` | `audits:read` | 実行履歴（ウィンドウ、ステータス、統計、フィンディング数）。 | +| `GET /audits/findings` | `audits:read` | 組織全体のフィンディング。`audit_id`、`status` でフィルタリング可能。優先度順にソート。 | +| `GET /audits/findings/:fid` | `audits:read` | フィンディングの詳細（推奨事項、証拠、優先度）。 | +| `POST /audits/findings/:fid/status` | `audits:write` | トリアージ：`{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`。 | + +「監査は実行されたが何も見つからなかった」「コードサンドボックスが無効になっている」「監査メールが届かない」などについては [troubleshooting.md](/ja/agenteye/troubleshooting#audits) を参照してください。 \ No newline at end of file diff --git a/docs/ja/agenteye/cli-recipes.mdx b/docs/ja/agenteye/cli-recipes.mdx index 127e14bc..f9a7bc9c 100644 --- a/docs/ja/agenteye/cli-recipes.mdx +++ b/docs/ja/agenteye/cli-recipes.mdx @@ -1,30 +1,30 @@ --- title: "エージェント向けCLIレシピ" -description: "エージェント向けAgentEye CLIレシピのドキュメント。" +description: "エージェント向けAgentEye CLIレシピドキュメント。" --- -スクリプトやコーディングエージェントから直接、セッション・イベント・評価データを取得し（再評価のトリガーも可能）、`jq` にパイプできるクリーンなJSON を stdout に出力します。これらのレシピは、AgentEye のオブザーバビリティデータを、ターミナルユーザーやAIコーディングエージェント（Claude Code、Cursor）がダッシュボードをクリックせずにクエリ・自動化できる形に変えます。 +セッション、イベント、評価データの取得（および再評価のトリガー）をスクリプトやコーディングエージェントから直接行えます。stdout にはクリーンな JSON が出力されるため、`jq` にそのままパイプできます。これらのレシピは、ダッシュボードを操作せずに、ターミナルユーザーやAIコーディングエージェント（Claude Code、Cursor）がAgentEyeの可観測性データをクエリ・自動化できるようにするものです。 -以下のパターンは AgentEye CLI（`agenteye`）へそのままコピーペーストできます。インストール・認証・全オプション一覧については [CLI](/ja/agenteye/cli) を参照してください。組み込みヘルプは `agenteye -h` または `agenteye -h` で確認できます。 +以下のパターンはAgentEye CLI（`agenteye`）にコピー＆ペーストしてすぐに使えます。インストール、認証、オプションの全一覧については [CLI](/ja/agenteye/cli) を参照してください。組み込みのヘルプは `agenteye -h` または `agenteye -h` で確認できます。 ## 基本ルール -1. **グローバルオプションはコマンドの*前*に指定する。** `agenteye --json sessions` が正しく、`agenteye sessions --json` は誤りです。グローバルオプションは `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet`、`--no-color` です。 -2. **出力をパースする場合は必ず `--json` を渡す。** データは JSON として **stdout** に出力され、人間向けのステータスやエラーは **stderr** に出力されるため、stdout が `jq` へのパイプに適した状態に保たれます。 -3. **分岐は stderr のテキストではなく終了コードで行う。** `0` 正常 · `2` 引数エラー · `3` ダッシュボード到達不能 · `4` 未ログインまたはセッション期限切れ · `5` 権限不足。 -4. **`-h` で仕様を確認する。** すべてのコマンドにフィルター・値のフォーマット・JSONの形式が記載されています。 +1. **グローバルオプションはコマンドの*前*に指定します。** `agenteye --json sessions` が正しく、`agenteye sessions --json` は誤りです。グローバルオプションは `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet`、`--no-color` です。 +2. **出力をパースする場合は必ず `--json` を渡してください。** データは JSON として **stdout** に出力され、人間向けのステータスやエラーは **stderr** に出力されるため、stdout はクリーンな状態で `jq` にパイプできます。 +3. **終了コードで分岐してください（stderrのテキストではなく）:** `0` 成功 · `2` 引数が不正 · `3` ダッシュボードに到達できない · `4` 未ログインまたはセッション期限切れ · `5` 権限不足。 +4. **`-h` で機能を確認できます。** 各コマンドにはフィルター、値のフォーマット、JSONの形状がドキュメント化されています。 ## 初回セットアップ ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # --base-url の繰り返しを省略 -agenteye login --email you@example.com # メールで届いたコードを貼り付け; 有効期間 ~24h +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # --base-url を繰り返さなくて済むように +agenteye login --email you@example.com # メールで届いたコードを貼り付ける（有効期間 約24時間） ``` -## 作業前の認証確認 +## 作業前に認証を確認する -`whoami` はセッションが存在しない・期限切れの場合もエラーにならず、代わりに `logged_in:false` を返します。そのため、エージェントが安全に認証状態を確認できます（ベースURLが未設定またはダッシュボードに到達できない場合は、非ゼロで終了することがあります）。 +`whoami` はセッションが存在しないか期限切れでもエラーになりません。代わりに `logged_in:false` を返すため、エージェントは安全に認証状態を確認できます（ベースURLが未設定またはダッシュボードに到達できない場合は、ゼロ以外の終了コードになる可能性があります）。 ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -32,28 +32,28 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## 失敗または低スコアのセッションを探す +## 失敗または低スコアのセッションを見つける ```bash # 過去24時間で評価がエラーになったセッション agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# helpfulness スコアが 0.5 以下の評価（特定エージェント対象） +# helpfulnessが0.5以下の評価（特定のエージェント） agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -スコアフィルタリングは `sessions` ではなく **`evals`** に対して行います。`--score KEY:MIN..MAX` は繰り返し指定可能でAND結合されます。いずれかの境界は省略可能です（`..0.5` は ≤ 0.5、`0.9..` は ≥ 0.9 を意味します）。1リクエストあたり最大20個のスコアフィルターを指定できます。それ以上はHTTP 400が返ります。`sessions` は `evals` と `--env`、`--status`、`--agent-id`、`--session-id`、時間範囲フィルターを共有しますが、`--score` はありません。 +スコアのフィルタリングは `sessions` ではなく **`evals`** で行います。`--score KEY:MIN..MAX` は繰り返し指定可能でAND結合されます。どちらの境界値も省略可能です（`..0.5` は ≤ 0.5、`0.9..` は ≥ 0.9 を意味します）。リクエストごとに最大20件のスコアフィルターを指定でき、それ以上はHTTP 400が返ります。`sessions` は `evals` と `--env`、`--status`、`--agent-id`、`--session-id`、時間範囲フィルターを共有しますが、`--score` はありません。 ## セッションをエンドツーエンドで読む -単一の `session show` コマンドはありません。イベント履歴とセッションの評価を組み合わせてください。 +単一の `session show` コマンドはありません。イベントの履歴とセッションの評価を組み合わせて使用してください。 ```bash # セッションの最新評価（ステータス + スコア） agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# 実行中の全イベント（全件取得は --limit を増やす） +# 実行中のすべてのイベント（全件取得には --limit を増やす） agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' # セッション内のツール呼び出しのみ @@ -63,74 +63,74 @@ agenteye --json events --session-id run-001 --event-type tool_use,tool_result -- ## 全件取得（ページネーション） -結果は新しい順で返され、カーソルページネーションを使用します。 +結果は新しい順で返され、カーソルによるページネーションが行われます。 ```bash -# 一括取得: 200行ページで最大500行を取得 +# 一括取得: 200件ずつのページで最大500件を取得 agenteye --json events --session-id run-001 --limit 500 --all > events.json -# 手動ページング: next_cursor を再利用 +# 手動ページング: next_cursor を次のリクエストに渡す page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## --fields で出力を絞り込む +## --fields で出力をスリム化する -エージェントが読み取るキーを（テーブルと `--json` の両方で）制限します。 +テーブルおよび `--json` の両方でキーを制限し、エージェントが読む量を減らします。 ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -不明なフィールド名は（終了コード `2` で）拒否され、有効なフィールド一覧が表示されます。フィールド名を確認する手軽な方法です。 +不明なフィールド名は（終了コード `2` で）有効なフィールドの一覧とともに拒否されるため、フィールド名を調べる簡単な方法としても使えます。 ## 有効なフィルター値を調べる ```bash agenteye --json list envs | jq -r '.values[]' # --env に使える値 -agenteye --json list tools | jq -r '.values[]' # ツール名; agents, models, event_types なども同様 +agenteye --json list tools | jq -r '.values[]' # ツール名（agents, models, event_types なども同様） agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX の有効な KEY ``` -## 組織の選択（マルチテナント） +## 組織を選択する（マルチテナント） -複数の組織に所属している場合、ログイン時にアクティブなテナントを選択します（保存されます）。 +複数の組織に所属している場合は、ログイン時にアクティブなテナントを選択します（設定は保存されます）。 ```bash agenteye login --org acme --email you@corp.com # ログインと同時にテナントを設定 agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # 1コマンドのみ上書き +agenteye --org globex --json sessions --since 24h # 1コマンドだけ上書き ``` -`--org` を指定しないマルチ組織ログインは非ゼロで終了し、選択可能な組織一覧を表示します。 +`--org` なしでマルチ組織アカウントにログインすると、ゼロ以外の終了コードで選択可能な組織の一覧が表示されます。 -## SDK/コレクター用APIキーのプロビジョニング +## SDK/コレクター用のAPIキーを発行する ```bash # シークレットは一度だけ表示されます — --json の場合は .key フィールドに含まれます key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # ローテーション; 無効化は agenteye keys disable ci-bot --yes +agenteye keys regenerate ci-bot --yes # ローテーション; 失効させるには agenteye keys disable ci-bot --yes ``` -## 保存済みまたはアドホッククエリの実行 +## 保存済みまたはアドホッククエリを実行する ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' agenteye --json query run errs --arg prod | jq '.rows' # 保存済みクエリ + 位置引数 $1 ``` -## インシデントの非対話的なトリアージ +## インシデントを非対話的にトリアージする ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> ミューテーション操作は `--json` 使用時またはstdinがTTYでない場合、確認プロンプトを自動的にスキップします。エージェントがハングしないようになっています。他の場所で明示的にスキップするには `--yes`/`-y` を渡してください。 +> ミューテーションは `--json` 使用時またはstdinがTTYでない場合、確認プロンプトを自動でスキップするため、エージェントがハングすることはありません。それ以外の場所で明示的にスキップするには `--yes`/`-y` を渡してください。 ## スクリプトでの終了コード処理 @@ -156,15 +156,15 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` （`key` は一度のみ表示） | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` （`key` は一度だけ表示） | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| 作成/更新/削除（全般） | リソースオブジェクト、または削除の場合は `{"deleted": true, "id"}` | +| create/update/delete（全般） | リソースオブジェクト、削除の場合は `{"deleted": true, "id"}` | | 失敗時（全般、`--json` 使用） | stdout に `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | -- **event** の各アイテム（`events`）: `id, session_id, agent_id, event_type, ts, payload, environment` -- **evaluation** の各アイテム（`evals`）: `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at` -- **session** の各アイテム（`sessions`）: `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation` +- 各**イベント**アイテム（`events`）: `id, session_id, agent_id, event_type, ts, payload, environment`。 +- 各**評価**アイテム（`evals`）: `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`。 +- 各**セッション**アイテム（`sessions`）: `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`。 -各コマンドの `--fields` は、そのコマンド固有のアイテムのフィールド名のみを受け付けます。`sessions` と `evals` ではフィールドセットが異なるため、一方で有効な名前が他方では拒否される場合があります。 \ No newline at end of file +各コマンドの `--fields` は、そのコマンド固有のアイテムのフィールド名のみを受け付けます。`sessions` と `evals` でフィールドセットが異なるため、一方で有効な名前が他方では拒否される場合があります。 \ No newline at end of file diff --git a/docs/ja/agenteye/deployment.mdx b/docs/ja/agenteye/deployment.mdx index 40e90665..996376c5 100644 --- a/docs/ja/agenteye/deployment.mdx +++ b/docs/ja/agenteye/deployment.mdx @@ -3,7 +3,6 @@ title: "デプロイメント" description: "AgentEye デプロイメントドキュメント。" --- - このガイドでは、AgentEye サーバーとダッシュボードを本番環境にデプロイする方法を説明します。 --- @@ -11,17 +10,17 @@ description: "AgentEye デプロイメントドキュメント。" ## アーキテクチャ概要 ``` - [ AIエージェントマシン ] [ あなたのインフラ ] + [ AI エージェントマシン ] [ お客様のインフラ ] Python SDK - | JSONLを書き込む +----------------------+ + | JSONL を書き込み +----------------------+ v +--->| PostgreSQL 15+ | - agenteye-collector --HTTP--+ | | (リレーショナルストア) | + agenteye-collector --HTTP--+ | | (リレーショナルストア) | | | +----------------------+ v | +--------+ | +----------------------+ | Server |<------+--->| ClickHouse 24+ | - +--------+ | | (イベント / 分析) | + +--------+ | | (イベント / 分析) | ^ | +----------------------+ API | | | | +----------------------+ @@ -30,135 +29,134 @@ description: "AgentEye デプロイメントドキュメント。" +-----------+ ``` -- **Server**: Rust 製 HTTP サービス。イベントバッチを受信し、ClickHouse に書き込み、PostgreSQL でリレーショナル状態を管理します。 -- **Dashboard**: Next.js ウェブアプリ。サーバー API 経由でのみ読み書きします。 -- **agenteye-collector**: サーバーホストではなく、エージェントマシンにデプロイします。 -- **Postgres 15+**: **必須**。（マルチテナントリリースで 14 から引き上げ。org-membership スキーマが列リスト `ON DELETE SET NULL` 外部キーを使用しており、これは Postgres 15+ の機能です。このバージョンをデプロイする前に Postgres をアップグレードしてください。）OLTP 状態を保管します: `api_keys`、`users`、`sessions`、`evaluation_jobs`（キュー）、`dashboards`、`saved_queries`、`otp_codes`、およびマルチテナントテーブル `orgs`、`org_memberships`、`org_settings`。 -- **ClickHouse 24+**: **必須**。すべての取り込みイベントの分析ストア。エンジン: `ReplacingMergeTree`、月単位でパーティション分割、`(session_id, ts, dedup_key)` 順。サーバーは `CLICKHOUSE_URL` 経由で接続します。同梱の `deploy/base/clickhouse/` にはパフォーマンスチューニング済みシングルノード設定が含まれています。**マルチテナント要件:** 同梱設定では SQL アクセス管理と `users_without_row_policies_can_read_rows=false` が有効化されており、サーバーが組織ごとに読み取り専用 ClickHouse ユーザーと行ポリシーを作成できます（SQL エディターと AI エージェントのエンジンレベルの分離境界）。独自の ClickHouse 設定を使用する場合は、これらの設定を引き継いでください（`deploy/base/clickhouse/configmap.yaml` 参照）。 -- **Redis 7+**: *オプション*の共有キャッシュ + レート制限バックエンド。サーバーとダッシュボードの両方が `REDIS_URL` 経由で接続します。存在しない場合、どちらも Postgres のみのパスに安全にフォールバックします。後述の **Redis（オプションキャッシュ）** を参照してください。 +- **Server**: Rust 製 HTTP サービス。イベントバッチを受信し、ClickHouse に書き込み、PostgreSQL でリレーショナルステートを管理します。 +- **Dashboard**: Next.js 製ウェブアプリ。すべての読み書きをサーバー API 経由で行います。 +- **agenteye-collector**: サーバーホストではなく、エージェントマシンにデプロイされます。 +- **Postgres 15+**: **必須。**（マルチテナントリリースで 14 から引き上げ。org メンバーシップスキーマが Postgres 15+ の列リスト `ON DELETE SET NULL` 外部キーを使用しています。このバージョンをデプロイする前に Postgres をアップグレードしてください。）OLTP ステートとして `api_keys`、`users`、`sessions`、`evaluation_jobs`（キュー）、`dashboards`、`saved_queries`、`otp_codes` に加え、マルチテナントテーブル `orgs`、`org_memberships`、`org_settings` を格納します。 +- **ClickHouse 24+**: **必須。** 取り込まれたすべてのイベントの分析ストアです。エンジン: `ReplacingMergeTree`、月単位でパーティション分割、`(session_id, ts, dedup_key)` 順。サーバーは `CLICKHOUSE_URL` 経由で接続します。バンドルの `deploy/base/clickhouse/` はパフォーマンス最適化済みのシングルノード設定を同梱しています。**マルチテナント要件:** バンドルの設定は SQL アクセス管理と `users_without_row_policies_can_read_rows=false` を有効にし、サーバーが組織ごとに読み取り専用 ClickHouse ユーザーとロウポリシーを作成できるようにします（SQL エディターと AI エージェント向けのエンジンレベルの分離境界）。独自の ClickHouse 設定を使用する場合は、これらの設定を引き継いでください（`deploy/base/clickhouse/configmap.yaml` を参照）。 +- **Redis 7+**: *オプションの* 共有キャッシュ + レート制限バックエンドです。サーバーとダッシュボードはどちらも `REDIS_URL` 経由で接続します。不在時は両方とも Postgres のみのパスに graceful にデグレードします。下記の **Redis（オプションキャッシュ）** を参照してください。 --- ## サーバー -### イメージのプル +### イメージの取得 ```bash echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> 現在のビルドは `beta-latest` で公開されています。`latest` は安定版リリースにのみ割り当てられます。本番環境では特定の `:v<バージョン>` タグを固定してください。[利用可能なイメージタグ](#available-image-tags)を参照してください。 +> 現在のビルドは `beta-latest` で公開されています。`latest` は安定版リリースにのみ割り当てられます。本番環境では特定の `:v<バージョン>` タグを固定することを推奨します。[利用可能なイメージタグ](#available-image-tags)を参照してください。 ### 環境変数 | 変数 | 必須 | デフォルト | 説明 | |---|---|---|---| -| `DATABASE_URL` | はい | なし | Postgres DSN。`postgres://` スキームの標準 libpq 接続文字列形式。`?sslmode=require` などの libpq パラメーターをサポートします。パスワードに `/`、`+`、`=` を含めないでください。URL セーフなパスワードの生成には `openssl rand -hex` を使用してください。 | -| `ADMIN_KEY` | いいえ | なし | ブートストラップ管理者 API キー。起動のたびに全権限でアップサートされます。値を変更して再起動することでローテーションできます。 | +| `DATABASE_URL` | はい | なし | Postgres DSN。スキーム `postgres://` の標準 libpq 接続文字列形式。`?sslmode=require` などの libpq パラメーターをサポート。パスワードに `/`、`+`、`=` を含めないでください。URL セーフなパスワードの生成には `openssl rand -hex` を使用してください。 | +| `ADMIN_KEY` | いいえ | なし | ブートストラップ管理者 API キー。起動のたびにすべての権限でアップサートされます。値を変更して再起動することでローテーションできます。 | | `LISTEN_ADDR` | いいえ | `0.0.0.0:8080` | バインドする TCP アドレス | | `MAX_BODY_BYTES` | いいえ | `134217728`（128 MB） | リクエストボディの最大サイズ | -| `ADMIN_EMAIL` | いいえ | なし | ブートストラップ管理者ユーザーのメールアドレス。起動のたびに全権限でアップサートされ、保護済みとしてマークされます（ダッシュボード/API から無効化や権限変更が不可）。ブートストラップ管理者をローテーションするには、`ADMIN_EMAIL` を変更して再起動してください。新しいメールアドレスが保護済みとしてアップサートされ、以前のアドレスは手動でデータベースから削除するまで保護が維持されます。 | -| `ALLOWED_EMAILS` | いいえ | なし（すべてブロック） | ユーザー作成およびログインを許可するメールアドレスのカンマ区切りリスト。完全なアドレス（`user@example.com`）とドメインワイルドカード（`*@example.com`）をサポートします。未設定の場合、ユーザーの作成もログインもできません。**初回起動時のシードのみ**: 初回起動時にデフォルト org のアローリストをシードします。それ以降は各 org の [`//settings`](#operational-settings) ページが正式な設定元となり、この環境変数の変更は無効です。 | -| `SMTP_HOST` | いいえ | なし | OTP メール送信用 SMTP サーバーのホスト名。未設定の場合、OTP コードは stdout に記録されます。 | -| `SMTP_PORT` | いいえ | `587` | SMTP サーバーのポート | +| `ADMIN_EMAIL` | いいえ | なし | ブートストラップ管理者ユーザーのメールアドレス。起動のたびにすべての権限でアップサートされ、保護済みとしてマーク（ダッシュボード/API 経由での無効化や権限変更不可）。ブートストラップ管理者をローテーションするには `ADMIN_EMAIL` を変更して再起動してください。新しいメールアドレスが保護済みとしてアップサートされ、以前のものはデータベースで手動クリアされるまで保護が維持されます。 | +| `ALLOWED_EMAILS` | いいえ | なし（全て拒否） | ユーザー作成とログインに許可されるメールのカンマ区切りリスト。完全なアドレス（`user@example.com`）とドメインワイルドカード（`*@example.com`）をサポート。未設定の場合、ユーザーの作成とログインはすべて不可。**初回起動時のみのシード**: 初回起動時にデフォルト org のアローリストをシードし、以降は各 org の [`//settings`](#operational-settings) ページが信頼できる情報源となり、この環境変数の変更は無効になります。 | +| `SMTP_HOST` | いいえ | なし | OTP メール送信用 SMTP サーバーのホスト名。未設定の場合、OTP コードは stdout にログ出力されます。 | +| `SMTP_PORT` | いいえ | `587` | SMTP サーバーポート | | `SMTP_USERNAME` | いいえ | なし | SMTP 認証ユーザー名 | | `SMTP_PASSWORD` | いいえ | なし | SMTP 認証パスワード | -| `SMTP_FROM` | いいえ | なし | OTP メールの送信者メールアドレス | -| `SMTP_TLS` | いいえ | STARTTLS | 明示的に無効にしない限り STARTTLS が使用されます。`false` または `0` でプレーンテキスト（TLS なし）送信になります。それ以外の値（未設定を含む）では STARTTLS が有効になります。 | -| `DASHBOARD_URL` | いいえ | 組み込みデフォルト | OTP メールのマジックリンクとアラート通知のインシデントマジックリンクの構築に使用するダッシュボードのオリジン。未設定の場合、組み込みデフォルト（OTP のみの場合はダッシュボード由来のリクエストオリジンを優先）にフォールバックします。メールと Slack/インシデントリンクの両方をあなたのダッシュボードに向けるために、ドメインが分かれている場合はこれを設定してください。後述の **Email マジックリンク URL** を参照してください。ほとんどのオペレーターはこの設定は不要です。 | -| `SESSION_TTL_SECS` | いいえ | `86400`（24 時間） | ダッシュボードセッションの有効期間（秒）。**初回起動時のシードのみ**: 初回デプロイ後は [`//settings`](#operational-settings) から org ごとに編集してください。 | -| `OTP_TTL_SECS` | いいえ | `600`（10 分） | OTP コードの有効期間（秒）。**初回起動時のシードのみ**: 初回デプロイ後は [`//settings`](#operational-settings) から org ごとに編集してください。 | -| `REDIS_URL` | いいえ | なし | オプションの共有キャッシュ + レート制限バックエンド（例: `redis://redis:6379/0`）。設定すると、サーバーは認証済み API キーのルックアップ、ダッシュボードの `/models` 集計、セッションリスト、env リストファセットをキャッシュし、OTP リクエストのレート制限を Postgres COUNT から Redis INCR に切り替えます。未設定または接続不可の場合、サーバーはキャッシュなしで動作します（OTP 制限は Postgres にフォールバック、その他のキャッシュ呼び出しはソースオブトゥルースにフォールスルー）。後述の **Redis（オプションキャッシュ）** を参照してください。 | -| `CLICKHOUSE_URL` | **はい** | なし | ClickHouse インスタンスのベース URL（例: `http://clickhouse:8123`）。サーバーは起動のたびにこのデータベースにイベントスキーマを適用し、ClickHouse に到達できない場合は起動を拒否します。後述の **ClickHouse（必須分析ストア）** を参照してください。 | +| `SMTP_FROM` | いいえ | なし | OTP メールの送信元メールアドレス | +| `SMTP_TLS` | いいえ | STARTTLS | 明示的に無効にしない限り STARTTLS が使用されます: `false` または `0` でプレーンテキスト（TLS なし）。それ以外の値（未設定を含む）で STARTTLS が有効になります。 | +| `DASHBOARD_URL` | いいえ | 組み込みデフォルト | OTP メールのマジックリンクおよびアラート通知のインシデントマジックリンク生成に使用するダッシュボードのオリジン。未設定の場合、組み込みデフォルトにフォールバック（OTP のみ、まずダッシュボード由来のリクエストオリジンを試みます）。ダッシュボードと API が別ドメインの場合、メールと Slack/インシデントリンクが正しいダッシュボードを指すよう設定してください。下記の **メールマジックリンク URL** を参照。ほとんどのオペレーターは設定不要です。 | +| `SESSION_TTL_SECS` | いいえ | `86400`（24 時間） | ダッシュボードセッションの有効期間（秒）。**初回起動時のみのシード**: 初回デプロイ後は [`//settings`](#operational-settings) で org ごとに編集可能。 | +| `OTP_TTL_SECS` | いいえ | `600`（10 分） | OTP コードの有効期間（秒）。**初回起動時のみのシード**: 初回デプロイ後は [`//settings`](#operational-settings) で org ごとに編集可能。 | +| `REDIS_URL` | いいえ | なし | オプションの共有キャッシュ + レート制限バックエンド（例: `redis://redis:6379/0`）。設定すると、サーバーは認証済み API キーのルックアップ、ダッシュボードの `/models` アグリゲート、セッションリスト、env リストファセットをキャッシュし、OTP リクエストのレート制限を Postgres COUNT から Redis INCR に移行します。未設定または到達不能の場合、サーバーはキャッシュなしで動作します（OTP 制限は Postgres にフォールバック、その他すべてのキャッシュ呼び出しは信頼できる情報源に素通しになります）。下記の **Redis（オプションキャッシュ）** を参照してください。 | +| `CLICKHOUSE_URL` | **はい** | なし | ClickHouse インスタンスのベース URL（例: `http://clickhouse:8123`）。サーバーは起動のたびにこのデータベースにイベントスキーマを適用し、ClickHouse に到達できない場合は起動を拒否します。下記の **ClickHouse（必須の分析ストア）** を参照してください。 | | `CLICKHOUSE_DATABASE` | いいえ | `agenteye` | ClickHouse データベース（スキーマ）名。存在しない場合、サーバーが起動時に作成します。 | -| `ORG_CH_SECRET` | いいえ（シングルテナント） / **はい（マルチ org）** | 開発用デフォルト | 各組織のテナントごとの ClickHouse パスワードの導出元となる HMAC キー。SQL エディターと AI エージェントの `run_query` は org 専用の読み取り専用 ClickHouse ユーザーとして実行され、行ポリシーがエンジンレベルでテナント分離を強制します。シングルテナントデプロイメントは組み込み開発用デフォルトで正常に起動できますが、**2 番目の org をプロビジョニングする前に強力で安定した値を設定する必要があります**（`agenteye-orgctl org create` CLI は組み込み開発用デフォルトでの実行を拒否します）。ローテーションすると次回起動時の再プロビジョニングまで各 org の ClickHouse ユーザーが孤立します（起動時の調整で自動的に修復されます）。秘密を保持し、レプリカ間で変更しないでください。org プロビジョニング自体はオペレーター専用です。後述の **組織（マルチテナント）** を参照してください。 | -| `DEFAULT_ORG_NAME` | いいえ | `Default` | 組み込みデフォルト org にシードされる表示名。**初回起動時のシードのみ**（org がまだ新規移行後の汎用 ID を持っている間のみ）。org の名前を変更（`agenteye-orgctl org rename`）すると、その名前が正式となり、この環境変数は以降無効です。 | -| `DEFAULT_ORG_SLUG` | いいえ | `default` | 組み込みデフォルト org の URL スラグ（ダッシュボードのパス `//…`）。`DEFAULT_ORG_NAME` と同じ初回起動時のみ / 未変更時のみのセマンティクスです。1〜40 文字の小文字英数字で、単独の内部ハイフンを使用でき、[予約語](#organizations-multi-tenancy)でない必要があります。無効な値は無視されます（org は `default` を維持）。シングルテナントのインストールを、デプロイ後の CLI 手順なしに `/default` の代わりに `/acme` などで表示できます。 | -| `RUST_LOG` | いいえ | `info` | ログの冗長性（`debug`、`warn`、`error`、`agenteye_server=trace`） | -| `EVALUATOR_ENDPOINT` | いいえ | なし | 評価サービスのベース URL（例: `http://evaluator:9000`）。未設定の場合、評価パイプライン全体が no-op になります（キュー行の書き込みなし、ワーカーなし）。[Evaluation Suite](/ja/agenteye/evaluation-suite) を参照してください。 | -| `EVALUATOR_TOKEN` | いいえ | なし | 評価サービスへの `Authorization: Bearer ` として送信されます。**評価サービスに設定されている値と同一である必要があります。** 評価サービスがトークンなしで設定されている場合のみオプションです。 | -| `EVALUATOR_WORKERS` | いいえ | `2` | 並行数: 評価をディスパッチするサーバーインスタンスごとのワーカータスク数。水平スケールされた複数のサーバーで安全に実行できます。 | -| `EVALUATOR_CLAIM_BATCH` | いいえ | `4` | 1 回のティックでシングルワーカーがクレームする評価の最大数。バッチは**並行して**ディスパッチされるため、評価エンドポイントへの総並行数は `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` になります。 | -| `EVALUATOR_POLL_IDLE_SECS` | いいえ | `2` | 処理待ちがない場合にワーカーがディスパッチ試行間にスリープする時間。 | -| `EVALUATOR_POLLING_INTERVAL_SECS` | いいえ | `10` | 評価サービスがレスポンスごとの `next_poll_secs` を返さず、`GET /config` から `default_poll_interval_secs` もアドバタイズしない場合の `GET /evaluate/{id}` ポーリングの最終フォールバック間隔（秒）。 | +| `ORG_CH_SECRET` | いいえ（シングルテナント）/ **はい（マルチ org）** | 開発デフォルト | 各組織のテナントごとの ClickHouse パスワードを導出する HMAC キー。SQL エディターと AI エージェントの `run_query` は org 専用の読み取り専用 ClickHouse ユーザーとして実行され、そのロウポリシーがエンジン内でテナント分離を強制します。シングルテナントデプロイは組み込みの開発デフォルトで問題なく起動しますが、**2 番目の org をプロビジョニングする前に強力で安定した値を設定する必要があります**（`agenteye-orgctl org create` CLI は組み込みの開発デフォルトでの実行を拒否します）。ローテーションすると、次回起動時の再プロビジョニング（起動時の調整が自動的に修復）まで、すべての org の ClickHouse ユーザーが孤立します。レプリカ間で秘密かつ不変に保ってください。org のプロビジョニング自体はオペレーター専用です。下記の **組織（マルチテナント）** を参照してください。 | +| `DEFAULT_ORG_NAME` | いいえ | `Default` | 組み込みデフォルト org にシードされる表示名。**初回起動時のみ**、かつ org がまだ新規移行後の汎用的なアイデンティティを持っている間のみ、起動時に適用され、以降は無視されます。org を（`agenteye-orgctl org rename` で）リネームすると、その名前が権威ある名前となり、この環境変数はそれ以上効果を持ちません。 | +| `DEFAULT_ORG_SLUG` | いいえ | `default` | 組み込みデフォルト org の URL スラッグ（ダッシュボードのパス `//…`）。`DEFAULT_ORG_NAME` と同様に初回起動時のみ/プリスティン状態のみのセマンティクスです。1〜40 文字の小文字英数字（内部ハイフン 1 つまで）で、[予約語](#organizations-multi-tenancy) でないことが必要。無効な値は無視されます（org は `default` のまま）。シングルテナントインストールで、デプロイ後の CLI 手順なしに `/default` の代わりに `/acme` のような表示が可能になります。 | +| `RUST_LOG` | いいえ | `info` | ログの詳細度（`debug`、`warn`、`error`、`agenteye_server=trace`） | +| `EVALUATOR_ENDPOINT` | いいえ | なし | 評価サービスのベース URL（例: `http://evaluator:9000`）。未設定の場合、評価パイプライン全体は no-op になり、キューの行も書き込まれず、ワーカーも実行されません。[評価スイート](/ja/agenteye/evaluation-suite)を参照してください。 | +| `EVALUATOR_TOKEN` | いいえ | なし | 評価サービスへの `Authorization: Bearer ` として送信されます。**評価サービスが設定されている値と同一である必要があります。** 評価サービスがトークンなしで設定されている場合のみオプションです。 | +| `EVALUATOR_WORKERS` | いいえ | `2` | 並行数: 評価をディスパッチするサーバーインスタンスごとのワーカータスク数。水平スケールされた複数のサーバーで安全に実行可能。 | +| `EVALUATOR_CLAIM_BATCH` | いいえ | `4` | 1 回のティックでシングルワーカーがクレームする評価の最大数。バッチは**並行して**ディスパッチされるため、評価エンドポイントへの合計並行数は `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` になります。 | +| `EVALUATOR_POLL_IDLE_SECS` | いいえ | `2` | 保留中のものがない場合に、ワーカーがディスパッチ試行の間にスリープする時間。 | +| `EVALUATOR_POLLING_INTERVAL_SECS` | いいえ | `10` | 評価サービスがレスポンスごとの `next_poll_secs` を返さず、`GET /config` の `default_poll_interval_secs` もアドバタイズしない場合の `GET /evaluate/{id}` ポーリングの最終フォールバックサイクル（秒）。 | | `EVALUATOR_REQUEST_TIMEOUT_MS` | いいえ | `30000` | 評価サービスへの HTTP リクエストごとのタイムアウト（ミリ秒）。 | -| `EVALUATOR_MAX_ATTEMPTS` | いいえ | `5` | この回数の失敗後、評価は終端的な `error`（失敗がリクエストタイムアウトの場合は `timeout`）として記録されます。 | -| `EVALUATOR_CONFIG_REFRESH_SECS` | いいえ | `300`（5 分） | サーバーが評価サービスから `GET /config` を再フェッチする頻度。 | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | いいえ | `3600`（1 時間） | AgentEye がセッションを `timeout` として終了するまでのポーリングキュー内の最大経過時間。永遠に `pending` を返す評価サービスに対するガード。 | -| `ALERT_WORKERS` | いいえ | `1` | 並行数: アラートルールを評価するサーバーインスタンスごとのワーカータスク数。[Alerts](/ja/agenteye/alerts) を参照してください。 | +| `EVALUATOR_MAX_ATTEMPTS` | いいえ | `5` | この回数の試行が失敗すると、評価は終端状態 `error`（失敗がリクエストタイムアウトの場合は `timeout`）として記録されます。 | +| `EVALUATOR_CONFIG_REFRESH_SECS` | いいえ | `300`（5 分） | サーバーが評価サービスの `GET /config` を再取得する頻度。 | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | いいえ | `3600`（1 時間） | セッションがポーリングキューに留まれる最大の実時間。AgentEye がこれを超えると `timeout` として終了します。評価サービスが永久に `pending` を返し続ける場合のガードです。 | +| `ALERT_WORKERS` | いいえ | `1` | 並行数: アラートルールを評価するサーバーインスタンスごとのワーカータスク数。[アラート](/ja/agenteye/alerts)を参照してください。 | | `ALERT_CLAIM_BATCH` | いいえ | `16` | 1 回のティックでシングルワーカーがクレームするアラートの最大数。 | -| `ALERT_POLL_IDLE_SECS` | いいえ | `5` | キューが空のときにアラートワーカーがスリープする時間。 | -| `ALERT_REQUEST_TIMEOUT_MS` | いいえ | `15000` | トリガー評価ごとのタイムアウト（ClickHouse クエリ + アウトバウンドチャンネル HTTP）。 | -| `ALERT_MAX_ATTEMPTS` | いいえ | `5` | 通常のケイデンスへの再スケジュール（指数バックオフの代わり）が行われるまでの連続した一時的失敗回数。 | -| `AUDIT_WORKERS` | いいえ | `1` | 並行数: 監査を実行するサーバーインスタンスごとのワーカータスク数。[Audits](/ja/agenteye/audits) を参照してください。 | -| `AUDIT_CLAIM_BATCH` | いいえ | `1` | 1 回のティックでシングルワーカーがクレームする監査の最大数。エージェント型の調査は 1 つの長いループであるため、デフォルトは 1 です。 | -| `AUDIT_POLL_IDLE_SECS` | いいえ | `30` | 監査が予定されていないときに監査ワーカーがスリープする時間。 | +| `ALERT_POLL_IDLE_SECS` | いいえ | `5` | キューが空の場合にアラートワーカーがスリープする時間。 | +| `ALERT_REQUEST_TIMEOUT_MS` | いいえ | `15000` | トリガー評価ごとのタイムアウト（ClickHouse クエリ + 外部チャンネル HTTP）。 | +| `ALERT_MAX_ATTEMPTS` | いいえ | `5` | 通常のサイクルでリスケジュールされる前の連続した一時的障害数（指数バックオフの代わりに）。 | +| `AUDIT_WORKERS` | いいえ | `1` | 並行数: 監査を実行するサーバーインスタンスごとのワーカータスク数。[監査](/ja/agenteye/audits)を参照してください。 | +| `AUDIT_CLAIM_BATCH` | いいえ | `1` | 1 回のティックでシングルワーカーがクレームする期限到来監査の最大数。エージェント的な調査は長いループのため、デフォルトは 1 です。 | +| `AUDIT_POLL_IDLE_SECS` | いいえ | `30` | 監査が期限切れでない場合に監査ワーカーがスリープする時間。 | | `AUDIT_REQUEST_TIMEOUT_MS` | いいえ | `30000` | ClickHouse へのポリシークエリごとのタイムアウト（ミリ秒）。 | -| `AUDIT_LLM_TIMEOUT_MS` | いいえ | `1440000` | AI アシスタントサービスへのエージェント型調査呼び出しのタイムアウト。完全なエージェントループは数分かかるため、サーバーがあきらめる前にエージェントが部分的な調査結果を返せるよう、エージェント自身の `AGENTEYE_AUDIT_TIMEOUT_MS` より**大きく**設定してください。 | -| `AUDIT_MAX_ATTEMPTS` | いいえ | `5` | 通常のケイデンスへの再スケジュール（指数バックオフの代わり）が行われるまでの連続した一時的失敗回数。 | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | いいえ | — | 監査のエージェント型調査は AI アシスタント `agent` サービスを呼び出します。**アシスタントと同じ接続を再利用する**ため、これら 2 つを**サーバー**にも設定してください（同梱のマニフェスト/compose はそうなっています）。両方設定 ⇒ 監査が AI 調査を実行。どちらか未設定 ⇒ 監査は**ポリシーのみ**で実行（決定論的 SQL ポリシーパスは引き続き実行）、監査ごとの `llm_enabled` フラグに関わらず。エージェントにも LLM が設定されている必要があります。[assistant.md](/ja/agenteye/assistant) を参照してください。 | +| `AUDIT_LLM_TIMEOUT_MS` | いいえ | `1440000` | AI アシスタントサービスへのエージェント的調査コールのタイムアウト。完全なエージェントループは数分かかります。サーバーが諦める前にエージェントが部分的な結果を返せるよう、エージェント自身の `AGENTEYE_AUDIT_TIMEOUT_MS` より**大きな値**に設定してください。 | +| `AUDIT_MAX_ATTEMPTS` | いいえ | `5` | 通常のサイクルでリスケジュールされる前の連続した一時的障害数（指数バックオフの代わりに）。 | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | いいえ | — | 監査のエージェント的調査は AI アシスタントの `agent` サービスを呼び出し、**アシスタントと同じ接続を再利用します**。そのため、これら 2 つは**サーバーにも設定する必要があります**（バンドルのマニフェスト/compose はそのようになっています）。両方設定 ⇒ 監査は AI 調査を実行し、どちらか未設定 ⇒ 監査は**ポリシーのみ**で実行されます（決定論的な SQL ポリシーパスは引き続き実行されます）。これは監査ごとの `llm_enabled` フラグに関わらず適用されます。エージェントにも LLM の設定が必要です — [assistant.md](/ja/agenteye/assistant) を参照してください。 | -**AI アシスタントサービス — 監査 + サンドボックス設定。** エージェント型調査とそのインポッド Python サンドボックスは、**エージェントサービス**（サーバーではない）で調整します。すべて `AGENTEYE_AUDIT_*` プレフィックス、すべてオプション: +**AI アシスタントサービス — 監査 + サンドボックス設定。** エージェント的調査とそのポッド内 Python サンドボックスは、**エージェントサービス**（サーバーではなく）で `AGENTEYE_AUDIT_*` プレフィックスを使用してすべてオプションとしてチューニングされます: | 変数 | デフォルト | 意味 | |---|---|---| -| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | 調査ごとの最大エージェントターン数。 | -| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | 1 回の調査の経過時間（20 分）。サーバーの `AUDIT_LLM_TIMEOUT_MS` より**小さく**設定する必要があります。 | -| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | エージェントポッドごとの同時調査数（チャットアシスタントの予算とは別）。 | +| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | 調査あたりの最大エージェントターン数。 | +| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | 1 回の調査の実時間（20 分）。サーバーの `AUDIT_LLM_TIMEOUT_MS` より**小さく**保ってください。 | +| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | エージェントポッドあたりの同時調査数（チャットアシスタントの予算とは独立）。 | | `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | bubblewrap サンドボックスのスクリプトごとの制限。 | -**サンドボックスのプラットフォーム要件。** 監査コードサンドボックスはモデルの Python を bubblewrap ジェイル内で実行しますが、これには**非特権ユーザー名前空間**が必要です。エージェントポッドは `clone()` フラグを許可する必要があります。k8s の場合は `seccompProfile: Unconfined`、compose の場合は `security_opt: [seccomp:unconfined]` をエージェントに設定してください。ノードカーネルが非特権ユーザー名前空間を無効にしている場合（一部の GKE COS イメージなど）、**サンドボックスのプリフライトが失敗し、監査は自動的に SQL のみに切り替わります**。エラーにはならず、エージェントの `/health` に `sandbox_available: false` が表示されるだけです。 +**サンドボックスのプラットフォーム要件。** 監査コードサンドボックスはモデルの Python を bubblewrap jail 内で実行します。これには**非特権ユーザー名前空間**が必要です。エージェントポッドは `clone()` フラグを許可する必要があります — k8s では `seccompProfile: Unconfined`、compose では `security_opt: [seccomp:unconfined]` をエージェントに設定してください。ノードのカーネルが非特権ユーザー名前空間を無効にしている場合（一部の GKE COS イメージなど）、サンドボックスの**プリフライトが失敗し、オーディターは自動的に SQL のみにデグレードします**。エラーは発生せず、エージェントの `/health` で `sandbox_available: false` として表示されるだけです。 ### 実行 -`DATABASE_URL` と `CLICKHOUSE_URL` を環境に設定し（サーバーは ClickHouse なしでの起動を拒否します）、コンテナに渡します: +環境変数に `DATABASE_URL` を設定し、コンテナに渡します: ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest ``` -サーバーは起動時にデータベースマイグレーションを自動実行します。別途マイグレーション手順は不要です。 +サーバーは起動時にデータベースマイグレーションを自動的に実行します。別途マイグレーション手順は不要です。 ### ヘルスチェック ``` -GET /health # 生存確認 - プロセス起動後は常に {"status":"ok"} -GET /ready # 準備確認 - Postgres + ClickHouse が到達可能なら 200、そうでなければ 503 +GET /health # 生存確認 - プロセスが起動すると常に {"status":"ok"} を返す +GET /ready # 準備確認 - Postgres + ClickHouse に到達できれば 200、そうでなければ 503 ``` -認証不要です。**生存確認**プローブには `/health` を、**準備確認** / ロードバランサープローブには `/ready` を使用してください。`/ready` はサーバーがサービスを提供するために必要なハード依存関係（Postgres + ClickHouse）をチェックするため、動作中でもデータベースに到達できないサーバーはローテーションから外され `NotReady` と表示されます。Redis は報告されますが準備確認を失敗させることはありません。同梱の Kubernetes マニフェストでは、準備確認プローブはすでに `/ready` を指しており、生存確認は `/health` のままです。Kubernetes ネイティブのポッド障害アラートを Slack に送信するオプトイン機能を含む全体像については、[enterprise-docs/health-monitoring.md](/ja/agenteye/health-monitoring) を参照してください。 +認証不要です。**liveness** プローブには `/health`、**readiness** / ロードバランサープローブには `/ready` を使用してください。`/ready` はサーバーがサービスを提供するために必須のハード依存関係（Postgres + ClickHouse）をチェックし、実行中でもデータベースに到達できないサーバーはローテーションから外れて `NotReady` として表示されます。Redis は報告されますが、readiness を失敗させることはありません。バンドルの Kubernetes マニフェストでは readiness プローブはすでに `/ready` を指しており、liveness は `/health` のままです。Slack へのオプトイン Kubernetes ネイティブポッド障害アラートを含む詳細については [enterprise-docs/health-monitoring.md](/ja/agenteye/health-monitoring) を参照してください。 -### Email マジックリンク URL +### メールマジックリンク URL -OTP ログインメールにはワンタップで**ダッシュボードを開く**ボタンが含まれています。クリックすると `/login?token=&email=
` に移動し、ダッシュボードはそのペアをセッションと交換してアプリにリダイレクトします（手動でのコード再入力は不要）。サーバーはリンクの構築に使用するダッシュボードのオリジンを 3 段階で解決します: +OTP ログインメールには**ダッシュボードをワンタップで開く**ボタンが含まれます。クリックすると `/login?token=&email=
` にアクセスし、ダッシュボードがそのペアをセッションに交換してアプリにリダイレクトします。手動でのコード再入力は不要です。サーバーはリンク生成に使用するダッシュボードオリジンを 3 段階で解決します: -1. **`X-AgentEye-Dashboard-Url` ヘッダー**: ダッシュボードの `/api/auth/otp/request` プロキシが、自身のパブリックオリジンから自動的に設定します。同一オリジンのデプロイメント（サーバーとダッシュボードがプロキシヘッダーを転送する 1 つのイングレスの背後でホストを共有している場合）では、**設定は不要です**。 -2. **`DASHBOARD_URL` 環境変数**: ダッシュボードがサーバーの OTP リクエストエンドポイントから見えるオリジンとは異なるオリジンで到達可能な場合（`api.example.com` / `app.example.com` の分割）、またはイングレスがパブリックホストをダッシュボードポッドに伝播しない場合（`request.nextUrl.origin` が `0.0.0.0:3000` のようなワイルドカードバインドに解決される場合）に設定してください。例: `DASHBOARD_URL=https://app.example.com`。 -3. **デフォルト**: `https://app.befailproof.ai`。上記のいずれも存在しない場合のみ使用されます。 +1. **`X-AgentEye-Dashboard-Url` ヘッダー**: ダッシュボードの `/api/auth/otp/request` プロキシが独自のパブリックオリジンから自動設定します。同一オリジンのデプロイ（サーバーとダッシュボードが 1 つのイングレスの背後でホストを共有し、プロキシヘッダーを転送している場合）では、**設定不要です**。 +2. **`DASHBOARD_URL` 環境変数**: サーバーの OTP リクエストエンドポイントが見るオリジンとは異なるオリジンでダッシュボードが到達可能な場合（`api.example.com` / `app.example.com` の分割）、またはイングレスがパブリックホストをダッシュボードポッドに伝播しない場合（`request.nextUrl.origin` が `0.0.0.0:3000` のようなワイルドカードバインドに解決される場合）に設定します。例: `DASHBOARD_URL=https://app.example.com`。 +3. **デフォルト**: 上記のいずれも存在しない場合のみ `https://app.befailproof.ai` が使用されます。 -ヘッダー値は検証されます。`https://*` およびループバック（`http://localhost*`、`http://127.0.0.1*`）オリジンのみ受け付け、ワイルドカードバインドアドレス（`0.0.0.0`、`[::]`）は `https://` スキームでも拒否されます。それ以外はティア 2 にフォールスルーします。 +ヘッダー値は検証されます。`https://*` およびループバック（`http://localhost*`、`http://127.0.0.1*`）オリジンのみが受け入れられ、`https://` スキームを使用していてもワイルドカードバインドアドレス（`0.0.0.0`、`[::]`）は拒否されます。それ以外はすべて段階 2 にフォールスルーします。 -ワンライナーで実行中のクラスターに設定できます（ファイルなし、kustomize の再ビルドなし）: +実行中のクラスターに 1 行で設定できます。ファイル編集や kustomize の再ビルドは不要です: ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -これによりロールアウトがトリガーされ、新しいポッドは最初のリクエストで値を受け取ります。このオーバーライドは Deployment にのみ存在するため、オーバーレイに対して後で `kustomize build | kubectl apply` を実行すると、オーバーレイの `server-env.yaml` パッチに同じ環境変数を追加しない限り上書きされます。 +これによりロールアウトがトリガーされ、新しいポッドは最初のリクエスト時に値を読み込みます。オーバーライドは Deployment 上にのみ存在することに注意してください。オーバーレイに対して後から `kustomize build | kubectl apply` を実行すると、同じ環境変数をオーバーレイの `server-env.yaml` パッチに追加しない限り、この設定は上書きされます。 --- ## ダッシュボード -### イメージのプル +### イメージの取得 ```bash docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest @@ -169,12 +167,12 @@ docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest | 変数 | 必須 | デフォルト | 説明 | |---|---|---|---| | `AGENTEYE_SERVER_URL` | はい | なし | サーバーのベース URL（例: `http://localhost:8080`） | -| `AGENTEYE_API_KEY` | はい | なし | ダッシュボードがサーバーへの認証に使用する API キー。全権限が必要です（管理者キー推奨）。 | -| `AE_LOG_LEVEL` | いいえ | `info` | サーバーサイドのログ冗長性: `debug`、`info`、`warn`、`error`。問題診断時にアップストリームリクエスト/レスポンス行とセッション検証トレースを確認するには `debug` に設定してください。 | -| `AE_LOG_JSON` | いいえ | 自動 | `1` で JSON 形式の行ごと出力を強制、`0` で人間が読みやすい出力を強制。未設定の場合、`NODE_ENV=production` であれば JSON が自動的に有効になります。本番環境では `jq` やログアグリゲーターでパースしやすいよう JSON が推奨されます。 | -| `AE_ANALYTICS_DISABLED` | いいえ | なし | `1`/`true` に設定すると、ダッシュボードの匿名プロダクト利用テレメトリが無効になります。後述の[テレメトリとプライバシー](#telemetry--privacy)を参照してください。 | -| `REDIS_URL` | いいえ | なし | オプションの共有キャッシュバックエンド（例: `redis://redis:6379/0`）。設定すると、ダッシュボードはレプリカ間で `validateSession()` の結果をキャッシュし、レイテンシ集計 / env リストプロキシルートの Next.js フェッチキャッシュを共有します。エッジサイドの OTP リクエストと検証のレート制限も、Redis が存在する場合はそれを使用します（Redis に到達できない場合はオープンフォールバック、サーバーサイドの制限がセキュリティの最終防衛線）。後述の **Redis（オプションキャッシュ）** を参照してください。 | -| `AGENTEYE_AGENT_URL` | いいえ | なし | オプションの AI アシスタント `agent` サービスのベース URL（例: `http://agent:9100`）。**未設定でアシスタントを完全に非表示にします**: ダッシュボードにアシスタントバブルが表示されなくなります。[enterprise-docs/assistant.md](/ja/agenteye/assistant) を参照してください。 | +| `AGENTEYE_API_KEY` | はい | なし | ダッシュボードがサーバーへの認証に使用する API キー。すべての権限が必要です（管理者キーを推奨）。 | +| `AE_LOG_LEVEL` | いいえ | `info` | サーバーサイドのログ詳細度: `debug`、`info`、`warn`、`error`。問題を診断する際にアップストリームのリクエスト/レスポンス行とセッション検証トレースを表示するには `debug` に設定してください。 | +| `AE_LOG_JSON` | いいえ | 自動 | `1` で JSON 行ごとの出力を強制、`0` で人間が読みやすい出力を強制。未設定の場合、`NODE_ENV=production` であれば自動的に JSON が有効になります。本番環境では `jq` やログアグリゲーターで解析しやすいよう JSON を推奨します。 | +| `AE_ANALYTICS_DISABLED` | いいえ | なし | `1`/`true` に設定するとダッシュボードの匿名製品利用テレメトリーを無効にします。下記の[テレメトリーとプライバシー](#telemetry--privacy)を参照してください。 | +| `REDIS_URL` | いいえ | なし | オプションの共有キャッシュバックエンド（例: `redis://redis:6379/0`）。設定すると、ダッシュボードはレプリカ間で `validateSession()` の結果をキャッシュし、レイテンシーアグリゲート / env リストプロキシルートの Next.js フェッチキャッシュを共有します。Redis が存在する場合、エッジサイドの OTP リクエストと検証のレート制限も Redis を使用します（Redis に到達できない場合はオープンフォールバック。セキュリティのバックストップはサーバーサイドの制限です）。下記の **Redis（オプションキャッシュ）** を参照してください。 | +| `AGENTEYE_AGENT_URL` | いいえ | なし | オプションの AI アシスタント `agent` サービスのベース URL（例: `http://agent:9100`）。**未設定のままにするとアシスタントを完全に非表示にします**: ダッシュボードにアシスタントのバブルは表示されません。[enterprise-docs/assistant.md](/ja/agenteye/assistant) を参照してください。 | | `AGENTEYE_AGENT_TOKEN` | いいえ | なし | ダッシュボードが `agent` サービスに提示する共有シークレット。エージェントに設定された `AGENTEYE_AGENT_TOKEN` と一致する必要があります。[enterprise-docs/assistant.md](/ja/agenteye/assistant) を参照してください。 | ### 実行 @@ -188,91 +186,91 @@ docker run -d --restart unless-stopped \ ghcr.io/agenteye-enterprise/dashboard:beta-latest ``` -### テレメトリとプライバシー +### テレメトリーとプライバシー -ダッシュボードは**匿名のプロダクト利用分析**を Exosphere の分析サービス（PostHog）に送信します。対象はどのダッシュボードページが閲覧されたか、API キーの作成やセッションの再評価などの一部の UI アクションです。この利用シグナルは機能の優先順位付けに活用されます。 +ダッシュボードは Exosphere の分析サービス（PostHog）に**匿名の製品利用分析**を送信します。どのダッシュボードページが表示されたか、API キーの作成やセッションの再評価などのいくつかの UI アクションが含まれます。この利用シグナルは優先すべき機能の判断に使用されます。 -- **エージェント、セッション、イベントデータはあなたのインフラの外に出ません。** レポートされるのはダッシュボード UI の利用のみです。ページ URL は送信前に識別子が取り除かれ、オペレーターは不透明な内部 ID でのみ識別されます（メールアドレスは使用されません）。 -- テレメトリは**デフォルトで有効**です。完全に無効にするには、ダッシュボードコンテナに `AE_ANALYTICS_DISABLED=1` を設定して再起動してください。 -- 分析はダッシュボード自身の `/ingest` パスに送信され、ダッシュボードがそれを PostHog（`https://us.i.posthog.com`）にリバースプロキシします。リクエストをファーストパーティに保つことで、ブラウザの広告ブロッカーにブロックされません。**ダッシュボードコンテナ**は PostHog へのアウトバウンドアクセスが必要です。ブロックされている場合、テレメトリは静かに何もせず、ダッシュボードへの影響はありません。 +- **エージェント、セッション、またはイベントデータがお客様のインフラ外に出ることは一切ありません。** 報告されるのはダッシュボードの UI 利用のみです。ページ URL は送信前に識別子が除去され、オペレーターは不透明な内部 ID でのみ識別され、メールアドレスは使用されません。 +- テレメトリーは**デフォルトで有効**です。完全に無効にするには、ダッシュボードコンテナに `AE_ANALYTICS_DISABLED=1` を設定して再起動してください。 +- 分析はダッシュボード自身の `/ingest` パスに送信され、ダッシュボードがそれを PostHog（`https://us.i.posthog.com`）にリバースプロキシします。リクエストをファーストパーティとして保つことで、ブラウザの広告ブロッカーによる遮断を防ぎます。**ダッシュボードコンテナ**は PostHog へのアウトバウンドアクセスが必要です。ブロックされている場合、テレメトリーは黙って何もせず、ダッシュボードへの影響はありません。 --- ## AI アシスタント（オプション） -ダッシュボード内 AI アシスタントを使用すると、チームがダッシュボードを離れることなく、平易な言葉でエージェントデータに対して質問できます（セッションの要約、`/queries` エディター用の SQL のドラフト作成、保存済みクエリのダッシュボードタイルへの変換など）。Claude Agents SDK 上で動作する別の内部 `agent` コンテナとして実行され、ダッシュボードのみがアクセスできます。**LLM エンドポイントを設定するまで無効のままです。** +ダッシュボード内蔵の AI アシスタントを使用すると、チームがダッシュボードを離れることなく、エージェントデータについて自然言語で質問できます（セッションの要約、`/queries` エディター向けの SQL ドラフト、保存済みクエリのダッシュボードタイルへの変換など）。これは Claude Agent SDK 上で動作する独立した内部 `agent` コンテナとして実行され、ダッシュボードからのみアクセスでき、**LLM エンドポイントを設定するまで無効状態のままです**。 -有効化するには、`agent` サービスに LLM 接続（**Portkey** の場合は `PORTKEY_API_KEY` + モデルカタログスラグ `AGENTEYE_AGENT_MODEL=@/`、Anthropic 直接の場合は `ANTHROPIC_API_KEY`、別のゲートウェイの場合は `ANTHROPIC_BASE_URL`、または Bedrock/Vertex）、**専用の**データキー、そしてダッシュボードと一致する共有 `AGENTEYE_AGENT_TOKEN` を設定します。ダッシュボードユーザーにはさらに `agent:use` 権限が必要です。 +有効にするには、`agent` サービスに LLM 接続（**Portkey** 経由で `PORTKEY_API_KEY` + モデルカタログスラッグ `AGENTEYE_AGENT_MODEL=@/`、直接 Anthropic 経由で `ANTHROPIC_API_KEY`、別のゲートウェイ経由で `ANTHROPIC_BASE_URL`、または Bedrock/Vertex）、**専用**データキー、ダッシュボードと一致する共有 `AGENTEYE_AGENT_TOKEN` を設定します。ダッシュボードユーザーには追加で `agent:use` 権限が必要です。 -アシスタントのデータキーは手動で発行する必要はありません。ランダムなシークレットを選択し、`agent` に `AGENTEYE_API_KEY` として設定し、`server` に `AGENT_API_KEY` として設定すると、サーバーが起動時に固定された権限セットでシードします。そのデータアクセスは読み取り専用（`events:read`、`evaluations:read`、`dashboards:read`、`queries:read`）であり、承認ゲート付きの作成スコープ（`dashboards:write`、`queries:write`、`queries:run`）も持っており、ユーザーに代わって保存済みクエリのドラフトと検証、ダッシュボードタイルの構築ができます。すべての SQL は org の読み取り専用 ClickHouse ロールを通じて実行されるため、これはアシスタントが作成できるものを広げるものであり、アクセスできるデータを広げるものではありません。スコープはコード内で固定されており、設定で変更できません。このキーは保護されており、API 経由での無効化や再生成はできず、値を変更して再起動することでのみローテーションできます。管理者/ダッシュボードキーをこの用途に再利用しないでください。 +アシスタントのデータキーは手動で作成する必要はありません。ランダムなシークレットを選択し、`agent` の `AGENTEYE_API_KEY` および `server` の `AGENT_API_KEY` として設定すると、サーバーが起動時に固定された権限セットでシードします。そのデータアクセスは読み取り専用（`events:read`、`evaluations:read`、`dashboards:read`、`queries:read`）で、承認ゲート付きの作成スコープ（`dashboards:write`、`queries:write`、`queries:run`）も保持しているため、保存済みクエリのドラフト・検証やダッシュボードタイルのビルドをユーザーの代わりに行えます。すべての SQL は org の読み取り専用 ClickHouse ロールを通じて実行されるため、これによりアシスタントが作成できる範囲は広がりますが、アクセスできるデータは広がりません。スコープはコードで固定されており、設定で拡大することはできません。このキーは保護されており、API 経由での無効化や再生成はできず、値を変更して再起動することでのみローテーションできます。管理者/ダッシュボードキーを再利用しないでください。 -完全なセットアップ、環境変数リファレンス、テレメトリオプション、セキュリティモデルは **[enterprise-docs/assistant.md](/ja/agenteye/assistant)** に記載されています。 +完全なセットアップ手順、環境変数リファレンス、テレメトリーオプション、セキュリティモデルは **[enterprise-docs/assistant.md](/ja/agenteye/assistant)** に記載されています。 --- -## ClickHouse（必須分析ストア） +## ClickHouse（必須の分析ストア） -ClickHouse は高イベント量でもダッシュボードを高速に保ち、`/queries` SQL エディターが単一ストアでイベント、評価、セッションをジョインできるようにします。すべての取り込みイベント、すべての終端評価結果、および派生したセッションごとの集計の必須正規ストアです。PostgreSQL はリレーショナル / 可変状態テーブル（api_keys、users、otp_codes、evaluation_jobs、dashboards、saved_queries）を保持し、分析サーフェスは ClickHouse に置かれているため、ダッシュボードのロールアップと独自の SQL クエリはデータベースをまたいだラウンドトリップなしにネイティブにスキャン・ジョインできます。サーバーは `CLICKHOUSE_URL` なしでは起動を拒否します。 +ClickHouse は高いイベントボリュームでもダッシュボードのレスポンシブさを維持し、`/queries` SQL エディターで単一のストア内でイベント、評価、セッションを結合できるようにします。これは取り込まれたすべてのイベント、すべての終端評価結果、および派生したセッションごとのアグリゲートの必須の正規ストアです。PostgreSQL はリレーショナル/ミュータブルステートテーブル（api_keys、users、otp_codes、evaluation_jobs、dashboards、saved_queries）を保持し、分析サーフェスは ClickHouse に格納されるため、ダッシュボードのロールアップと独自の SQL クエリがクロスデータベースのラウンドトリップなしにネイティブにスキャン・結合できます。サーバーは `CLICKHOUSE_URL` なしでは起動を拒否します。 ### スキーマ -サーバー起動時に 3 つの ClickHouse オブジェクトが作成されます。すべてべき等（`CREATE IF NOT EXISTS`）です: +サーバー起動時に 3 つの ClickHouse オブジェクトが冪等に作成されます（`CREATE IF NOT EXISTS`）: -- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`、`toYYYYMM(ts)` でパーティション分割、`(session_id, ts, dedup_key)` 順。重複挿入（コレクターのリトライ）はマージ時に 1 行に集約されます。サーバーはすべてのイベントに対して決定論的な SHA-256 `dedup_key` を計算するため、リトライは安全です。 -- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`、`toYYYYMM(finished_at)` でパーティション分割、`(session_id, finished_at, dedup_key)` 順。評価パイプラインによって終端評価結果ごとに 1 度書き込まれます。`events` と同じ dedup キーモデル。 -- **`agenteye.agent_sessions`**: `agenteye.events` 上の**ビュー**（物理テーブルではありません）。すべての列は派生値（`started_at = min(ts)`、`last_event_at = max(ts)`、`ended_at = max(if event_type='agent_end', ts, NULL)`、`event_count = count()` など）です。イベントごとのアップサートや個別のバックフィルは不要で、ビューは `events` の内容を自動的に反映します。 +- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`、`toYYYYMM(ts)` でパーティション分割、`(session_id, ts, dedup_key)` 順。重複挿入（コレクターのリトライ）はマージ時に単一行に集約されます。サーバーはすべてのイベントに対して決定論的な SHA-256 `dedup_key` を計算するため、リトライは安全です。 +- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`、`toYYYYMM(finished_at)` でパーティション分割、`(session_id, finished_at, dedup_key)` 順。評価パイプラインによって終端評価結果ごとに 1 回書き込まれます。`events` と同じ dedup キーモデルです。 +- **`agenteye.agent_sessions`**: `agenteye.events` 上の**ビュー**（物理テーブルではありません）。すべてのカラムは派生（`started_at = min(ts)`、`last_event_at = max(ts)`、`ended_at = max(event_type='agent_end' の場合 ts、それ以外 NULL)`、`event_count = count()` など）。イベントごとのアップサートや別途バックフィルはなく、ビューは `events` の内容を自動的に反映します。 `analytics.evaluations` / `analytics.sessions` を参照する保存済みクエリとの後方互換性のため、サーバーは `agenteye.*` テーブル上のビューを持つ `analytics` ClickHouse データベースも作成します。`analytics.events`、`analytics.evaluations`、`analytics.agent_sessions`、`analytics.sessions` はすべて正しく解決されます。 ### 設定 -同梱の docker-compose と `deploy/base/clickhouse/` には AgentEye のワークロード向けにチューニングされた ClickHouse サービスが含まれています: +バンドルの docker-compose と `deploy/base/clickhouse/` は AgentEye のワークロード向けにチューニングされた ClickHouse サービスを同梱しています: -- 同梱ベースオーバーレイでのメモリ: リクエスト 2 GiB / 制限 4 GiB（小規模 POC/ステージングノードに合わせたサイズ）。本番環境のお客様はオーバーレイでスケールアップしてください。推奨最低値はリクエスト 2c/4Gi、制限 6c/8Gi。`max_server_memory_usage_to_ram_ratio=0.9` -- マークキャッシュ 5 GiB + 非圧縮キャッシュ 8 GiB +- バンドルのベースオーバーレイでは 2 GiB リクエスト / 4 GiB 制限メモリ（小規模な POC/ステージングノード向けサイズ）。本番環境のお客様はオーバーレイを増強してください。推奨フロアは 2c / 4Gi リクエスト、6c / 8Gi 制限です。`max_server_memory_usage_to_ram_ratio=0.9` +- 5 GiB マークキャッシュ + 8 GiB 非圧縮キャッシュ - `background_pool_size=16`、`background_merges_mutations_concurrency_ratio=2` - MergeTree: `parts_to_throw_insert=3000`、`parts_to_delay_insert=1500`、`non_replicated_deduplication_window=1000` - `local_io_method=auto`（対応カーネルでは io_uring） -- `fsync_metadata=0`: at-least-once 取り込み + ReplacingMergeTree dedup のため許容 +- `fsync_metadata=0`: at-least-once インジェスト + ReplacingMergeTree dedup のため許容可能 - `query_log` は 30 日 TTL で有効。`query_thread_log` は削除済み（高 QPS でコストが高い） - ユーザーサイドクエリに `max_execution_time=30` -- StatefulSet テンプレートで 100 GiB PVC（お客様のオーバーレイでは本番環境向けに高速 SSD ストレージクラスにオーバーライドすることを推奨） +- StatefulSet テンプレートに 100 GiB PVC（本番環境では高速 SSD ストレージクラスへのオーバーライドを推奨） ### バックアップ -データセット全体は毎夜 1 つのリストア可能なアーカイブにキャプチャされるため、クラスターやストレージの損失から回復できます。ClickHouse は毎日の `agenteye-backup` CronJob によって自動的にバックアップされ、PostgreSQL と ClickHouse を 1 回のパスで一緒にダンプします。ClickHouse は HTTP API 経由で読み取られます。`agenteye.events` と `agenteye.evaluations` は ClickHouse ネイティブ形式でダンプされ（ビューと行ポリシーはサーバー起動時に再作成されるため、テーブルデータが完全な内容です）、Postgres ダンプとともに 1 つの圧縮アーカイブにまとめられてオブジェクトストレージにアップロードされます。 +完全なデータセットは毎夜単一のリストア可能なアーカイブに取り込まれるため、クラスターやストレージの損失からも復旧できます。ClickHouse は日次の `agenteye-backup` CronJob によって自動バックアップされ、PostgreSQL と ClickHouse の両方を 1 回のパスでダンプします。ClickHouse は HTTP API 経由で読み取られます。`agenteye.events` と `agenteye.evaluations` は ClickHouse ネイティブ形式でダンプされ（ビューとロウポリシーはサーバー起動時に再作成されるため、テーブルデータが完全な情報です）、Postgres ダンプとともに単一の圧縮アーカイブにまとめてオブジェクトストレージにアップロードされます。 -宛先バケットとクラウド認証情報はオーバーレイごとに設定します。アップロード設定とリストア手順については、[enterprise-docs/kubernetes-deployment.md](/ja/agenteye/kubernetes-deployment) の**バックアップ**セクションを参照してください。 +アップロード先のバケットとクラウドクレデンシャルはオーバーレイごとに設定します。アップロード設定とリストア手順については [enterprise-docs/kubernetes-deployment.md](/ja/agenteye/kubernetes-deployment) の**バックアップ**セクションを参照してください。 --- ## Redis（オプションキャッシュ） -Redis はサーバーとダッシュボードが使用する**オプション**の共有キャッシュ + レート制限バックエンドです。Redis をデプロイし、両サービスに `REDIS_URL` を設定すると: +Redis はサーバーとダッシュボードが使用する**オプションの**共有キャッシュ + レート制限バックエンドです。Redis がデプロイされ、両方のサービスに `REDIS_URL` が設定されている場合: -- **Server** は認証済み API キーのルックアップ、`/events/environments` + `/evaluations/environments` リスト、`/events/latency_aggregate` ロールアップ（ダッシュボードがポーリングする最も重いクエリ）、`/sessions` リストをキャッシュし、OTP リクエストのレート制限を Postgres `COUNT(*)` から Redis `INCR + EXPIRE` に切り替えます。 -- **Dashboard** は `validateSession()` の結果をキャッシュし、典型的なページロードが発行する 10〜20 の認証済み API 呼び出しがすべて 1 つのアップストリームセッションチェックを共有できるようにします。OTP リクエストと OTP 検証のレート制限もダッシュボードエッジで行います。 +- **サーバー** は認証済み API キーのルックアップ、`/events/environments` + `/evaluations/environments` リスト、`/events/latency_aggregate` ロールアップ（ダッシュボードがポーリングする最も重いクエリ）、`/sessions` リストをキャッシュし、OTP リクエストのレート制限を Postgres の `COUNT(*)` から Redis の `INCR + EXPIRE` に切り替えます。 +- **ダッシュボード** は `validateSession()` の結果をキャッシュして、典型的なページロードが発行する 10〜20 回の認証済み API 呼び出しが 1 回のアップストリームセッションチェックを共有できるようにします。また、ダッシュボードエッジで OTP リクエストと OTP 検証のレート制限も行います。 -**Redis に到達できない場合、両サービスは安全にデグレードします。** すべてのキャッシュ呼び出しは有界タイムアウト内に `Err` を返し、呼び出し元はソースオブトゥルース（サーバーでは Postgres、ダッシュボードではアップストリームの Rust サーバー）にフォールバックします。OTP レート制限はサーバー上の Postgres `COUNT(*)` パスにフォールバックします（セキュリティプロパティは維持されます）。ダッシュボードのエッジ OTP 制限はオープンフォールバックしますが、サーバーサイドの制限は引き続き機能します。Redis のダウンはレイテンシを低下させますが、正確性には影響しません。 +**Redis に到達できない場合、両方のサービスは graceful にデグレードします。** すべてのキャッシュ呼び出しは制限されたタイムアウト内で `Err` を返し、呼び出し元は信頼できる情報源（サーバーでは Postgres、ダッシュボードではアップストリームの Rust サーバー）にフォールバックします。OTP レート制限はサーバーの Postgres `COUNT(*)` パスにフォールバックします（セキュリティ特性は維持されます）。ダッシュボードのエッジ OTP 制限はオープンフォールバックになりますが、サーバーサイドの制限は引き続き有効です。Redis のダウンはレイテンシーを低下させますが、正確性には影響しません。 ### 設定 -docker-compose バンドルにはすでに Redis サービスが含まれており、`REDIS_URL=redis://redis:6379/0` がサーバーとダッシュボードに設定されています。外部 Redis を使用するには、`REDIS_URL` をエンドポイントに設定し、compose ファイルから `redis` サービスを削除してください。 +docker-compose バンドルにはすでに Redis サービスが含まれており、`REDIS_URL=redis://redis:6379/0` がサーバーとダッシュボードに配線されています。外部 Redis を使用するには、`REDIS_URL` をエンドポイントに設定し、compose ファイルから `redis` サービスを削除してください。 ### メモリと永続化 -同梱の Redis イメージは `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru` で実行されます。AOF 永続化によりキャッシュはコンテナ再起動後も存続します。`everysec` はキャッシュ書き込みの最後の 1 秒を失っても無害なため、適切な耐久性/パフォーマンスのバランスです。LRU エビクションによりメモリの増大を抑制します。 +バンドルの Redis イメージは `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru` で実行されます。AOF 永続化によりコンテナの再起動後もキャッシュが生き残ります。`everysec` は、最後の 1 秒のキャッシュ書き込みが失われても無害なため、適切な耐久性/パフォーマンスのバランスです。LRU 退避によりメモリの増加を抑えます。 -### Redis をデプロイしないケース +### Redis をデプロイすべきでない場合 -- 単一インスタンスの開発/QA 環境。サーバー上のインプロセスキャッシュだけでもレプリカごとのメリットの大部分が得られます。Redis はシングルインスタンス設定では不要なクロスレプリカ共有を追加するものです。 -- エアギャップ環境で、もう 1 つサービスを運用するコストがレイテンシの改善を上回る場合。 +- シングルインスタンスの開発/QA 環境。サーバー上のインプロセスキャッシュだけでレプリカごとの利点のほとんどが得られます。Redis はシングルインスタンス設定では不要なクロスレプリカ共有を追加するだけです。 +- 別のサービスを運用するコストがレイテンシー改善を上回るエアギャップインストール環境。 --- ## Docker Compose（推奨） -`docker-compose.yml` は `agenteye-enterprise/releases` リポジトリで入手できます。1 つのコマンドで Postgres、ClickHouse、Redis、サーバー、ダッシュボードを起動できます。 +`docker-compose.yml` は `agenteye-enterprise/releases` リポジトリで入手できます。1 つのコマンドで Postgres、サーバー、ダッシュボードを起動します。 ```bash GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ @@ -282,7 +280,7 @@ GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ cd agenteye ``` -**`.env` でデフォルトをオーバーライド:** +**`.env` でデフォルトを上書きする:** ``` # URL セーフなパスワードを使用してください（/、+、= 文字を含まない）。 @@ -294,7 +292,7 @@ ADMIN_KEY=your-admin-secret ADMIN_EMAIL=admin@yourcompany.com ALLOWED_EMAILS=*@yourcompany.com -# OTP メール用 SMTP（省略すると OTP コードが stdout に記録されます） +# OTP メール用 SMTP（省略すると OTP コードが stdout にログ出力されます） # SMTP_HOST=smtp.yourprovider.com # SMTP_PORT=587 # SMTP_USERNAME=your-smtp-user @@ -324,79 +322,79 @@ docker compose down -v ## 運用設定 -以前は環境変数で固定されていた少数の運用上の調整項目が、ダッシュボードの **`//settings`** ページから組織ごとに編集できるようになりました。各 org が独自に設定します。変更は数秒以内に有効になります（再起動や再デプロイは不要）。 +以前は環境変数で固定されていた少数の運用上の設定項目は、ダッシュボードの **`//settings`** ページから組織ごとに編集できるようになりました。各 org が独自の設定を行います。変更は再起動や再デプロイなしで数秒以内に反映されます。 | 設定 | ブートストラップ環境変数 | 制御内容 | |---|---|---| -| 許可されたサインイン | `ALLOWED_EMAILS` | OTP の受信とユーザー追加が許可されるメールアドレス（または `*@domain.com` ワイルドカード） | -| デフォルトユーザー権限 | `DEFAULT_USER_PERMISSIONS` | 管理者が **+ new user** を開いたときにあらかじめ選択される権限トークンのカンマ区切りリスト。各トークンは [API key permissions](/ja/agenteye/api-keys) に記載された文字列のいずれかである必要があります。デフォルトは `standard` プリセット: 読み取り専用アクセスに加え、日常的なオンコールアクション（再評価のトリガー、クエリの実行、インシデントの確認、アシスタントの使用）。 | -| セッション有効期間 | `SESSION_TTL_SECS` | ダッシュボードのログインが再認証なしに有効な期間。ダッシュボードは 5 秒ごとにアップストリームセッションを再確認するため、`//users` での権限更新は対象ユーザーの次のリクエストで有効になります（再ログイン不要）。 | +| 許可されたサインイン | `ALLOWED_EMAILS` | OTP の受信とユーザーとしての追加が許可されるメール（または `*@domain.com` ワイルドカード） | +| デフォルトユーザー権限 | `DEFAULT_USER_PERMISSIONS` | 管理者が **+ new user** を開いた際に事前選択される権限トークンのカンマ区切りリスト。各トークンは [API キー権限](/ja/agenteye/api-keys) に記載されている文字列のいずれかである必要があります。デフォルトは `standard` プリセット: 読み取り専用アクセスに加え、日常的なオンコールアクション（再評価のトリガー、クエリの実行、インシデントの確認、アシスタントの使用）。 | +| セッション有効期間 | `SESSION_TTL_SECS` | 再認証が必要になるまでのダッシュボードログインの有効期間。ダッシュボードは 5 秒ごとにアップストリームセッションを再チェックするため、`//users` での権限更新は影響を受けるユーザーの次のリクエスト時に反映され、再ログインは不要です。 | | ワンタイムコードの有効期間 | `OTP_TTL_SECS` | OTP / マジックリンクが使用可能な期間 | -| アラート通知チャンネル | `ALERTS_ENABLED_CHANNELS` | アラートディスパッチャーが使用を許可されるチャンネル種別のカンマ区切りリスト: `email`、`slack`、`webhook`。アラートごとの設定は引き続き `//alerts/` で行いますが、ディスパッチャーはすべてのアウトバウンド配信をこのセットでフィルタリングします。ここで無効にされたチャンネルは `skipped_disabled` 監査行で短絡されます。`dashboard` チャンネル（ローカル監査挿入）は常に許可されます。デフォルトは 3 つすべて有効。 | +| アラート通知チャンネル | `ALERTS_ENABLED_CHANNELS` | アラートディスパッチャーが使用を許可されるチャンネル種別のカンマ区切りリスト: `email`、`slack`、`webhook`。アラートごとの設定は引き続き `//alerts/` で作成しますが、ディスパッチャーはこのセットを通じてすべての送信配信をフィルタリングし、ここで無効化されたチャンネルは `skipped_disabled` 監査行でショートサーキットされます。`dashboard` チャンネル（ローカル監査挿入）は常に許可されます。デフォルトは 3 つすべてが有効です。 | ### ブートストラップの仕組み -設定は `org_settings` に組織ごとに保存されます。初回起動時、サーバーはデフォルト org の欠落している行に対応する環境変数（または環境変数が未設定の場合は適切なデフォルト値）からシードします。それ以降は**保存された値がソースオブトゥルースとなり、環境変数は無視されます**。後から環境変数を変更して再起動しても、ライブ org の値には影響せず、追加の org はデフォルトから始まって独自に設定します。 +設定は `org_settings` に組織ごとに保存されます。初回起動時、サーバーはデフォルト org の欠落している行を対応する環境変数（または環境変数が未設定の場合は適切なデフォルト）からシードします。その後、**保存された値が信頼できる情報源となり、環境変数は無視されます**。後の再起動で環境変数を変更しても、稼働中の org の値には影響せず、追加の org はデフォルト値から始まり独自に設定します。 つまり: -- 新規デプロイでは、上記の環境変数を設定すると、デフォルト org が初回起動時にそれらを読み込みます。 -- 後から値を変更するには、ダッシュボードにログインして `//settings` で編集してください。変更はすべてのサーバーレプリカに数秒以内に適用されます（再起動不要）。 -- ブートストラップが有効だったことを確認するため、起動ログ行にシードされた内容と既に存在していた内容が記録されます: +- 新規デプロイの場合は、上記のように環境変数を設定すると、デフォルト org が初回起動時にそれを読み取ります。 +- 後で値を変更するには、ダッシュボードにログインして `//settings` で編集してください。変更はすべてのサーバーレプリカに数秒以内に反映されます。再起動は不要です。 +- 起動ログ行にシードされた内容と既存のものが記録されるため、ブートストラップが有効になったことを確認できます: ```text INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true ``` -#### 組織をまたいだサインインのセマンティクス +#### 組織間のサインインセマンティクス -セッションと OTP はユーザーに対してグローバルであり、単一の org に紐付けられません。そのため、2 つのルールがサインイン時に org ごとの設定を調整します: +セッションと OTP はユーザーに対してグローバルであり、単一の org に限定されません。そのため、サインイン時に 2 つのルールが org ごとの設定を調整します: -- **セッション / OTP の有効期間**: ユーザーが所属する org の中で最も厳しい（最短の）有効期間が優先されます。 -- **許可されたサインイン**: ゲートはすべての org のアローリストと org メンバーシップを OR 結合します。任意の org のアローリストがそのメールアドレスを許可している場合、**またはその**ユーザーがすでにいずれかの org のメンバーである場合に、OTP をリクエストできます。 +- **セッション / OTP 有効期間**: ユーザーが所属するすべての org の中で最も厳しい（最短の）有効期間が採用されます。 +- **許可されたサインイン**: ゲートは org メンバーシップとともにすべての org のアローリストを OR で組み合わせます。いずれかの org のアローリストがメールを許可している**か**、すでにいずれかの org のメンバーである場合、ユーザーは OTP をリクエストできます。 ### 権限 `//settings` ページへのアクセスは 2 つの権限でゲートされています: -- `settings:read`: ページと現在の値の閲覧。 -- `settings:write`: 変更の保存。 +- `settings:read`: ページと現在の値を閲覧できます。 +- `settings:write`: 変更を保存できます。 -ブートストラップ管理者ユーザー（`ADMIN_EMAIL` からシード）は、他のすべての権限とともに両方を自動的に取得します。必要に応じて `//users` から他のユーザーに付与してください。 +ブートストラップ管理者ユーザー（`ADMIN_EMAIL` からシード）は、他のすべての権限とともに両方を自動的に取得します。他のユーザーへの付与は `//users` から必要に応じて行ってください。 --- ## 組織（マルチテナント） -1 つのデプロイメントで複数の独立した**組織**（テナント）を提供できます。データのすべての行はちょうど 1 つの org に属し、分離はデータベースエンジンで強制されます。シングルテナントインストールではここで何もする必要はありません。すべてのデータは組み込みの `default` org に存在します。（その org に分かりやすい名前と URL スラグを付けて、例えば `/default` の代わりに `/acme` に配置することもできます。初回起動前に `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` を設定するか、`agenteye-orgctl org rename` でいつでも名前を変更できます。） +1 つのデプロイメントで複数の分離された**組織**（テナント）を扱えます。すべてのデータ行はちょうど 1 つの org に属し、分離はデータベースエンジンで強制されます。シングルテナントインストールでは何も設定不要で、すべてのデータは組み込みの `default` org に格納されます。（その org に分かりやすい名前と URL スラッグを設定して、`/default` の代わりに `/acme` のようなパスで表示させるには、初回起動前に `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` を設定するか、いつでも `agenteye-orgctl org rename` でリネームできます。） -**テナントプロビジョニングはオペレーター専用です。** 組織とそのメンバーシップは、**`agenteye-orgctl`** CLI で作成・管理します。この CLI はサーバーイメージ内に同梱されており（`agenteye-server` と並んで）、**既存のサーバーポッド内で実行されます**。**別個のポッド/ジョブ、HTTP API、ダッシュボードボタンはありません。** サーバーの `DATABASE_URL`、`CLICKHOUSE_URL`、`ORG_CH_SECRET` を再利用します。 +**テナントのプロビジョニングはオペレーター専用です。** 組織とそのメンバーシップは **`agenteye-orgctl`** CLI で作成・管理します。これは**サーバーイメージ内**（`agenteye-server` と並んで）に同梱され、**既存のサーバーポッド内で実行されます**。**別のポッド/Job、HTTP API、ダッシュボードボタンはありません**。サーバーの `DATABASE_URL`、`CLICKHOUSE_URL`、`ORG_CH_SECRET` を再利用します。 ```bash -# Docker Compose - 実行中のサーバーサービスに exec: +# Docker Compose - 実行中のサーバーサービスに exec で入る: docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp" docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin -# Kubernetes - 実行中のサーバー Deployment に exec: +# Kubernetes - 実行中のサーバー Deployment に exec で入る: kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list ``` -利用可能なサブコマンド: `org create | list | rename | delete | purge` と `member add | list | update | remove`。組み込み権限セット `admin`、`standard`、`read-only` があります。追加されたメンバーは最初のダッシュボードログイン時に OTP を受け取ります。 +利用可能な動詞: `org create | list | rename | delete | purge` と `member add | list | update | remove`、組み込みの権限セット `admin`、`standard`、`read-only` があります。追加されたメンバーは最初のダッシュボードログイン時に OTP を受け取ります。 -**2 番目の org を作成する前に:** 強力で安定した `ORG_CH_SECRET` を設定してください（`org create` コマンドは組み込み開発用デフォルトでの実行を拒否します）。また Postgres が **15+** であることを確認してください。**変更なし:** org ごとの API キーは引き続き org メンバーがダッシュボード/API でミントします。org とメンバーのライフサイクルのみ CLI に移動しました。完全なコマンドリファレンスと実例: **[enterprise-docs/tenant-management.md](/ja/agenteye/tenant-management)**。 +**2 番目の org を作成する前に:** 強力で安定した `ORG_CH_SECRET` を設定してください（`org create` コマンドは組み込みの開発デフォルトでの実行を拒否します）。また Postgres が **15+** であることを確認してください。**変更なし:** org ごとの API キーは引き続きダッシュボード/API で org メンバーによって作成されます。org + メンバーのライフサイクル管理のみが CLI に移動しました。完全なコマンドリファレンスと実例: **[enterprise-docs/tenant-management.md](/ja/agenteye/tenant-management)**。 --- -## コンテキストウィンドウ充填率 +## コンテキストウィンドウの使用率 -各 `model_response` イベントには**コンテキスト充填率ピル**が表示されます。入力トークンと出力トークンの合計をそのモデルのコンテキストウィンドウに対するパーセンテージで表します。バンドは `healthy`（0〜24%）、`watch`（25〜49%）、`compacting`（50〜74%）、`reset context`（75〜100%）です。AgentEye は一般的なモデル ID を自動的に解決するため、初期設定は不要です。 +各 `model_response` イベントには**コンテキスト使用率のピル**が表示されます。入力トークンと出力トークンの合計がそのモデルのコンテキストウィンドウに対する割合として表示されます。バンドは `healthy`（0〜24%）、`watch`（25〜49%）、`compacting`（50〜74%）、`reset context`（75〜100%）です。AgentEye は一般的なモデル ID を自動的に解決するため、初期設定は不要です。 -組織が送信した各モデルは **Settings → model context windows** に表示されます。`settings:write` 権限を持つユーザーはそのウィンドウをオーバーライドしたり、プライベート/プロキシモデルを追加したりできます（0〜1,000,000 トークン）。`0` は「不明」を意味し、ピルを非表示にします。変更は新たに取り込まれたイベントに適用されます。`settings:read` 権限を持つユーザーはリストを閲覧できます。 +組織が送信したすべてのモデルは **Settings → model context windows** に表示されます。`settings:write` 権限を持つユーザーはウィンドウをオーバーライドするか、プライベート/プロキシモデルを追加できます（0〜1,000,000 トークン）。`0` は「不明」を意味し、ピルを非表示にします。変更は新たに取り込まれたイベントに適用されます。`settings:read` 権限を持つユーザーはリストを閲覧できます。 -アップグレード後の新しいイベントには、その時点から充填率が入ります。既存のデプロイメントで**過去の**イベント（およびモデルごとのリスト）にも入力するには、ワンオフのバックフィルを実行します。これはサーバーイメージ内に同梱されており（`agenteye-orgctl` と同様）、既存のサーバーポッド内で実行されます: +アップグレード後の新しいイベントにはその時点から使用率が付与されます。既存のデプロイメントの**過去の**イベント（およびモデルごとのリスト）にも適用するには、一回限りのバックフィルを実行してください。これはサーバーイメージ内（`agenteye-orgctl` と同様）に同梱されており、既存のサーバーポッドで実行されます: ```bash -# プレビュー（org ごとのミューテーションを表示、変更なし）: +# プレビュー（org ごとのミューテーションを表示し、何も変更しない）: kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window --dry-run # 適用: kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window @@ -404,12 +402,12 @@ kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window docker compose exec server agenteye-backfill-context-window ``` -べき等（再実行しても安全）であり、ポッドの `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` を再利用します。モデルウィンドウを編集した後、既存のイベントを再計算したい場合は再実行してください。 +冪等（再実行しても安全）であり、ポッドの `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` を再利用します。モデルウィンドウを編集した後に既存のイベントを再計算したい場合は再実行してください。 --- ## 本番環境での考慮事項 -- **Postgres**: マネージド Postgres サービスまたは定期バックアップ付きの専用インスタンスを使用してください。`DATABASE_URL` は `sslmode=require` などの標準 libpq パラメーターをすべてサポートしています。 +- **Postgres**: マネージド Postgres サービスまたは定期的なバックアップを持つ専用インスタンスを使用してください。`DATABASE_URL` は暗号化接続のための `sslmode=require` を含むすべての標準 libpq パラメーターをサポートします。 - **TLS**: TLS を終端するリバースプロキシ（nginx、Caddy、Traefik）の背後にサーバーとダッシュボードを配置してください。 -- **ファイアウォール**: サーバーポート（デフォルト 8080）はコレクターマシンとダッシュボードホストからのみアクセス可能にし、パブリックインターネットからは到達できないようにして \ No newline at end of file +- **ファ \ No newline at end of file diff --git a/docs/ja/agenteye/getting-started.mdx b/docs/ja/agenteye/getting-started.mdx index 8297788b..75d6ad43 100644 --- a/docs/ja/agenteye/getting-started.mdx +++ b/docs/ja/agenteye/getting-started.mdx @@ -1,50 +1,50 @@ --- -title: "AgentEye のスタートガイド" -description: "AgentEye のスタートガイドドキュメント" +title: "AgentEyeを始める" +description: "AgentEye の入門ドキュメントです。" --- -このガイドでは、AgentEye のセットアップを一通り説明します。サーバーとダッシュボードのデプロイ、エージェントマシンへのコレクターのインストール、Python エージェントコードへのインストルメンテーションの追加まで順を追って解説します。 +このガイドでは、AgentEye のセットアップを一通り説明します。サーバーとダッシュボードのデプロイ、エージェントマシンへのコレクターのインストール、そして Python エージェントコードへの計装を順を追って解説します。 --- ## AgentEye とは？ -AgentEye は **AI エージェント向けのセルフホスト型オブザーバビリティ・評価プラットフォーム**です。エージェントの動作、つまり実行の各ステップを記録し、完了した各実行の品質を自動的にスコアリングします。これにより、本番環境でのエージェントの挙動を把握し、ユーザーより先に品質低下を検知できます。 +AgentEye は **AI エージェント向けのセルフホスト型観測・評価プラットフォーム**です。エージェントの動作（実行の各ステップ）を記録し、完了した実行の品質を自動でスコアリングします。これにより、本番環境でのエージェントの挙動を把握し、ユーザーが問題に気づく前にリグレッションを検出できます。 -データは一方向に流れます。エージェントコードが **Python SDK** を通じて**イベント**を送出 → 軽量な**コレクター**デーモンがそれをまとめて**サーバー**に送信 → イベントと分析データが **ClickHouse** に保存（組織、ユーザー、API キー、ダッシュボード、保存クエリなどの運用状態は **Postgres** に保存）→ **ダッシュボード**ですべてを確認。 +データは一方向に流れます。エージェントコードが **Python SDK** を通じて **イベント** を送出 → 軽量な **コレクター** デーモンがイベントをバッチ処理して **サーバー** に送信 → イベントと分析データが **ClickHouse** に保存（組織、ユーザー、API キー、ダッシュボード、保存クエリなどの運用状態は **Postgres** に格納）→ すべてを **ダッシュボード** で閲覧。 主な機能： -- **Events（イベント）** — エージェント実行のステップごとの生の記録（ツール呼び出し、モデル呼び出し、フック、エラー）。 -- **Sessions（セッション）** — イベントを実行単位で集約した行。各実行は**自動評価**されスコアが付きます。 -- **Evaluations（評価）** — 独自のエバリュエーターサービスが生成する品質スコア。手動レビューなしで品質低下を検知できます。 -- **Queries & Dashboards（クエリ＆ダッシュボード）** — データに対する保存済み ClickHouse SQL と、組織共有のダッシュボードへのグラフ表示。 -- **Alerts & Incidents（アラート＆インシデント）** — 閾値ルールによるページング通知（メール、Slack、Webhook、ダッシュボード内）と、トリアージのためのインシデントワークフロー。 -- **CLI & AI アシスタント** — ターミナルクライアント（`agenteye`）と、自然言語で質問できるダッシュボード内アシスタント。 +- **イベント** — 各エージェント実行のステップごとの生データ（ツール呼び出し、モデル呼び出し、フック、エラー）。 +- **セッション** — それらのイベントを実行ごとの1行にまとめたもの。各実行は**自動評価**されてスコアが付与されます。 +- **評価** — 独自の評価サービスが生成する品質スコア。手動レビューなしに品質低下を検出できます。 +- **クエリ＆ダッシュボード** — データに対して保存した ClickHouse SQL を、共有・組織スコープのダッシュボードにグラフ表示。 +- **アラート＆インシデント** — 閾値ルールによる通知（メール、Slack、Webhook、ダッシュボード内）と、トリアージのためのインシデントワークフロー。 +- **CLI＆AI アシスタント** — ターミナルクライアント（`agenteye`）と、自然言語で質問できるダッシュボード内アシスタント。 -すべて自社インフラで運用できます。単一の Docker Compose スタック（本ガイド）、本番向け Kubernetes インストール、または単一のコロケーションポッドとして構成可能です。以降のガイドでは Compose スタックをエンドツーエンドでセットアップします。 +これらすべてを自社インフラで運用できます。単一の Docker Compose スタック（本ガイド）、本番向け Kubernetes インストール、または単一の同居ポッドとして構成できます。このガイドでは Compose スタックをエンドツーエンドでセットアップします。 --- -## Step 1: 認証 +## ステップ 1: 認証 -AgentEye のすべてのアーティファクトは `agenteye-enterprise` GitHub 組織から配布されています。エンタープライズ開発者は独自の GitHub PAT を生成できます。具体的な手順と必要な権限については [enterprise-docs/github-token.md](/ja/agenteye/github-token) をご確認ください。 +AgentEye のすべての成果物は `agenteye-enterprise` GitHub 組織から配布されています。エンタープライズ開発者は自分の GitHub PAT を生成できます。正確な手順と必要な権限については [enterprise-docs/github-token.md](/ja/agenteye/github-token) を参照してください。 ```bash export AGENTEYE_TOKEN= -# Docker を GHCR に対して認証する +# Authenticate Docker against GHCR echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin ``` --- -## Step 2: サーバーとダッシュボードのデプロイ +## ステップ 2: サーバーとダッシュボードをデプロイする -サーバーはコレクターからイベントを受け取りクエリ可能にします。ダッシュボードはそれらを確認する場所です。取り込まれたイベントと分析データは ClickHouse（必須の分析ストア）に保存され、Postgres には組織、ユーザー、API キー、ダッシュボード、保存クエリなどの運用状態が保存されます。 +サーバーはコレクターからイベントを受信してクエリ可能な状態にし、ダッシュボードはそれを閲覧する場所です。取り込まれたイベントと分析データは ClickHouse（必須の分析ストア）に保存され、Postgres には組織、ユーザー、API キー、ダッシュボード、保存クエリなどの運用状態が格納されます。 -**公開された Compose ファイルをダウンロードします：** +**公開されている Compose ファイルをダウンロード：** ```bash mkdir -p ./agenteye @@ -55,38 +55,32 @@ curl -fsSL \ cd agenteye ``` -**シークレットを設定します：** +**シークレットを設定：** -デフォルトの `admin` 認証情報でデプロイが実行されないよう、`.env` ファイルを作成します。最低限 `ADMIN_KEY` と `POSTGRES_PASSWORD` を設定してください： +デプロイがデフォルトの `admin` 認証情報で動かないよう、`.env` ファイルを作成します。最低限 `ADMIN_KEY` と `POSTGRES_PASSWORD` を設定してください： ```bash POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -後続のステップ（例：Step 3 の `curl`）から直接参照できるよう、現在のシェルにも `ADMIN_KEY` をエクスポートします： - -```bash -export ADMIN_KEY=your-admin-secret -``` - -**スタックを起動します：** +**スタックを起動：** ```bash docker compose up -d ``` -これにより、必須の ClickHouse 分析ストアとオプションの Redis キャッシュを含む完全なスタックが、サーバーおよびダッシュボードとともに起動します。サーバーの起動には ClickHouse が正常に動作している必要があります。 +これにより、必須の ClickHouse 分析ストアとオプションの Redis キャッシュを含む、サーバーとダッシュボードを含むフルスタックが起動します。サーバーが起動するには ClickHouse が正常稼働している必要があります。 -サーバーは `http://localhost:8080` で、ダッシュボードは `http://localhost:3000` でリクエストを待ち受けます。 +サーバーは `http://localhost:8080`、ダッシュボードは `http://localhost:3000` でリッスンしています。 -本番デプロイ（カスタム Postgres、TLS、リバースプロキシ）については [enterprise-docs/deployment.md](/ja/agenteye/deployment) をご参照ください。 +本番デプロイ（カスタム Postgres、TLS、リバースプロキシ）については [enterprise-docs/deployment.md](/ja/agenteye/deployment) を参照してください。 --- -## Step 3: コレクター用 API キーの作成 +## ステップ 3: コレクター用 API キーを作成する -各コレクターはスコープ付き API キーで認証します。Step 2 で設定した `ADMIN_KEY` を使用して作成します： +各コレクターはスコープ付き API キーで認証します。ステップ 2 で設定した `ADMIN_KEY` を使って API キーを作成します： ```bash curl -s -X POST http://localhost:8080/keys \ @@ -95,15 +89,15 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -`key` の値は自分で指定します。Step 4 のコレクター設定で使用します。キー管理の詳細については [enterprise-docs/api-keys.md](/ja/agenteye/api-keys) をご参照ください。 +`key` の値は自分で指定します。ステップ 4 のコレクター設定でこの値を使用してください。キー管理の詳細は [enterprise-docs/api-keys.md](/ja/agenteye/api-keys) を参照してください。 --- -## Step 4: コレクターのインストール +## ステップ 4: コレクターをインストールする AI エージェントを実行するすべてのマシンにコレクターデーモンをインストールします。 -**バイナリをダウンロードします（Linux x86_64）：** +**バイナリをダウンロード（Linux x86_64）：** ```bash VERSION=0.0.1-beta.13 @@ -114,9 +108,9 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> これは **Linux x86_64** ビルドをダウンロードします。macOS（Apple Silicon または Intel）、Linux arm64、Docker / systemd / launchd のセットアップについては [collector-installation.md](/ja/agenteye/collector-installation) を参照してください。各プラットフォーム向けのダウンロードが記載されています。上記コマンドでインストールされる Linux バイナリは他の環境では動作しません。 +> これは **Linux x86_64** ビルドをダウンロードします。macOS（Apple Silicon または Intel）、Linux arm64、または Docker / systemd / launchd のセットアップについては [collector-installation.md](/ja/agenteye/collector-installation) を参照してください。各プラットフォームのダウンロード先が記載されています。上記コマンドは Linux バイナリをインストールするため、他の環境では動作しません。 -**設定します：** +**設定：** ```bash mkdir -p ~/.agenteye @@ -128,25 +122,25 @@ cat > ~/.agenteye/config.json </…`）がプレフィックスとして付きます。 +イベントが流れ始めると、**analyze** ページで未加工のアクティビティを実用的な知見に変換できます。エージェントの挙動を計測し、チームで知見を共有し、問題が発生した瞬間に通知を受け取ることができます。ダッシュボードページは組織スコープで、アドレスバーに表示される URL は組織スラグ（`//…`）でプレフィックスされます。 -- **Queries**（`//queries`）：イベントと評価に対する保存済み再利用可能クエリのライブラリから開始します（組み込みプリセットと独自クエリ）… +- **Queries**（`//queries`）：イベントと評価データに対する保存済み再利用可能なクエリのライブラリ（組み込みプリセットと独自クエリ）から始めます…… -![保存済みクエリライブラリ：組み込みプリセットとカスタムクエリを並べたグリッド表示](/agenteye/images/queries.png) +![保存クエリライブラリ：組み込みプリセットとカスタムクエリが並んだグリッド](/agenteye/images/queries.png) - …そして SQL コンポーザーで開いて調整し、ライブ結果を確認できます： + ……次に SQL コンポーザーで開いて調整し、ライブ結果とともに実行できます： -![保存済みクエリを実行する SQL クエリコンポーザー。スキーマサイドバーとライブ結果グリッド付き](/agenteye/images/query-lab.png) +![保存クエリを実行している SQL クエリコンポーザー、スキーマサイドバーとライブ結果グリッド付き](/agenteye/images/query-lab.png) -- **Dashboards**（`//dashboards`）：クエリを折れ線・棒・面・円グラフのタイルとして組織共有ダッシュボードにピン留めできます。 +- **Dashboards**（`//dashboards`）：クエリを折れ線、棒、エリア、円グラフのタイルとして固定し、共有・組織全体のダッシュボードを作成。 -![保存済みクエリで構築したダッシュボード：時間別イベント数の折れ線グラフ、タイプ別エラーの棒グラフ、レイテンシの面グラフ、モデル別トークン数](/agenteye/images/dashboard-fleet.png) +![保存クエリから構築されたダッシュボード：時間別イベント数の折れ線、エラータイプ別の棒グラフ、レイテンシのエリアチャート、モデル別トークン数](/agenteye/images/dashboard-fleet.png) -- **Alerts**（`//alerts`）：任意の閾値をページングルールに昇格し、メール・Slack・Webhook・ダッシュボード内で通知を受け取れます。[enterprise-docs/alerts.md](/ja/agenteye/alerts) をご参照ください。 +- **Alerts**（`//alerts`）：任意の閾値をページングルールに昇格させ、メール、Slack、Webhook、またはダッシュボード内で通知を受け取ります。[enterprise-docs/alerts.md](/ja/agenteye/alerts) を参照してください。 --- ## 次のステップ -- [Deployment（デプロイ）](/ja/agenteye/deployment)：本番環境向けの堅牢化 -- [API Keys（API キー）](/ja/agenteye/api-keys)：アクセス管理 -- [Troubleshooting（トラブルシューティング）](/ja/agenteye/troubleshooting)：問題の診断 \ No newline at end of file +- [デプロイメント](/ja/agenteye/deployment)：本番環境向けの強化 +- [API キー](/ja/agenteye/api-keys)：アクセス管理 +- [トラブルシューティング](/ja/agenteye/troubleshooting)：問題の診断 \ No newline at end of file diff --git a/docs/ja/agenteye/managed-deployment.mdx b/docs/ja/agenteye/managed-deployment.mdx index 69750752..78c8f0f2 100644 --- a/docs/ja/agenteye/managed-deployment.mdx +++ b/docs/ja/agenteye/managed-deployment.mdx @@ -1,171 +1,171 @@ --- title: "Kubernetesクラスターへのマネージドデプロイ" -description: "KubernetesクラスターへのAgentEyeマネージドデプロイのドキュメント" +description: "KubernetesクラスターへのAgentEyeマネージドデプロイに関するドキュメントです。" --- -AgentEyeは、AIおよびLLMエージェント向けのセルフホスト型オブザーバビリティ・評価プラットフォームです。エージェントセッション、ツール呼び出し、モデルリクエスト、エラーをキャプチャし、検索可能なアナリティクスと評価に変換して、オプションの読み取り専用AIアシスタントを備えたダッシュボードに結果を表示します。 +AgentEyeは、AIおよびLLMエージェント向けのセルフホスト型オブザーバビリティ・評価プラットフォームです。エージェントセッション、ツール呼び出し、モデルへのリクエスト、エラーをキャプチャし、検索可能な分析・評価データに変換して、オプションの読み取り専用AIアシスタントを備えたダッシュボードに結果を表示します。 -マネージドデプロイメントモデルでは、お客様が専用のKubernetesクラスターを用意し、Exosphereがそのクラスター内でプラットフォーム全体を運用します。すべてのコンポーネントのデプロイ、設定、運用、バックアップ、アップグレードをExosphereが代行します。お客様のチームは、データベース、証明書、アップグレードの管理を行うことなく、エージェントの可視化・アナリティクス・評価・オプションのアシスタントといったプラットフォームの価値を享受できます。すべてのデータはお客様のクラウドアカウント内に保持されます。 +マネージドデプロイモデルでは、お客様が専用のKubernetesクラスターを用意し、Exosphereがそのクラスター内でプラットフォーム全体を運用します。すべてのコンポーネントのデプロイ、設定、運用、バックアップ、アップグレードをExosphereが代行します。お客様のチームは、データベース、証明書、アップグレードの管理なしに、エージェントの可視化、分析、評価、オプションのアシスタントといったプラットフォームの価値をそのまま享受できます。すべてのデータはお客様のクラウドアカウント内に保持されます。 --- ## 前提条件 -- コンテナイメージのプルおよびアーティファクトのダウンロードに使用する **GitHub PAT**（[GitHub トークンのセットアップ](/ja/agenteye/github-token) を参照） -- **専用のKubernetesクラスター**（以下の要件を参照） -- データベースバックアップ用の **ストレージバケット** -- **ネットワーク接続**: クラスターのロードバランサーへのポート 443 インバウンド +- コンテナイメージのプルおよびアーティファクトのダウンロードに使用する**GitHub PAT**（詳細は[enterprise-docs/github-token.md](/ja/agenteye/github-token)を参照） +- **専用Kubernetesクラスター**（下記の要件を参照） +- データベースバックアップ用の**ストレージバケット** +- **ネットワーク接続**: クラスターのロードバランサーへのポート443のインバウンドアクセス --- -## ステップ 1: 専用Kubernetesクラスターのプロビジョニング +## ステップ1: 専用Kubernetesクラスターのプロビジョニング -AgentEye専用のKubernetesクラスターを作成してください。他のワークロードと共有しないことで、プラットフォーム全体（アプリケーションサービス、データベース、アナリティクス、キャッシュ）が既存のインフラに影響を与えることなく独立した環境で動作します。 +AgentEye専用のKubernetesクラスターを作成します。他のワークロードと共有しないようにすることで、プラットフォーム全体（アプリケーションサービス、データベース、分析、キャッシュ）が分離された環境で動作し、既存のインフラに影響を与えません。 | 要件 | 詳細 | |---|---| -| **ディストリビューション** | 準拠したKubernetes: EKS、GKE、AKS、またはセルフマネージド | -| **バージョン** | 1.27 以降 | -| **ノードプール** | 最小構成: **3ノード、各4 vCPU / 8 GB RAM**（標準的な汎用インスタンス） | -| **ストレージ** | ブロックボリュームをプロビジョニングするデフォルトの StorageClass（例: AWSの `gp3`、GCPの `pd-ssd`） | -| **ロードバランサー** | クラウドのLoadBalancerサービスをプロビジョニングできること（EKS、GKE、AKSでは標準対応） | +| **ディストリビューション** | 準拠した任意のKubernetes: EKS、GKE、AKS、またはセルフマネージド | +| **バージョン** | 1.27以降 | +| **ノードプール** | 最小構成: **3ノード、各4 vCPU / 8 GB RAM**（標準汎用インスタンス） | +| **ストレージ** | ブロックボリュームをプロビジョニングするデフォルトのStorageClass（例: AWSの`gp3`、GCPの`pd-ssd`） | +| **ロードバランサー** | クラウドのLoadBalancerサービスをプロビジョニングできること（EKS、GKE、AKSではデフォルトで対応） | -> Exosphereはクラスター内のその他すべてをインストール・管理します: イングレスコントローラー、TLS証明書、データベース、キャッシュ、モニタリング、およびすべてのアプリケーションデプロイメント。 +> Exosphereは、クラスター内のその他すべてのコンポーネント（イングレスコントローラー、TLS証明書、データベース、キャッシュ、モニタリング、すべてのアプリケーションデプロイ）をインストールおよび管理します。 --- -## ステップ 2: AgentEyeチームへのアクセス付与 +## ステップ2: AgentEyeチームへのアクセス権の付与 -Exosphereは、名前空間、カスタムリソース定義、イングレスコントローラー、ストレージプロビジョナーを管理するために、cluster-adminアクセス（または同等の広範なRBAC）が必要です。 +Exosphereは、名前空間、カスタムリソース定義、イングレスコントローラー、ストレージプロビジョナーを管理するために、cluster-admin権限（またはそれに相当する広範なRBAC）が必要です。 | 要件 | 詳細 | |---|---| | **アクセス方法** | IAMロール（EKS/GKEでは推奨）、kubeconfig、またはSSOベースのアクセス | -| **VPN / 踏み台サーバー** | Kubernetes APIサーバーがプライベートな場合は、Exosphere運用チーム向けにVPN認証情報または踏み台サーバーへのアクセスを提供してください | +| **VPN / 踏み台サーバー** | Kubernetes APIサーバーがプライベートの場合、Exosphere運用チーム向けにVPN認証情報または踏み台サーバーへのアクセスを提供してください | --- -## ステップ 3: ネットワーク接続の設定 +## ステップ3: ネットワーク接続の設定 -ネットワークチームは、クラスターのロードバランサーへの**ポート 443** インバウンドトラフィックを許可する必要があります。デプロイメントでは2つの独立したロードバランサーが稼働します。1つはイベントの取り込み用（mTLS保護）、もう1つはダッシュボード用です。 +ネットワークチームは、クラスターのロードバランサーへの**ポート443**のインバウンドトラフィックを許可する必要があります。デプロイでは2つの独立したロードバランサーを使用します。1つはイベント取り込み用（mTLS保護）、もう1つはダッシュボード用です。 | トラフィック | 送信元 | 宛先 | セキュリティ | |---|---|---|---| -| **イベント取り込み** | お客様のクラスター内のコレクターポッド | イングレストLoadBalancer、ポート 443 | mTLS（クライアント証明書）+ APIキー | -| **ダッシュボード** | 開発者のブラウザ | ダッシュボードLoadBalancer、ポート 443 | お客様のドメインでのHTTPS、パスワードレスメールOTPサインイン | +| **イベント取り込み** | お客様のクラスター内のCollectorポッド | Ingest LoadBalancer、ポート443 | mTLS（クライアント証明書）+ APIキー | +| **ダッシュボード** | 開発者のブラウザ | Dashboard LoadBalancer、ポート443 | お客様のドメインでのHTTPS、パスワードレスのメールOTPサインイン | -取り込みエンドポイントは相互TLSで保護されており、コレクターはすべてのリクエストで有効なクライアント証明書**と**有効なAPIキーの両方を提示する必要があります。ダッシュボードは独自のロードバランサーとホスト名で動作し、サインインはお客様が許可リストに登録したメールアドレス/ドメインに制限されます。 +取り込みエンドポイントは相互TLSで保護されており、Collectorはすべてのリクエストで有効なクライアント証明書**および**有効なAPIキーを提示する必要があります。ダッシュボードは専用のロードバランサーとホスト名で動作し、サインインはお客様が許可リストに登録したメールアドレス/ドメインに限定されます。 -**DNSレコード（一度のみ）:** お客様が管理するドメインの下に2つのCNAMEレコードを作成します。1つは取り込みエンドポイント用、もう1つはダッシュボード用（例: `agenteye.your-company.example`）で、Exosphereが提供するロードバランサーのホスト名を指します。Exosphereは両方のホスト名に対してパブリック信頼のTLS証明書を自動的にプロビジョニングし、更新も含めて管理します。 +**DNSレコード（初回のみ）:** お客様が管理するドメイン配下に2つのCNAMEレコードを作成します。1つは取り込みエンドポイント用、もう1つはダッシュボード用（例: `agenteye.your-company.example`）で、Exosphereが提供するロードバランサーのホスト名を指します。その後、Exosphereは両ホスト名に対してパブリックで信頼されたTLS証明書を自動的にプロビジョニングし、更新も自動で行います。 -> **ポート 80 について:** 証明書の自動発行と更新は、各ロードバランサーのポート 80 へのHTTPで検証されます。ダッシュボードのロードバランサーを社内IPレンジに制限するセキュリティポリシーがある場合は、事前にExosphereにお知らせください。証明書の検証方式をDNSベースの方法（お客様側で追加のDNSレコードが1件必要）に切り替えることで、制限が適用されていても証明書の更新が継続して機能します。 +> **ポート80について:** 証明書の自動発行・更新は、各ロードバランサーのポート80へのHTTPアクセスを通じて検証されます。ダッシュボードのロードバランサーを社内IPレンジに制限するセキュリティポリシーがある場合は、事前にExosphereにご連絡ください。証明書の検証をDNSベースの方式（お客様側で1件のDNSレコードを追加）に切り替えることで、制限を設けた後も更新が継続して機能するようにします。 -> **アウトバウンド:** クラスターノードは `ghcr.io` からコンテナイメージをプルするためにインターネットアクセスが必要です。アウトバウンドトラフィックが制限されている場合は、`ghcr.io` を許可リストに追加するか、内部レジストリにイメージをミラーリングしてください。 +> **アウトバウンド:** クラスターのノードは`ghcr.io`からコンテナイメージをプルするためにインターネットアクセスが必要です。アウトバウンドトラフィックを制限しているネットワーク環境の場合は、`ghcr.io`を許可リストに追加するか、イメージを内部レジストリにミラーリングしてください。 --- -## ステップ 4: バックアップ用ストレージバケットの提供 +## ステップ4: バックアップ用ストレージバケットの準備 -データベースのバックアップは、お客様が所有するクラウドストレージバケットに保存されます。 +データベースバックアップは、お客様が所有するクラウドストレージバケットに保存されます。 | 要件 | 詳細 | |---|---| | **サービス** | S3（AWS）、GCS（GCP）、またはAzure Blob Storage | -| **アクセス** | IAMロール for サービスアカウント（EKSのIRSA、GKEのWorkload Identity）経由でクラスターノードへの書き込みアクセスを付与するか、認証情報を提供してください | -| **保持期間** | バケットのライフサイクルポリシー（保持期間、アーカイブルール）はお客様が管理します。Exosphereがバックアップを書き込み、保持期間はお客様が決定します | +| **アクセス** | サービスアカウント向けIAMロール（EKSではIRSA、GKEではWorkload Identity）を通じてクラスターのノードに書き込みアクセス権を付与するか、認証情報を提供してください | +| **保持期間** | バケットのライフサイクルポリシー（保持期間、アーカイブルール）はお客様が管理します。Exosphereはバックアップを書き込み、保持期間はお客様が決定します | -1日1回のバックアップで、PostgreSQL（リレーショナルデータ）とClickHouse（イベントと評価）の両方を1つの圧縮アーカイブにダンプし、お客様のバケットにアップロードします。バックアップはアップグレード前にも実行されます。 +1日1回のバックアップで、PostgreSQL（リレーショナル状態）とClickHouse（イベントおよび評価）の両方を1つの圧縮アーカイブにダンプし、お客様のバケットにアップロードします。アップグレード前にもバックアップが実行されます。 --- -## ステップ 5: 担当者の指定 +## ステップ5: 担当者の指定 -クラスターレベルの問題（ノードの健全性、クラウドアカウントの制限、ネットワークの変更）に対応する、お客様側の担当者またはSlack/Teamsチャンネルを1つ指定してください。日常的な運用ではこの担当者への連絡は発生しません。 +クラスターレベルの問題（ノードの健全性、クラウドアカウントの制限、ネットワーク変更）に対応するための担当者またはSlack/Teamsチャンネルを1つ指定してください。日常的な運用ではこの担当者への連絡は発生しません。 --- ## デプロイされるコンポーネント -Exosphereがクラスターへのアクセスを取得すると、以下のコンポーネントがデプロイされ、管理されます。 +Exosphereがクラスターへのアクセス権を取得した後、以下のコンポーネントがデプロイされ、管理されます。 | コンポーネント | 役割 | |---|---| -| **AgentEyeサーバー** | コレクターからイベントを受信し、アナリティクスを実行し、ダッシュボードにデータを提供するHTTP API | -| **ダッシュボード** | エージェントセッション、ツール呼び出し、モデルリクエスト、エラーを表示するWebインターフェース。オプションの読み取り専用AIアシスタントをホスト | -| **ClickHouse** | 取り込まれたイベント、アナリティクス、評価のための必須の正規ストア | +| **AgentEye Server** | CollectorからイベントをHTTPで受信し、分析を実行して、ダッシュボードにデータを提供するAPI | +| **Dashboard** | エージェントセッション、ツール呼び出し、モデルへのリクエスト、エラーを表示するWebインターフェース。オプションの読み取り専用AIアシスタントもホストします | +| **ClickHouse** | 取り込まれたイベント、分析、評価の正規ストアとして必須 | | **PostgreSQL** | 組織、APIキー、ユーザー、ダッシュボード、保存済みクエリのリレーショナルストア | -| **Redis** | オプションの共有キャッシュおよびレート制限バックエンド。利用不可能な場合もプラットフォームはグレースフルに機能低下 | -| **AIアシスタント（オプション）** | 内部の読み取り専用アシスタントコンテナ。LLMエンドポイントが設定されるまで無効 | -| **イングレスコントローラー** | 2つのロードバランサー（mTLS保護の取り込み用と、ダッシュボード用）。パブリック信頼の自動更新TLS証明書でTLSを終端し、取り込みエンドポイントでmTLSを強制 | -| **cert-manager** | TLS証明書のプロビジョニングとmTLSクライアント証明書の発行を自動化 | -| **証明書モニタリング** | 証明書の有効期限を確認し、更新期限が近づいたときにアラート（例: Slack）を送信するスケジュールジョブ | +| **Redis** | オプションの共有キャッシュおよびレート制限バックエンド。利用不可の場合もプラットフォームはグレースフルデグレードで動作します | +| **AIアシスタント（オプション）** | 内部の読み取り専用アシスタントコンテナ。LLMエンドポイントが設定されるまで無効状態を維持します | +| **イングレスコントローラー** | 2つのロードバランサー（mTLS保護の取り込み用と、ダッシュボード用）でTLSを終端し、パブリックで信頼された自動更新証明書を使用。取り込みエンドポイントにmTLSを適用します | +| **cert-manager** | TLS証明書のプロビジョニングおよびmTLSクライアント証明書の発行を自動化します | +| **証明書モニタリング** | スケジュールされたジョブが証明書の有効期限を確認し、更新が近づいた際にアラートを送信します（例: Slack） | -マネージドオファリングには、エージェントのアクティビティをお客様の評価基準に基づいてスコアリングする評価パイプラインの運用も含まれます。これらの機能の詳細については、[アシスタント](/ja/agenteye/assistant)および[評価スイート](/ja/agenteye/evaluation-suite)を参照してください。 +マネージドオファリングでは、エージェントのアクティビティをお客様の評価基準に対してスコアリングするプラットフォームの評価パイプラインも運用します。これらの機能の詳細については、[enterprise-docs/assistant.md](/ja/agenteye/assistant)および[enterprise-docs/evaluation-suite.md](/ja/agenteye/evaluation-suite)を参照してください。 --- -## お客様へ提供されるもの +## お客様に提供されるもの -デプロイ完了後、以下が提供されます。 +デプロイ完了後、以下の情報が提供されます。 | 項目 | 詳細 | |---|---| -| **ダッシュボードURL** | お客様のドメイン配下のホスト名（例: `https://agenteye.your-company.example`）。パブリック信頼の自動更新TLS証明書で提供。提供されるロードバランサーのホスト名に対してCNAMEを1件作成するだけで、サインインはパスワードレスのメールOTP | -| **コレクターエンドポイント** | 取り込みホスト名の `/events` パス（例: `https://ingest.your-company.example/events`）、mTLS保護 | -| **クライアント証明書バンドル** | クラスターごと: クライアント証明書、秘密鍵、CA証明書をKubernetes Secretマニフェストとして提供。クラスターごとに1度適用 | -| **GitHub PAT** | コレクターバイナリおよびPython SDKパッケージのダウンロード用 | -| **コレクターAPIキー** | `events:add` 権限を持つスコープ付きキー。コレクターデプロイメントごとに1つ | -| **インストールガイド** | コレクターとPython SDKのステップバイステップドキュメント | +| **ダッシュボードURL** | お客様のドメイン配下のホスト名（例: `https://agenteye.your-company.example`）。パブリックで信頼された自動更新TLS証明書で提供されます。Exosphereが提供するロードバランサーのホスト名へのCNAMEを1件作成するだけで、サインインはパスワードレスのメールOTPで行います | +| **Collectorエンドポイント** | 取り込みホスト名の`/events`パス（例: `https://ingest.your-company.example/events`）、mTLS保護付き | +| **クライアント証明書バンドル** | クラスターごとに: クライアント証明書、秘密鍵、CA証明書をKubernetes Secretマニフェストとして提供。各クラスターに1回適用します | +| **GitHub PAT** | CollectorバイナリおよびPython SDKパッケージのダウンロードに使用します | +| **Collector APIキー** | `events:add`権限を持つスコープ付きキー。Collectorデプロイごとに1つ発行します | +| **インストールガイド** | CollectorおよびPython SDKのステップバイステップのドキュメント | --- -## セットアップ後の作業 +## セットアップ後にお客様が行うこと -継続的な作業はAgentEyeクラスターではなく、お客様自身のエージェントマシン上でのみ発生します。 +継続的な作業は、AgentEyeクラスターではなく、お客様自身のエージェントマシン上のみで発生します。 -1. AIエージェントが稼働する各Kubernetesクラスターに**コレクターをインストール**: クライアント証明書をマウントし、エンドポイントURLとAPIキーを設定します。[コレクターのインストール](/ja/agenteye/collector-installation)を参照してください。 -2. エージェントコードに**Python SDKを統合**します。[Python SDK](/ja/agenteye/python-sdk)を参照してください。 +1. AIエージェントが稼働している各Kubernetesクラスターに**Collectorをインストール**します。クライアント証明書をマウントし、エンドポイントURLとAPIキーを設定します。詳細は[enterprise-docs/collector-installation.md](/ja/agenteye/collector-installation)を参照してください。 +2. エージェントのコードに**Python SDKを統合**します。詳細は[enterprise-docs/python-sdk.md](/ja/agenteye/python-sdk)を参照してください。 3. ブラウザで**ダッシュボードを開き**、エージェントのアクティビティを確認します。 -クラスター運用、データベース管理、証明書の更新、アップグレードは一切不要です。 +クラスターの運用、データベースの管理、証明書の更新、アップグレードは一切不要です。 --- ## セキュリティ -- **データはお客様のクラウドアカウント内に保持されます。** クラスター、ストレージ、データベースはすべてお客様の環境で稼働します。データがお客様の境界外に出ることはありません。 -- **アクセスはお客様が管理します。** クラスターはお客様のアカウント内にあります。Exosphereのアクセスをいつでも監査、監視、または取り消すことができます。すべての操作はお客様のクラウドの監査ログ（CloudTrail、GCP監査ログなど）に記録されます。 -- **イベント取り込みにはmTLSを使用。** すべてのコレクターリクエストに有効なクライアント証明書とAPIキーの両方が必要です。漏洩したキーは証明書がなければ無意味であり、盗まれた証明書は有効なキーがなければ無意味です。 -- **ダッシュボードのアクセス制御。** ダッシュボードはイベント取り込みとは分離した独自のロードバランサーで稼働し、サインインはお客様が許可リストに登録したメールアドレス/ドメインに制限されたパスワードレスのメールOTPです。ロードバランサーへのIPソースレンジ許可リストはリクエストに応じて対応可能です。証明書の自動更新がロードバランサーに到達できる必要があるため、制限を適用する場合はExosphereがDNSベースの証明書検証と組み合わせることで、制限下でも証明書の更新が継続して機能します。 -- **クラスターごとの証明書。** お客様の各クラスターにはそれぞれ固有のクライアント証明書が発行されます。あるクラスターが侵害された場合、その証明書のみを独立して失効させることができ、他のクラスターには影響しません。 +- **データはお客様のクラウドアカウント内に保持されます。** クラスター、ストレージ、データベースはすべてお客様の環境で動作します。お客様の境界外にデータが出ることはありません。 +- **アクセスはお客様が管理します。** クラスターはお客様のアカウント内にあります。Exosphereのアクセスはいつでも監査、モニタリング、または取り消しが可能です。すべての操作はお客様のクラウドの監査ログ（CloudTrail、GCP Audit Logsなど）に記録されます。 +- **イベント取り込みにmTLSを適用。** すべてのCollectorリクエストには、有効なクライアント証明書とAPIキーの両方が必要です。APIキーが漏洩しても証明書がなければ無効であり、証明書が盗まれても有効なAPIキーがなければ利用できません。 +- **ダッシュボードのアクセス制御。** ダッシュボードはイベント取り込みとは独立した専用のロードバランサーで動作し、サインインはお客様が許可リストに登録したメールアドレス/ドメインに限定されたパスワードレスのメールOTPです。ロードバランサーへのIPソースレンジ制限はリクエストに応じて対応可能です。証明書の自動更新にはロードバランサーへのアクセスが必要なため、Exosphereは制限とDNSベースの証明書検証を組み合わせて、制限下でも更新が継続して機能するようにします。 +- **クラスターごとの証明書。** お客様の各クラスターには固有のクライアント証明書が発行されます。あるクラスターが侵害された場合、その証明書のみを個別に失効させることができ、他のクラスターには影響しません。 --- -## デプロイメントタイムライン +## デプロイのスケジュール -| フェーズ | 所要期間 | お客様の関与 | +| フェーズ | 期間 | お客様の関与 | |---|---|---| -| **クラスタープロビジョニング** | 1〜2日 | クラスターをプロビジョニングし、Exosphereにアクセスを付与 | -| **プラットフォームセットアップ** | 1日 | 不要。Exosphereがすべてのインフラコンポーネントをインストール | -| **アプリケーションデプロイメント** | 1日 | 不要。Exosphereがサーバー、ダッシュボードをデプロイし、APIキーを作成 | -| **コレクターロールアウト** | 1〜3日 | お客様のクラスターにコレクターをインストール（Exosphereによるガイダンスあり） | -| **本番バーンイン** | 1週間 | 不要。Exosphereが監視・チューニングを実施 | +| **クラスターのプロビジョニング** | 1〜2日 | クラスターのプロビジョニングとExosphereへのアクセス権の付与 | +| **プラットフォームのセットアップ** | 1日 | なし。Exosphereがすべてのインフラコンポーネントをインストール | +| **アプリケーションのデプロイ** | 1日 | なし。Exosphereがサーバー、ダッシュボードをデプロイし、APIキーを作成 | +| **Collectorの展開** | 1〜3日 | お客様のクラスターにCollectorをインストール（Exosphereがガイド） | +| **本番環境バーンイン** | 1週間 | なし。Exosphereがモニタリングとチューニングを実施 | -キックオフから本番稼働まで、典型的なトータル期間: **約2週間** +キックオフから本番稼働まで、通常の合計期間: **約2週間** --- ## サポート -ご質問やお問い合わせは、Exosphereの `support@exosphere.host` までご連絡ください。 +ご質問や問題がある場合は、`support@exosphere.host` までExosphereにお問い合わせください。 --- ## 次のステップ - [はじめに](/ja/agenteye/getting-started): エンドツーエンドのウォークスルー -- [コレクターのインストール](/ja/agenteye/collector-installation): コレクターのインストールと設定 -- [Python SDK](/ja/agenteye/python-sdk): エージェントコードのインストルメンテーション +- [Collectorのインストール](/ja/agenteye/collector-installation): Collectorのインストールと設定 +- [Python SDK](/ja/agenteye/python-sdk): エージェントコードへの計装 - [APIキー](/ja/agenteye/api-keys): アクセスと権限の管理 -- [トラブルシューティング](/ja/agenteye/troubleshooting): 一般的な問題と解決策 \ No newline at end of file +- [トラブルシューティング](/ja/agenteye/troubleshooting): よくある問題と解決策 \ No newline at end of file diff --git a/docs/pt-br/agenteye/audits.mdx b/docs/pt-br/agenteye/audits.mdx index 95997279..291308c9 100644 --- a/docs/pt-br/agenteye/audits.mdx +++ b/docs/pt-br/agenteye/audits.mdx @@ -1,106 +1,106 @@ --- -title: "Auditorias — detecção de melhorias por agentes" -description: "Documentação do AgentEye Audits — detecção de melhorias por agentes." +title: "Auditorias — detecção de melhorias por agente" +description: "Documentação das Auditorias do AgentEye — detecção de melhorias por agente." --- -Auditorias são tarefas recorrentes que analisam os logs do seu agente **entre sessões** para encontrar pontos de melhoria. Enquanto um alerta monitora uma métrica específica que você já conhece em tempo quase real, uma auditoria *investiga*: em um cronograma que você define, ela executa uma verificação de políticas determinística sobre a janela de tempo, depois envia um **agente de confiabilidade com IA** para analisar suas sessões — o agente consulta os dados diretamente, lê transcrições suspeitas e (quando necessário) executa pequenos scripts de análise, produzindo **recomendações de melhoria** com as evidências correspondentes. -Use auditorias para responder "o que devo corrigir ou melhorar nos meus agentes?" — e alertas para ser notificado imediatamente quando um limite específico for ultrapassado. Cada melhoria está vinculada às sessões e consultas exatas que a embasam, e um único clique cria um alerta pré-preenchido para detectar recorrências. +Auditorias são jobs recorrentes que analisam os logs do seu agente **entre sessões** para identificar pontos de melhoria. Enquanto um alerta monitora uma métrica específica que você já conhece em tempo quase real, uma auditoria *investiga*: num agendamento definido por você, ela executa uma passagem de políticas determinística sobre a janela de tempo e, em seguida, solta um **agente de confiabilidade com IA** sobre suas sessões — o agente consulta os dados diretamente, lê transcrições suspeitas e (quando necessário) executa pequenos scripts de análise, produzindo **recomendações de melhoria** com as evidências por trás de cada uma. -A interface do painel está disponível em **`//audits`** (barra lateral → *analyze* → *audits*), protegida pelas permissões `audits:read` / `audits:write`. +Use auditorias para responder "o que devo corrigir ou melhorar nos meus agentes?" — e alertas para ser notificado no momento em que um limite específico é ultrapassado. Cada melhoria aponta para as sessões exatas e consultas que a embasam, e um único clique cria um alerta pré-preenchido para capturar recorrências. + +A superfície do dashboard é **`//audits`** (barra lateral → *analyze* → *audits*), protegida pelas permissões `audits:read` / `audits:write`. --- ## Como uma execução funciona -Cada execução tem duas camadas — uma base determinística e uma investigação por agentes. +Cada execução tem duas camadas — uma base determinística e uma investigação por agente. -### 1. A verificação de políticas (determinística) +### 1. A passagem de políticas (determinística) -Antes de qualquer modelo ser executado, a auditoria realiza um conjunto de **verificações de políticas em SQL** sobre a janela de tempo: consultas agregadas delimitadas que sinalizam padrões problemáticos conhecidos e reportam *quantos* eventos / *quais* sessões corresponderam — nunca o texto correspondente em si. O catálogo inclui: +Antes de qualquer modelo ser executado, a auditoria realiza um pequeno catálogo de **verificações de política em SQL** sobre a janela de tempo: consultas de agregação delimitadas que identificam padrões problemáticos conhecidos e reportam *quantos* eventos / *quais* sessões corresponderam — nunca o texto correspondente em si. O catálogo inclui: -- **Vazamento de segredos / credenciais** em cargas de eventos — chaves de acesso AWS, chaves de API `sk-…`, chaves privadas PEM, tokens JWT / bearer e atribuições de credencial `KEY=…`. +- **Vazamento de segredos / credenciais** em payloads de eventos — chaves de acesso AWS, chaves de API `sk-…`, chaves privadas PEM, tokens JWT / bearer e atribuições de credenciais do tipo `KEY=…`. - **Marcadores de injeção de prompt** — "ignore previous instructions", "reveal your system prompt" e similares. -- **PII** — números com formato de CPF/SSN (heurístico). -- **Negações de permissão de ferramentas** e **loops descontrolados de chamadas de ferramentas**. +- **PII** — números com formato de CPF/SSN (heurística). +- **Negações de permissão de ferramentas** e **loops descontrolados de chamadas a ferramentas**. -Hits de política são persistidos como descobertas (tipo `policy`) que **sempre aparecem** (nunca são removidos pelo limite por execução) e são entregues ao agente de IA como pontos de partida. Como essa camada não precisa de modelo, uma auditoria ainda produz os sinais de segurança mais importantes mesmo que o agente de IA esteja indisponível. +Ocorrências de política são persistidas como findings (tipo `policy`) que **sempre aparecem** (nunca são cortados pelo limite por execução) e são repassados ao agente de IA como pistas iniciais. Como essa camada não requer nenhum modelo, uma auditoria ainda produz seus sinais de segurança mais importantes mesmo que o agente de IA esteja indisponível. -### 2. A investigação por agentes (IA) +### 2. A investigação por agente (IA) -A auditoria então executa um **agente autônomo de confiabilidade** (o mesmo serviço Claude Agent SDK que alimenta o assistente do painel, com um prompt específico para auditorias). Com base no **escopo** da auditoria (agentes selecionados × ambientes) e na **janela de tempo**, o agente: +A auditoria então executa um **agente de confiabilidade autônomo** (o mesmo serviço Claude Agent SDK que alimenta o assistente do dashboard, com um prompt específico para auditoria). Com base no **escopo** da auditoria (agentes selecionados × ambientes) e na **janela de tempo**, o agente: - executa consultas SQL somente leitura nas suas tabelas de analytics, -- lê algumas transcrições de sessão representativas, -- opcionalmente escreve e executa **scripts Python curtos em um sandbox isolado dentro do pod** (sem rede, sem acesso ao sistema de arquivos, segredos removidos) para análises que o SQL não consegue expressar — agrupamento de erros, cálculo de distribuições, varredura de cargas já obtidas, -- e registra cada **melhoria** bem fundamentada que encontra. +- lê um conjunto de transcrições de sessões representativas, +- opcionalmente escreve e executa pequenos **scripts Python em um sandbox isolado dentro do pod** (sem rede, sem acesso ao sistema de arquivos, segredos removidos) para análises que o SQL não consegue expressar — agrupamento de erros, cálculo de distribuições, varredura de payloads já obtidos, +- e registra cada **melhoria** bem fundamentada que encontrar. -O agente percorre diversas linhas de investigação — agrupamento de erros, desvio em relação a uma linha de base, falhas de objetivo nas transcrições, uso indevido de ferramentas, trade-offs de qualidade/custo e lacunas de cobertura — conforme a **sensibilidade** da auditoria (baixa / média / alta). Cada melhoria **deve citar evidências**: os IDs das sessões que o agente inspecionou de fato e/ou o SQL executado. O servidor valida que as sessões citadas existem e **descarta qualquer melhoria sem evidência válida**, garantindo que o agente investigue sem inventar. +O agente trabalha em várias linhas investigativas — agrupamento de erros, desvio em relação a uma linha de base, falha de objetivo em transcrições, uso inadequado de ferramentas, trade-offs de qualidade/custo e lacunas de cobertura — de acordo com a **sensibilidade** da auditoria (baixa / média / alta). Cada melhoria **deve citar evidências**: os IDs das sessões que o agente efetivamente inspecionou e/ou o SQL que executou. O servidor valida que as sessões citadas existem e **descarta qualquer melhoria sem evidências válidas**, garantindo que o agente investiga mas nunca inventa. Cada melhoria inclui: -- uma **recomendação** (a mudança concreta a ser feita — ajuste de prompt, correção de schema de ferramenta, política de retry, guardrail, mais cobertura de avaliação), +- uma **recomendação** (a mudança concreta a ser feita — um ajuste de prompt, uma correção no schema de ferramenta, uma política de retry, um guardrail, mais cobertura de avaliação), - um **impacto esperado** e uma estimativa de **esforço** (baixo / médio / alto), -- uma **magnitude** — `big` (um operador deve ser notificado), `medium` (pertence ao relatório da execução) ou `small` (contexto do painel), -- uma **impressão digital** estável (baseada na categoria + escopo do problema, *não* nas sessões desta execução) para que o mesmo problema seja rastreado entre execuções mesmo quando as evidências mudam, -- e, quando um monitor determinístico simples poderia detectar recorrências, um **alerta sugerido** que você pode criar em um clique. +- uma **magnitude** — `big` (um operador deve ser alertado), `medium` (pertence ao relatório de execução) ou `small` (contexto do dashboard), +- um **fingerprint** estável (baseado na categoria + escopo do problema, *não* nas sessões desta execução) para que o mesmo problema seja rastreado de execução em execução mesmo quando as evidências mudam, +- e, quando um observador determinístico simples pode capturar recorrências, um **alerta sugerido** que você pode criar com um clique. -> **A camada de IA é opcional, mas recomendada.** Se nenhum agente de IA estiver configurado para o pipeline de auditoria, as execuções ainda ocorrem, persistem as descobertas de política e reportam honestamente "análise indisponível" para a camada de agentes, em vez de passar silenciosamente. +> **A camada de IA é opcional, mas recomendada.** Se nenhum agente de IA estiver configurado para o pipeline de auditoria, as execuções ainda acontecem, persistem os findings de política e reportam honestamente "análise indisponível" para a camada agêntica — em vez de passar silenciosamente sem resultados. ### Modos de falha -As melhorias são classificadas no **catálogo de modos de falha** duráveis da sua organização (ou propõem um novo modo). Os modos fornecem identidade estável aos padrões entre execuções e rastreamento de recorrência em longo prazo. +Melhorias são classificadas no **catálogo de modos de falha** duráveis da sua organização (ou propõem um novo modo). Os modos dão aos padrões uma identidade estável entre execuções e permitem rastreamento de recorrência no longo prazo. -## Ciclo de vida de triagem +## Ciclo de vida da triagem -Na página de uma descoberta (`/audits//findings/`): +Em uma página de finding (`/audits//findings/`): | Ação | Efeito | |---|---| -| **acknowledge** | Mantém a descoberta visível, mas reduz sua prioridade pela metade. | -| **resolve** | Marca como corrigido. Se o padrão realmente retornar, reabre como **new** — tornando uma regressão evidente, sem ser silenciosamente arquivada no histórico. | -| **mute** / **dismiss** | Supressão permanente: a impressão digital do padrão é memorizada e nunca mais aparece, mesmo entre execuções. Use mute para "conhecido, aceito"; dismiss para "não é útil". | -| **reopen** | Remove a supressão / resolução e classifica o padrão novamente. | -| **assign** | Direciona a descoberta a um operador (membro da organização) para responsabilização. Prioridade e estado de supressão permanecem inalterados. | +| **acknowledge** | Mantém o finding visível, mas reduz sua prioridade à metade. | +| **resolve** | Marca como corrigido. Se o padrão realmente retornar depois, ele reabre como **new** — tornando a regressão visível, não silenciosamente absorvida pelo histórico. | +| **mute** / **dismiss** | Supressão durável: o fingerprint do padrão é memorizado e nunca aparece novamente, mesmo entre execuções. Use mute para "conhecido e aceito"; dismiss para "não é útil". | +| **reopen** | Limpa a supressão / resolução e reposiciona o padrão na fila. | -O ruído de baixo sinal é controlado por auditoria com um limite de descobertas por execução (`top_k`) para as melhorias geradas por agentes. Descobertas de política ignoram esse limite (são relevantes para segurança e sempre exibidas). Tudo que for cortado pelo limite é contabilizado nas estatísticas da execução — nada é descartado silenciosamente. +O ruído de baixo sinal é controlado por auditoria com um limite de findings por execução (`top_k`) sobre as melhorias agênticas. Findings de política ignoram esse limite (são relevantes para segurança e sempre exibidos). Tudo que for cortado pelo limite é contabilizado nas estatísticas da execução — nada é descartado silenciosamente. ## Agendamento -- **Cadência** (`schedule_interval_secs`): de horária a semanal; **diária é o padrão**. Auditorias são deliberadamente menos frequentes que alertas — uma investigação por agentes examina janelas inteiras e leva minutos para executar. -- **Janela**: lookback contínuo fixo (por exemplo, "cada execução analisa os últimos 7 dias") ou **desde a última execução** (padrão) — cada execução continua de onde a anterior bem-sucedida terminou, com uma pequena sobreposição para que eventos no limite nunca sejam perdidos. -- A próxima execução é agendada um intervalo completo após a **conclusão** da anterior, portanto uma execução lenta nunca empilha uma segunda execução simultânea da mesma auditoria. -- **Run now** na página da auditoria a agenda para execução imediata. +- **Cadência** (`schedule_interval_secs`): de horária a semanal; **diária é o padrão**. Auditorias são deliberadamente mais espaçadas do que alertas — uma investigação agêntica varre janelas inteiras e leva minutos para executar. +- **Janela**: ou um lookback fixo e contínuo (ex.: "cada execução analisa os últimos 7 dias") ou **desde-a-última-execução** (o padrão) — cada execução retoma de onde a anterior bem-sucedida parou, com uma pequena sobreposição para que eventos de fronteira nunca sejam perdidos. +- A próxima execução é agendada um intervalo completo após a **conclusão** da anterior, garantindo que uma execução lenta nunca empilhe uma segunda execução concorrente da mesma auditoria. +- **Run now** na página da auditoria a torna imediatamente elegível para execução. ## Seleção de modelo -Ao criar uma auditoria, você pode escolher qual modelo a investigação utiliza, a partir da **lista de modelos configurados pelo operador** para o serviço de agentes. Com um único modelo configurado, o seletor o exibe como legenda; com vários, você escolhe. Deixar sem definir usa o padrão configurado. +Ao criar uma auditoria, você pode escolher qual modelo a investigação utiliza, dentre a **lista de modelos configurados pelo seu operador** para o serviço de agente. Com um único modelo configurado, o seletor o exibe como legenda; com vários, você escolhe. Deixar sem definir utiliza o padrão configurado. ## Notificações -Quando uma execução encontra descobertas **novas**, a auditoria notifica os canais configurados da sua organização — os mesmos canais e configurações do gate `alerts.enabled_channels` usados pelo pipeline de alertas: +Quando uma execução encontra findings **novos**, a auditoria notifica os canais configurados da sua organização — os mesmos canais do `alerts.enabled_channels` e configurações que o pipeline de alertas utiliza: - **Slack** — um resumo dos novos itens significativos (`big`) com um link direto. -- **Email** — um **relatório de auditoria** formatado listando as novas melhorias (maior severidade, recomendações por item, link direto), enviado quando a auditoria tem um canal de **email** vinculado e há pelo menos uma nova descoberta. +- **Email** — um **relatório de auditoria** formatado listando as novas melhorias (maior severidade, recomendações por item, link direto), enviado quando a auditoria tem um canal de **email** configurado e há pelo menos um finding novo. -Descobertas recorrentes já conhecidas não geram novas notificações. +Findings recorrentes já conhecidos não geram novas notificações. ## Referência de configuração -As definições de auditoria são gerenciadas no painel (`/audits/new`) ou via API. As configurações por auditoria incluem a cadência e janela do agendamento, o escopo (`{"environments": [...], "agent_ids": [...]}`), a sensibilidade (`low` / `medium` / `high`), os canais de notificação, o limite de descobertas por execução (`top_k`) e o modelo (via `llm_budget.model`). Configurações do servidor no nível do operador (timeouts, sandbox, a URL do serviço de agentes) estão documentadas em [deployment.md](/pt-br/agenteye/deployment). +As definições de auditoria são gerenciadas no dashboard (`/audits/new`) ou via API. As configurações por auditoria incluem a cadência e a janela de agendamento, o escopo (`{"environments": [...], "agent_ids": [...]}`), a sensibilidade (`low` / `medium` / `high`), os canais de notificação, o limite de findings por execução (`top_k`) e o modelo (via `llm_budget.model`). Configurações de servidor no nível do operador (timeouts, sandbox, URL do serviço de agente) estão documentadas em [deployment.md](/pt-br/agenteye/deployment). ## API -Todos os endpoints são com escopo de organização e seguem a autenticação padrão por bearer key (consulte [api-keys.md](/pt-br/agenteye/api-keys)). +Todos os endpoints têm escopo de organização e seguem a autenticação padrão por bearer key (veja [api-keys.md](/pt-br/agenteye/api-keys)). | Endpoint | Permissão | Finalidade | |---|---|---| | `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | Listar / criar definições de auditoria. | | `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Inspecionar, editar, excluir uma auditoria. | -| `POST /audits/:id/run` | `audits:write` | Agendar a auditoria para execução imediata. | -| `GET /audits/:id/runs` | `audits:read` | Histórico de execuções (janela, status, estatísticas, contagens de descobertas). | -| `GET /audits/findings` | `audits:read` | Descobertas de toda a organização, filtráveis por `audit_id`, `status`; ordenadas por prioridade. | -| `GET /audits/findings/:fid` | `audits:read` | Detalhes completos da descoberta (recomendação, evidências, prioridade). | +| `POST /audits/:id/run` | `audits:write` | Tornar a auditoria imediatamente elegível para execução. | +| `GET /audits/:id/runs` | `audits:read` | Histórico de execuções (janela, status, estatísticas, contagem de findings). | +| `GET /audits/findings` | `audits:read` | Findings de toda a organização, filtráveis por `audit_id`, `status`; ordenados por prioridade. | +| `GET /audits/findings/:fid` | `audits:read` | Detalhes completos do finding (recomendação, evidências, prioridade). | | `POST /audits/findings/:fid/status` | `audits:write` | Triagem: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | -Para os casos "a auditoria executou mas não encontrou nada", "o sandbox de código está desativado" e "email de auditoria não entregue", consulte [troubleshooting.md](/pt-br/agenteye/troubleshooting#audits). \ No newline at end of file +Para "auditoria executou mas não encontrou nada", "o sandbox de código está desativado" e "email de auditoria não foi entregue", veja [troubleshooting.md](/pt-br/agenteye/troubleshooting#audits). \ No newline at end of file diff --git a/docs/pt-br/agenteye/cli-recipes.mdx b/docs/pt-br/agenteye/cli-recipes.mdx index bef42ada..1aa774b4 100644 --- a/docs/pt-br/agenteye/cli-recipes.mdx +++ b/docs/pt-br/agenteye/cli-recipes.mdx @@ -3,28 +3,27 @@ title: "Receitas de CLI para agentes" description: "Documentação de receitas de CLI do AgentEye para agentes." --- +Obtenha dados de sessões, eventos e avaliações (e acione reavaliações) diretamente de um script ou agente de codificação, com JSON limpo no stdout que pode ser redirecionado para o `jq`. Essas receitas transformam os dados de observabilidade do AgentEye em algo que um usuário de terminal ou um agente de codificação de IA (Claude Code, Cursor) pode consultar e automatizar, sem precisar clicar pelo dashboard. -Acesse dados de sessão, evento e avaliação (e dispare reavaliações) diretamente de um script ou agente de código, com JSON limpo no stdout que se encaixa diretamente no `jq`. Essas receitas transformam os dados de observabilidade do AgentEye em algo que um usuário de terminal ou um agente de codificação com IA (Claude Code, Cursor) pode consultar e automatizar, sem precisar clicar no dashboard. - -Os padrões abaixo estão prontos para copiar e colar no CLI do AgentEye (`agenteye`). Para instalação, autenticação e a lista completa de opções, consulte [CLI](/pt-br/agenteye/cli); execute `agenteye -h` ou `agenteye -h` para ver a ajuda integrada. +Os padrões abaixo estão prontos para copiar e colar com a CLI do AgentEye (`agenteye`). Para instalação, autenticação e a lista completa de opções, consulte [CLI](/pt-br/agenteye/cli); execute `agenteye -h` ou `agenteye -h` para obter a ajuda integrada. ## Regras de ouro -1. **As opções globais vêm *antes* do comando.** `agenteye --json sessions` está correto; `agenteye sessions --json` não está. As globais são `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Passe `--json` sempre que for fazer parsing da saída.** Os dados vão para o **stdout** como JSON; status e erros para humanos vão para o **stderr**, então o stdout permanece limpo para ser redirecionado ao `jq`. -3. **Tome decisões com base no código de saída**, não no texto do stderr: `0` ok · `2` argumentos inválidos · `3` não foi possível alcançar o dashboard · `4` não autenticado ou sessão expirada · `5` permissão ausente. -4. **Descubra com `-h`.** Cada comando documenta seus filtros, formatos de valores e estrutura JSON. +1. **As opções globais vêm *antes* do comando.** `agenteye --json sessions` está correto; `agenteye sessions --json` não está. As opções globais são `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **Use `--json` sempre que for processar a saída.** Os dados vão para o **stdout** como JSON; status e erros para humanos vão para o **stderr**, mantendo o stdout limpo para redirecionar ao `jq`. +3. **Tome decisões com base no código de saída**, não no texto do stderr: `0` ok · `2` argumentos inválidos · `3` não consegue alcançar o dashboard · `4` não autenticado ou sessão expirada · `5` permissão ausente. +4. **Descubra com `-h`.** Cada comando documenta seus filtros, formatos de valor e estrutura JSON. ## Configuração inicial ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # para não precisar repetir --base-url +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # para não repetir --base-url agenteye login --email you@example.com # cole o código enviado por e-mail; válido por ~24h ``` -## Confirme a autenticação antes de executar qualquer operação +## Confirme a autenticação antes de começar -`whoami` nunca retorna erro por sessão ausente ou expirada; ele reporta `logged_in:false` em vez disso, então um agente pode verificar o estado de autenticação com segurança. (Ainda pode sair com código diferente de zero se nenhuma URL base estiver definida ou o dashboard estiver inacessível.) +`whoami` nunca retorna erro quando a sessão está ausente ou expirada; ele reporta `logged_in:false`, permitindo que um agente verifique o estado de autenticação com segurança. (Ainda pode sair com código não zero se nenhuma URL base estiver definida ou se o dashboard estiver inacessível.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -32,44 +31,44 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## Encontre sessões com falha ou pontuação baixa +## Encontre sessões com falhas ou pontuações baixas ```bash -# sessões nas últimas 24h cuja avaliação retornou erro +# sessões nas últimas 24h cujas avaliações retornaram erro agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# avaliações com pontuação <= 0.5 em utilidade, para um agente específico +# avaliações com pontuação <= 0.5 em helpfulness, para um agente específico agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -A filtragem por pontuação está em **`evals`**, não em `sessions`. `--score KEY:MIN..MAX` é repetível e combinado com AND; qualquer limite é opcional (`..0.5` significa ≤ 0,5, `0.9..` significa ≥ 0,9). Você pode passar até 20 filtros de pontuação por requisição; mais do que isso retorna HTTP 400. `sessions` compartilha os filtros `--env`, `--status`, `--agent-id`, `--session-id` e de intervalo de tempo com `evals`, mas não possui `--score`. +O filtro por pontuação fica em **`evals`**, não em `sessions`. `--score KEY:MIN..MAX` pode ser repetido e é combinado com AND; qualquer um dos limites é opcional (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Você pode passar até 20 filtros de pontuação por requisição; mais do que isso retorna HTTP 400. `sessions` compartilha os filtros `--env`, `--status`, `--agent-id`, `--session-id` e de intervalo de tempo com `evals`, mas não possui `--score`. -## Leia uma sessão do início ao fim +## Leia uma sessão completa Não existe um único comando `session show` — combine o histórico de eventos com a avaliação da sessão: ```bash -# avaliação mais recente da sessão (status + pontuações) +# a avaliação mais recente da sessão (status + pontuações) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# todos os eventos da execução (aumente --limit para uma varredura completa) +# todos os eventos da execução (aumente --limit para varredura completa) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# apenas as chamadas de ferramenta em uma sessão +# apenas as chamadas de ferramenta de uma sessão agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` ## Busque tudo (paginação) -Os resultados são ordenados do mais recente para o mais antigo e são paginados por cursor. +Os resultados são retornados do mais recente para o mais antigo e paginados por cursor. ```bash -# tudo de uma vez: busca até 500 registros em páginas de 200 +# em uma única chamada: busca até 500 registros em páginas de 200 agenteye --json events --session-id run-001 --limit 500 --all > events.json -# paginação manual: passe next_cursor de volta +# paginação manual: repasse o next_cursor page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" @@ -77,14 +76,14 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') ## Reduza a saída com --fields -Restrinja as chaves (tanto na tabela quanto no `--json`) para diminuir o que um agente precisa ler. +Restrinja as chaves (tanto na tabela quanto no `--json`) para diminuir o que um agente precisa processar. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Nomes de campos desconhecidos são rejeitados (saída `2`) com a lista de campos válidos — uma forma prática de descobrir os nomes disponíveis. +Nomes de campos desconhecidos são rejeitados (saída `2`) com a lista de valores válidos — uma forma rápida de descobrir os nomes dos campos. ## Descubra valores de filtro válidos @@ -94,45 +93,45 @@ agenteye --json list tools | jq -r '.values[]' # nomes de ferramentas; agenteye --json list score_filters | jq -r '.values[]' # KEY válida para --score KEY:MIN..MAX ``` -## Selecione sua organização (multi-tenant) +## Escolha sua organização (multi-tenant) -Se você pertence a mais de uma organização, escolha o tenant ativo no login (ele é salvo): +Se você pertence a mais de uma organização, escolha o tenant ativo no momento do login (ele é salvo): ```bash agenteye login --org acme --email you@corp.com # define o tenant no mesmo passo do login agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # sobrescreve para um único comando +agenteye --org globex --json sessions --since 24h # substitui para um único comando ``` -Um login multi-organização sem `--org` sai com código diferente de zero e exibe as organizações disponíveis para escolha. +Um login com múltiplas organizações sem `--org` sai com código não zero e exibe as organizações disponíveis para escolha. ## Provisione uma chave de API para o SDK/coletor ```bash -# o segredo é exibido UMA ÚNICA VEZ — com --json está no campo .key +# o segredo é exibido UMA ÚNICA VEZ — com --json ele fica no campo .key key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # rotaciona; use agenteye keys disable ci-bot --yes para revogar ``` -## Execute uma consulta salva ou ad-hoc +## Execute uma query salva ou ad-hoc ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # uma consulta salva + um $1 posicional +agenteye --json query run errs --arg prod | jq '.rows' # uma query salva + um argumento posicional $1 ``` -## Faça triagem de um incidente de forma não interativa +## Trate um incidente de forma não interativa ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> Mutações ignoram automaticamente o prompt de confirmação quando `--json` está presente ou quando o stdin não é um TTY, para que agentes nunca fiquem travados; passe `--yes`/`-y` para ignorá-lo explicitamente em outros contextos. +> Mutações ignoram automaticamente o prompt de confirmação quando `--json` está ativo ou quando o stdin não é um TTY, então agentes nunca ficam travados; use `--yes`/`-y` para ignorá-lo explicitamente em outros contextos. -## Tratamento de código de saída em um script +## Tratamento de códigos de saída em um script ```bash out=$(agenteye --json sessions --since 1h) || code=$? @@ -145,7 +144,7 @@ case "${code:-0}" in esac ``` -## Formatos de saída JSON +## Estruturas de saída JSON | Comando | JSON no stdout (com `--json`) | |---|---| @@ -167,4 +166,4 @@ esac - Cada item de **avaliação** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. - Cada item de **sessão** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -O `--fields` de cada comando aceita exatamente os nomes de campo do seu próprio item — o conjunto difere entre `sessions` e `evals`, então um nome válido para um pode ser rejeitado pelo outro. \ No newline at end of file +O `--fields` de cada comando aceita exatamente os nomes de campos do seu próprio item — o conjunto difere entre `sessions` e `evals`, portanto um nome válido para um pode ser rejeitado pelo outro. \ No newline at end of file diff --git a/docs/pt-br/agenteye/deployment.mdx b/docs/pt-br/agenteye/deployment.mdx index a5eaaa91..1ece5416 100644 --- a/docs/pt-br/agenteye/deployment.mdx +++ b/docs/pt-br/agenteye/deployment.mdx @@ -1,16 +1,17 @@ --- -title: "Deployment" -description: "Documentação de deployment do AgentEye." +title: "Implantação" +description: "Documentação de implantação do AgentEye." --- -Este guia aborda como fazer o deploy do servidor e do dashboard do AgentEye em produção. + +Este guia cobre a implantação do servidor e dashboard do AgentEye em produção. --- ## Visão Geral da Arquitetura ``` - [ Máquinas dos agentes de IA ] [ Sua infraestrutura ] + [ Máquinas do agente de IA ] [ Sua infraestrutura ] Python SDK | escreve JSONL +----------------------+ @@ -21,7 +22,7 @@ Este guia aborda como fazer o deploy do servidor e do dashboard do AgentEye em p +--------+ | | Server |<------+ +----------------------+ +--------+ +--->| ClickHouse 24+ | - ^ | | (eventos / analytics)| + ^ | | (eventos / analítica)| API | | +----------------------+ | | +-----------+ | +----------------------+ @@ -30,134 +31,133 @@ Este guia aborda como fazer o deploy do servidor e do dashboard do AgentEye em p ``` - **Server**: Serviço HTTP em Rust; recebe lotes de eventos, grava-os no ClickHouse e mantém o estado relacional no PostgreSQL. -- **Dashboard**: Aplicação web em Next.js; lê e escreve exclusivamente via API do servidor. -- **agenteye-collector**: implantado nas máquinas dos agentes, não no host do servidor. -- **Postgres 15+**: OBRIGATÓRIO. (Elevado do 14 na versão multi-tenant; o schema de membros de org usa uma foreign key `ON DELETE SET NULL` com lista de colunas, disponível apenas no Postgres 15+. Atualize o Postgres antes de fazer o deploy desta versão.) Armazena o estado OLTP: `api_keys`, `users`, `sessions`, `evaluation_jobs` (fila), `dashboards`, `saved_queries`, `otp_codes`, além das tabelas multi-tenant `orgs`, `org_memberships`, `org_settings`. -- **ClickHouse 24+**: OBRIGATÓRIO. O armazenamento de analytics para cada evento ingerido. Engine: `ReplacingMergeTree`, particionado por mês, ordenado por `(session_id, ts, dedup_key)`. O servidor conecta via `CLICKHOUSE_URL`; o `deploy/base/clickhouse/` incluído no pacote traz uma configuração de nó único ajustada para performance. **Requisito multi-tenant:** a configuração inclusa habilita gerenciamento de acesso SQL + `users_without_row_policies_can_read_rows=false` para que o servidor possa criar um usuário ClickHouse somente leitura + row policy por organização (o limite de isolamento imposto pelo engine para o editor SQL e o agente de IA). Se você fornecer sua própria configuração do ClickHouse, inclua essas definições (veja `deploy/base/clickhouse/configmap.yaml`). -- **Redis 7+**: cache compartilhado *opcional* + backend de rate limiting. Servidor e dashboard conectam via `REDIS_URL`. Se ausente, ambos degradam de forma elegante para caminhos somente via Postgres. Veja **Redis (cache opcional)** abaixo. +- **Dashboard**: Aplicação web em Next.js; lê e escreve exclusivamente por meio da API do servidor. +- **agenteye-collector**: implantado nas máquinas do agente, não no host do servidor. +- **Postgres 15+**: OBRIGATÓRIO. (Elevado da versão 14 na release multi-tenant; o esquema org-membership usa uma foreign key `ON DELETE SET NULL` com lista de colunas, que é Postgres 15+. Atualize o Postgres antes de implantar esta versão.) Armazena o estado OLTP: `api_keys`, `users`, `sessions`, `evaluation_jobs` (fila), `dashboards`, `saved_queries`, `otp_codes`, além das tabelas multi-tenant `orgs`, `org_memberships`, `org_settings`. +- **ClickHouse 24+**: OBRIGATÓRIO. O armazenamento analítico para cada evento ingerido. Engine: `ReplacingMergeTree`, particionado por mês, ordenado por `(session_id, ts, dedup_key)`. O servidor se conecta via `CLICKHOUSE_URL`; o `deploy/base/clickhouse/` incluído no pacote traz uma configuração de nó único otimizada para desempenho. **Requisito multi-tenant:** a configuração incluída habilita o gerenciamento de acesso SQL + `users_without_row_policies_can_read_rows=false` para que o servidor possa criar um usuário ClickHouse somente leitura + row policy por organização (o limite de isolamento imposto pela engine para o editor SQL e o agente de IA). Se você fornecer sua própria configuração do ClickHouse, mantenha essas configurações (veja `deploy/base/clickhouse/configmap.yaml`). +- **Redis 7+**: *opcional* — cache compartilhado + backend de rate limit. O servidor e o dashboard se conectam via `REDIS_URL`. Se ausente, ambos degradam graciosamente para caminhos somente com Postgres. Veja **Redis (cache opcional)** abaixo. --- ## Servidor -### Baixar a imagem +### Obtendo a imagem ```bash echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> As builds atuais são publicadas sob `beta-latest`; `latest` é atribuído apenas a releases estáveis. Em produção, fixe uma tag específica `:v`; veja [Tags de imagem disponíveis](#available-image-tags). +> As builds atuais são publicadas sob `beta-latest`; `latest` é atribuído apenas a releases estáveis. Para produção, fixe uma tag específica `:v`; veja [Tags de Imagem Disponíveis](#available-image-tags). ### Variáveis de ambiente | Variável | Obrigatória | Padrão | Descrição | |---|---|---|---| -| `DATABASE_URL` | Sim | none | DSN do Postgres. Formato de string de conexão libpq padrão com esquema `postgres://`. Suporta `?sslmode=require` e outros parâmetros libpq. A senha não deve conter `/`, `+` ou `=`; use `openssl rand -hex` para gerar senhas seguras para URL. | -| `ADMIN_KEY` | Não | none | Chave de API admin de bootstrap. Inserida/atualizada com todas as permissões em cada inicialização. Troque alterando o valor e reiniciando. | -| `LISTEN_ADDR` | Não | `0.0.0.0:8080` | Endereço TCP para bind | +| `DATABASE_URL` | Sim | nenhum | DSN do Postgres. Formato de string de conexão libpq padrão com esquema `postgres://`. Suporta `?sslmode=require` e outros parâmetros libpq. A senha não deve conter `/`, `+` ou `=`; use `openssl rand -hex` para gerar senhas seguras para URL. | +| `ADMIN_KEY` | Não | nenhum | Chave de API admin inicial. Inserida/atualizada com todas as permissões a cada inicialização. Troque alterando o valor e reiniciando. | +| `LISTEN_ADDR` | Não | `0.0.0.0:8080` | Endereço TCP para vincular | | `MAX_BODY_BYTES` | Não | `134217728` (128 MB) | Tamanho máximo do corpo da requisição | -| `ADMIN_EMAIL` | Não | none | Email do usuário admin de bootstrap. Inserido/atualizado com todas as permissões em cada inicialização e marcado como protegido: não pode ser desativado nem ter permissões modificadas via dashboard/API. Para trocar o admin de bootstrap, altere `ADMIN_EMAIL` e reinicie; o novo email é inserido como protegido, e o anterior mantém sua proteção até ser removido manualmente no banco de dados. | -| `ALLOWED_EMAILS` | Não | none (todos bloqueados) | Lista separada por vírgulas de emails permitidos para criação de usuário e login. Suporta endereços exatos (`user@example.com`) e wildcards de domínio (`*@example.com`). Se não definido, nenhum usuário pode ser criado ou fazer login. **Seed apenas no primeiro boot**: alimenta a allowlist da org padrão no primeiro boot; a partir daí, a página [`//settings`](#operational-settings) de cada org é a fonte de verdade e alterar essa variável de ambiente não tem efeito. | -| `SMTP_HOST` | Não | none | Hostname do servidor SMTP para envio de emails com OTP. Se não definido, os códigos OTP são registrados no stdout. | +| `ADMIN_EMAIL` | Não | nenhum | E-mail do usuário admin inicial. Inserido/atualizado com todas as permissões a cada inicialização e marcado como protegido: não pode ser desabilitado nem ter suas permissões modificadas via dashboard/API. Para trocar o admin inicial, altere `ADMIN_EMAIL` e reinicie; o novo e-mail é inserido como protegido, e o anterior mantém sua proteção até ser limpo manualmente no banco de dados. | +| `ALLOWED_EMAILS` | Não | nenhum (todos bloqueados) | Lista de e-mails permitidos para criação de usuário e login, separados por vírgula. Suporta endereços exatos (`user@example.com`) e curingas de domínio (`*@example.com`). Se não definido, nenhum usuário pode ser criado ou fazer login. **Apenas na primeira inicialização**: alimenta a lista de permissões da org padrão na primeira inicialização; a partir daí, a página [`//settings`](#operational-settings) de cada org é a fonte da verdade e alterar esta variável de ambiente não tem efeito. | +| `SMTP_HOST` | Não | nenhum | Nome do host do servidor SMTP para envio de e-mails OTP. Se não definido, os códigos OTP são registrados no stdout. | | `SMTP_PORT` | Não | `587` | Porta do servidor SMTP | -| `SMTP_USERNAME` | Não | none | Nome de usuário para autenticação SMTP | -| `SMTP_PASSWORD` | Não | none | Senha para autenticação SMTP | -| `SMTP_FROM` | Não | none | Endereço de email remetente para emails com OTP | -| `SMTP_TLS` | Não | STARTTLS | STARTTLS é usado por padrão, a menos que você o desative explicitamente: `false` ou `0` envia em texto puro (sem TLS); qualquer outro valor — incluindo não definido — habilita STARTTLS. | -| `DASHBOARD_URL` | Não | padrão interno | Origem do dashboard usada para construir tanto o magic link do email com OTP quanto os magic links de incidentes nas notificações de alertas. Se não definido, recorre a um padrão interno (e, apenas para OTP, à origem derivada da requisição do dashboard primeiro). Defina isso para setups com domínio separado para que links de email e Slack/incidente apontem para o seu dashboard. Veja **URL do magic link de email** abaixo; a maioria dos operadores não precisa definir isso. | -| `SESSION_TTL_SECS` | Não | `86400` (24 h) | Duração da sessão do dashboard em segundos. **Seed apenas no primeiro boot**: edite por org via [`//settings`](#operational-settings) após o primeiro deploy. | -| `OTP_TTL_SECS` | Não | `600` (10 min) | Período de validade do código OTP em segundos. **Seed apenas no primeiro boot**: edite por org via [`//settings`](#operational-settings) após o primeiro deploy. | -| `REDIS_URL` | Não | none | Cache compartilhado opcional + backend de rate limiting, ex.: `redis://redis:6379/0`. Quando definido, o servidor cacheia lookups de API key autenticados, o agregado `/models` do dashboard, a lista de sessões e a faceta de lista de ambientes; também move o rate limiting de requisição OTP do Postgres COUNT para o Redis INCR. Se não definido ou inacessível, o servidor funciona sem o cache (o limite OTP recai para o Postgres, todas as outras chamadas de cache passam diretamente para a fonte de verdade). Veja **Redis (cache opcional)** abaixo. | -| `CLICKHOUSE_URL` | **Sim** | none | URL base da instância ClickHouse, ex.: `http://clickhouse:8123`. O servidor aplica o schema de eventos a esse banco a cada inicialização e recusa o boot se não conseguir alcançar o ClickHouse. Veja **ClickHouse (armazenamento de analytics obrigatório)** abaixo. | +| `SMTP_USERNAME` | Não | nenhum | Nome de usuário para autenticação SMTP | +| `SMTP_PASSWORD` | Não | nenhum | Senha para autenticação SMTP | +| `SMTP_FROM` | Não | nenhum | Endereço de e-mail do remetente para e-mails OTP | +| `SMTP_TLS` | Não | STARTTLS | STARTTLS é usado, a menos que você o desative explicitamente: `false` ou `0` envia em texto simples (sem TLS); qualquer outro valor — inclusive não definido — habilita STARTTLS. | +| `DASHBOARD_URL` | Não | padrão interno | Origem do dashboard usada para construir tanto o magic link do e-mail OTP quanto os magic links de incidentes nas notificações de alerta. Se não definido, usa um padrão interno (e, apenas para OTP, a origem derivada da requisição do dashboard primeiro). Defina para configurações de domínios separados, para que tanto o e-mail quanto os links do Slack/incidentes apontem para o seu dashboard. Veja **URL do magic link de e-mail** abaixo; a maioria dos operadores não precisa definir isso. | +| `SESSION_TTL_SECS` | Não | `86400` (24 h) | Duração da sessão do dashboard em segundos. **Apenas na primeira inicialização**: edite por org via [`//settings`](#operational-settings) após o primeiro deploy. | +| `OTP_TTL_SECS` | Não | `600` (10 min) | Período de validade do código OTP em segundos. **Apenas na primeira inicialização**: edite por org via [`//settings`](#operational-settings) após o primeiro deploy. | +| `REDIS_URL` | Não | nenhum | Backend opcional de cache compartilhado + rate limit, ex.: `redis://redis:6379/0`. Quando definido, o servidor faz cache de lookups de API keys autenticadas, o agregado `/models` do dashboard, a lista de sessões e a faceta de lista de ambientes; também move o rate limiting de requisições OTP do Postgres COUNT para o Redis INCR. Se não definido ou inacessível, o servidor funciona sem o cache (o limite OTP recai para o Postgres; todas as outras chamadas de cache passam direto para a fonte da verdade). Veja **Redis (cache opcional)** abaixo. | +| `CLICKHOUSE_URL` | **Sim** | nenhum | URL base da instância do ClickHouse, ex.: `http://clickhouse:8123`. O servidor aplica o esquema de eventos a esse banco de dados a cada inicialização e se recusa a iniciar se não conseguir alcançar o ClickHouse. Veja **ClickHouse (armazenamento analítico obrigatório)** abaixo. | | `CLICKHOUSE_DATABASE` | Não | `agenteye` | Nome do banco de dados (schema) do ClickHouse. O servidor o cria na inicialização se não existir. | -| `ORG_CH_SECRET` | Não (single-tenant) / **Sim (multi-org)** | padrão de dev | Chave HMAC a partir da qual a senha ClickHouse por tenant de cada organização é derivada. O editor SQL e o `run_query` do agente de IA executam como o usuário ClickHouse somente leitura da org, cuja row policy impõe o isolamento do tenant no engine. Deployments single-tenant funcionam bem com o padrão de dev interno; **antes de provisionar uma segunda org você DEVE definir um valor forte e estável**, pois o CLI `agenteye-orgctl org create` recusa executar com o padrão de dev interno. Rotacioná-lo deixa o usuário ClickHouse de cada org órfão até a próxima inicialização reaprovisioná-los (a reconciliação no boot cura isso automaticamente). Mantenha-o secreto e inalterado entre réplicas. O provisionamento de orgs em si é exclusivo do operador; veja **Organizações (multi-tenancy)** abaixo. | -| `DEFAULT_ORG_NAME` | Não | `Default` | Nome de exibição semeado para a org padrão interna. **Seed apenas no primeiro boot**, e somente enquanto a org ainda mantém sua identidade genérica recém-migrada, aplicado na inicialização e depois ignorado. Uma vez que você renomeia a org (`agenteye-orgctl org rename`) a renomeação é autoritativa e essa variável de ambiente não tem mais efeito. | -| `DEFAULT_ORG_SLUG` | Não | `default` | Slug de URL para a org padrão interna, o caminho do dashboard em que ela vive (`//…`). Mesma semântica de apenas-primeiro-boot/apenas-pristine que `DEFAULT_ORG_NAME`. Deve ter 1-40 caracteres alfanuméricos minúsculos com hífens internos simples e não ser uma [palavra reservada](#organizations-multi-tenancy); um valor inválido é ignorado (a org mantém `default`). Permite que uma instalação single-tenant apareça como ex. `/acme` em vez de `/default` sem nenhuma etapa de CLI pós-deploy. | +| `ORG_CH_SECRET` | Não (single-tenant) / **Sim (multi-org)** | padrão de desenvolvimento | Chave HMAC da qual a senha ClickHouse por tenant de cada organização é derivada. O editor SQL e o `run_query` do agente de IA são executados como o usuário ClickHouse somente leitura da org, cuja row policy impõe o isolamento de tenant na engine. Deployments single-tenant funcionam bem com o padrão de desenvolvimento interno; **antes de provisionar uma segunda org, você DEVE definir um valor forte e estável**, pois o CLI `agenteye-orgctl org create` se recusa a executar com o padrão de desenvolvimento interno. Rotacionar esse valor torna órfão o usuário ClickHouse de cada org até a próxima inicialização reaprovisioná-los (a reconciliação na inicialização corrige isso automaticamente). Mantenha-o secreto e inalterado em todas as réplicas. O provisionamento de orgs é exclusivo do operador; veja **Organizações (multi-tenancy)** abaixo. | +| `DEFAULT_ORG_NAME` | Não | `Default` | Nome de exibição inserido para a org padrão integrada. **Apenas na primeira inicialização**, e somente enquanto a org ainda mantém sua identidade genérica recém-migrada, aplicado na inicialização e depois ignorado. Após renomear a org (`agenteye-orgctl org rename`), o novo nome é autoritativo e esta variável não tem mais efeito. | +| `DEFAULT_ORG_SLUG` | Não | `default` | Slug de URL para a org padrão integrada, o caminho do dashboard onde ela reside (`//…`). Mesma semântica de apenas na primeira inicialização / apenas quando em estado original que `DEFAULT_ORG_NAME`. Deve ter entre 1 e 40 caracteres alfanuméricos minúsculos com hífens internos simples e não ser uma [palavra reservada](#organizations-multi-tenancy); um valor inválido é ignorado (a org mantém `default`). Permite que uma instalação single-tenant se apresente como, por exemplo, `/acme` em vez de `/default` sem nenhuma etapa de CLI pós-deploy. | | `RUST_LOG` | Não | `info` | Verbosidade de log (`debug`, `warn`, `error`, `agenteye_server=trace`) | -| `EVALUATOR_ENDPOINT` | Não | none | URL base do seu serviço de avaliação (ex.: `http://evaluator:9000`). Quando não definido, todo o pipeline de avaliação é uma no-op; nenhuma linha de fila é escrita, nenhum worker é executado. Veja [Suite de Avaliação](/pt-br/agenteye/evaluation-suite). | -| `EVALUATOR_TOKEN` | Não | none | Enviado como `Authorization: Bearer ` ao avaliador. **Deve ser igual ao valor com o qual o serviço de avaliação está configurado.** Opcional somente se o seu avaliador estiver configurado sem token. | -| `EVALUATOR_WORKERS` | Não | `2` | Concorrência: número de tarefas de worker por instância do servidor que despacham avaliações. Seguro para executar em múltiplos servidores com escalonamento horizontal. | -| `EVALUATOR_CLAIM_BATCH` | Não | `4` | Número máximo de avaliações que um único worker reivindica por tick. Os lotes são despachados **concorrentemente**, portanto a concorrência total no seu endpoint de avaliação é `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | Não | `2` | Quanto tempo um worker dorme entre tentativas de despacho quando não há nada pendente. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | Não | `10` | Cadência de fallback final (segundos) para polls `GET /evaluate/{id}` quando o avaliador não retorna um `next_poll_secs` por resposta e não anuncia um `default_poll_interval_secs` via `GET /config`. | +| `EVALUATOR_ENDPOINT` | Não | nenhum | URL base do seu serviço avaliador (ex.: `http://evaluator:9000`). Quando não definido, todo o pipeline de avaliação é um no-op; nenhuma linha de fila é escrita, nenhum worker é executado. Veja [Suite de Avaliação](/pt-br/agenteye/evaluation-suite). | +| `EVALUATOR_TOKEN` | Não | nenhum | Enviado como `Authorization: Bearer ` para o avaliador. **Deve ser igual ao valor com o qual o serviço avaliador está configurado.** Opcional apenas se o seu avaliador estiver configurado sem token. | +| `EVALUATOR_WORKERS` | Não | `2` | Concorrência: número de tarefas worker por instância do servidor que despacham avaliações. Seguro para executar em vários servidores com escala horizontal. | +| `EVALUATOR_CLAIM_BATCH` | Não | `4` | Número máximo de avaliações que um único worker reivindica por tick. Os lotes são despachados **concorrentemente**, portanto a concorrência total no seu endpoint avaliador é `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | Não | `2` | Quanto tempo um worker dorme entre tentativas de despacho quando nada está pendente. | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Não | `10` | Cadência de fallback final (segundos) para polls `GET /evaluate/{id}` quando o avaliador não retorna um `next_poll_secs` por resposta e não anuncia um `default_poll_interval_secs` de `GET /config`. | | `EVALUATOR_REQUEST_TIMEOUT_MS` | Não | `30000` | Timeout por requisição HTTP contra o avaliador (milissegundos). | -| `EVALUATOR_MAX_ATTEMPTS` | Não | `5` | Após este número de tentativas falhas, uma avaliação é registrada como `error` terminal (ou `timeout` se as falhas foram timeouts de requisição). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | Não | `300` (5 min) | Com que frequência o servidor rebusca `GET /config` do avaliador. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Não | `3600` (1 h) | Tempo máximo de relógio que uma sessão pode permanecer na fila de polling antes do AgentEye encerrá-la com `timeout`. Protege contra um avaliador que retorna `pending` indefinidamente. | -| `ALERT_WORKERS` | Não | `1` | Concorrência: número de tarefas de worker por instância do servidor que avaliam regras de alerta. Veja [Alertas](/pt-br/agenteye/alerts). | +| `EVALUATOR_MAX_ATTEMPTS` | Não | `5` | Após esse número de tentativas com falha, uma avaliação é registrada como `error` terminal (ou `timeout` se as falhas foram timeouts de requisição). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | Não | `300` (5 min) | Com que frequência o servidor re-busca `GET /config` do avaliador. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Não | `3600` (1 h) | Tempo máximo de relógio de parede que uma sessão pode permanecer na fila de polling antes de o AgentEye encerrá-la como `timeout`. Protege contra um avaliador que retorna `pending` indefinidamente. | +| `ALERT_WORKERS` | Não | `1` | Concorrência: número de tarefas worker por instância do servidor que avaliam regras de alerta. Veja [Alertas](/pt-br/agenteye/alerts). | | `ALERT_CLAIM_BATCH` | Não | `16` | Número máximo de alertas que um único worker reivindica por tick. | | `ALERT_POLL_IDLE_SECS` | Não | `5` | Quanto tempo um worker de alertas dorme quando a fila está vazia. | -| `ALERT_REQUEST_TIMEOUT_MS` | Não | `15000` | Timeout por avaliação de trigger (queries do ClickHouse + HTTP do canal de saída). | +| `ALERT_REQUEST_TIMEOUT_MS` | Não | `15000` | Timeout de avaliação por disparo (consultas ClickHouse + HTTP de canal de saída). | | `ALERT_MAX_ATTEMPTS` | Não | `5` | Falhas transitórias consecutivas antes de um alerta ser reagendado em sua cadência normal em vez de backoff exponencial. | -| `AUDIT_WORKERS` | Não | `1` | Concorrência: número de tarefas de worker por instância do servidor que executam auditorias. Veja [Auditorias](/pt-br/agenteye/audits). | -| `AUDIT_CLAIM_BATCH` | Não | `1` | Número máximo de auditorias pendentes que um único worker reivindica por tick. Uma investigação agêntica é um loop longo, então o padrão é 1. | +| `AUDIT_WORKERS` | Não | `1` | Concorrência: número de tarefas worker por instância do servidor que executam auditorias. Veja [Auditorias](/pt-br/agenteye/audits). | +| `AUDIT_CLAIM_BATCH` | Não | `1` | Número máximo de auditorias pendentes que um único worker reivindica por tick. Uma investigação agêntica é um longo loop, então o padrão é 1. | | `AUDIT_POLL_IDLE_SECS` | Não | `30` | Quanto tempo um worker de auditorias dorme quando nenhuma auditoria está pendente. | -| `AUDIT_REQUEST_TIMEOUT_MS` | Não | `30000` | Timeout por query de política contra o ClickHouse (milissegundos). | -| `AUDIT_LLM_TIMEOUT_MS` | Não | `1440000` | Timeout para a chamada de investigação agêntica ao serviço de assistente de IA. Um loop de agente completo dura minutos; mantenha isso ACIMA do `AGENTEYE_AUDIT_TIMEOUT_MS` do próprio agente para que o agente retorne seus achados parciais antes de o servidor desistir. | +| `AUDIT_REQUEST_TIMEOUT_MS` | Não | `30000` | Timeout por consulta de política contra o ClickHouse (milissegundos). | +| `AUDIT_LLM_TIMEOUT_MS` | Não | `1440000` | Timeout para a chamada de investigação agêntica ao serviço de assistente de IA. Um loop de agente completo dura minutos; mantenha isso ACIMA do próprio `AGENTEYE_AUDIT_TIMEOUT_MS` do agente para que ele retorne seus resultados parciais antes de o servidor desistir. | | `AUDIT_MAX_ATTEMPTS` | Não | `5` | Falhas transitórias consecutivas antes de uma auditoria ser reagendada em sua cadência normal em vez de backoff exponencial. | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | Não | — | A investigação agêntica da auditoria chama o serviço `agent` de assistente de IA, **reutilizando a mesma conexão do assistente** — portanto defina esses dois também no **servidor** (os manifestos/compose incluídos no pacote já fazem isso). Ambos definidos ⇒ auditorias executam a investigação de IA; qualquer um não definido ⇒ auditorias executam **somente políticas** (o passo determinístico de política SQL ainda é executado), independentemente do flag `llm_enabled` por auditoria. O agente também deve ter um LLM configurado — veja [assistant.md](/pt-br/agenteye/assistant). | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | Não | — | A investigação agêntica da auditoria chama o serviço `agent` do assistente de IA, **reutilizando a mesma conexão do assistente** — portanto, defina esses dois no **servidor** também (os manifestos/compose incluídos fazem isso). Ambos definidos ⇒ as auditorias executam a investigação de IA; qualquer um não definido ⇒ as auditorias executam **somente política** (o passo de política SQL determinístico ainda é executado), independentemente da flag `llm_enabled` por auditoria. O agente também deve ter um LLM configurado — veja [assistant.md](/pt-br/agenteye/assistant). | -**Serviço de assistente de IA — configurações de auditoria + sandbox.** A investigação agêntica e seu sandbox Python no pod são ajustados no **serviço agent** (não no servidor), todos com o prefixo `AGENTEYE_AUDIT_*` e todos opcionais: +**Serviço de assistente de IA — configurações de auditoria + sandbox.** A investigação agêntica e seu sandbox Python no pod são ajustados no **serviço de agente** (não no servidor), todos com o prefixo `AGENTEYE_AUDIT_*` e todos opcionais: | Variável | Padrão | Significado | |---|---|---| | `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Máximo de turnos do agente por investigação. | -| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Tempo de relógio para uma investigação (20 min). Deve ficar **abaixo** do `AUDIT_LLM_TIMEOUT_MS` do servidor. | +| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Tempo de relógio de parede para uma investigação (20 min). Deve ficar **abaixo** do `AUDIT_LLM_TIMEOUT_MS` do servidor. | | `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Investigações simultâneas por pod de agente (separado do orçamento do assistente de chat). | | `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Limites por script para o sandbox bubblewrap. | -**Requisito de plataforma do Sandbox.** O sandbox de código da auditoria executa o Python do modelo dentro de um jail bubblewrap, que precisa de **namespaces de usuário sem privilégio**. O pod do agente deve permitir os flags `clone()` — defina `seccompProfile: Unconfined` (k8s) ou `security_opt: [seccomp:unconfined]` (compose) no agente. Onde o kernel do nó desabilita namespaces de usuário sem privilégio (ex.: algumas imagens GKE COS), o sandbox **falha no preflight e o auditor degrada automaticamente para somente SQL** — sem erro, apenas um `sandbox_available: false` no `/health` do agente. +**Requisito de plataforma do sandbox.** O sandbox de código de auditoria executa o Python do modelo dentro de uma jaula bubblewrap, que precisa de **namespaces de usuário sem privilégios**. O pod do agente deve permitir as flags `clone()` — defina `seccompProfile: Unconfined` (k8s) ou `security_opt: [seccomp:unconfined]` (compose) no agente. Onde o kernel do nó desabilita namespaces de usuário sem privilégios (ex.: algumas imagens GKE COS), o sandbox **falha no preflight e o auditor degrada automaticamente para somente SQL** — sem erro, apenas um `sandbox_available: false` no `/health` do agente. ### Executar -Defina `DATABASE_URL` e `CLICKHOUSE_URL` no seu ambiente (o servidor recusa o boot sem o ClickHouse), e então passe-os para o container: +Defina `DATABASE_URL` em seu ambiente e passe para o container: ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest ``` -O servidor executa as migrations do banco de dados automaticamente na inicialização; nenhuma etapa de migration separada é necessária. +O servidor executa as migrações de banco de dados automaticamente na inicialização; nenhuma etapa de migração separada é necessária. ### Health check ``` -GET /health # liveness - sempre {"status":"ok"} uma vez que o processo está em execução +GET /health # liveness - sempre {"status":"ok"} quando o processo está ativo GET /ready # readiness - 200 quando Postgres + ClickHouse estão acessíveis, caso contrário 503 ``` -Nenhuma autenticação necessária. Use `/health` para probes de **liveness** e `/ready` para probes de **readiness** / load balancer. `/ready` verifica as dependências obrigatórias sem as quais o servidor não consegue atender (Postgres + ClickHouse), então um servidor em execução que não consegue alcançar seu banco de dados é removido da rotação e aparece como `NotReady`; o Redis é reportado mas nunca falha o readiness. Nos manifestos Kubernetes incluídos no pacote, o probe de readiness já aponta para `/ready` e o liveness permanece em `/health`. Veja [enterprise-docs/health-monitoring.md](/pt-br/agenteye/health-monitoring) para o quadro completo, incluindo alertas opcionais para o Slack sobre falhas de pods Kubernetes-native. +Nenhuma autenticação necessária. Use `/health` para probes de **liveness** e `/ready` para probes de **readiness** / balanceador de carga. `/ready` verifica as dependências obrigatórias sem as quais o servidor não pode operar (Postgres + ClickHouse), portanto, um servidor em execução que não consegue alcançar seu banco de dados é retirado de rotação e exibido como `NotReady`; o Redis é reportado, mas nunca falha o readiness. Nos manifestos Kubernetes incluídos, a probe de readiness já aponta para `/ready` e o liveness permanece em `/health`. Veja [enterprise-docs/health-monitoring.md](/pt-br/agenteye/health-monitoring) para o quadro completo, incluindo alertas opcionais de falha de pod nativos do Kubernetes para o Slack. -### URL do magic link de email +### URL do magic link de e-mail -Os emails de login OTP contêm um botão **abrir o dashboard** com um toque. Ao clicar, o usuário vai para `/login?token=&email=
`; o dashboard troca esse par por uma sessão e redireciona para o aplicativo, sem reinserção manual do código. O servidor resolve a origem do dashboard usada para construir o link em três níveis: +Os e-mails de login OTP contêm um botão **abrir o dashboard** com um único toque. Ao clicar, o usuário é direcionado para `/login?token=&email=
`; o dashboard troca esse par por uma sessão e redireciona para o aplicativo, sem necessidade de inserir o código manualmente. O servidor resolve a origem do dashboard usada para construir o link em três níveis: -1. **Header `X-AgentEye-Dashboard-Url`**: definido automaticamente pelo proxy `/api/auth/otp/request` do dashboard a partir de sua própria origem pública. Em um deploy de mesma origem (servidor e dashboard compartilham um host atrás de um ingress que encaminha headers de proxy), **nenhuma configuração é necessária**. -2. **Variável de ambiente `DASHBOARD_URL`**: defina isso se seu dashboard está acessível em uma origem diferente daquela que o endpoint de requisição OTP do servidor vê (domínios separados `api.example.com` / `app.example.com`), ou se o seu ingress não propaga o host público para o pod do dashboard (para que `request.nextUrl.origin` não resolva para um bind wildcard como `0.0.0.0:3000`). Exemplo: `DASHBOARD_URL=https://app.example.com`. -3. **Padrão**: `https://app.befailproof.ai`, usado apenas se nenhum dos anteriores estiver presente. +1. **Header `X-AgentEye-Dashboard-Url`**: definido automaticamente pelo proxy `/api/auth/otp/request` do dashboard a partir de sua própria origem pública. Em um deploy no mesmo domínio (servidor e dashboard compartilham um host atrás de um único ingress que encaminha os headers do proxy), **nenhuma configuração é necessária**. +2. **Variável de ambiente `DASHBOARD_URL`**: defina isso se o seu dashboard estiver acessível em uma origem diferente daquela que o endpoint de requisição OTP do servidor vê (domínios separados `api.example.com` / `app.example.com`), ou se o seu ingress não propaga o host público para o pod do dashboard (para que `request.nextUrl.origin` não resolva para um endereço bind curinga como `0.0.0.0:3000`). Exemplo: `DASHBOARD_URL=https://app.example.com`. +3. **Padrão**: `https://app.befailproof.ai`, usado apenas se nenhum dos itens acima estiver presente. -O valor do header é validado: apenas origens `https://*` e loopback (`http://localhost*`, `http://127.0.0.1*`) são aceitas, e endereços de bind wildcard (`0.0.0.0`, `[::]`) são rejeitados mesmo com o esquema `https://`. Qualquer outra coisa passa para o nível 2. +O valor do header é validado: apenas origens `https://*` e loopback (`http://localhost*`, `http://127.0.0.1*`) são aceitos, e endereços bind curinga (`0.0.0.0`, `[::]`) são rejeitados mesmo com o esquema `https://`. Qualquer outra coisa passa para o nível 2. -Defina em um cluster em execução com um one-liner; sem arquivo, sem rebuild do kustomize: +Defina em um cluster em execução com um comando de uma linha; sem arquivo, sem rebuild do kustomize: ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -Isso aciona um rollout; os novos pods captam o valor na primeira requisição. Note que o override vive apenas no Deployment; um `kustomize build | kubectl apply` subsequente contra o overlay vai apagá-lo, a menos que você adicione a mesma variável de ambiente ao patch `server-env.yaml` do seu overlay. +Isso aciona um rollout; os novos pods capturam o valor na primeira requisição. Observe que a substituição reside apenas no Deployment; um `kustomize build | kubectl apply` subsequente contra o overlay irá apagá-la, a menos que você adicione a mesma variável de ambiente ao patch `server-env.yaml` do seu overlay. --- ## Dashboard -### Baixar a imagem +### Obtendo a imagem ```bash docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest @@ -167,14 +167,14 @@ docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest | Variável | Obrigatória | Padrão | Descrição | |---|---|---|---| -| `AGENTEYE_SERVER_URL` | Sim | none | URL base do servidor, ex.: `http://localhost:8080` | -| `AGENTEYE_API_KEY` | Sim | none | Chave de API que o dashboard usa para autenticar no servidor. Precisa de todas as permissões (chave admin recomendada). | -| `AE_LOG_LEVEL` | Não | `info` | Verbosidade de log no lado do servidor: `debug`, `info`, `warn`, `error`. Defina como `debug` para ver linhas de requisição/resposta upstream e traces de validação de sessão ao diagnosticar problemas. | -| `AE_LOG_JSON` | Não | automático | `1` força saída JSON por linha; `0` força saída legível por humanos. Quando não definido, JSON é habilitado automaticamente se `NODE_ENV=production`. JSON é recomendado em produção para que os logs sejam parseados facilmente com `jq` ou um agregador de logs. | -| `AE_ANALYTICS_DISABLED` | Não | none | Defina como `1`/`true` para desabilitar a telemetria anônima de uso do produto do dashboard. Veja [Telemetria e privacidade](#telemetry--privacy) abaixo. | -| `REDIS_URL` | Não | none | Backend de cache compartilhado opcional, ex.: `redis://redis:6379/0`. Quando definido, o dashboard cacheia resultados de `validateSession()` entre réplicas e compartilha o cache de fetch do Next.js para as rotas de proxy de latência-agregada / env-list. Os rate limits de requisição e verificação OTP no lado do edge também usam Redis quando presente (falha aberta se o Redis estiver inacessível; o limite no lado do servidor é o backstop de segurança). Veja **Redis (cache opcional)** abaixo. | -| `AGENTEYE_AGENT_URL` | Não | none | URL base do serviço `agent` de assistente de IA opcional, ex.: `http://agent:9100`. **Deixe não definido para ocultar o assistente completamente**: nenhuma bolha do assistente aparece no dashboard. Veja [enterprise-docs/assistant.md](/pt-br/agenteye/assistant). | -| `AGENTEYE_AGENT_TOKEN` | Não | none | Segredo compartilhado que o dashboard apresenta ao serviço `agent`. Deve corresponder ao `AGENTEYE_AGENT_TOKEN` configurado no agente. Veja [enterprise-docs/assistant.md](/pt-br/agenteye/assistant). | +| `AGENTEYE_SERVER_URL` | Sim | nenhum | URL base do servidor, ex.: `http://localhost:8080` | +| `AGENTEYE_API_KEY` | Sim | nenhum | Chave de API que o dashboard usa para se autenticar no servidor. Precisa de todas as permissões (chave admin recomendada). | +| `AE_LOG_LEVEL` | Não | `info` | Verbosidade de log do lado do servidor: `debug`, `info`, `warn`, `error`. Defina como `debug` para ver linhas de requisição/resposta upstream e rastreamentos de validação de sessão ao diagnosticar problemas. | +| `AE_LOG_JSON` | Não | automático | `1` força saída JSON por linha; `0` força saída legível por humanos. Quando não definido, o JSON é habilitado automaticamente se `NODE_ENV=production`. JSON é recomendado em produção para que os logs sejam analisados corretamente com `jq` ou um agregador de logs. | +| `AE_ANALYTICS_DISABLED` | Não | nenhum | Defina como `1`/`true` para desabilitar a telemetria anônima de uso de produto do dashboard. Veja [Telemetria e privacidade](#telemetry--privacy) abaixo. | +| `REDIS_URL` | Não | nenhum | Backend opcional de cache compartilhado, ex.: `redis://redis:6379/0`. Quando definido, o dashboard faz cache dos resultados de `validateSession()` entre réplicas e compartilha o cache de fetch do Next.js para as rotas proxy de latência-agregada / lista de ambientes. Os rate limits OTP de requisição e verificação do lado do edge também usam Redis quando disponível (falhando abertos se o Redis estiver inacessível; o limite do lado do servidor é a salvaguarda de segurança). Veja **Redis (cache opcional)** abaixo. | +| `AGENTEYE_AGENT_URL` | Não | nenhum | URL base do serviço `agent` do assistente de IA opcional, ex.: `http://agent:9100`. **Deixe não definido para ocultar o assistente completamente**: nenhuma bolha do assistente aparece no dashboard. Veja [enterprise-docs/assistant.md](/pt-br/agenteye/assistant). | +| `AGENTEYE_AGENT_TOKEN` | Não | nenhum | Segredo compartilhado que o dashboard apresenta ao serviço `agent`. Deve corresponder ao `AGENTEYE_AGENT_TOKEN` configurado no agente. Veja [enterprise-docs/assistant.md](/pt-br/agenteye/assistant). | ### Executar @@ -189,89 +189,89 @@ docker run -d --restart unless-stopped \ ### Telemetria e privacidade -O dashboard envia **analytics anônimos de uso do produto** para o serviço de analytics da Exosphere (PostHog): quais páginas do dashboard são visitadas e algumas ações de UI, como criar uma chave de API ou reavaliar uma sessão. Esse sinal de uso informa quais funcionalidades são priorizadas. +O dashboard envia **análises anônimas de uso de produto** para o serviço de análise da Exosphere (PostHog): quais páginas do dashboard são visualizadas e um conjunto de ações de interface como criar uma chave de API ou reavaliar uma sessão. Esse sinal de uso informa quais funcionalidades são priorizadas. -- **Nenhum dado de agente, sessão ou evento jamais sai da sua infraestrutura.** Apenas o uso da UI do dashboard é reportado. As URLs de páginas são despidas de identificadores antes do envio, e os operadores são identificados apenas por um id interno opaco, nunca por email. +- **Nenhum dado de agente, sessão ou evento sai da sua infraestrutura.** Apenas o uso da interface do dashboard é reportado. As URLs de página são removidas de identificadores antes do envio, e os operadores são identificados apenas por um id interno opaco, nunca por e-mail. - A telemetria está **habilitada por padrão**. Para desativá-la completamente, defina `AE_ANALYTICS_DISABLED=1` no container do dashboard e reinicie. -- Os analytics são enviados para o próprio caminho `/ingest` do dashboard, que o dashboard faz proxy reverso para o PostHog (`https://us.i.posthog.com`). Manter as requisições como first-party significa que bloqueadores de anúncio do navegador não as descartam. O **container do dashboard** precisa de acesso de saída para o PostHog; se estiver bloqueado, a telemetria silenciosamente não faz nada e o dashboard não é afetado. +- As análises são enviadas para o próprio caminho `/ingest` do dashboard, que o dashboard faz proxy reverso para o PostHog (`https://us.i.posthog.com`). Manter as requisições como first-party significa que bloqueadores de anúncios do navegador não as descartam. O **container do dashboard** precisa de acesso de saída para o PostHog; se estiver bloqueado, a telemetria silenciosamente não faz nada e o dashboard não é afetado. --- ## Assistente de IA (opcional) -Um assistente de IA integrado ao dashboard permite que sua equipe faça perguntas sobre os dados dos agentes em linguagem natural (resumindo sessões, redigindo SQL para o editor `/queries` e transformando queries salvas em tiles do dashboard) sem sair do dashboard. Ele roda como um container interno separado `agent` (no Claude Agents SDK) que apenas o dashboard consegue alcançar, e permanece **desabilitado até você configurar um endpoint de LLM**. +Um assistente de IA integrado ao dashboard permite que sua equipe faça perguntas sobre os dados do agente em linguagem natural (resumindo sessões, redigindo SQL para o editor `/queries` e transformando consultas salvas em tiles do dashboard) sem sair do dashboard. Ele é executado como um container `agent` interno separado (no Agents SDK) que somente o dashboard pode alcançar, e permanece **desabilitado até que você configure um endpoint de LLM**. -Para habilitá-lo, você define no serviço `agent` uma conexão de LLM (**Portkey** via `PORTKEY_API_KEY` + um slug do catálogo de modelos `AGENTEYE_AGENT_MODEL=@/`, Anthropic direto via `ANTHROPIC_API_KEY`, outro gateway via `ANTHROPIC_BASE_URL`, ou Bedrock/Vertex), uma chave de dados **dedicada** e um `AGENTEYE_AGENT_TOKEN` compartilhado correspondente ao dashboard. Os usuários do dashboard também precisam da permissão `agent:use`. +Para habilitá-lo, você define no serviço `agent` uma conexão de LLM (**Portkey** via `PORTKEY_API_KEY` + um slug de catálogo de modelos `AGENTEYE_AGENT_MODEL=@/`, Anthropic direto via `ANTHROPIC_API_KEY`, outro gateway via `ANTHROPIC_BASE_URL`, ou Bedrock/Vertex), uma chave de dados **dedicada** e um `AGENTEYE_AGENT_TOKEN` compartilhado correspondente ao dashboard. Os usuários do dashboard também precisam da permissão `agent:use`. -Para a chave de dados do assistente, você não precisa criar nada manualmente: escolha um segredo aleatório, defina-o como `AGENTEYE_API_KEY` no `agent` **e** como `AGENT_API_KEY` no `server`, e o servidor o alimenta na inicialização com um conjunto fixo de permissões. Seu acesso a dados é somente leitura (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), e adicionalmente possui escopos de autoria com aprovação (`dashboards:write`, `queries:write`, `queries:run`) para que ele possa redigir e validar queries salvas e construir tiles do dashboard em nome do usuário; todo SQL ainda é executado pelo papel ClickHouse somente leitura da org, portanto isso amplia o que o assistente pode criar, não os dados que pode acessar. Os escopos são fixos no código e não podem ser ampliados por configuração. Essa chave é protegida; não pode ser desabilitada ou regenerada via API, apenas rotacionada alterando o valor e reiniciando. Nunca reutilize a chave admin/dashboard para isso. +Para a chave de dados do assistente, você não cria nada manualmente: escolha um segredo aleatório, defina-o como `AGENTEYE_API_KEY` no `agent` **e** como `AGENT_API_KEY` no `server`, e o servidor o inicializa com um conjunto fixo de permissões na inicialização. Seu acesso aos dados é somente leitura (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), e ele adicionalmente possui escopos de autoria com aprovação (`dashboards:write`, `queries:write`, `queries:run`) para que possa redigir e validar consultas salvas e criar tiles de dashboard em nome do usuário; todo SQL ainda é executado pelo role ClickHouse somente leitura da org, portanto isso amplia o que o assistente pode criar, não os dados que ele pode acessar. Os escopos são fixos no código e não podem ser ampliados por configuração. Essa chave é protegida; não pode ser desabilitada ou regenerada via API, apenas rotacionada alterando o valor e reiniciando. Nunca reutilize a chave admin/dashboard para isso. -A configuração completa, a referência completa de variáveis de ambiente, opções de telemetria e o modelo de segurança estão em **[enterprise-docs/assistant.md](/pt-br/agenteye/assistant)**. +A configuração completa, a referência completa de variáveis de ambiente, as opções de telemetria e o modelo de segurança estão em **[enterprise-docs/assistant.md](/pt-br/agenteye/assistant)**. --- -## ClickHouse (armazenamento de analytics obrigatório) +## ClickHouse (armazenamento analítico obrigatório) -O ClickHouse mantém seus dashboards responsivos em altos volumes de eventos e permite que o editor SQL `/queries` faça joins entre eventos, avaliações e sessões em um único armazenamento. É o armazenamento canônico obrigatório para cada evento ingerido, cada resultado de avaliação terminal e os agregados derivados por sessão. O PostgreSQL mantém as tabelas relacionais/de estado mutável (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); a superfície analítica vive no ClickHouse para que os rollups do dashboard e suas próprias queries SQL possam escanear e fazer joins nativamente, sem round-trips entre bancos de dados. O servidor recusa o boot sem `CLICKHOUSE_URL`. +O ClickHouse mantém seus dashboards responsivos em altos volumes de eventos e permite que o editor SQL `/queries` faça joins entre eventos, avaliações e sessões em um único armazenamento. É o armazenamento canônico obrigatório para cada evento ingerido, cada resultado de avaliação terminal e os agregados derivados por sessão. O PostgreSQL mantém as tabelas relacionais/de estado mutável (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); a camada analítica reside no ClickHouse para que os rollups do dashboard e suas próprias consultas SQL possam escaneá-la e fazer joins nativamente, sem round-trips entre bancos de dados. O servidor se recusa a iniciar sem `CLICKHOUSE_URL`. ### Schema Três objetos ClickHouse são criados na inicialização do servidor, todos idempotentes (`CREATE IF NOT EXISTS`): -- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, particionado por `toYYYYMM(ts)`, ordenado por `(session_id, ts, dedup_key)`. Inserções duplicadas (retentativas do collector) colapsam para uma única linha no momento do merge; o servidor calcula um `dedup_key` SHA-256 determinístico para cada evento, tornando as retentativas seguras. -- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, particionado por `toYYYYMM(finished_at)`, ordenado por `(session_id, finished_at, dedup_key)`. Escrito uma vez por resultado de avaliação terminal pelo pipeline de avaliação. Mesmo modelo de dedup-key que `events`. +- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, particionado por `toYYYYMM(ts)`, ordenado por `(session_id, ts, dedup_key)`. Inserções duplicadas (retentativas do collector) colapsam para uma única linha no momento do merge; o servidor computa um `dedup_key` SHA-256 determinístico para cada evento, tornando as retentativas seguras. +- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, particionado por `toYYYYMM(finished_at)`, ordenado por `(session_id, finished_at, dedup_key)`. Escrito uma vez por resultado de avaliação terminal pelo pipeline do avaliador. Mesmo modelo de dedup-key que `events`. - **`agenteye.agent_sessions`**: uma **VIEW** sobre `agenteye.events`, não uma tabela física. Cada coluna é derivada (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, etc.). Sem upsert por evento e sem backfill separado; a view reflete automaticamente o que estiver em `events`. -Para compatibilidade retroativa com queries salvas que referenciam `analytics.evaluations` / `analytics.sessions`, o servidor também cria um banco de dados ClickHouse `analytics` com views sobre as tabelas `agenteye.*`; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` resolvem corretamente. +Para compatibilidade retroativa com consultas salvas que referenciam `analytics.evaluations` / `analytics.sessions`, o servidor também cria um banco de dados `analytics` no ClickHouse com views sobre as tabelas `agenteye.*`; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` resolvem corretamente. ### Configuração -O docker-compose incluso e `deploy/base/clickhouse/` trazem um serviço ClickHouse ajustado para a carga de trabalho do AgentEye: +O docker-compose incluído e `deploy/base/clickhouse/` trazem um serviço ClickHouse ajustado para a carga de trabalho do AgentEye: -- 2 GiB solicitados / 4 GiB limite de memória no overlay base incluso (dimensionado para nós pequenos de POC/staging); clientes de produção devem aumentar o overlay — o piso recomendado é 2c / 4Gi request, 6c / 8Gi limit. `max_server_memory_usage_to_ram_ratio=0.9` -- 5 GiB mark cache + 8 GiB uncompressed cache +- 2 GiB solicitado / 4 GiB limite de memória no overlay base incluído (dimensionado para caber em nós pequenos de POC/staging); clientes de produção devem aumentar — o mínimo recomendado é 2c / 4Gi de request, 6c / 8Gi de limit. `max_server_memory_usage_to_ram_ratio=0.9` +- 5 GiB de mark cache + 8 GiB de uncompressed cache - `background_pool_size=16`, `background_merges_mutations_concurrency_ratio=2` - MergeTree: `parts_to_throw_insert=3000`, `parts_to_delay_insert=1500`, `non_replicated_deduplication_window=1000` - `local_io_method=auto` (io_uring em kernels suportados) -- `fsync_metadata=0`: aceitável por causa da ingestão pelo menos uma vez + dedup do ReplacingMergeTree -- `query_log` habilitado com TTL de 30 dias; `query_thread_log` removido (caro em QPS alto) -- `max_execution_time=30` para queries do lado do usuário -- PVC de 100 GiB no template StatefulSet (os overlays do cliente DEVEM sobrescrever para uma classe de armazenamento SSD rápida em produção) +- `fsync_metadata=0`: aceitável devido à ingestão at-least-once + dedup ReplacingMergeTree +- `query_log` habilitado com TTL de 30 dias; `query_thread_log` removido (caro em alto QPS) +- `max_execution_time=30` para consultas do usuário +- PVC de 100 GiB no template StatefulSet (os overlays do cliente DEVEM substituir por uma storage class SSD rápida para produção) ### Backups -Seu conjunto de dados completo é capturado nightly em um único arquivo restaurável, então uma perda de cluster ou armazenamento é recuperável. O ClickHouse é feito backup automaticamente pelo CronJob diário `agenteye-backup`, que despeja tanto o PostgreSQL quanto o ClickHouse em uma única passagem. O ClickHouse é lido via sua API HTTP: `agenteye.events` e `agenteye.evaluations` são despejados no formato nativo do ClickHouse (as views e row policies são recriadas pelo servidor na inicialização, então os dados da tabela são o quadro completo) e empacotados com o dump do Postgres em um único arquivo comprimido enviado para o seu armazenamento de objetos. +Seu conjunto de dados completo é capturado diariamente em um único arquivo restaurável, portanto uma perda de cluster ou armazenamento é recuperável. O ClickHouse tem backup automático feito pelo CronJob `agenteye-backup` diário, que faz dump do PostgreSQL e do ClickHouse em uma única passagem. O ClickHouse é lido pela sua API HTTP: `agenteye.events` e `agenteye.evaluations` são dumpados no formato nativo do ClickHouse (as views e row policies são recriadas pelo servidor na inicialização, portanto os dados da tabela são o quadro completo) e empacotados com o dump do Postgres em um único arquivo comprimido enviado para o seu armazenamento de objetos. -O bucket de destino e as credenciais de nuvem são configurados por overlay. Veja a seção **Backups** de [enterprise-docs/kubernetes-deployment.md](/pt-br/agenteye/kubernetes-deployment) para configuração de upload e passos de restauração. +O bucket de destino e as credenciais de nuvem são configurados por overlay. Veja a seção **Backups** de [enterprise-docs/kubernetes-deployment.md](/pt-br/agenteye/kubernetes-deployment) para configuração de upload e etapas de restauração. --- ## Redis (cache opcional) -O Redis é um cache compartilhado **opcional** + backend de rate limiting usado pelo servidor e pelo dashboard. Com o Redis implantado e `REDIS_URL` definido em ambos os serviços: +O Redis é um backend **opcional** de cache compartilhado + rate limit usado pelo servidor e pelo dashboard. Com o Redis implantado e `REDIS_URL` definido em ambos os serviços: -- **Servidor** cacheia lookups de API key autenticados, as listas `/events/environments` + `/evaluations/environments`, o rollup `/events/latency_aggregate` (a query mais pesada que o dashboard faz poll), a lista `/sessions`, e troca o rate limiting de requisição OTP de um `COUNT(*)` do Postgres por um `INCR + EXPIRE` do Redis. -- **Dashboard** cacheia resultados de `validateSession()` para que as 10-20 chamadas de API autenticadas que um carregamento de página típico faz compartilhem uma única verificação de sessão upstream. Também faz rate limiting de requisição e verificação OTP no edge do dashboard. +- **Servidor** faz cache de lookups de API keys autenticadas, as listas `/events/environments` + `/evaluations/environments`, o rollup `/events/latency_aggregate` (a consulta mais pesada que o dashboard realiza periodicamente), a lista `/sessions`, e troca o rate limiting de requisições OTP de um `COUNT(*)` Postgres para um `INCR + EXPIRE` Redis. +- **Dashboard** faz cache dos resultados de `validateSession()` para que as 10-20 chamadas de API autenticadas que um carregamento de página típico realiza compartilhem uma única verificação de sessão upstream. Também aplica rate limit nas requisições OTP e na verificação OTP na borda do dashboard. -**Ambos os serviços degradam de forma elegante se o Redis estiver inacessível.** Cada chamada de cache retorna `Err` dentro de um timeout limitado e o chamador recai para a fonte de verdade (Postgres no servidor, o servidor Rust upstream no dashboard). O rate limiting OTP recai para o caminho `COUNT(*)` do Postgres no servidor (a propriedade de segurança é preservada); o limite OTP de edge do dashboard falha aberto enquanto o limite do lado do servidor ainda é mantido. O Redis fora do ar degrada a latência, não a correção. +**Ambos os serviços degradam graciosamente se o Redis estiver inacessível.** Cada chamada de cache retorna `Err` dentro de um timeout limitado e o chamador recai para a fonte da verdade (Postgres no servidor, o servidor Rust upstream no dashboard). O rate limiting OTP recai para o caminho `COUNT(*)` do Postgres no servidor (a propriedade de segurança é preservada); o limite OTP de borda do dashboard falha aberto enquanto o limite do lado do servidor ainda vale. O Redis fora do ar degrada a latência, não a correção. ### Configuração O pacote docker-compose já inclui um serviço Redis e conecta `REDIS_URL=redis://redis:6379/0` ao servidor e ao dashboard. Para usar um Redis externo, defina `REDIS_URL` para o seu endpoint e remova o serviço `redis` do arquivo compose. -### Memória + persistência +### Memória e persistência -A imagem Redis inclusa no pacote executa com `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. A persistência AOF significa que o cache sobrevive a reinicializações do container; `everysec` é o equilíbrio certo de durabilidade/performance porque perder o último segundo de writes de cache é inofensivo. A evicção LRU limita o crescimento de memória. +A imagem Redis incluída é executada com `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. A persistência AOF significa que o cache sobrevive a reinicializações do container; `everysec` é o equilíbrio certo entre durabilidade e desempenho, pois perder o último segundo de escritas de cache é inofensivo. A evicção LRU limita o crescimento da memória. ### Quando NÃO implantar o Redis -- Dev/QA de instância única. Os caches em processo no servidor por si só entregam a maior parte do benefício por réplica; o Redis adiciona o compartilhamento entre réplicas que setups de instância única não precisam. +- Dev/QA de instância única. Os caches em processo no servidor sozinho entregam a maior parte do benefício por réplica; o Redis adiciona o compartilhamento entre réplicas que as configurações de instância única não precisam. - Instalações air-gapped onde o custo operacional de executar mais um serviço supera o ganho de latência. --- ## Docker Compose (recomendado) -Um `docker-compose.yml` está disponível no repositório `agenteye-enterprise/releases`. Ele sobe o Postgres, ClickHouse, Redis, o servidor e o dashboard com um único comando. +Um `docker-compose.yml` está disponível no repositório `agenteye-enterprise/releases`. Ele inicializa o Postgres, o servidor e o dashboard com um único comando. ```bash GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ @@ -281,10 +281,10 @@ GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ cd agenteye ``` -**Sobrescreva os padrões via `.env`:** +**Substitua os padrões via `.env`:** ``` -# Use senhas seguras para URL (sem os caracteres /, +, ou =). +# Use senhas seguras para URL (sem caracteres /, + ou =). # Gere com: openssl rand -hex 24 POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret @@ -293,7 +293,7 @@ ADMIN_KEY=your-admin-secret ADMIN_EMAIL=admin@yourcompany.com ALLOWED_EMAILS=*@yourcompany.com -# SMTP para emails OTP (omita para registrar códigos OTP no stdout) +# SMTP para e-mails OTP (omita para registrar códigos OTP no stdout) # SMTP_HOST=smtp.yourprovider.com # SMTP_PORT=587 # SMTP_USERNAME=your-smtp-user @@ -323,25 +323,25 @@ docker compose down -v ## Configurações operacionais -Um pequeno conjunto de parâmetros operacionais que antes eram fixados por variáveis de ambiente agora são editáveis por organização na página **`//settings`** do dashboard; cada org configura os seus próprios. As alterações entram em vigor em segundos, sem restart e sem redeploy. +Um pequeno conjunto de ajustes operacionais que costumavam ser fixados por variáveis de ambiente agora é editável por organização na página **`//settings`** do dashboard; cada org configura a sua própria. As alterações entram em vigor em segundos, sem reinicialização e sem redeploy. -| Configuração | Variável de ambiente de bootstrap | O que controla | +| Configuração | Variável de ambiente inicial | O que controla | |---|---|---| -| Logins permitidos | `ALLOWED_EMAILS` | Emails (ou wildcards `*@dominio.com`) autorizados a receber um OTP e serem adicionados como usuários | -| Permissões padrão do usuário | `DEFAULT_USER_PERMISSIONS` | Tokens de permissão separados por vírgula pré-selecionados quando um admin abre **+ novo usuário**. Cada token deve ser uma das strings listadas em [Permissões de chave de API](/pt-br/agenteye/api-keys). Padrão para o preset `standard`: acesso somente leitura mais as ações cotidianas de plantão (disparar reavaliações, executar queries, confirmar incidentes, usar o assistente). | -| Tempo de vida da sessão | `SESSION_TTL_SECS` | Por quanto tempo um login no dashboard permanece válido antes de reautenticação. O dashboard reverifica a sessão upstream a cada 5 segundos, então uma atualização de permissão em `//users` entra em vigor na próxima requisição do usuário afetado, sem necessidade de novo login. | -| Tempo de vida do código único | `OTP_TTL_SECS` | Por quanto tempo um OTP / magic-link permanece utilizável | -| Canais de notificação de alertas | `ALERTS_ENABLED_CHANNELS` | Lista separada por vírgulas de tipos de canal que o despachante de alertas pode usar: `email`, `slack`, `webhook`. A configuração por alerta ainda é feita em `//alerts/`, mas o despachante filtra cada entrega de saída por este conjunto; um canal desabilitado aqui é curto-circuitado com uma linha de auditoria `skipped_disabled`. O canal `dashboard` (o insert de auditoria local) é sempre permitido. Padrão para os três habilitados. | +| Logins permitidos | `ALLOWED_EMAILS` | E-mails (ou curingas `*@domain.com`) com permissão para receber um OTP e ser adicionados como usuários | +| Permissões padrão do usuário | `DEFAULT_USER_PERMISSIONS` | Tokens de permissão separados por vírgula pré-selecionados quando um admin abre **+ novo usuário**. Cada token deve ser uma das strings listadas em [Permissões de chave de API](/pt-br/agenteye/api-keys). O padrão é o preset `standard`: acesso somente leitura mais as ações cotidianas de plantão (acionar reavaliações, executar consultas, reconhecer incidentes, usar o assistente). | +| Tempo de vida da sessão | `SESSION_TTL_SECS` | Por quanto tempo um login no dashboard permanece válido antes de nova autenticação. O dashboard re-verifica a sessão upstream a cada 5 segundos, portanto uma atualização de permissão em `//users` entra em vigor na próxima requisição do usuário afetado, sem novo login. | +| Tempo de vida do código único | `OTP_TTL_SECS` | Por quanto tempo um OTP / magic link permanece utilizável | +| Canais de notificação de alerta | `ALERTS_ENABLED_CHANNELS` | Lista separada por vírgula de tipos de canais que o dispatcher de alertas tem permissão para usar: `email`, `slack`, `webhook`. A configuração por alerta ainda é criada em `//alerts/`, mas o dispatcher filtra cada entrega de saída por esse conjunto; um canal desabilitado aqui curto-circuita com uma linha de auditoria `skipped_disabled`. O canal `dashboard` (a inserção de auditoria local) é sempre permitido. O padrão é todos os três habilitados. | ### Como o bootstrap funciona -As configurações são armazenadas por organização em `org_settings`. No primeiro boot, o servidor alimenta as linhas ausentes da org padrão a partir da variável de ambiente correspondente (ou um padrão sensato se a variável não estiver definida). Depois disso, **o valor armazenado é a fonte de verdade e a variável de ambiente é ignorada**; alterar a variável de ambiente em um restart posterior não afetará o valor de uma org em produção, e orgs adicionais iniciam com padrões e configuram os seus próprios. +As configurações são armazenadas por organização em `org_settings`. Na primeira inicialização, o servidor alimenta as linhas ausentes da org padrão a partir da variável de ambiente correspondente (ou um padrão razoável se a variável não estiver definida). Após isso, **o valor armazenado é a fonte da verdade e a variável de ambiente é ignorada**; alterar a variável de ambiente em uma reinicialização posterior não afetará o valor de uma org em funcionamento, e orgs adicionais começam com os padrões e configuram as suas próprias. -Isso significa que: +Isso significa: -- Para um deploy novo, defina as variáveis de ambiente como mostrado acima e a org padrão as lerá no primeiro boot. -- Para alterar um valor posteriormente, faça login no dashboard e edite em `//settings`. A alteração é aplicada em segundos em todas as réplicas do servidor; nenhum restart é necessário. -- Uma linha de log na inicialização registra o que foi alimentado vs. o que já estava presente, para que você possa confirmar que o bootstrap teve efeito: +- Para um deploy novo, defina as variáveis de ambiente conforme mostrado acima e a org padrão as lerá na primeira inicialização. +- Para alterar um valor posteriormente, faça login no dashboard e edite em `//settings`. A alteração se aplica em segundos em todas as réplicas do servidor; sem reinicialização necessária. +- Uma linha de log na inicialização registra o que foi alimentado versus o que já estava presente, para que você possa confirmar que o bootstrap teve efeito: ```text INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true @@ -349,10 +349,10 @@ Isso significa que: #### Semântica de login entre organizações -Uma sessão e um OTP são globais para o usuário, não para uma única org, então duas regras reconciliam as configurações por org no momento do login: +Uma sessão e um OTP são globais para o usuário, não para uma única org, portanto duas regras reconciliam as configurações por org no momento do login: -- **Tempo de vida da sessão / OTP**: o tempo de vida mais restritivo (mais curto) entre as orgs às quais o usuário pertence prevalece. -- **Logins permitidos**: a porta faz OR de cada allowlist de org com a associação de org: um usuário pode solicitar um OTP se a allowlist de qualquer org admitir seu email **ou** ele já for membro de qualquer org. +- **Tempo de vida da sessão / OTP**: o mais restritivo (mais curto) entre as orgs às quais o usuário pertence prevalece. +- **Logins permitidos**: a verificação faz OR de todas as listas de permissão de cada org com a associação à org: um usuário pode solicitar um OTP se a lista de permissão de qualquer org admitir seu e-mail **ou** ele já for membro de qualquer org. ### Permissões @@ -361,41 +361,41 @@ O acesso a uma página `//settings` é controlado por duas permissões: - `settings:read`: ver a página e os valores atuais. - `settings:write`: salvar alterações. -O usuário admin de bootstrap (alimentado a partir de `ADMIN_EMAIL`) recebe ambas automaticamente junto com todas as outras permissões. Conceda-as a outros usuários a partir de `//users` conforme necessário. +O usuário admin inicial (alimentado de `ADMIN_EMAIL`) recebe ambas automaticamente, junto com todas as outras permissões. Conceda-as a outros usuários em `//users` conforme necessário. --- ## Organizações (multi-tenancy) -Um único deployment pode servir múltiplas **organizações** (tenants) isoladas; cada linha de dados pertence exatamente a uma org e o isolamento é imposto no engine do banco de dados. Uma instalação single-tenant não precisa de nada aqui; todos os dados vivem em uma org `default` integrada. (Você pode dar a essa org um nome mais amigável e slug de URL, para que ela viva em ex. `/acme` em vez de `/default`, definindo `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` antes do primeiro boot, ou renomeando-a a qualquer momento com `agenteye-orgctl org rename`.) +Um único deploy pode servir múltiplas **organizações** (tenants) isoladas; cada linha de dados pertence a exatamente uma org e o isolamento é imposto no engine do banco de dados. Uma instalação single-tenant não precisa de nada aqui; todos os dados residem em uma org `default` integrada. (Você pode dar a essa org um nome mais amigável e slug de URL, para que ela fique em, por exemplo, `/acme` em vez de `/default`, definindo `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` antes da primeira inicialização, ou renomeando-a a qualquer momento com `agenteye-orgctl org rename`.) -**O provisionamento de tenants é exclusivo do operador.** Organizações e suas associações são criadas e gerenciadas com o CLI **`agenteye-orgctl`**, que é distribuído **dentro da imagem do servidor** (ao lado de `agenteye-server`) e executa **dentro do pod do servidor existente**; não há **pod/Job separado, sem API HTTP e sem botão no dashboard**. Ele reutiliza `DATABASE_URL`, `CLICKHOUSE_URL` e `ORG_CH_SECRET` do servidor. +**O provisionamento de tenants é exclusivo do operador.** Organizações e suas associações são criadas e gerenciadas com o CLI **`agenteye-orgctl`**, que vem **dentro da imagem do servidor** (ao lado de `agenteye-server`) e é executado **dentro do pod do servidor existente**; **não há pod/Job separado, sem API HTTP e sem botão no dashboard**. Ele reutiliza o `DATABASE_URL`, `CLICKHOUSE_URL` e `ORG_CH_SECRET` do servidor. ```bash -# Docker Compose - exec no serviço servidor em execução: +# Docker Compose - exec no serviço do servidor em execução: docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp" docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin -# Kubernetes - exec no Deployment servidor em execução: +# Kubernetes - exec no Deployment do servidor em execução: kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list ``` Verbos disponíveis: `org create | list | rename | delete | purge` e `member add | list | update | remove`, com conjuntos de permissões integrados `admin`, `standard` e `read-only`. Membros adicionados recebem um OTP no primeiro login no dashboard. -**Antes de criar uma segunda org:** defina um `ORG_CH_SECRET` forte e estável (o comando `org create` recusa executar com o padrão de dev interno) e garanta que o Postgres seja **15+**. **Sem alteração:** chaves de API por org ainda são criadas no dashboard/API por membros da org; apenas o ciclo de vida de org + membro foi movido para o CLI. Referência completa de comandos e um exemplo prático: **[enterprise-docs/tenant-management.md](/pt-br/agenteye/tenant-management)**. +**Antes de criar uma segunda org:** defina um `ORG_CH_SECRET` forte e estável (o comando `org create` se recusa a executar com o padrão de desenvolvimento interno) e certifique-se de que o Postgres seja **15+**. **Inalterado:** chaves de API por org ainda são criadas no dashboard/API por membros da org; apenas o ciclo de vida da org + membro foi movido para o CLI. Referência completa de comandos e um exemplo prático: **[enterprise-docs/tenant-management.md](/pt-br/agenteye/tenant-management)**. --- -## Preenchimento da janela de contexto +## Preenchimento de janela de contexto -Cada evento `model_response` mostra um **indicador de preenchimento de contexto** — tokens de entrada mais saída como percentagem da janela de contexto daquele modelo. As faixas são `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%) e `reset context` (75–100%). O AgentEye resolve IDs de modelos comuns automaticamente, portanto nenhuma configuração inicial é necessária. +Cada evento `model_response` exibe uma **pílula de context-fill** — tokens de entrada mais saída como percentual da janela de contexto desse modelo. As faixas são `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%) e `reset context` (75–100%). O AgentEye resolve IDs de modelos comuns automaticamente, portanto nenhuma configuração inicial é necessária. -Cada modelo que uma organização envia aparece em **Configurações → janelas de contexto de modelos**. Usuários com `settings:write` podem sobrescrever sua janela ou adicionar um modelo privado/proxy (0–1.000.000 tokens); `0` significa "desconhecido" e suprime o indicador. As alterações se aplicam a eventos recém-ingeridos. Usuários com `settings:read` podem visualizar a lista. +Cada modelo que uma organização envia aparece em **Configurações → janelas de contexto de modelos**. Usuários com `settings:write` podem substituir sua janela ou adicionar um modelo privado/proxy (0–1.000.000 tokens); `0` significa "desconhecido" e suprime a pílula. As alterações se aplicam a eventos recém-ingeridos. Usuários com `settings:read` podem visualizar a lista. -Novos eventos recebem o preenchimento a partir do momento em que você atualiza. Para também popular eventos **históricos** (e a lista por modelo) para um deployment existente, execute o backfill único — ele é distribuído dentro da imagem do servidor (como `agenteye-orgctl`) e executa no pod do servidor existente: +Novos eventos recebem o preenchimento a partir do momento em que você atualiza. Para também popular eventos **históricos** (e a lista por modelo) em um deploy existente, execute o backfill único — ele vem dentro da imagem do servidor (como `agenteye-orgctl`) e é executado no pod do servidor existente: ```bash -# preview (imprime a mutação por org, não altera nada): +# prévia (imprime a mutação por org, não altera nada): kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window --dry-run # aplicar: kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window @@ -403,25 +403,25 @@ kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window docker compose exec server agenteye-backfill-context-window ``` -É idempotente (seguro para re-executar) e reutiliza `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` do pod. Execute novamente após editar janelas de modelos se quiser que os eventos existentes sejam recomputados. +É idempotente (seguro para re-executar) e reutiliza `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` do pod. Re-execute-o após editar as janelas de modelos se quiser que os eventos existentes sejam recomputados. --- -## Considerações para produção +## Considerações de produção - **Postgres**: Use um serviço Postgres gerenciado ou uma instância dedicada com backups regulares. O `DATABASE_URL` suporta todos os parâmetros libpq padrão, incluindo `sslmode=require` para conexões criptografadas. -- **TLS**: Coloque o servidor e o dashboard atrás de um proxy reverso (nginx, Caddy, Traefik) que encerra o TLS. -- **Firewall**: A porta do servidor (padrão 8080) deve ser acessível apenas pelas máquinas do collector e pelo host do dashboard, não pela internet pública. -- **Chave admin**: Defina `ADMIN_KEY` como um segredo aleatório forte. Após o bootstrap, crie chaves com escopos dedicados para collectors e o dashboard em vez de usar a chave admin em todo lugar. -- **Tags de imagem**: Fixe na versão nos seus manifestos de release (por exemplo, `server:v0.0.1-beta.48`) em produção em vez de uma tag flutuante para evitar atualizações não intencionais. As builds beta atuais são publicadas sob `beta-latest`; `latest` é atribuído apenas a releases estáveis. -- **Monitoramento de saúde**: No Kubernetes, o probe de readiness usa `/ready` (acessibilidade do Postgres + ClickHouse) enquanto o liveness permanece em `/health`. Para alertas de toda a frota sobre "o AgentEye está funcionando?" para o Slack, habilite o add-on Robusta opcional; veja [enterprise-docs/health-monitoring.md](/pt-br/agenteye/health-monitoring). +- **TLS**: Coloque o servidor e o dashboard atrás de um proxy reverso (nginx, Caddy, Traefik) que encerre o TLS. +- **Firewall**: A porta do servidor (padrão 8080) deve ser acessível apenas a partir das máquinas do collector e do host do dashboard, não da internet pública. +- **Chave admin**: Defina `ADMIN_KEY` como um segredo aleatório forte. Após o bootstrap, crie chaves com escopo dedicado para collectors e o dashboard em vez de usar a chave admin em todo lugar. +- **Tags de imagem**: Fixe na versão nos manifestos de release (por exemplo, `server:v0.0.1-beta.48`) em produção, em vez de uma tag flutuante, para evitar upgrades não intencionais. As builds beta atuais são publicadas sob `beta-latest`; `latest` é atribuído apenas a releases estáveis. +- **Monitoramento de saúde**: No Kubernetes, a probe de readiness usa `/ready` (acessibilidade do Postgres + ClickHouse) enquanto o liveness permanece em `/health`. Para alertas "o AgentEye está funcionando?" em toda a frota para o Slack, habilite o add-on Robusta opcional; veja [enterprise-docs/health-monitoring.md](/pt-br/agenteye/health-monitoring). --- -## Tags de imagem disponíveis +## Tags de Imagem Disponíveis | Tag | Descrição | |-----|-------------| -| `latest` | Último release estável | -| `beta-latest` | Último pré-release (beta) | +| `latest` | Última release estável | +| `beta-latest` | Última pré-release (beta) | | `v` | Versão fixada, ex.: `v0.0.1-beta.48` (recomendado para produção) | \ No newline at end of file diff --git a/docs/pt-br/agenteye/getting-started.mdx b/docs/pt-br/agenteye/getting-started.mdx index 1e3799a1..033ccfa4 100644 --- a/docs/pt-br/agenteye/getting-started.mdx +++ b/docs/pt-br/agenteye/getting-started.mdx @@ -1,34 +1,34 @@ --- -title: "Primeiros Passos com AgentEye" -description: "Documentação de Primeiros Passos com AgentEye." +title: "Primeiros Passos com o AgentEye" +description: "Documentação de introdução ao AgentEye." --- -Este guia apresenta uma configuração completa do AgentEye: implantação do servidor e do dashboard, instalação do coletor em uma máquina de agente e instrumentação do seu código Python de agente. +Este guia apresenta uma configuração completa do AgentEye: implantando o servidor e o dashboard, instalando o coletor em uma máquina de agente e instrumentando o código do seu agente Python. --- ## O que é o AgentEye? -O AgentEye é uma **plataforma de observabilidade e avaliação self-hosted para agentes de IA**. Ele registra tudo o que seus agentes fazem — cada etapa de uma execução — e pontua automaticamente a qualidade de cada execução concluída, para que você possa acompanhar o comportamento dos seus agentes em produção e identificar regressões antes que seus usuários percebam. +O AgentEye é uma **plataforma de observabilidade e avaliação self-hosted para agentes de IA**. Ele registra o que seus agentes fazem — cada etapa de uma execução — e pontua automaticamente a qualidade de cada execução concluída, para que você possa ver como seus agentes se comportam em produção e detectar regressões antes que seus usuários percebam. -Os dados fluem em uma única direção: seu código de agente emite **eventos** via **Python SDK** → um daemon **coletor** leve os agrupa e envia para o **servidor** → eventos e análises são armazenados no **ClickHouse** (estado operacional como organizações, usuários, chaves de API, dashboards e queries salvas fica no **Postgres**) → você explora tudo no **dashboard**. +Os dados fluem em uma única direção: seu código de agente emite **eventos** por meio do **SDK Python** → um daemon **coletor** leve agrupa e os envia ao **servidor** → eventos e análises são armazenados no **ClickHouse** (o estado operacional, como organizações, usuários, chaves de API, dashboards e consultas salvas, fica no **Postgres**) → você explora tudo no **dashboard**. O que você obtém: -- **Eventos** — o rastro bruto, passo a passo, de cada execução de agente (chamadas de ferramentas, chamadas de modelo, hooks, erros). +- **Eventos** — o rastro bruto, por etapa, de cada execução de agente (chamadas de ferramenta, chamadas de modelo, hooks, erros). - **Sessões** — esses eventos consolidados em uma linha por execução, cada uma **avaliada e pontuada automaticamente**. - **Avaliações** — pontuações de qualidade produzidas pelos seus próprios serviços de avaliação, para que quedas de qualidade apareçam sem revisão manual. -- **Queries e dashboards** — SQL ClickHouse salvo sobre seus dados, visualizado em dashboards compartilhados com escopo por organização. -- **Alertas e incidentes** — regras de limite que notificam você (e-mail, Slack, webhook, in-dashboard) além de um fluxo de trabalho de incidentes para triagem. -- **CLI e assistente de IA** — um cliente de terminal (`agenteye`) e um assistente integrado ao dashboard para fazer perguntas em linguagem natural. +- **Consultas e dashboards** — SQL ClickHouse salvo sobre seus dados, visualizado em dashboards compartilhados com escopo de organização. +- **Alertas e incidentes** — regras de limiar que notificam você (e-mail, Slack, webhook, no dashboard) além de um fluxo de trabalho de incidentes para triagem. +- **CLI e assistente de IA** — um cliente de terminal (`agenteye`) e um assistente no dashboard para fazer perguntas em linguagem natural. -Você executa tudo na sua própria infraestrutura, como uma stack Docker Compose (este guia), uma instalação Kubernetes para produção ou um único pod co-localizado. O restante deste guia configura a stack Compose do início ao fim. +Você executa tudo isso na sua própria infraestrutura, como uma stack Docker Compose (este guia), uma instalação Kubernetes para produção ou um único pod colocado. O restante deste guia configura a stack Compose do início ao fim. --- ## Passo 1: Autenticar -Todos os artefatos do AgentEye são distribuídos pela organização GitHub `agenteye-enterprise`. Como desenvolvedor enterprise, você pode gerar seu próprio GitHub PAT. Siga [enterprise-docs/github-token.md](/pt-br/agenteye/github-token) para os passos exatos e as permissões necessárias. +Todos os artefatos do AgentEye são distribuídos pela organização `agenteye-enterprise` no GitHub. Como desenvolvedor enterprise, você pode gerar seu próprio GitHub PAT. Siga [enterprise-docs/github-token.md](/pt-br/agenteye/github-token) para os passos exatos e as permissões necessárias. ```bash export AGENTEYE_TOKEN= @@ -41,7 +41,7 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin ## Passo 2: Implantar o Servidor e o Dashboard -O servidor recebe eventos dos coletores e os torna consultáveis; o dashboard é onde você os explora. Eventos ingeridos e análises ficam no ClickHouse (o armazenamento de análises obrigatório), enquanto o Postgres mantém o estado operacional como organizações, usuários, chaves de API, dashboards e queries salvas. +O servidor recebe eventos dos coletores e os torna consultáveis; o dashboard é onde você os explora. Eventos ingeridos e análises ficam no ClickHouse (o armazenamento de análises obrigatório), enquanto o Postgres mantém o estado operacional, como organizações, usuários, chaves de API, dashboards e consultas salvas. **Baixe o arquivo compose publicado:** @@ -63,29 +63,23 @@ POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -Também exporte `ADMIN_KEY` no seu shell atual para que os passos seguintes (por exemplo, o `curl` do Passo 3) possam referenciá-lo diretamente: - -```bash -export ADMIN_KEY=your-admin-secret -``` - **Inicie a stack:** ```bash docker compose up -d ``` -Isso sobe a stack completa, incluindo o armazenamento de análises ClickHouse obrigatório e um cache Redis opcional, juntamente com o servidor e o dashboard. O ClickHouse precisa estar saudável para o servidor iniciar. +Isso sobe a stack completa, incluindo o armazenamento de análises ClickHouse obrigatório e um cache Redis opcional, junto com o servidor e o dashboard. O ClickHouse precisa estar saudável para o servidor iniciar. -O servidor agora está ouvindo em `http://localhost:8080` e o dashboard em `http://localhost:3000`. +O servidor agora está escutando em `http://localhost:8080` e o dashboard em `http://localhost:3000`. -Para implantações em produção (Postgres personalizado, TLS, proxy reverso), consulte [enterprise-docs/deployment.md](/pt-br/agenteye/deployment). +Para implantações em produção (Postgres personalizado, TLS, proxy reverso), veja [enterprise-docs/deployment.md](/pt-br/agenteye/deployment). --- ## Passo 3: Criar uma Chave de API para o Coletor -Cada coletor se autentica com uma chave de API com escopo definido. Use o `ADMIN_KEY` que você definiu no Passo 2 para criar uma: +Cada coletor se autentica com uma chave de API com escopo. Use o `ADMIN_KEY` definido no Passo 2 para criar uma: ```bash curl -s -X POST http://localhost:8080/keys \ @@ -94,7 +88,7 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -Você define o valor de `key` você mesmo; use-o na configuração do coletor no Passo 4. Consulte [enterprise-docs/api-keys.md](/pt-br/agenteye/api-keys) para o gerenciamento completo de chaves. +Você fornece o valor de `key` você mesmo; use-o na configuração do coletor no Passo 4. Veja [enterprise-docs/api-keys.md](/pt-br/agenteye/api-keys) para o gerenciamento completo de chaves. --- @@ -113,7 +107,7 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> Isso baixa o build **Linux x86_64**. Para macOS (Apple Silicon ou Intel), Linux arm64, ou configuração via Docker / systemd / launchd, consulte [collector-installation.md](/pt-br/agenteye/collector-installation), que lista o download para cada plataforma — o comando acima instala um binário Linux que não funcionará em outros sistemas operacionais. +> Isso baixa o build para **Linux x86_64**. Para macOS (Apple Silicon ou Intel), Linux arm64, ou configuração via Docker / systemd / launchd, veja [collector-installation.md](/pt-br/agenteye/collector-installation), que lista o download para cada plataforma — o comando acima instala um binário Linux que não funcionará em outros sistemas. **Configure:** @@ -133,19 +127,19 @@ EOF agenteye-collector start ``` -Verifique a conectividade com um flush único (encerra após esvaziar quaisquer eventos pendentes): +Verifique a conectividade com um flush único (encerra após drenar quaisquer eventos pendentes): ```bash agenteye-collector flush ``` -Para configuração via Docker, systemd e launchd, consulte [enterprise-docs/collector-installation.md](/pt-br/agenteye/collector-installation). +Para configuração com Docker, systemd e launchd, veja [enterprise-docs/collector-installation.md](/pt-br/agenteye/collector-installation). --- -## Passo 5: Instalar o Python SDK +## Passo 5: Instalar o SDK Python -Em cada máquina onde você deseja instrumentar o código de agente, instale o wheel a partir do GitHub Releases. +Em cada máquina onde você deseja instrumentar o código do agente, instale o wheel a partir do GitHub Releases. ```bash VERSION=0.0.1b9 @@ -159,7 +153,7 @@ pip install agenteye-${VERSION}-py3-none-any.whl ## Passo 6: Instrumentar Seu Agente -Adicione eventos ao seu código de agente. No mínimo, emita `agent_start` e `agent_end`: +Adicione eventos ao código do seu agente. No mínimo, emita `agent_start` e `agent_end`: ```python import agenteye @@ -179,51 +173,51 @@ agenteye.event.agent_end( ) ``` -Os eventos são armazenados em buffer e enviados para `$AGENTEYE_HOME/events/` (ou `~/.agenteye/events/` se `AGENTEYE_HOME` não estiver definido) a cada 500 ms. O coletor os processa automaticamente. +Os eventos são armazenados em buffer e enviados para `$AGENTEYE_HOME/events/` (ou `~/.agenteye/events/` se `AGENTEYE_HOME` não estiver definido) a cada 500 ms. O coletor os captura automaticamente. -Consulte [enterprise-docs/python-sdk.md](/pt-br/agenteye/python-sdk) para a API completa de eventos. +Veja [enterprise-docs/python-sdk.md](/pt-br/agenteye/python-sdk) para a API completa de eventos. --- ## Passo 7: Visualizar Eventos no Dashboard -Abra `http://your-dashboard-host:3000` e faça login. O AgentEye envia um código de uso único por e-mail (ou um magic link de clique único), portanto não há senha para gerenciar. +Abra `http://your-dashboard-host:3000` e faça login. O AgentEye envia um código de uso único por e-mail (ou um link mágico de um clique), então não há senha para gerenciar. ![A tela de login do AgentEye, que envia um código de uso único para o seu e-mail](/agenteye/images/login.png) -Uma vez dentro, a página **Events** exibe um rastro em tempo real de todos os eventos ingeridos. Filtre por `session_id` ou `agent_id` para detalhar uma execução específica. +Após entrar, a página **Events** exibe um rastro em tempo real de todos os eventos ingeridos. Filtre por `session_id` ou `agent_id` para detalhar uma execução específica. -![O stream de Eventos em tempo real, com código de cores por tipo de evento e filtrável por ambiente, agente e sessão](/agenteye/images/events-stream.png) +![O stream de eventos ao vivo, com código de cores por tipo de evento e filtrável por ambiente, agente e sessão](/agenteye/images/events-stream.png) -A página **Sessions** consolida esses eventos em uma linha por execução. O AgentEye avalia automaticamente as sessões concluídas, portanto cada execução é pontuada e regressões de qualidade aparecem sem revisão manual; a pontuação de avaliação mais recente aparece em cada linha de forma imediata: +A página **Sessions** consolida esses eventos em uma linha por execução. O AgentEye avalia automaticamente as sessões concluídas, portanto cada execução é pontuada e regressões de qualidade aparecem sem revisão manual; a pontuação de avaliação mais recente é exibida em cada linha de relance: -![A lista de Sessões, uma linha por execução, com indicadores de status e badges de pontuação de avaliação](/agenteye/images/sessions-list.png) +![A lista de sessões, uma linha por execução, com indicadores de status e emblemas de pontuação de avaliação](/agenteye/images/sessions-list.png) -Para configurar como as sessões são pontuadas, consulte [enterprise-docs/evaluation-suite.md](/pt-br/agenteye/evaluation-suite). +Para configurar como as sessões são pontuadas, veja [enterprise-docs/evaluation-suite.md](/pt-br/agenteye/evaluation-suite). -Clique em qualquer sessão para abrir seu **grafo de execução**, uma visualização estilo git de como agentes, ferramentas, hooks e chamadas de modelo se desenrolaram ao longo do tempo, com sub-agentes paralelos em suas próprias faixas e um detalhamento por execução no painel lateral direito: +Clique em qualquer sessão para abrir seu **gráfico de execução**, uma visualização no estilo git de como agentes, ferramentas, hooks e chamadas de modelo se desenrolaram ao longo do tempo, com sub-agentes paralelos em suas próprias faixas e um detalhamento por execução no painel lateral direito: -![O grafo de execução estilo git de uma sessão ao lado da sua linha do tempo de eventos, com o painel de detalhamento de ferramentas/modelo/hook](/agenteye/images/session-detail.png) +![O gráfico de execução no estilo git de uma sessão ao lado da linha do tempo de eventos, com o painel de detalhamento de ferramenta/modelo/hook](/agenteye/images/session-detail.png) --- -## Passo 8: Explorar, Visualizar e Configurar Alertas +## Passo 8: Explorar, visualizar e alertar -Com os eventos fluindo, as páginas de **análise** transformam atividade bruta em respostas, para que você possa medir o comportamento do agente, compartilhar descobertas com o time e ser notificado no momento em que algo regredir. As páginas do dashboard têm escopo por organização, então as URLs que você vê na barra de endereços são prefixadas com o slug da sua org (`//…`). +Com os eventos fluindo, as páginas de **análise** transformam atividade bruta em respostas, para que você possa medir o comportamento do agente, compartilhar descobertas com a equipe e ser notificado no momento em que algo regredir. As páginas do dashboard têm escopo de organização, portanto as URLs que você vê na barra de endereços são prefixadas com o slug da sua organização (`//…`). -- **Queries** (`//queries`): comece a partir de uma biblioteca de queries reutilizáveis salvas sobre seus eventos e avaliações (predefinições integradas mais as suas próprias)… +- **Queries** (`//queries`): comece a partir de uma biblioteca de consultas salvas e reutilizáveis sobre seus eventos e avaliações (predefinições integradas mais as suas próprias)… -![A biblioteca de queries salvas: uma grade de queries reutilizáveis, tanto predefinições integradas quanto personalizadas](/agenteye/images/queries.png) +![A biblioteca de consultas salvas: uma grade de consultas reutilizáveis, tanto predefinições integradas quanto personalizadas](/agenteye/images/queries.png) …depois abra uma no compositor SQL para ajustá-la e executá-la com resultados em tempo real: -![O compositor de queries SQL executando uma query salva, com uma barra lateral de esquema e uma grade de resultados em tempo real](/agenteye/images/query-lab.png) +![O compositor de consultas SQL executando uma consulta salva, com uma barra lateral de esquema e uma grade de resultados em tempo real](/agenteye/images/query-lab.png) -- **Dashboards** (`//dashboards`): fixe queries como tiles de linha, barra, área ou pizza em dashboards compartilhados por toda a organização. +- **Dashboards** (`//dashboards`): fixe consultas como blocos de linha, barra, área ou pizza em dashboards compartilhados em toda a organização. -![Um dashboard construído a partir de queries salvas: uma linha de eventos por hora, um gráfico de barras de erros por tipo, um gráfico de área de latência e tokens por modelo](/agenteye/images/dashboard-fleet.png) +![Um dashboard construído a partir de consultas salvas: uma linha de eventos por hora, uma barra de erros por tipo, um gráfico de área de latência e tokens por modelo](/agenteye/images/dashboard-fleet.png) -- **Alertas** (`//alerts`): transforme qualquer limite em uma regra de notificação que avisa por e-mail, Slack, webhook ou in-dashboard. Consulte [enterprise-docs/alerts.md](/pt-br/agenteye/alerts). +- **Alerts** (`//alerts`): promova qualquer limite a uma regra de notificação que avisa por e-mail, Slack, webhook ou no dashboard. Veja [enterprise-docs/alerts.md](/pt-br/agenteye/alerts). --- diff --git a/docs/pt-br/agenteye/managed-deployment.mdx b/docs/pt-br/agenteye/managed-deployment.mdx index a3348888..29e1c937 100644 --- a/docs/pt-br/agenteye/managed-deployment.mdx +++ b/docs/pt-br/agenteye/managed-deployment.mdx @@ -1,107 +1,106 @@ --- title: "Implantação Gerenciada no Seu Cluster Kubernetes" -description: "Documentação da Implantação Gerenciada do AgentEye no Seu Cluster Kubernetes." +description: "Documentação de Implantação Gerenciada do AgentEye no Seu Cluster Kubernetes." --- +O AgentEye é uma plataforma de observabilidade e avaliação auto-hospedada para agentes de IA e LLM. Ele captura sessões de agentes, chamadas de ferramentas, requisições de modelos e erros, transformando-os em análises e avaliações pesquisáveis, e exibe os resultados em um painel com um assistente de IA opcional somente leitura. -O AgentEye é uma plataforma de observabilidade e avaliação self-hosted para agentes de IA e LLM. Ele captura sessões de agentes, chamadas de ferramentas, requisições de modelos e erros, transforma-os em análises e avaliações pesquisáveis, e exibe os resultados em um dashboard com um assistente de IA opcional somente leitura. - -No modelo de implantação gerenciada, você fornece um cluster Kubernetes dedicado e a Exosphere executa toda a plataforma dentro dele, implantando, configurando, operando, fazendo backup e atualizando cada componente em seu nome. Sua equipe obtém o valor da plataforma (visibilidade dos agentes, análises, avaliação e o assistente opcional) sem precisar operar bancos de dados, certificados ou atualizações. Todos os dados permanecem dentro da sua conta na nuvem. +No modelo de implantação gerenciada, você fornece um cluster Kubernetes dedicado e a Exosphere executa a plataforma completa dentro dele, implantando, configurando, operando, fazendo backup e atualizando cada componente em seu nome. Sua equipe obtém o valor da plataforma (visibilidade de agentes, análises, avaliação e o assistente opcional) sem precisar operar bancos de dados, certificados ou atualizações. Todos os dados permanecem dentro da sua conta na nuvem. --- ## Pré-requisitos -- Um **GitHub PAT** para baixar imagens de contêiner e artefatos (consulte [Configuração do Token GitHub](/pt-br/agenteye/github-token)) -- Um **cluster Kubernetes dedicado** (consulte os requisitos abaixo) -- Um **bucket de armazenamento** para backups do banco de dados +- Um **GitHub PAT** para baixar imagens de contêiner e artefatos (veja [enterprise-docs/github-token.md](/pt-br/agenteye/github-token)) +- Um **cluster Kubernetes dedicado** (veja os requisitos abaixo) +- Um **bucket de armazenamento** para backups de banco de dados - **Conectividade de rede**: porta 443 de entrada para o load balancer do cluster --- ## Etapa 1: Provisionar um Cluster Kubernetes Dedicado -Crie um cluster Kubernetes dedicado ao AgentEye. Ele não deve ser compartilhado com outras cargas de trabalho, para que toda a plataforma (serviços de aplicação, bancos de dados, análises e cache) seja executada em isolamento sem impactar sua infraestrutura existente. +Crie um cluster Kubernetes dedicado ao AgentEye. Ele não deve ser compartilhado com outras cargas de trabalho, para que a plataforma completa (serviços de aplicação, bancos de dados, análises e cache) seja executada de forma isolada sem impactar sua infraestrutura existente. | Requisito | Detalhes | |---|---| -| **Distribuição** | Qualquer Kubernetes compatível: EKS, GKE, AKS ou autogerenciado | -| **Versão** | 1.27 ou superior | +| **Distribuição** | Qualquer Kubernetes conformante: EKS, GKE, AKS ou autogerenciado | +| **Versão** | 1.27 ou posterior | | **Pool de nós** | Mínimo: **3 nós, 4 vCPU / 8 GB de RAM cada** (instâncias de uso geral padrão) | -| **Armazenamento** | Uma StorageClass padrão que provisiona volumes em bloco (ex.: `gp3` na AWS, `pd-ssd` no GCP) | -| **Load Balancer** | O cluster deve ser capaz de provisionar serviços LoadBalancer na nuvem (padrão em EKS, GKE, AKS) | +| **Armazenamento** | Um StorageClass padrão que provisiona volumes em bloco (ex.: `gp3` na AWS, `pd-ssd` no GCP) | +| **Load Balancer** | O cluster deve ser capaz de provisionar serviços de LoadBalancer na nuvem (padrão no EKS, GKE, AKS) | -> A Exosphere instala e gerencia tudo o mais dentro do cluster: controladores de ingresso, certificados TLS, bancos de dados, cache, monitoramento e todos os deployments de aplicação. +> A Exosphere instala e gerencia tudo o mais dentro do cluster: controladores de ingress, certificados TLS, bancos de dados, cache, monitoramento e todas as implantações de aplicações. --- -## Etapa 2: Conceder Acesso à Equipe AgentEye +## Etapa 2: Conceder Acesso à Equipe do AgentEye -A Exosphere precisa de acesso cluster-admin (ou RBAC amplo equivalente) para gerenciar namespaces, definições de recursos personalizados, controladores de ingresso e provisionadores de armazenamento. +A Exosphere precisa de acesso de cluster-admin (ou RBAC amplo equivalente) para gerenciar namespaces, definições de recursos personalizados, controladores de ingress e provisionadores de armazenamento. | Requisito | Detalhes | |---|---| -| **Método de acesso** | Função IAM (preferida para EKS/GKE), kubeconfig ou acesso baseado em SSO | +| **Método de acesso** | IAM role (preferido para EKS/GKE), kubeconfig ou acesso baseado em SSO | | **VPN / bastion** | Se o servidor de API do Kubernetes for privado, forneça credenciais de VPN ou acesso via bastion para a equipe de operações da Exosphere | --- -## Etapa 3: Configurar a Conectividade de Rede +## Etapa 3: Configurar Conectividade de Rede -Sua equipe de rede precisa permitir tráfego de entrada na **porta 443** para os load balancers do cluster. A implantação utiliza dois load balancers separados: um para ingestão de eventos (protegido por mTLS) e outro para o dashboard: +Sua equipe de rede precisa permitir tráfego de entrada na **porta 443** para os load balancers do cluster. A implantação utiliza dois load balancers separados: um para ingestão de eventos (protegido por mTLS) e outro para o painel: | Tráfego | Origem | Destino | Segurança | |---|---|---|---| -| **Ingestão de eventos** | Pods coletores nos seus clusters | Load Balancer de ingestão, porta 443 | mTLS (certificado de cliente) + chave de API | -| **Dashboard** | Navegadores dos desenvolvedores | Load Balancer do dashboard, porta 443 | HTTPS no seu domínio, login por OTP de e-mail sem senha | +| **Ingestão de eventos** | Pods coletores nos seus clusters | Ingest LoadBalancer, porta 443 | mTLS (certificado de cliente) + chave de API | +| **Painel** | Navegadores dos desenvolvedores | Dashboard LoadBalancer, porta 443 | HTTPS no seu domínio, login OTP por e-mail sem senha | -O endpoint de ingestão é protegido por TLS mútuo; os coletores devem apresentar um certificado de cliente válido **e** uma chave de API válida em cada requisição. O dashboard é executado em seu próprio load balancer e hostname, com acesso restrito aos endereços de e-mail/domínios autorizados por você. +O endpoint de ingestão é protegido por TLS mútuo; os coletores devem apresentar um certificado de cliente válido **e** uma chave de API válida em cada requisição. O painel é executado em seu próprio load balancer e hostname, com login restrito aos endereços de e-mail/domínios na sua lista de permissões. -**Registros DNS (uma única vez):** você cria dois registros CNAME em um domínio que você controla — um para o endpoint de ingestão e outro para o dashboard (ex.: `agenteye.sua-empresa.exemplo`) — apontando para os hostnames do load balancer fornecidos pela Exosphere. A Exosphere então provisiona automaticamente certificados TLS de confiança pública para ambos os hostnames, incluindo as renovações. +**Registros DNS (uma única vez):** você cria dois registros CNAME em um domínio que você controla — um para o endpoint de ingestão e outro para o painel (ex.: `agenteye.sua-empresa.exemplo`) — apontando para os hostnames do load balancer fornecidos pela Exosphere. A Exosphere então provisiona automaticamente certificados TLS publicamente confiáveis para ambos os hostnames, incluindo renovações. -> **Observação sobre a porta 80:** a emissão e renovação automáticas de certificados são validadas via HTTP na porta 80 de cada load balancer. Se a sua política de segurança exigir restringir o load balancer do dashboard a faixas de IP corporativas, informe a Exosphere primeiro — nós mudamos a validação de certificados para o método baseado em DNS (um registro DNS extra do seu lado) para que as renovações continuem funcionando com a restrição ativa. +> **Observação sobre a porta 80:** a emissão e renovação automáticas de certificados são validadas via HTTP na porta 80 de cada load balancer. Se sua política de segurança exigir restringir o load balancer do painel a intervalos de IP corporativos, informe a Exosphere com antecedência — nós alteramos a validação de certificados para um método baseado em DNS (um registro DNS extra do seu lado) para que as renovações continuem funcionando por trás da restrição. -> **Saída:** Os nós do cluster precisam de acesso à internet para baixar imagens de contêiner de `ghcr.io`. Se a sua rede restringe o tráfego de saída, adicione `ghcr.io` à lista de permissões ou espelhe as imagens para o seu registro interno. +> **Saída:** os nós do cluster precisam de acesso à internet para baixar imagens de contêiner do `ghcr.io`. Se sua rede restringir o tráfego de saída, adicione `ghcr.io` à lista de permissões ou espelhe as imagens para seu registro interno. --- ## Etapa 4: Fornecer um Bucket de Armazenamento para Backup -Os backups do banco de dados são armazenados em um bucket de armazenamento na nuvem que pertence a você. +Os backups do banco de dados são armazenados em um bucket de armazenamento na nuvem que você possui. | Requisito | Detalhes | |---|---| | **Serviço** | S3 (AWS), GCS (GCP) ou Azure Blob Storage | -| **Acesso** | Conceda acesso de escrita aos nós do cluster via função IAM para contas de serviço (IRSA no EKS, Workload Identity no GKE) ou forneça credenciais | +| **Acesso** | Conceda acesso de escrita aos nós do cluster via IAM role para contas de serviço (IRSA no EKS, Workload Identity no GKE) ou forneça credenciais | | **Retenção** | Você controla a política de ciclo de vida do bucket (período de retenção, regras de arquivamento). A Exosphere grava os backups; você decide por quanto tempo mantê-los | -Um único backup diário exporta tanto o PostgreSQL (estado relacional) quanto o ClickHouse (eventos e avaliações) em um arquivo compactado e o envia ao seu bucket. Os backups também são executados antes de cada atualização. +Um único backup diário exporta tanto o PostgreSQL (estado relacional) quanto o ClickHouse (eventos e avaliações) em um arquivo comprimido e faz upload para o seu bucket. Os backups também são executados antes de cada atualização. --- ## Etapa 5: Designar um Ponto de Contato -Indique uma pessoa ou canal do Slack/Teams no seu lado para questões no nível do cluster: saúde dos nós, limites da conta na nuvem, mudanças de rede. As operações do dia a dia não envolvem esse contato. +Forneça uma pessoa ou canal do Slack/Teams do seu lado para questões no nível do cluster: integridade dos nós, limites da conta na nuvem, mudanças na rede. As operações do dia a dia não envolvem esse contato. --- ## O Que Implantamos -Assim que a Exosphere obtiver acesso ao cluster, os seguintes componentes serão implantados e gerenciados para você: +Assim que a Exosphere tiver acesso ao cluster, os seguintes componentes são implantados e gerenciados para você: | Componente | Função | |---|---| -| **AgentEye Server** | API HTTP que recebe eventos dos coletores, executa análises e fornece dados ao dashboard | -| **Dashboard** | Interface web para visualização de sessões de agentes, chamadas de ferramentas, requisições de modelos e erros; hospeda o assistente de IA opcional somente leitura | +| **AgentEye Server** | API HTTP que recebe eventos dos coletores, executa análises e serve dados para o painel | +| **Dashboard** | Interface web para visualizar sessões de agentes, chamadas de ferramentas, requisições de modelos e erros; hospeda o assistente de IA opcional somente leitura | | **ClickHouse** | Armazenamento canônico obrigatório para eventos ingeridos, análises e avaliações | -| **PostgreSQL** | Armazenamento relacional para organizações, chaves de API, usuários, dashboards e consultas salvas | -| **Redis** | Cache compartilhado opcional e backend de limitação de taxa; a plataforma degrada graciosamente se não estiver disponível | +| **PostgreSQL** | Armazenamento relacional para organizações, chaves de API, usuários, painéis e consultas salvas | +| **Redis** | Cache compartilhado opcional e backend de limitação de taxa; a plataforma degrada graciosamente se estiver indisponível | | **Assistente de IA (opcional)** | Contêiner assistente interno somente leitura; permanece desativado até que um endpoint de LLM seja configurado | -| **Controladores de ingresso** | Dois load balancers (um para ingestão protegida por mTLS, outro para o dashboard) encerrando TLS com certificados de confiança pública e renovação automática, e aplicando mTLS no endpoint de ingestão | +| **Controladores de ingress** | Dois load balancers (um para ingestão protegida por mTLS, outro para o painel) encerrando TLS com certificados publicamente confiáveis e renovados automaticamente, e aplicando mTLS no endpoint de ingestão | | **cert-manager** | Automatiza o provisionamento de certificados TLS e a emissão de certificados de cliente mTLS | -| **Monitoramento de certificados** | Um job agendado verifica a expiração dos certificados e envia alertas (ex.: para o Slack) conforme os certificados se aproximam da renovação | +| **Monitoramento de certificados** | Um job agendado verifica a expiração de certificados e envia alertas (ex.: para o Slack) à medida que os certificados se aproximam da renovação | -A oferta gerenciada também opera o pipeline de avaliação da plataforma, que pontua a atividade dos agentes com base nos seus critérios de avaliação. Consulte [Assistente](/pt-br/agenteye/assistant) e [Suite de Avaliação](/pt-br/agenteye/evaluation-suite) para saber o que essas capacidades oferecem. +A oferta gerenciada também opera o pipeline de avaliação da plataforma, que pontua a atividade dos agentes com base nos seus critérios de avaliação. Veja [enterprise-docs/assistant.md](/pt-br/agenteye/assistant) e [enterprise-docs/evaluation-suite.md](/pt-br/agenteye/evaluation-suite) para entender o que essas capacidades oferecem. --- @@ -111,10 +110,10 @@ Após a conclusão da implantação, você recebe: | Item | Detalhes | |---|---| -| **URL do Dashboard** | Um hostname no seu domínio (ex.: `https://agenteye.sua-empresa.exemplo`), servido com um certificado TLS de confiança pública e renovação automática. Você cria um CNAME para o hostname do load balancer que fornecemos; o login é por OTP de e-mail sem senha | +| **URL do painel** | Um hostname no seu domínio (ex.: `https://agenteye.sua-empresa.exemplo`), servido com um certificado TLS publicamente confiável e renovado automaticamente. Você cria um CNAME para o hostname do load balancer que fornecemos; o login é OTP por e-mail sem senha | | **Endpoint do coletor** | O caminho `/events` do hostname de ingestão (ex.: `https://ingest.sua-empresa.exemplo/events`), protegido por mTLS | | **Bundle de certificado de cliente** | Por cluster: certificado de cliente, chave privada e certificado CA entregues como um manifesto de Secret do Kubernetes. Aplique uma vez por cluster | -| **GitHub PAT** | Para download de binários do coletor e pacotes do SDK Python | +| **GitHub PAT** | Para baixar binários do coletor e pacotes do SDK Python | | **Chaves de API do coletor** | Chaves com escopo de permissão `events:add`, uma por implantação de coletor | | **Guias de instalação** | Documentação passo a passo para o coletor e o SDK Python | @@ -122,22 +121,22 @@ Após a conclusão da implantação, você recebe: ## O Que Você Faz Após a Configuração -O único trabalho contínuo é nas suas próprias máquinas de agentes, não no cluster do AgentEye: +Seu único trabalho contínuo é nas suas próprias máquinas de agentes, não no cluster do AgentEye: -1. **Instale o coletor** em cada cluster Kubernetes que executa agentes de IA: monte o certificado de cliente e configure a URL do endpoint e a chave de API. Consulte [Instalação do Coletor](/pt-br/agenteye/collector-installation). -2. **Integre o SDK Python** ao código do seu agente. Consulte [SDK Python](/pt-br/agenteye/python-sdk). -3. **Abra o dashboard** no seu navegador para visualizar a atividade dos agentes. +1. **Instale o coletor** em cada cluster Kubernetes que executa agentes de IA: monte o certificado de cliente e configure a URL do endpoint e a chave de API. Veja [enterprise-docs/collector-installation.md](/pt-br/agenteye/collector-installation). +2. **Integre o SDK Python** no código do seu agente. Veja [enterprise-docs/python-sdk.md](/pt-br/agenteye/python-sdk). +3. **Abra o painel** no seu navegador para visualizar a atividade dos agentes. -Sem operações de cluster, sem gerenciamento de banco de dados, sem renovações de certificados, sem atualizações. +Sem operações no cluster, sem gerenciamento de banco de dados, sem renovações de certificados, sem atualizações. --- ## Segurança -- **Os dados permanecem na sua conta na nuvem.** O cluster, o armazenamento e os bancos de dados são executados no seu ambiente. Nenhum dado sai do seu perímetro. +- **Os dados permanecem na sua conta na nuvem.** O cluster, o armazenamento e os bancos de dados são todos executados no seu ambiente. Nenhum dado sai do seu perímetro. - **Você controla o acesso.** O cluster está na sua conta. Você pode auditar, monitorar ou revogar o acesso da Exosphere a qualquer momento. Todas as operações passam pelo log de auditoria da sua nuvem (CloudTrail, GCP Audit Logs, etc.). - **mTLS na ingestão de eventos.** Cada requisição do coletor exige tanto um certificado de cliente válido quanto uma chave de API. Uma chave vazada é inútil sem o certificado; um certificado roubado é inútil sem uma chave válida. -- **Controle de acesso ao dashboard.** O dashboard é executado em seu próprio load balancer, separado da ingestão de eventos, e o login é por OTP de e-mail sem senha, restrito aos endereços de e-mail/domínios autorizados por você. Uma lista de permissões de faixas de IP de origem no load balancer está disponível mediante solicitação; como a renovação automática de certificados precisa acessar o load balancer, a Exosphere combina a restrição com a validação de certificados baseada em DNS para que as renovações continuem funcionando. +- **Controle de acesso ao painel.** O painel é executado em seu próprio load balancer, separado da ingestão de eventos, e o login é OTP por e-mail sem senha, restrito aos endereços de e-mail/domínios na sua lista de permissões. Uma lista de permissões de intervalo de IP de origem no load balancer está disponível mediante solicitação; como a renovação automática de certificados precisa alcançar o load balancer, a Exosphere combina a restrição com a validação de certificados baseada em DNS para que as renovações continuem funcionando. - **Certificados por cluster.** Cada um dos seus clusters recebe seu próprio certificado de cliente. Se um cluster for comprometido, esse certificado é revogado de forma independente, sem afetar os demais. --- @@ -148,11 +147,11 @@ Sem operações de cluster, sem gerenciamento de banco de dados, sem renovaçõe |---|---|---| | **Provisionamento do cluster** | 1-2 dias | Provisionar o cluster e conceder acesso à Exosphere | | **Configuração da plataforma** | 1 dia | Nenhum; a Exosphere instala todos os componentes de infraestrutura | -| **Implantação da aplicação** | 1 dia | Nenhum; a Exosphere implanta o servidor, o dashboard e cria as chaves de API | +| **Implantação da aplicação** | 1 dia | Nenhum; a Exosphere implanta o servidor, o painel e cria as chaves de API | | **Rollout do coletor** | 1-3 dias | Instalar os coletores nos seus clusters (com orientação da Exosphere) | -| **Burn-in em produção** | 1 semana | Nenhum; a Exosphere monitora e ajusta | +| **Estabilização em produção** | 1 semana | Nenhum; a Exosphere monitora e ajusta | -Total típico: **~2 semanas** do kickoff até a produção pronta. +Total típico: **~2 semanas** do início até estar pronto para produção. --- diff --git a/docs/ru/agenteye/audits.mdx b/docs/ru/agenteye/audits.mdx index 25de5223..b2893838 100644 --- a/docs/ru/agenteye/audits.mdx +++ b/docs/ru/agenteye/audits.mdx @@ -1,107 +1,106 @@ --- -title: "Audits — обнаружение улучшений агентов" -description: "AgentEye Audits — документация обнаружения улучшений агентов." +title: "Audits — обнаружение возможностей улучшения агентов" +description: "AgentEye Audits — документация по обнаружению возможностей улучшения агентов." --- -Audits — это повторяющиеся задания, которые анализируют логи вашего агента **между сеансами** в поиске областей для улучшения. Если alert отслеживает одну известную вам метрику в режиме реального времени, audit *исследует*: по расписанию, которое вы установили, он выполняет детерминированный проход политики по временному окну, а затем запускает **AI-агента надежности** на ваших сеансах — агент запрашивает данные самостоятельно, читает подозрительные транскрипты и (при необходимости) запускает небольшие аналитические скрипты, а затем составляет **рекомендации по улучшениям** с доказательствами, подтверждающими каждую из них. +Audits — это повторяющиеся задания, которые анализируют журналы вашего агента **между сессиями** в поиске вещей, достойных улучшения. Если оповещение отслеживает одну известную вам метрику в режиме реального времени, аудит *расследует*: по установленному расписанию он запускает детерминированный проход политики над окном, а затем отпускает **AI-агента надежности** на ваши сессии — агент сам запрашивает данные, читает подозрительные транскрипты и (при необходимости) запускает небольшие аналитические скрипты, затем выдает **рекомендации по улучшению** с доказательствами, стоящими за каждой из них. -Используйте audits для ответа на вопрос «что нужно исправить или улучшить в моих агентах?» — и alerts для получения уведомления в момент пересечения определенного порога. Каждое улучшение содержит ссылки на точные сеансы и запросы, на основе которых оно выявлено, и один клик создает предзаполненный alert для перехвата повторений. +Используйте audits для ответа на вопрос "что мне нужно исправить или улучшить в своих агентах?" — и оповещения для отправки уведомления в момент, когда определенный порог перейден. Каждое улучшение ссылается на точные сессии и запросы, за ним стоящие, и один клик создает предзаполненное оповещение для отслеживания повторений. -Поверхность дашборда — **`//audits`** (боковая панель → *analyze* → *audits*), защищена разрешениями `audits:read` / `audits:write`. +Поверхность панели управления — **`//audits`** (боковая панель → *analyze* → *audits*), защищена разрешениями `audits:read` / `audits:write`. --- ## Как работает запуск -Каждый запуск имеет два уровня — детерминированный базовый уровень и исследование на основе агента. +Каждый запуск имеет два уровня — детерминированный уровень и агентское расследование. ### 1. Проход политики (детерминированный) -Перед запуском любой модели audit выполняет небольшой набор **проверок политики SQL** по временному окну: ограниченные агрегированные запросы, которые помечают известные плохие паттерны и сообщают, *сколько* событий / *какие* сеансы совпали — никогда не сам текст совпадений. Каталог включает: +Перед запуском любой модели аудит выполняет небольшой набор **SQL проверок политики** над окном: ограниченные агрегирующие запросы, которые выявляют известные плохие шаблоны и сообщают *сколько* событий / *какие* сессии совпали — никогда не сам совпадающий текст. Каталог включает: -- **Утечка секретов / учетных данных** в полезных нагрузках событий — AWS ключи доступа, API ключи типа `sk-…`, приватные ключи PEM, JWT / bearer токены и назначения учетных данных типа `KEY=…`. -- **Маркеры prompt-injection** — "игнорировать предыдущие инструкции", "раскрыть системное приглашение" и подобные. -- **PII** — номера похожие на SSN (эвристический анализ). -- **Отказы в доступе к инструментам** и **зацикленные вызовы инструментов**. +- **Утечка секретов / учетных данных** в полезных нагрузках событий — AWS ключи доступа, ключи API `sk-…`, приватные ключи PEM, JWT / bearer токены и назначения учетных данных `KEY=…`. +- **Маркеры инъекции подсказок** — "ignore previous instructions", "reveal your system prompt" и аналогичные. +- **PII** — номера в формате SSN (эвристика). +- **Отказы в разрешениях инструментов** и **циклы непрерывных вызовов инструментов**. -Обнаружения политики сохраняются как findings (вид `policy`), которые **всегда отображаются** (их никогда не удаляет лимит per-run), и передаются AI-агенту как стартовые подсказки. Поскольку этому уровню не нужна модель, audit все равно выдает свои наиболее важные сигналы безопасности, даже если AI-агент недоступен. +Совпадения политики сохраняются как выводы (тип `policy`), которые **всегда появляются** (они никогда не урезаются по лимиту за запуск), и передаются AI-агенту как начальные зацепки. Поскольку этот уровень не требует модели, аудит по-прежнему выдает свои самые важные сигналы безопасности, даже если AI-агент недоступен. -### 2. Исследование на основе агента (AI) +### 2. Агентское расследование (AI) -Затем audit запускает **автономный агент надежности** (тот же сервис Claude Agent SDK, который работает в помощнике дашборда, с подсказкой, специфичной для audit). Учитывая **область** audit (выбранные агенты × окружения) и **временное окно**, агент: +Затем аудит запускает **автономного агента надежности** (тот же сервис Claude Agent SDK, который питает помощника панели управления, с аудит-специфичной подсказкой). Учитывая **область** аудита (выбранные агенты × окружения) и **временное окно**, агент: -- выполняет запросы SQL только для чтения к вашим аналитическим таблицам, -- читает несколько репрезентативных транскриптов сеансов, -- при необходимости пишет и запускает короткие **Python скрипты в защищенной изолированной sandbox** (без сети, без доступа к файловой системе, секреты очищены) для анализа, который SQL не может выразить — кластеризация ошибок, вычисление распределений, просмотр полезных нагрузок, которые он уже загрузил, -- и записывает каждое хорошо обоснованное **улучшение**, которое он находит. +- запускает только для чтения SQL запросы к вашим таблицам аналитики, +- читает несколько репрезентативных транскриптов сессий, +- опционально пишет и запускает короткие **Python скрипты в защищенной in-pod песочнице** (без сети, без доступа к файловой системе, секреты удалены) для анализа, который SQL не может выразить — кластеризация ошибок, вычисление распределений, сканирование полезных нагрузок, которые он уже получил, +- и записывает каждое хорошо подкрепленное **улучшение**, которое находит. -Он работает через несколько следственных линий — кластеризация ошибок, отклонение от базовой линии, неудача цели в транскриптах, неправильное использование инструментов, компромиссы качества/стоимости и пробелы в охвате — согласно **чувствительности** audit (низкая / средняя / высокая). Каждое улучшение **должно содержать доказательства**: идентификаторы сеансов, которые агент действительно проверил, и/или SQL, который он запустил. Сервер проверяет, что указанные сеансы существуют, и **отбрасывает любое улучшение без подтверждающих доказательств**, поэтому агент исследует, но никогда не придумывает. +Он работает через несколько линий расследования — кластеризацию ошибок, дрейф против базовой линии, отказ в цели в транскриптах, неправильное использование инструментов, компромиссы качество/стоимость и пробелы в охвате — при **чувствительности** аудита (low / medium / high). Каждое улучшение **должно цитировать доказательства**: идентификаторы сессий, которые агент фактически проверил, и/или SQL, который он запустил. Сервер проверяет, что цитируемые сессии существуют, и **отбрасывает любое улучшение без сохранившихся доказательств**, поэтому агент расследует, но никогда не выдумывает. Каждое улучшение содержит: -- **рекомендацию** (конкретное изменение для внесения — корректировку приглашения, исправление схемы инструмента, политику повтора, guardrail, большее покрытие eval), -- оценку **ожидаемого влияния** и **усилия** (низкое / среднее / высокое), -- **масштаб** — `big` (оператора нужно уведомить), `medium` (должно быть в отчете о запуске) или `small` (контекст дашборда), -- стабильный **fingerprint** (из категории проблемы + область, *не* из сеансов этого запуска), поэтому одна и та же проблема отслеживается от запуска к запуску даже при изменении доказательств, -- и, где простой детерминированный watcher может перехватить повторение, **предложенный alert**, который вы можете создать в один клик. +- **рекомендацию** (конкретное изменение для внесения — корректировка подсказки, исправление схемы инструмента, политика повторных попыток, guardrail, больше оценочного охвата), +- **ожидаемое влияние** и оценку **усилий** (low / medium / high), +- **величину** — `big` (оператора следует вызвать), `medium` (принадлежит отчету запуска), или `small` (контекст панели управления), +- стабильный **отпечаток** (из категории проблемы + область, *не* сессии этого запуска), поэтому та же проблема отслеживается от запуска к запуску, даже когда доказательства меняются, +- и, где простой детерминированный наблюдатель мог бы поймать повторение, **предложенное оповещение**, которое вы можете создать в один клик. -> **AI-уровень опционален, но рекомендуется.** Если никакой AI-агент не настроен для конвейера audit, запуски по-прежнему выполняются, сохраняют findings политики и честно сообщают "анализ недоступен" для уровня агента вместо молчаливого прохождения. +> **Слой AI опционален, но рекомендуется.** Если для конвейера аудита не настроен никакой AI-агент, запуски по-прежнему выполняются, сохраняют выводы политики и честно сообщают "анализ недоступен" для агентского слоя, а не молча проходят. ### Режимы отказа -Улучшения классифицируются в долговечный **каталог режимов отказа** вашей организации (или предлагают новый режим). Режимы дают паттернам стабильную идентичность между запусками и отслеживание долгосрочного повторения. +Улучшения классифицируются в каталог **режимов отказа** вашей организации (или предлагают новый режим). Режимы дают шаблонам стабильную идентичность между запусками и долгосрочное отслеживание повторений. -## Жизненный цикл триажа +## Жизненный цикл сортировки -На странице findings (`/audits//findings/`): +На странице вывода (`/audits//findings/`): | Действие | Эффект | |---|---| -| **acknowledge** | Оставляет finding видимым, но вдвое снижает его приоритет. | -| **resolve** | Отмечает как исправленное. Если паттерн действительно вернется позже, он откроется как **new** — поэтому регрессия будет заметна, а не молча сложена в историю. | -| **mute** / **dismiss** | Длительное подавление: отпечаток (fingerprint) паттерна запоминается и никогда больше не отображается, даже между запусками. Используйте mute для "известного, принятого"; dismiss для "не полезно". | -| **reopen** | Очищает подавление / разрешение и переранжирует паттерн. | -| **assign** | Маршрутизирует finding оператору (члену организации) для владения. Приоритет и состояние подавления не изменяются. | +| **acknowledge** | Держит вывод видимым, но снижает его приоритет вдвое. | +| **resolve** | Отмечает исправленным. Если шаблон действительно вернется позже, он снова откроется как **new** — поэтому регрессия громкая, а не тихо сложена в историю. | +| **mute** / **dismiss** | Долговечное подавление: отпечаток шаблона запоминается и никогда больше не появляется, даже между запусками. Используйте mute для "известного, принято"; dismiss для "не полезно". | +| **reopen** | Очищает подавление / разрешение и переоценивает шаблон. | -Шум с низким сигналом управляется для каждого audit с помощью лимита per-run на agentic improvements (`top_k`). Findings политики обходят лимит (они важны для безопасности и всегда показываются). Все обрезанное лимитом подсчитывается в статистике запуска — ничего не отбрасывается молча. +Низкосигнальный шум контролируется для каждого аудита с лимитом выводов за запуск (`top_k`) на агентские улучшения. Выводы политики обходят лимит (они безопасны и всегда показаны). Все, что отрезано лимитом, подсчитывается в статистике запуска — ничего не тихо отбрасывается. ## Расписание -- **Cadence** (`schedule_interval_secs`): ежечасно или еженедельно; **ежедневно по умолчанию**. Audits намеренно грубше, чем alerts — исследование на основе агента сканирует целые окна и работает в течение минут. -- **Window**: либо фиксированный скользящий lookback (например, "каждый запуск сканирует последние 7 дней"), либо **since-last-run** (по умолчанию) — каждый запуск продолжает с того, где закончился предыдущий успешный, с небольшим перекрытием, чтобы события на границе никогда не пропускались. -- Следующий запуск планируется на полный интервал после завершения предыдущего, поэтому медленный запуск никогда не создает второй одновременный запуск того же audit. -- **Run now** на странице audit делает его срочным. +- **Cadence** (`schedule_interval_secs`): почасовой до еженедельный; **ежедневный по умолчанию**. Audits намеренно грубее оповещений — агентское расследование сканирует целые окна и работает в течение минут. +- **Window**: либо фиксированный откат (например, "каждый запуск сканирует последние 7 дней"), либо **since-last-run** (по умолчанию) — каждый запуск подхватывает там, где закончился предыдущий успешный, с небольшим перекрытием, чтобы граничные события никогда не были пропущены. +- Следующий запуск запланирован на полный интервал после завершения предыдущего, поэтому медленный запуск никогда не складывает второй одновременный запуск того же аудита. +- **Run now** на странице аудита делает его срочным сразу. ## Выбор модели -При создании audit вы можете выбрать, какую модель использует исследование, из **списка моделей, которые ваш оператор настроил** для сервиса агента. С одной настроенной моделью средство выбора показывает ее как подпись; с несколькими — вы выбираете. Если оставить его без установки, будет использована настроенная по умолчанию. +При создании аудита вы можете выбрать, какую модель будет использовать расследование, из **списка моделей, настроенных вашим оператором** для сервиса агента. С одной настроенной моделью выбиратель показывает её как заголовок; с несколькими вы выбираете. Оставив её неустановленной, используется настроенный по умолчанию. ## Уведомления -Когда запуск выявляет **новые** findings, audit уведомляет настроенные каналы вашей организации — те же ворота `alerts.enabled_channels` и настройки, которые использует конвейер alerts: +Когда запуск появляется **новыми** выводами, аудит уведомляет настроенные каналы вашей организации — те же шлюз `alerts.enabled_channels` и настройки, которые использует конвейер оповещений: -- **Slack** — краткое описание значительных (`big`) новых элементов с глубокой ссылкой. -- **Email** — оформленный **отчет audit**, перечисляющий новые улучшения (высший приоритет, рекомендации по элементам, глубокая ссылка), отправляется, когда audit имеет подключенный канал **email** и есть по крайней мере один новый finding. +- **Slack** — резюме значительных (`big`) новых элементов с глубокой ссылкой. +- **Email** — разработанный **audit report** со списком новых улучшений (высший приоритет серьезности, рекомендации для каждого элемента, глубокая ссылка), отправленный когда аудит имеет подключенный **email** канал и есть по крайней мере один новый вывод. -Повторяющиеся, но известные findings не отправляют повторные уведомления. +Повторяющиеся, но известные выводы не отправляют уведомления повторно. -## Справочник по конфигурации +## Справочник конфигурации -Определения Audit управляются в дашборде (`/audits/new`) или через API. Настройки per-audit включают cadence расписания и window, область (`{"environments": [...], "agent_ids": [...]}`), чувствительность (`low` / `medium` / `high`), каналы уведомлений, лимит per-run для findings (`top_k`) и модель (через `llm_budget.model`). Параметры сервера уровня оператора (timeouts, sandbox, URL сервиса агента) описаны в [deployment.md](/ru/agenteye/deployment). +Определения аудитов управляются на панели управления (`/audits/new`) или через API. Параметры для каждого аудита включают график cadence и window, область (`{"environments": [...], "agent_ids": [...]}}`), чувствительность (`low` / `medium` / `high`), каналы уведомления, лимит выводов за запуск (`top_k`) и модель (через `llm_budget.model`). Параметры уровня оператора на сервере (timeout, sandbox, URL сервиса агента) задокументированы в [deployment.md](/ru/agenteye/deployment). ## API -Все endpoints имеют область org и следуют стандартной аутентификации bearer-key (см. [api-keys.md](/ru/agenteye/api-keys)). +Все endpoints относятся к организации и следуют стандартной аутентификации с ключом bearer (см. [api-keys.md](/ru/agenteye/api-keys)). -| Endpoint | Разрешение | Назначение | +| Endpoint | Разрешение | Цель | |---|---|---| -| `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | Список / создание определений audit. | -| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Проверка, редактирование, удаление audit. | -| `POST /audits/:id/run` | `audits:write` | Сделать audit срочным. | -| `GET /audits/:id/runs` | `audits:read` | История запусков (window, статус, статистика, количество findings). | -| `GET /audits/findings` | `audits:read` | Org-wide findings, фильтруемые по `audit_id`, `status`; отсортированы по приоритету. | -| `GET /audits/findings/:fid` | `audits:read` | Полные детали findings (рекомендация, доказательства, приоритет). | -| `POST /audits/findings/:fid/status` | `audits:write` | Триаж: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | - -Для "audit запустился, но ничего не найдено", "code sandbox отключена" и "email от audit не доставлена", см. [troubleshooting.md](/ru/agenteye/troubleshooting#audits). \ No newline at end of file +| `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | Получить список / создать определения аудитов. | +| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Проверить, отредактировать, удалить аудит. | +| `POST /audits/:id/run` | `audits:write` | Сделать аудит срочным немедленно. | +| `GET /audits/:id/runs` | `audits:read` | История запусков (window, status, stats, counts выводов). | +| `GET /audits/findings` | `audits:read` | Выводы для всей организации, фильтруемые по `audit_id`, `status`; отсортированные по приоритету. | +| `GET /audits/findings/:fid` | `audits:read` | Полный деталь вывода (рекомендация, доказательства, приоритет). | +| `POST /audits/findings/:fid/status` | `audits:write` | Сортировка: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | + +Для "аудит запустился, но ничего не нашел", "песочница кода отключена" и "аудит email не доставлен", см. [troubleshooting.md](/ru/agenteye/troubleshooting#audits). \ No newline at end of file diff --git a/docs/ru/agenteye/cli-recipes.mdx b/docs/ru/agenteye/cli-recipes.mdx index 01cef519..4f480dc9 100644 --- a/docs/ru/agenteye/cli-recipes.mdx +++ b/docs/ru/agenteye/cli-recipes.mdx @@ -1,19 +1,18 @@ --- title: "CLI рецепты для агентов" -description: "Документация CLI рецептов AgentEye для агентов." +description: "Документация AgentEye CLI рецептов для агентов." --- +Извлекайте данные сессий, событий и оценок (и запускайте переоценки) прямо из скрипта или кодирующего агента с чистым JSON на stdout, который можно передать прямо в `jq`. Эти рецепты превращают данные наблюдаемости AgentEye в то, что может запросить и автоматизировать пользователь терминала или AI кодирующий агент (Claude Code, Cursor), без навигации по панели управления. -Извлекайте данные о сессиях, событиях и оценках (и запускайте переоценки) прямо из скрипта или кодирующего агента с чистым JSON на stdout, который можно передавать в `jq`. Эти рецепты превращают данные наблюдаемости AgentEye в нечто, что может запрашивать и автоматизировать пользователь терминала или кодирующий AI-агент (Claude Code, Cursor), без необходимости кликать по панели управления. - -Приведённые ниже паттерны готовы к копированию для AgentEye CLI (`agenteye`). Инструкции по установке, аутентификации и полный список опций см. в [CLI](/ru/agenteye/cli); запустите `agenteye -h` или `agenteye -h` для встроенной справки. +Приведённые ниже примеры готовы к копированию и вставке для AgentEye CLI (`agenteye`). Для установки, аутентификации и полного списка параметров см. [CLI](/ru/agenteye/cli); запустите `agenteye -h` или `agenteye -h` для встроенной справки. ## Золотые правила -1. **Глобальные опции идут *перед* командой.** `agenteye --json sessions` — правильно; `agenteye sessions --json` — нет. Глобальные опции: `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Передавайте `--json` всякий раз, когда разбираете вывод.** Данные выводятся на **stdout** в JSON; статусные сообщения и ошибки выводятся на **stderr**, так что stdout остаётся чистым для передачи в `jq`. -3. **Ветвитесь по коду выхода, не по тексту stderr**: `0` ок · `2` неверные аргументы · `3` не удалось достичь панель управления · `4` не аутентифицирован или истекла сессия · `5` недостаточно прав. -4. **Исследуйте с помощью `-h`.** Каждая команда документирует свои фильтры, форматы значений и форму JSON. +1. **Глобальные опции идут *перед* командой.** `agenteye --json sessions` — правильно; `agenteye sessions --json` — неправильно. Глобальные параметры: `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **Передавайте `--json` при каждом разборе выходных данных.** Данные выводятся в **stdout** как JSON; статус и ошибки идут в **stderr**, поэтому stdout остаётся чистым для передачи в `jq`. +3. **Ветвитесь по коду выхода**, а не по тексту stderr: `0` ok · `2` неверные аргументы · `3` панель управления недоступна · `4` не залогирован или сессия истекла · `5` отсутствует разрешение. +4. **Изучайте с помощью `-h`.** Каждая команда документирует свои фильтры, форматы значений и форму JSON. ## Одноразовая настройка @@ -22,9 +21,9 @@ export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # чтобы не agenteye login --email you@example.com # вставьте отправленный по почте код; действителен ~24ч ``` -## Подтвердите аутентификацию перед работой +## Проверьте аутентификацию перед работой -`whoami` никогда не ошибается при отсутствующей или истекшей сессии; вместо этого он сообщает `logged_in:false`, поэтому агент может безопасно проверить состояние аутентификации. (Он всё ещё может выйти с ненулевым кодом, если не установлен базовый URL или панель управления недоступна.) +`whoami` никогда не ошибается при отсутствующей или истёкшей сессии; вместо этого сообщает `logged_in:false`, поэтому агент может безопасно проверить состояние аутентификации. (Он всё ещё может выйти с ненулевым кодом, если не установлен базовый URL или панель управления недоступна.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -32,20 +31,20 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## Найдите неудачные или низкоскоринговые сессии +## Найдите сессии с ошибками или низким рейтингом ```bash -# сессии за последние 24ч, оценка которых ошибилась +# сессии за последние 24ч, у которых оценка ошибалась agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# оценки с баллом <= 0.5 по полезности для одного агента +# оценки со сметкой ≤ 0.5 по helpfulness для одного агента agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -Фильтрация по баллам находится на **`evals`**, а не на `sessions`. `--score KEY:MIN..MAX` повторяется и объединяется с AND; любая граница опциональна (`..0.5` означает ≤ 0.5, `0.9..` означает ≥ 0.9). Вы можете передать до 20 фильтров по баллам в одном запросе; больше возвращает HTTP 400. `sessions` разделяет фильтры `--env`, `--status`, `--agent-id`, `--session-id` и временного диапазона с `evals`, но не имеет `--score`. +Фильтрация по баллам находится в **`evals`**, а не в `sessions`. `--score KEY:MIN..MAX` повторяется и комбинируется через AND; любая граница опциональна (`..0.5` означает ≤ 0.5, `0.9..` означает ≥ 0.9). Вы можете передать до 20 фильтров по баллам за запрос; больше вернёт HTTP 400. `sessions` имеет фильтры `--env`, `--status`, `--agent-id`, `--session-id` и диапазон времени, общие с `evals`, но не имеет `--score`. -## Прочитайте одну сессию от начала до конца +## Прочитайте одну сессию полностью Нет единой команды `session show` — объедините цепь событий с оценкой сессии: @@ -53,7 +52,7 @@ agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ # последняя оценка сессии (статус + баллы) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# каждое событие в прогоне (повысьте --limit для полного обзора) +# каждое событие в прогоне (повысьте --limit для полного обхода) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' # только вызовы инструментов в сессии @@ -61,52 +60,52 @@ agenteye --json events --session-id run-001 --event-type tool_use,tool_result -- | jq '.events[].payload' ``` -## Получите всё (постраничность) +## Получите всё (постраничная навигация) -Результаты отсортированы по убыванию и использует курсорную постраничность. +Результаты отсортированы от новых к старым и используют постраничную навигацию по курсору. ```bash -# одноразово: получите до 500 строк по 200 строк в страницу +# за один раз: получите до 500 строк порциями по 200 строк agenteye --json events --session-id run-001 --limit 500 --all > events.json -# ручная постраничность: передайте next_cursor обратно +# ручная постраничная навигация: передайте next_cursor обратно page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## Сокращайте вывод с помощью --fields +## Уменьшите выходные данные с помощью --fields -Ограничьте ключи (в таблице и в `--json`) для снижения объёма информации, которую должен прочитать агент. +Ограничьте ключи (как в таблице, так и в `--json`), чтобы сократить объём, который должен прочитать агент. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Неизвестные имена полей отклоняются (выход `2`) с указанием допустимого списка — дешёвый способ обнаружить имена полей. +Неизвестные имена полей отклоняются (выход `2`) со списком действительных, это дешёвый способ найти имена полей. -## Обнаружьте допустимые значения фильтров +## Откройте допустимые значения фильтров ```bash agenteye --json list envs | jq -r '.values[]' # значения для --env agenteye --json list tools | jq -r '.values[]' # имена инструментов; также agents, models, event_types, … -agenteye --json list score_filters | jq -r '.values[]' # допустимый KEY для --score KEY:MIN..MAX +agenteye --json list score_filters | jq -r '.values[]' # допустимое KEY для --score KEY:MIN..MAX ``` ## Выберите вашу организацию (мультитенантность) -Если вы принадлежите более чем одной организации, выберите активный тенант при входе (он сохраняется): +Если вы принадлежите более чем одной организации, выберите активного тенанта при входе (это сохраняется): ```bash -agenteye login --org acme --email you@corp.com # установите тенанта на том же шаге входа +agenteye login --org acme --email you@corp.com # установите тенанта на том же этапе, что и вход agenteye --json orgs list | jq -r '.orgs[].org_slug' agenteye --org globex --json sessions --since 24h # переопределите для одной команды ``` -Вход в мультиорганизационную систему без `--org` завершается с ненулевым кодом и выводит организации на выбор. +Вход в мультиорганизацию без `--org` выходит с ненулевым кодом и выводит организации на выбор. -## Провизионируйте ключ API для SDK/сборщика +## Подготовьте API ключ для SDK/сборщика ```bash # секрет выводится ОДИН РАЗ — с --json это поле .key @@ -114,25 +113,25 @@ key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # ротация; agenteye keys disable ci-bot --yes для отзыва ``` -## Запустите сохранённый или специальный запрос +## Запустите сохранённый или ad-hoc запрос ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' agenteye --json query run errs --arg prod | jq '.rows' # сохранённый запрос + позиционный $1 ``` -## Классифицируйте инцидент неинтерактивно +## Разберитесь в инциденте в неинтерактивном режиме ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> Мутации автоматически пропускают подтверждение при `--json` или когда stdin не является TTY, так что агенты никогда не зависают; передайте `--yes`/`-y` для явного пропуска в других местах. +> Мутации автоматически пропускают подтверждение под `--json` или когда stdin не TTY, поэтому агенты никогда не зависают; передайте `--yes`/`-y` для явного пропуска в других местах. -## Обработка кода выхода в скрипте +## Обработка кодов выхода в скрипте ```bash out=$(agenteye --json sessions --since 1h) || code=$? @@ -145,7 +144,7 @@ case "${code:-0}" in esac ``` -## Формы JSON вывода +## Формы выходных данных JSON | Команда | stdout JSON (с `--json`) | |---|---| @@ -156,15 +155,15 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` показывается один раз) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` показан один раз) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete (любой) | объект ресурса или `{"deleted": true, "id"}` для удалений | -| сбой (любой, с `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` на stdout | +| create/update/delete (любой) | объект ресурса или `{"deleted": true, "id"}` для удаления | +| failure (любой, с `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` в stdout | -- Каждый элемент **события** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. -- Каждый элемент **оценки** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. -- Каждый элемент **сессии** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. +- Каждый элемент **event** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. +- Каждый элемент **evaluation** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. +- Каждый элемент **session** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -`--fields` каждой команды принимает ровно имена полей своего собственного элемента — набор отличается между `sessions` и `evals`, поэтому имя, допустимое для одной, может быть отклонено другой. \ No newline at end of file +Параметр `--fields` каждой команды принимает ровно имена полей своего собственного элемента — набор отличается между `sessions` и `evals`, поэтому имя, действительное для одного, может быть отклонено другим. \ No newline at end of file diff --git a/docs/ru/agenteye/deployment.mdx b/docs/ru/agenteye/deployment.mdx index 3ad061f2..aae61431 100644 --- a/docs/ru/agenteye/deployment.mdx +++ b/docs/ru/agenteye/deployment.mdx @@ -1,163 +1,163 @@ --- -title: "Развертывание" -description: "Документация по развертыванию AgentEye." +title: "Развёртывание" +description: "Документация по развёртыванию AgentEye." --- -Это руководство охватывает развертывание сервера AgentEye и панели управления в production. + +Это руководство охватывает развёртывание сервера AgentEye и приборной панели в продакшене. --- ## Обзор архитектуры ``` - [ Машины с ИИ-агентами ] [ Ваша инфраструктура ] + [ AI agent machines ] [ Your infrastructure ] Python SDK - | записывает JSONL +----------------------+ + | writes JSONL +----------------------+ v +--->| PostgreSQL 15+ | - agenteye-collector --HTTP--+ | | (реляционное | - | | | хранилище) | - v | +----------------------+ - +--------+ | + agenteye-collector --HTTP--+ | | (relational store) | + | | +----------------------+ + v | + +--------+ | +----------------------+ | Server |<------+--->| ClickHouse 24+ | - +--------+ | | (события / аналитика)| + +--------+ | | (events / analytics) | ^ | +----------------------+ API | | | | +----------------------+ - +-----------+ +- - >| Redis 7+ (опционально)| + +-----------+ +- - >| Redis 7+ (optional) | | Dashboard | +----------------------+ +-----------+ ``` -- **Server**: HTTP-сервис на Rust; получает пакеты событий, записывает их в ClickHouse и поддерживает relational-состояние в PostgreSQL. -- **Dashboard**: веб-приложение Next.js; читает и записывает исключительно через API сервера. -- **agenteye-collector**: развертывается на машинах агентов, а не на хосте сервера. -- **Postgres 15+**: ТРЕБУЕТСЯ. (Повышено с 14 в релизе multi-tenant; схема org-membership использует foreign key с `ON DELETE SET NULL` для списка колонок, что требует Postgres 15+. Обновите Postgres перед развертыванием этой версии.) Хранит OLTP-состояние: `api_keys`, `users`, `sessions`, `evaluation_jobs` (очередь), `dashboards`, `saved_queries`, `otp_codes`, плюс multi-tenant таблицы `orgs`, `org_memberships`, `org_settings`. -- **ClickHouse 24+**: ТРЕБУЕТСЯ. Аналитическое хранилище для каждого ingested события. Engine: `ReplacingMergeTree`, разделенное по месяцам, отсортированное по `(session_id, ts, dedup_key)`. Сервер подключается через `CLICKHOUSE_URL`; встроенная конфигурация `deploy/base/clickhouse/` содержит оптимизированную конфигурацию для single-node. **Требование для multi-tenant:** встроенная конфигурация включает управление доступом SQL + `users_without_row_policies_can_read_rows=false`, чтобы сервер мог создать одного read-only пользователя ClickHouse + row policy на организацию (boundary изоляции, обеспечиваемое engine, для SQL-редактора и ИИ-агента). Если вы используете собственную конфигурацию ClickHouse, перенесите эти параметры (см. `deploy/base/clickhouse/configmap.yaml`). -- **Redis 7+**: *опционально* shared cache + rate-limit backend. Сервер и панель управления подключаются через `REDIS_URL`. Если отсутствует, оба gracefully деградируют до Postgres-only путей. См. **Redis (опциональный кеш)** ниже. +- **Server**: HTTP-сервис на Rust; получает пакеты событий, записывает их в ClickHouse и поддерживает состояние в PostgreSQL. +- **Dashboard**: веб-приложение на Next.js; читает и пишет исключительно через API сервера. +- **agenteye-collector**: развёртывается на машинах агентов, а не на хосте сервера. +- **Postgres 15+**: ТРЕБУЕТСЯ. (Повышено с 14 в версии с поддержкой нескольких арендаторов; схема членства в организации использует иностранный ключ `ON DELETE SET NULL` со списком столбцов, что поддерживается только в Postgres 15+. Обновите Postgres перед развёртыванием этой версии.) Хранит состояние OLTP: `api_keys`, `users`, `sessions`, `evaluation_jobs` (очередь), `dashboards`, `saved_queries`, `otp_codes`, а также таблицы для нескольких арендаторов `orgs`, `org_memberships`, `org_settings`. +- **ClickHouse 24+**: ТРЕБУЕТСЯ. Хранилище аналитики для каждого полученного события. Engine: `ReplacingMergeTree`, разбиение по месяцам, упорядочение по `(session_id, ts, dedup_key)`. Сервер подключается через `CLICKHOUSE_URL`; поставляемая конфигурация `deploy/base/clickhouse/` содержит оптимизированную конфигурацию для одного узла. **Требование для нескольких арендаторов:** поставляемая конфигурация включает управление доступом SQL + `users_without_row_policies_can_read_rows=false`, позволяя серверу создавать по одному пользователю ClickHouse только для чтения + политику строк для каждой организации (граница изоляции, поддерживаемая engine). Если вы используете собственную конфигурацию ClickHouse, перенесите эти параметры (см. `deploy/base/clickhouse/configmap.yaml`). +- **Redis 7+**: *опциональный* общий кеш + бэкенд ограничения частоты запросов. И сервер, и приборная панель подключаются через `REDIS_URL`. При отсутствии оба корректно переходят на использование только Postgres. См. **Redis (опциональный кеш)** ниже. --- -## Server +## Сервер -### Получение образа +### Получить образ ```bash echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> Текущие сборки публикуются под `beta-latest`; `latest` присваивается только stable релизам. Для production используйте конкретный тег `:v`; см. [Доступные теги образов](#доступные-теги-образов). +> Текущие сборки публикуются под `beta-latest`; `latest` присваивается только стабильным релизам. Для продакшена зафиксируйте конкретный тег `:v`; см. [Доступные теги образов](#доступные-теги-образов). ### Переменные окружения | Переменная | Требуется | По умолчанию | Описание | |---|---|---|---| -| `DATABASE_URL` | Да | нет | Postgres DSN. Стандартная строка подключения libpq с схемой `postgres://`. Поддерживает `?sslmode=require` и другие параметры libpq. Пароль не должен содержать `/`, `+` или `=`; используйте `openssl rand -hex` для генерации URL-безопасных паролей. | -| `ADMIN_KEY` | Нет | нет | Bootstrap admin API key. Upserted со всеми разрешениями при каждом запуске. Ротируйте, изменив значение и перезагрузив. | +| `DATABASE_URL` | Да | нет | Postgres DSN. Строка подключения в стандартном формате libpq со схемой `postgres://`. Поддерживает `?sslmode=require` и другие параметры libpq. Пароль не должен содержать `/`, `+` или `=`; используйте `openssl rand -hex` для генерации безопасных для URL паролей. | +| `ADMIN_KEY` | Нет | нет | Начальный ключ API администратора. Обновляется со всеми разрешениями при каждом запуске. Для ротации измените значение и перезагрузитесь. | | `LISTEN_ADDR` | Нет | `0.0.0.0:8080` | TCP-адрес для привязки | -| `MAX_BODY_BYTES` | Нет | `134217728` (128 MB) | Максимальный размер тела запроса | -| `ADMIN_EMAIL` | Нет | нет | Email bootstrap admin пользователя. Upserted со всеми разрешениями при каждом запуске и отмечен как protected: не может быть отключен или иметь измененные разрешения через dashboard/API. Чтобы ротировать bootstrap admin, измените `ADMIN_EMAIL` и перезагрузитесь; новый email upserted как protected, а предыдущий сохраняет protection до ручной очистки в БД. | -| `ALLOWED_EMAILS` | Нет | нет (все заблокированы) | Список разделенных запятыми разрешенных адресов электронной почты для создания пользователя и входа. Поддерживает точные адреса (`user@example.com`) и wildcards домена (`*@example.com`). Если не установлено, никакие пользователи не могут быть созданы или войти. **Только первая загрузка**: заполняет allowlist org по умолчанию при первой загрузке; после этого страница [`//settings`](#operational-settings) каждой org является источником истины и изменение этой переменной окружения не имеет эффекта. | -| `SMTP_HOST` | Нет | нет | Имя хоста SMTP-сервера для отправки OTP-писем. Если не установлено, OTP-коды логируются в stdout вместо этого. | +| `MAX_BODY_BYTES` | Нет | `134217728` (128 МБ) | Максимальный размер тела запроса | +| `ADMIN_EMAIL` | Нет | нет | Email начального пользователя администратора. Обновляется со всеми разрешениями при каждом запуске и помечается защищённым: не может быть отключен или иметь изменены разрешения через приборную панель/API. Для ротации начального администратора измените `ADMIN_EMAIL` и перезагрузитесь; новый email обновляется как защищённый, а предыдущий сохраняет защиту до ручной очистки в БД. | +| `ALLOWED_EMAILS` | Нет | нет (все заблокированы) | Список допускаемых адресов email через запятую для создания и входа пользователей. Поддерживает точные адреса (`user@example.com`) и подстановочные знаки домена (`*@example.com`). Если не задано, никакие пользователи не могут быть созданы или войти. **Только при первой загрузке**: заполняет список разрешений организации по умолчанию при первой загрузке; затем страница `//settings` каждой организации является источником истины и изменение этой переменной окружения не имеет эффекта. | +| `SMTP_HOST` | Нет | нет | Имя хоста SMTP-сервера для отправки email с OTP. При отсутствии коды OTP логируются в stdout. | | `SMTP_PORT` | Нет | `587` | Порт SMTP-сервера | -| `SMTP_USERNAME` | Нет | нет | Имя пользователя SMTP-аутентификации | -| `SMTP_PASSWORD` | Нет | нет | Пароль SMTP-аутентификации | -| `SMTP_FROM` | Нет | нет | Адрес отправителя для OTP-писем | -| `SMTP_TLS` | Нет | STARTTLS | STARTTLS используется, если вы явно не отключите: `false` или `0` отправляет plaintext (без TLS); любое другое значение — включая не установленное — включает STARTTLS. | -| `DASHBOARD_URL` | Нет | встроенное значение по умолчанию | Источник Dashboard, используемый для построения как magic link в OTP-письме, так и incident magic-links в уведомлениях оповещений. Если не установлено, он возвращается к встроенному значению по умолчанию (и, только для OTP, к origin, полученному из dashboard первым). Установите это для split-domain конфигураций, чтобы как email, так и Slack/incident ссылки указывали на вашу dashboard. См. **Email magic-link URL** ниже; большинство операторов это устанавливать не должны. | -| `SESSION_TTL_SECS` | Нет | `86400` (24 ч) | Продолжительность dashboard сессии в секундах. **Только первая загрузка**: редактируйте по org через [`//settings`](#operational-settings) после первого развертывания. | -| `OTP_TTL_SECS` | Нет | `600` (10 мин) | Период действия OTP-кода в секундах. **Только первая загрузка**: редактируйте по org через [`//settings`](#operational-settings) после первого развертывания. | -| `REDIS_URL` | Нет | нет | Опциональный shared cache + rate-limit backend, например `redis://redis:6379/0`. При установке сервер кеширует аутентифицированные поиски API-ключей, aggregate `/models` dashboard, список сессий и env-list facet; он также перемещает OTP-request rate limiting с Postgres COUNT на Redis INCR. Если не установлено или недостижимо, сервер работает без кеша (OTP limit возвращается к Postgres, каждый другой вызов кеша возвращается к источнику истины). См. **Redis (опциональный кеш)** ниже. | -| `CLICKHOUSE_URL` | **Да** | нет | Базовый URL ClickHouse экземпляра, например `http://clickhouse:8123`. Сервер применяет свою схему событий к этой БД при каждом запуске и отказывается загружаться, если не может достичь ClickHouse. См. **ClickHouse (требуемое аналитическое хранилище)** ниже. | -| `CLICKHOUSE_DATABASE` | Нет | `agenteye` | Имя ClickHouse database (schema). Сервер создает его при запуске, если он не существует. | -| `ORG_CH_SECRET` | Нет (single-tenant) / **Да (multi-org)** | dev default | HMAC key, из которого получается пароль per-tenant ClickHouse каждой организации. SQL-редактор и `run_query` ИИ-агента выполняются как read-only ClickHouse пользователь org, чей row policy обеспечивает tenant isolation в engine. Single-tenant развертывания хорошо загружаются на встроенный dev default; **перед provisioning второй org вы ДОЛЖНЫ установить сильное, стабильное значение**, потому что CLI `agenteye-orgctl org create` отказывает на встроенном dev default. Ротация orphans каждого org's ClickHouse пользователя до следующей загрузки re-provisions их (boot-time reconcile лечит это автоматически). Держите это в секрете и неизменяемым на replicas. Org provisioning сам по себе только для operator; см. **Organizations (multi-tenancy)** ниже. | -| `DEFAULT_ORG_NAME` | Нет | `Default` | Отображаемое имя, заполненное для встроенной org по умолчанию. **Только первая загрузка**, и только пока org все еще имеет свежее migrated generic identity, применяется при запуске, затем игнорируется. После переименования org (`agenteye-orgctl org rename`) переименование является authoritative и эта переменная окружения не имеет дальнейшего эффекта. | -| `DEFAULT_ORG_SLUG` | Нет | `default` | URL slug для встроенной org по умолчанию, dashboard path, где она живет (`//…`). Той же first-boot-only / pristine-only семантики как `DEFAULT_ORG_NAME`. Должен быть 1-40 lowercase буквы и цифры с одними internal hyphens и не [зарезервированное слово](#organizations-multi-tenancy); неправильное значение игнорируется (org сохраняет `default`). Позволяет single-tenant install представляться как например `/acme` вместо `/default` без post-deploy CLI step. | +| `SMTP_USERNAME` | Нет | нет | Имя пользователя для аутентификации SMTP | +| `SMTP_PASSWORD` | Нет | нет | Пароль для аутентификации SMTP | +| `SMTP_FROM` | Нет | нет | Адрес отправителя для email с OTP | +| `SMTP_TLS` | Нет | STARTTLS | STARTTLS используется, если вы явно не отключите это: `false` или `0` отправляют в открытом виде (без TLS); любое другое значение — включая отсутствие — включает STARTTLS. | +| `DASHBOARD_URL` | Нет | встроенное значение по умолчанию | Источник приборной панели, используемый для построения как волшебной ссылки OTP, так и волшебных ссылок инцидентов в уведомлениях об оповещениях. При отсутствии возвращается к встроенному значению по умолчанию (и только для OTP — сначала к источнику, производному от приборной панели). Установите это для конфигураций с разделением доменов, чтобы как email, так и ссылки Slack/инцидентов указывали на вашу приборную панель. См. **Email волшебная ссылка URL** ниже; большинству операторов это не требуется. | +| `SESSION_TTL_SECS` | Нет | `86400` (24 ч) | Продолжительность сеанса приборной панели в секундах. **Только при первой загрузке**: редактируйте для каждой организации через [`//settings`](#операционные-настройки) после первого развёртывания. | +| `OTP_TTL_SECS` | Нет | `600` (10 мин) | Период действительности кода OTP в секундах. **Только при первой загрузке**: редактируйте для каждой организации через [`//settings`](#операционные-настройки) после первого развёртывания. | +| `REDIS_URL` | Нет | нет | Опциональный общий кеш + бэкенд ограничения частоты запросов, например `redis://redis:6379/0`. При установке сервер кеширует поиски аутентифицированных ключей API, агрегат `/models` приборной панели, список сеансов и фасет списка окружений; также переводит ограничение частоты запросов OTP с Postgres COUNT на Redis INCR. При отсутствии или недоступности сервер работает без кеша (лимит OTP возвращается на Postgres, каждый другой кеш переходит к источнику истины). См. **Redis (опциональный кеш)** ниже. | +| `CLICKHOUSE_URL` | **Да** | нет | Базовый URL экземпляра ClickHouse, например `http://clickhouse:8123`. Сервер применяет свою схему событий к этой БД при каждом запуске и отказывается загружаться, если не может достичь ClickHouse. См. **ClickHouse (требуемое хранилище аналитики)** ниже. | +| `CLICKHOUSE_DATABASE` | Нет | `agenteye` | Имя БД (схемы) ClickHouse. Сервер создаёт её при запуске, если она не существует. | +| `ORG_CH_SECRET` | Нет (один арендатор) / **Да (несколько организаций)** | значение по умолчанию для разработки | Ключ HMAC, из которого происходит пароль ClickHouse каждой организации для работы с конкретным арендатором. SQL-редактор и `run_query` агента выполняются от имени пользователя ClickHouse, доступного только для чтения организации, чья политика строк обеспечивает изоляцию арендатора в engine. Развёртывания с одним арендатором хорошо загружаются со встроенным значением по умолчанию для разработки; **перед подготовкой второй организации вы ДОЛЖНЫ установить сильное, стабильное значение**, потому что CLI `agenteye-orgctl org create` отказывается работать со встроенным значением по умолчанию для разработки. Его ротация сирот каждого пользователя ClickHouse организации до следующей перезагрузки (при загрузке система автоматически заживляет это). Держите его в тайне и не изменяйте между репликами. Сама подготовка организации доступна только оператору; см. **Организации (мультитенантность)** ниже. | +| `DEFAULT_ORG_NAME` | Нет | `Default` | Отображаемое имя, заполняемое встроенной организацией по умолчанию. **Только при первой загрузке** и только пока организация сохраняет своё свежемигрированное универсальное имя, применяется при запуске, затем игнорируется. После переименования организации (`agenteye-orgctl org rename`) переименование авторитетно и эта переменная окружения больше не влияет. | +| `DEFAULT_ORG_SLUG` | Нет | `default` | URL-слаг встроенной организации по умолчанию, путь приборной панели, где она находится (`//…`). Та же семантика первой загрузки / только для неиспорченных, что и `DEFAULT_ORG_NAME`. Должен быть 1-40 строчных буквенно-цифровых символов с одиночными внутренними дефисами и не быть [зарезервированным словом](#организации-мультитенантность); недействительное значение игнорируется (организация остаётся `default`). Позволяет установке с одним арендатором представляться как `/acme` вместо `/default` без шага CLI после развёртывания. | | `RUST_LOG` | Нет | `info` | Уровень логирования (`debug`, `warn`, `error`, `agenteye_server=trace`) | -| `EVALUATOR_ENDPOINT` | Нет | нет | Базовый URL вашего evaluator service (например `http://evaluator:9000`). Если не установлено, весь evaluation pipeline - это no-op; никакие queue rows не записываются, никакие workers не работают. См. [Evaluation Suite](/ru/agenteye/evaluation-suite). | -| `EVALUATOR_TOKEN` | Нет | нет | Отправляется как `Authorization: Bearer ` к evaluator. **Должен равняться тому же значению, с которым скonfigurирован evaluator service.** Опционально только если ваш evaluator скonfigurирован без токена. | -| `EVALUATOR_WORKERS` | Нет | `2` | Concurrency: количество worker задач на экземпляр сервера, которые dispatch evaluations. Безопасно работать на multiple horizontally-scaled servers. | -| `EVALUATOR_CLAIM_BATCH` | Нет | `4` | Максимальное количество evaluations, которое один worker claims за tick. Batch dispatched **concurrently**, таким образом total concurrency на вашем evaluator endpoint - это `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | Нет | `2` | Как долго worker спит между dispatch попытками, когда ничего не в очереди. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | Нет | `10` | Final fallback cadence (секунды) для `GET /evaluate/{id}` polls, когда evaluator не возвращает per-response `next_poll_secs` и не advertises `default_poll_interval_secs` от `GET /config`. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | Нет | `30000` | Per-HTTP-request timeout против evaluator (миллисекунды). | -| `EVALUATOR_MAX_ATTEMPTS` | Нет | `5` | После этого количества failed попыток evaluation записывается как terminal `error` (или `timeout`, если failures были request timeouts). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | Нет | `300` (5 мин) | Как часто сервер повторно fetches `GET /config` от evaluator. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Нет | `3600` (1 ч) | Максимальное wallclock время, в течение которого сессия может оставаться в polling queue перед тем, как AgentEye прерывает ее как `timeout`. Guards против evaluator, который возвращает `pending` навсегда. | -| `ALERT_WORKERS` | Нет | `1` | Concurrency: количество worker задач на экземпляр сервера, которые evaluate alert rules. См. [Alerts](/ru/agenteye/alerts). | -| `ALERT_CLAIM_BATCH` | Нет | `16` | Максимальное количество alerts, которое один worker claims за tick. | -| `ALERT_POLL_IDLE_SECS` | Нет | `5` | Как долго alerts worker спит, когда очередь пуста. | -| `ALERT_REQUEST_TIMEOUT_MS` | Нет | `15000` | Per-trigger evaluation timeout (ClickHouse queries + outbound channel HTTP). | -| `ALERT_MAX_ATTEMPTS` | Нет | `5` | Consecutive transient failures перед тем, как alert reschedules на его normal cadence вместо exponential backoff. | -| `AUDIT_WORKERS` | Нет | `1` | Concurrency: количество worker задач на экземпляр сервера, которые execute audits. См. [Audits](/ru/agenteye/audits). | -| `AUDIT_CLAIM_BATCH` | Нет | `1` | Максимальное количество due audits, которое один worker claims за tick. Agentic investigation - это один долгий loop, таким образом default - 1. | -| `AUDIT_POLL_IDLE_SECS` | Нет | `30` | Как долго audits worker спит, когда no audit is due. | -| `AUDIT_REQUEST_TIMEOUT_MS` | Нет | `30000` | Per-policy-query timeout против ClickHouse (миллисекунды). | -| `AUDIT_LLM_TIMEOUT_MS` | Нет | `1440000` | Timeout для agentic investigation call к AI assistant service. Full agent loop работает в течение минут; держите это ABOVE agent's own `AGENTEYE_AUDIT_TIMEOUT_MS` таким образом agent возвращает свои partial findings перед тем, как сервер give up. | -| `AUDIT_MAX_ATTEMPTS` | Нет | `5` | Consecutive transient failures перед тем, как audit reschedules на его normal cadence вместо exponential backoff. | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | Нет | — | Audit's agentic investigation вызывает AI-assistant `agent` service, **reusing the same connection как assistant** — таким образом установите эти два также на **сервер** (встроенные manifests/compose делают). Оба установлены ⇒ audits run the AI investigation; либо unset ⇒ audits run **policy-only** (deterministic SQL policy pass все еще runs), независимо от per-audit `llm_enabled` flag. Agent также должен иметь LLM, скonfigurирован — см. [assistant.md](/ru/agenteye/assistant). | - -**AI assistant service — audit + sandbox settings.** Agentic investigation и его in-pod Python sandbox tuned на **agent service** (не на сервер), все на префиксе `AGENTEYE_AUDIT_*` и все опционально: +| `EVALUATOR_ENDPOINT` | Нет | нет | Базовый URL вашего сервиса evaluator (например `http://evaluator:9000`). При отсутствии весь конвейер оценки является no-op; никакие строки очереди не пишутся, никакие рабочие не работают. См. [Evaluation Suite](/ru/agenteye/evaluation-suite). | +| `EVALUATOR_TOKEN` | Нет | нет | Отправляется как `Authorization: Bearer ` к evaluator. **Должно быть равно тому же значению, с которым настроен сервис evaluator.** Опционально только если ваш evaluator настроен без токена. | +| `EVALUATOR_WORKERS` | Нет | `2` | Параллелизм: количество рабочих задач на экземпляр сервера, который отправляет оценки. Безопасно работать на нескольких горизонтально масштабируемых серверах. | +| `EVALUATOR_CLAIM_BATCH` | Нет | `4` | Максимальное количество оценок, которые один рабочий требует за один цикл. Пакеты отправляются **параллельно**, поэтому общий параллелизм на вашей конечной точке evaluator составляет `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | Нет | `2` | Как долго рабочий спит между попытками отправки, когда нечего делать. | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Нет | `10` | Окончательный запасной каданс (секунды) для опросов `GET /evaluate/{id}`, когда evaluator не возвращает `next_poll_secs` для каждого ответа и не объявляет `default_poll_interval_secs` из `GET /config`. | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | Нет | `30000` | Тайм-аут за запрос HTTP к evaluator (миллисекунды). | +| `EVALUATOR_MAX_ATTEMPTS` | Нет | `5` | После стольких неудачных попыток оценка записывается как терминальная `error` (или `timeout`, если ошибки были тайм-аутами запросов). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | Нет | `300` (5 мин) | Как часто сервер переполучает `GET /config` от evaluator. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Нет | `3600` (1 ч) | Максимальное время существования сеанса в очереди опроса перед тем, как AgentEye завершит его как `timeout`. Защищает от evaluator, который возвращает `pending` бесконечно. | +| `ALERT_WORKERS` | Нет | `1` | Параллелизм: количество рабочих задач на экземпляр сервера, который оценивает правила оповещений. См. [Alerts](/ru/agenteye/alerts). | +| `ALERT_CLAIM_BATCH` | Нет | `16` | Максимальное количество оповещений, которые один рабочий требует за один цикл. | +| `ALERT_POLL_IDLE_SECS` | Нет | `5` | Как долго рабочий оповещений спит, когда очередь пуста. | +| `ALERT_REQUEST_TIMEOUT_MS` | Нет | `15000` | Тайм-аут оценки за срабатывание (запросы ClickHouse + исходящий HTTP канала). | +| `ALERT_MAX_ATTEMPTS` | Нет | `5` | Последовательные переходящие ошибки перед тем, как оповещение перепланируется с его нормальным каданс вместо экспоненциального отката. | +| `AUDIT_WORKERS` | Нет | `1` | Параллелизм: количество рабочих задач на экземпляр сервера, который выполняет аудиты. См. [Audits](/ru/agenteye/audits). | +| `AUDIT_CLAIM_BATCH` | Нет | `1` | Максимальное количество просроченных аудитов, которые один рабочий требует за один цикл. Агентское расследование — это один длинный цикл, поэтому значение по умолчанию — 1. | +| `AUDIT_POLL_IDLE_SECS` | Нет | `30` | Как долго рабочий аудитов спит, когда нет просроченного аудита. | +| `AUDIT_REQUEST_TIMEOUT_MS` | Нет | `30000` | Тайм-аут за запрос политики к ClickHouse (миллисекунды). | +| `AUDIT_LLM_TIMEOUT_MS` | Нет | `1440000` | Тайм-аут для вызова агентского расследования к сервису ИИ-ассистента. Полный цикл агента работает минуты; держите это ВЫШЕ `AGENTEYE_AUDIT_TIMEOUT_MS` агента, чтобы агент вернул свои частичные находки перед тем, как сервер сдаст. | +| `AUDIT_MAX_ATTEMPTS` | Нет | `5` | Последовательные переходящие ошибки перед тем, как аудит перепланируется с его нормальным каданс вместо экспоненциального отката. | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | Нет | — | Агентское расследование аудита вызывает сервис ИИ-ассистента `agent`, **повторно используя то же соединение, что и ассистент** — поэтому установите эти два на **сервере** также (поставляемые манифесты/compose делают это). Оба установлены ⇒ аудиты запускают расследование ИИ; либо один не установлен ⇒ аудиты запускают **только политику** (детерминированный SQL проход политики всё ещё работает), независимо от флага `llm_enabled` для каждого аудита. Агент должен также иметь настроенную LLM — см. [assistant.md](/ru/agenteye/assistant). | + +**Сервис ИИ-ассистента — параметры аудита + песочницы.** Агентское расследование и его Python-песочница в pod настраиваются на **сервисе агента** (не на сервере), все с префиксом `AGENTEYE_AUDIT_*` и все опциональные: | Переменная | По умолчанию | Значение | |---|---|---| -| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Max agent turns на investigation. | -| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Wall-clock для одного investigation (20 мин). Должно оставаться **below** server's `AUDIT_LLM_TIMEOUT_MS`. | -| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Concurrent investigations на agent pod (отдельно от chat assistant's budget). | -| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Per-script limits для bubblewrap sandbox. | +| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Макс ходов агента за расследование. | +| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Настенные часы для одного расследования (20 мин). Должны оставаться **ниже** `AUDIT_LLM_TIMEOUT_MS` сервера. | +| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Одновременные расследования на pod агента (отдельно от бюджета ассистента чата). | +| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Пределы за скрипт для песочницы bubblewrap. | -**Sandbox platform requirement.** Audit code sandbox запускает model's Python в bubblewrap jail, который needs **unprivileged user namespaces**. Agent pod должен allow `clone()` flags — установите `seccompProfile: Unconfined` (k8s) или `security_opt: [seccomp:unconfined]` (compose) на agent. Где node kernel отключает unprivileged user namespaces (например некоторые GKE COS images), sandbox **preflight fails и auditor degrades к SQL-only автоматически** — никакой ошибки, просто `sandbox_available: false` на agent's `/health`. +**Требование платформы песочницы.** Песочница кода аудита запускает Python модели внутри клетки bubblewrap, которая нуждается в **пространствах имён пользователей без привилегий**. Pod агента должен позволять флаги `clone()` — установите `seccompProfile: Unconfined` (k8s) или `security_opt: [seccomp:unconfined]` (compose) на агенте. Где ядро узла отключает пространства имён пользователей без привилегий (например, некоторые образы GKE COS), песочница **проверка перед полётом завершается неудачей и аудитор автоматически понижается только до SQL** — нет ошибки, просто `sandbox_available: false` на `/health` агента. ### Запуск -Установите `DATABASE_URL` и `CLICKHOUSE_URL` в вашу окружение (сервер отказывается загружаться без ClickHouse), затем передайте их в контейнер: +Установите `DATABASE_URL` в вашу окружение, затем передайте её в контейнер: ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest ``` -Сервер запускает миграции базы данных автоматически при запуске; никакого отдельного шага миграции не требуется. +Сервер автоматически запускает миграции БД при запуске; отдельный шаг миграции не требуется. ### Проверка здоровья ``` -GET /health # liveness - всегда {"status":"ok"} когда процесс запущен +GET /health # liveness - всегда {"status":"ok"} после запуска процесса GET /ready # readiness - 200 когда Postgres + ClickHouse достижимы, иначе 503 ``` -Аутентификация не требуется. Используйте `/health` для **liveness** проб и `/ready` для **readiness** / load-balancer проб. `/ready` проверяет hard dependencies, без которых сервер не может служить (Postgres + ClickHouse), поэтому сервер, который работает, но не может достичь свою базу данных, исключается из ротации и показывается как `NotReady`; Redis передается но никогда не falls readiness. На встроенных Kubernetes manifests readiness probe уже указывает на `/ready` и liveness остается на `/health`. См. [enterprise-docs/health-monitoring.md](/ru/agenteye/health-monitoring) для полной картины, включая opt-in Kubernetes-native pod-failure alerting к Slack. +Аутентификация не требуется. Используйте `/health` для проб **liveness** и `/ready` для проб **readiness** / балансировщика нагрузки. `/ready` проверяет жёсткие зависимости, без которых сервер не может работать (Postgres + ClickHouse), поэтому сервер, который работает, но не может достичь своей БД, выводится из ротации и отображается как `NotReady`; Redis сообщается, но никогда не вызывает ошибку готовности. На поставляемых манифестах Kubernetes проба готовности уже указывает на `/ready`, а liveness остаётся на `/health`. См. [enterprise-docs/health-monitoring.md](/ru/agenteye/health-monitoring) для полной картины, включая opt-in оповещение об ошибке pod на Slack, собственное для Kubernetes. -### Email magic-link URL +### Email волшебная ссылка URL -OTP login emails содержат one-tap **open the dashboard** кнопку. Клик на нее приводит пользователя на `/login?token=&email=
`; dashboard обменивает эту пару на сессию и перенаправляет в приложение, без ручного повторного ввода кода. Сервер разрешает origin dashboard, используемый для построения ссылки, в три уровня: +Email логина OTP содержит кнопку одного касания **откройте приборную панель**. Клик по ней приводит пользователя на `/login?token=&email=
`; приборная панель обменивает эту пару на сеанс и перенаправляет в приложение без ручного повторного ввода кода. Сервер разрешает источник приборной панели, используемый для построения ссылки в три уровня: -1. **`X-AgentEye-Dashboard-Url` header**: автоматически установлено dashboard's `/api/auth/otp/request` proxy из его собственного public origin. В same-origin deployment (сервер и dashboard share host за одним ingress, который forwards proxy headers), **никакая конфигурация не требуется**. -2. **`DASHBOARD_URL` env var**: установите это, если ваша dashboard достижима на другом origin, чем тот, который видит server's OTP request endpoint (split `api.example.com` / `app.example.com`), или если ваш ingress не propagates public host в dashboard pod (таким образом `request.nextUrl.origin` иначе разрешится на wildcard bind как `0.0.0.0:3000`). Пример: `DASHBOARD_URL=https://app.example.com`. -3. **Default**: `https://app.befailproof.ai`, используется только если ни один из выше не присутствует. +1. **Заголовок `X-AgentEye-Dashboard-Url`**: установлено автоматически прокси приборной панели `/api/auth/otp/request` из её собственного публичного источника. В развёртывании в одном источнике (сервер и приборная панель используют один хост позади одного ingress, который передаёт заголовки прокси), **никакая конфигурация не требуется**. +2. **Переменная окружения `DASHBOARD_URL`**: установите это, если ваша приборная панель достижима на другом источнике, чем тот, который видит конечная точка OTP сервера (разделённые `api.example.com` / `app.example.com`), или если ваш ingress не распространяет публичный хост в pod приборной панели (поэтому `request.nextUrl.origin` иначе разрешит привязку подстановочного знака как `0.0.0.0:3000`). Пример: `DASHBOARD_URL=https://app.example.com`. +3. **По умолчанию**: `https://app.befailproof.ai`, используется только если ни один из вышеперечисленных не присутствует. -Значение header валидируется: только `https://*` и loopback (`http://localhost*`, `http://127.0.0.1*`) origins принимаются, и wildcard bind addresses (`0.0.0.0`, `[::]`) отклоняются даже с `https://` схемой. Что-либо еще падает через tier 2. +Значение заголовка проверяется: принимаются только источники `https://*` и loopback (`http://localhost*`, `http://127.0.0.1*`), а адреса привязки подстановочного знака (`0.0.0.0`, `[::]`) отвергаются даже с схемой `https://`. Всё остальное переходит на уровень 2. -Установите это на running cluster с one-liner; no file, no kustomize rebuild: +Установите его на работающем кластере с одной строчкой; без файла, без перестроения kustomize: ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -Это запускает rollout; новые pods берут значение при первом запросе. Отметим, что override живет только на Deployment; последующий `kustomize build | kubectl apply` против overlay сотрет его, если вы не добавите тот же env var в вашу overlay's `server-env.yaml` patch. +Это запускает rollout; новые pod-ы подбирают значение при первом запросе. Обратите внимание, что переопределение живёт только на Deployment; последующее `kustomize build | kubectl apply` для оверлея сотрёт его, если вы не добавите ту же переменную окружения в патч `server-env.yaml` вашего оверлея. --- -## Dashboard +## Приборная панель -### Получение образа +### Получить образ ```bash docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest @@ -168,13 +168,13 @@ docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest | Переменная | Требуется | По умолчанию | Описание | |---|---|---|---| | `AGENTEYE_SERVER_URL` | Да | нет | Базовый URL сервера, например `http://localhost:8080` | -| `AGENTEYE_API_KEY` | Да | нет | API key, который dashboard использует для аутентификации на сервере. Нуждается во всех разрешениях (рекомендуется admin key). | -| `AE_LOG_LEVEL` | Нет | `info` | Server-side log verbosity: `debug`, `info`, `warn`, `error`. Установите на `debug` для просмотра upstream-request/response lines и session-validation traces при диагностике проблем. | -| `AE_LOG_JSON` | Нет | auto | `1` forces JSON-per-line output; `0` forces human-readable output. Если не установлено, JSON включен автоматически, если `NODE_ENV=production`. JSON рекомендуется в production, таким образом logs parse cleanly с `jq` или log aggregator. | -| `AE_ANALYTICS_DISABLED` | Нет | нет | Установите на `1`/`true` для отключения dashboard's anonymous product-usage telemetry. См. [Telemetry & privacy](#telemetry--privacy) ниже. | -| `REDIS_URL` | Нет | нет | Опциональный shared cache backend, например `redis://redis:6379/0`. При установке, dashboard кеширует `validateSession()` результаты на replicas и shares Next.js fetch cache для latency-aggregate / env-list proxy routes. Edge-side OTP request и verify rate limits также используют Redis, если present (falling open если Redis unreachable; server-side limit - это security backstop). См. **Redis (опциональный кеш)** ниже. | -| `AGENTEYE_AGENT_URL` | Нет | нет | Базовый URL опционального AI-assistant `agent` service, например `http://agent:9100`. **Оставьте это не установленным, чтобы скрыть assistant полностью**: no assistant bubble появляется в dashboard. См. [enterprise-docs/assistant.md](/ru/agenteye/assistant). | -| `AGENTEYE_AGENT_TOKEN` | Нет | нет | Shared secret, который dashboard представляет `agent` service. Должен соответствовать `AGENTEYE_AGENT_TOKEN`, скonfigurирован на agent. См. [enterprise-docs/assistant.md](/ru/agenteye/assistant). | +| `AGENTEYE_API_KEY` | Да | нет | Ключ API, который приборная панель использует для аутентификации на сервере. Нужны все разрешения (рекомендуется ключ администратора). | +| `AE_LOG_LEVEL` | Нет | `info` | Серверная буквальность логирования: `debug`, `info`, `warn`, `error`. Установите на `debug`, чтобы видеть строки запроса/ответа к вышестоящему и трассировки проверки сеанса при диагностике проблем. | +| `AE_LOG_JSON` | Нет | авто | `1` заставляет вывод JSON-per-line; `0` заставляет удобочитаемый вывод. При отсутствии JSON включается автоматически если `NODE_ENV=production`. JSON рекомендуется в продакшене, чтобы логи чистили с `jq` или агрегатором логов. | +| `AE_ANALYTICS_DISABLED` | Нет | нет | Установите на `1`/`true`, чтобы отключить анонимную телеметрию использования продукта приборной панели. См. [Телеметрия & конфиденциальность](#телеметрия--конфиденциальность) ниже. | +| `REDIS_URL` | Нет | нет | Опциональный общий бэкенд кеша, например `redis://redis:6379/0`. При установке приборная панель кеширует результаты `validateSession()` между репликами и делится fetch кешем Next.js для маршрутов латентности-агрегата / env-list прокси. Ограничения частоты запросов OTP на граничной стороне также используют Redis при наличии (открываются при недоступности Redis; серверная граница это отступление по безопасности). См. **Redis (опциональный кеш)** ниже. | +| `AGENTEYE_AGENT_URL` | Нет | нет | Базовый URL опционального сервиса ИИ-ассистента `agent`, например `http://agent:9100`. **Оставьте не установленным, чтобы полностью скрыть ассистента**: никакой пузырь ассистента не появляется на приборной панели. См. [enterprise-docs/assistant.md](/ru/agenteye/assistant). | +| `AGENTEYE_AGENT_TOKEN` | Нет | нет | Общий секрет, который приборная панель представляет сервису `agent`. Должен совпадать с `AGENTEYE_AGENT_TOKEN`, настроенным на агенте. См. [enterprise-docs/assistant.md](/ru/agenteye/assistant). | ### Запуск @@ -187,91 +187,91 @@ docker run -d --restart unless-stopped \ ghcr.io/agenteye-enterprise/dashboard:beta-latest ``` -### Telemetry & privacy +### Телеметрия & конфиденциальность -Dashboard отправляет **anonymous product-usage analytics** в analytics service Exosphere (PostHog): какие dashboard pages просмотрены и handful UI actions, такие как creating API key или re-evaluating session. Этот usage signal информирует о приоритизации features. +Приборная панель отправляет **анонимную телеметрию использования продукта** в сервис аналитики Exosphere (PostHog): какие страницы приборной панели просматриваются и ряд действий UI, таких как создание ключа API или переоценка сеанса. Этот сигнал использования информирует о том, какие функции получают приоритет. -- **Никакие agent, session, или event data никогда не покидают вашу инфраструктуру.** Только dashboard UI usage сообщается. Page URLs stripped идентификаторов перед отправкой, и operators идентифицированы только opaque internal id, никогда по email. -- Telemetry **включен по умолчанию**. Чтобы отключить его полностью, установите `AE_ANALYTICS_DISABLED=1` на dashboard контейнере и перезагрузитесь. -- Analytics отправляются на dashboard's собственный `/ingest` path, который dashboard reverse-proxies к PostHog (`https://us.i.posthog.com`). Keeping requests first-party означает, что browser ad-blockers не drops их. Dashboard контейнер needs outbound access к PostHog; если это заблокировано, telemetry silently делает ничего и dashboard unaffected. +- **Никакие данные агента, сеанса или события никогда не покидают вашу инфраструктуру.** Сообщается только использование UI приборной панели. URL страниц удаляют идентификаторы перед отправкой, и операторы идентифицируются только по непрозрачному внутреннему id, никогда по email. +- Телеметрия **включена по умолчанию**. Чтобы полностью отключить, установите `AE_ANALYTICS_DISABLED=1` на контейнере приборной панели и перезагрузитесь. +- Аналитика отправляются на путь приборной панели `/ingest`, который приборная панель обратный прокси к PostHog (`https://us.i.posthog.com`). Сохранение запросов от первого лица означает, что блокировщики рекламы браузера их не отбрасывают. **Контейнер приборной панели** нуждается в исходящем доступе к PostHog; если он заблокирован, телеметрия молча ничего не делает и приборная панель не затронута. --- -## AI Assistant (опционально) +## ИИ-ассистент (опционально) -In-dashboard AI assistant позволяет вашей team задавать вопросы о их agent data на plain language (summarising sessions, drafting SQL для `/queries` редактора, и turning saved queries в dashboard tiles) не покидая dashboard. Он запускается как отдельный internal `agent` контейнер (на Claude Agent SDK), который может достигать только dashboard, и остается **отключенным, пока вы не сконфигурируете LLM endpoint**. +ИИ-ассистент в приборной панели позволяет вашей команде задавать вопросы о данных своего агента на обычном языке (резюмировать сеансы, черновик SQL для редактора `/queries` и превращать сохранённые запросы в плитки приборной панели) без покидания приборной панели. Он работает как отдельный внутренний контейнер `agent` (на Agents SDK) к которому может достичь только приборная панель, и остаётся **отключённым до тех пор, пока вы не настроите конечную точку LLM**. -Чтобы включить его, вы устанавливаете на `agent` service LLM connection (**Portkey** через `PORTKEY_API_KEY` + model-catalog slug `AGENTEYE_AGENT_MODEL=@/`, direct Anthropic через `ANTHROPIC_API_KEY`, другой gateway через `ANTHROPIC_BASE_URL`, или Bedrock/Vertex), **dedicate** data key, и shared `AGENTEYE_AGENT_TOKEN`, совпадающий с dashboard. Dashboard users дополнительно нуждаются в разрешении `agent:use`. +Чтобы включить, вы установите на сервис `agent` подключение LLM (**Portkey** через `PORTKEY_API_KEY` + слаг каталога моделей `AGENTEYE_AGENT_MODEL=@/`, прямой Anthropic через `ANTHROPIC_API_KEY`, другой шлюз через `ANTHROPIC_BASE_URL` или Bedrock/Vertex), **выделенный** ключ данных и общий `AGENTEYE_AGENT_TOKEN`, совпадающий с приборной панелью. Пользователи приборной панели дополнительно нуждаются в разрешении `agent:use`. -Для assistant's data key вы не mint ничего вручную: выберите random secret, установите его как `AGENTEYE_API_KEY` на `agent` **и** как `AGENT_API_KEY` на `server`, и server seeds его при startup с fixed permission set. Его data access - это read-only (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), и он дополнительно держит approval-gated authoring scopes (`dashboards:write`, `queries:write`, `queries:run`), таким образом он может draft и validate saved queries и build dashboard tiles от user's имени; весь SQL все еще runs через org's read-only ClickHouse role, таким образом это widens что assistant может author, не какие data он может reach. Scopes fixed в коде и не могут быть widened конфигурацией. Тот key protected; он не может быть disabled или regenerated через API, только ротирован путем изменения значения и перезагрузки. Никогда не переиспользуйте admin/dashboard key для этого. +Для ключа данных ассистента вы не чеканьте что-нибудь вручную: выберите случайный секрет, установите его как `AGENTEYE_API_KEY` на `agent` **и** как `AGENT_API_KEY` на `server`, и сервер заполняет его при запуске с фиксированным набором разрешений. Его доступ к данным только для чтения (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), и он дополнительно держит области авторства, прошедшие шлюз одобрения (`dashboards:write`, `queries:write`, `queries:run`), поэтому он может черновик и проверить сохранённые запросы и построить плитки приборной панели от имени пользователя; весь SQL всё ещё работает через роль ClickHouse только для чтения организации, поэтому это расширяет то, что ассистент может создать, а не то, какие данные он может достичь. Области фиксированы в коде и не могут быть расширены конфигурацией. Этот ключ защищён; он не может быть отключен или перегенерирован через API, только ротирован путём изменения значения и перезагрузки. Никогда не повторно используйте ключ администратора/приборной панели для этого. -Полная setup, полная переменная окружения reference, telemetry options, и security model в **[enterprise-docs/assistant.md](/ru/agenteye/assistant)**. +Полная настройка, полная ссылка на переменные окружения, опции телеметрии и модель безопасности находятся в **[enterprise-docs/assistant.md](/ru/agenteye/assistant)**. --- -## ClickHouse (требуемое аналитическое хранилище) +## ClickHouse (требуемое хранилище аналитики) -ClickHouse держит ваши dashboards responsive при high event volumes и позволяет `/queries` SQL редактору join across events, evaluations, и sessions в одном store. Это требуемый canonical store для каждого ingested события, каждого terminal evaluation outcome, и derived per-session aggregates. PostgreSQL holds relational / mutable-state tables (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); analytical surface lives в ClickHouse, таким образом dashboard's rollups и ваши собственные SQL queries могут scan и join его natively, без cross-database round-trips. Сервер отказывается загружаться без `CLICKHOUSE_URL`. +ClickHouse держит приборные панели отзывчивыми при высоких объёмах событий и позволяет редактору SQL `/queries` присоединять события, оценки и сеансы в одном хранилище. Это требуемое канонические хранилище для каждого полученного события, каждого терминального результата оценки и производных агрегатов за сеанс. PostgreSQL держит реляционные / изменяемые таблицы состояния (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); аналитическая поверхность живёт в ClickHouse, так что rollup приборной панели и ваши собственные SQL запросы могут сканировать и присоединять её нативно, без кросс-БД круговых путей. Сервер отказывается загружаться без `CLICKHOUSE_URL`. -### Schema +### Схема -Три ClickHouse объекта создаются при startup сервера, все idempotent (`CREATE IF NOT EXISTS`): +Три объекта ClickHouse создаются при запуске сервера, все идемпотентные (`CREATE IF NOT EXISTS`): -- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, разделено по `toYYYYMM(ts)`, отсортировано по `(session_id, ts, dedup_key)`. Duplicate inserts (collector retries) collapse в одну row при merge time; сервер вычисляет deterministic SHA-256 `dedup_key` для каждого события, таким образом retries безопасны. -- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, разделено по `toYYYYMM(finished_at)`, отсортировано по `(session_id, finished_at, dedup_key)`. Написано один раз на terminal evaluation outcome от evaluator pipeline. Same dedup-key model как `events`. -- **`agenteye.agent_sessions`**: a **VIEW** над `agenteye.events`, не физическая table. Каждая колонка derived (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, и т.д.). No per-event upsert и никакой отдельный backfill; view auto-reflects что бы ни было в `events`. +- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, разбиение по `toYYYYMM(ts)`, упорядочение по `(session_id, ts, dedup_key)`. Дублирующиеся вставки (повторы сборщика) сворачиваются в одну строку во время слияния; сервер вычисляет детерминированный SHA-256 `dedup_key` для каждого события, поэтому повторы безопасны. +- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, разбиение по `toYYYYMM(finished_at)`, упорядочение по `(session_id, finished_at, dedup_key)`. Написано один раз за терминальный результат оценки конвейером evaluator. Та же модель dedup-key, что и `events`. +- **`agenteye.agent_sessions`**: **ПРЕДСТАВЛЕНИЕ** над `agenteye.events`, а не физическая таблица. Каждый столбец является производным (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()` и т.д.). Нет upsert за событие и нет отдельной заливки; представление автоматически отражает всё, что находится в `events`. -Для backwards-compat с saved queries, которые reference `analytics.evaluations` / `analytics.sessions`, сервер также создает ClickHouse database `analytics` с views над `agenteye.*` таблицами; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` все resolve правильно. +Для обратной совместимости с сохранёнными запросами, которые ссылаются на `analytics.evaluations` / `analytics.sessions`, сервер также создаёт БД ClickHouse `analytics` с представлениями над таблицами `agenteye.*`; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` все разрешаются корректно. -### Configuration +### Конфигурация -Встроенный docker-compose и `deploy/base/clickhouse/` поставляют ClickHouse service, tuned для AgentEye's workload: +Поставляемые docker-compose и `deploy/base/clickhouse/` содержат сервис ClickHouse, настроенный для рабочей нагрузки AgentEye: -- 2 GiB requested / 4 GiB limit memory в shipped base overlay (sized для fit small POC/staging nodes); production customers должны overlay up — recommended floor - 2c / 4Gi request, 6c / 8Gi limit. `max_server_memory_usage_to_ram_ratio=0.9` -- 5 GiB mark cache + 8 GiB uncompressed cache +- 2 ГиБ запрошено / 4 ГиБ лимит памяти в поставляемом базовом оверлее (размер для маленьких узлов POC/staging); клиенты продакшена должны наложить up — рекомендуемый минимум 2c / 4Gi запрос, 6c / 8Gi лимит. `max_server_memory_usage_to_ram_ratio=0.9` +- 5 ГиБ mark cache + 8 ГиБ uncompressed cache - `background_pool_size=16`, `background_merges_mutations_concurrency_ratio=2` - MergeTree: `parts_to_throw_insert=3000`, `parts_to_delay_insert=1500`, `non_replicated_deduplication_window=1000` -- `local_io_method=auto` (io_uring на supported kernels) -- `fsync_metadata=0`: приемлемо благодаря at-least-once ingest + ReplacingMergeTree dedup -- `query_log` включен с 30-day TTL; `query_thread_log` удален (expensive при high QPS) -- `max_execution_time=30` для user-side queries -- 100 GiB PVC в StatefulSet template (customer overlays SHOULD override к fast SSD storage class для production) +- `local_io_method=auto` (io_uring на поддерживаемых ядрах) +- `fsync_metadata=0`: допустимо из-за at-least-once inggest + ReplacingMergeTree dedup +- `query_log` включен с TTL 30 дней; `query_thread_log` удалён (дорого при высоком QPS) +- `max_execution_time=30` для запросов пользователей +- 100 ГиБ PVC в шаблоне StatefulSet (оверлеи клиентов ДОЛЖНЫ переопределить на быстрый класс хранилища SSD для продакшена) -### Backups +### Резервные копии -Ваш full dataset captured nightly в одном restorable archive, таким образом cluster или storage loss recoverable. ClickHouse backed up автоматически daily `agenteye-backup` CronJob, который dumps обе PostgreSQL и ClickHouse в одном pass. ClickHouse - read over его HTTP API: `agenteye.events` и `agenteye.evaluations` dumped в ClickHouse-native format (views и row policies recreated сервером при startup, таким образом table data - это complete picture) и bundled с Postgres dump в одном compressed archive uploaded к вашему object storage. +Ваш полный набор данных захватывается каждую ночь в один восстанавливаемый архив, поэтому потеря кластера или хранилища восстанавливается. ClickHouse автоматически резервируется ежедневным CronJob `agenteye-backup`, который сбрасывает PostgreSQL и ClickHouse в одном пасс. ClickHouse читается по его HTTP API: `agenteye.events` и `agenteye.evaluations` сбрасываются в родном формате ClickHouse (представления и политики строк переоздаются сервером при запуске, поэтому данные таблицы полная картина) и объединяются с дампом Postgres в один сжатый архив, загруженный в ваше хранилище объектов. -Destination bucket и cloud credentials скonfigured per overlay. См. **Backups** section of [enterprise-docs/kubernetes-deployment.md](/ru/agenteye/kubernetes-deployment) для upload configuration и restore steps. +Корзина назначения и учётные данные облака настраиваются для каждого оверлея. См. раздел **Backups** в [enterprise-docs/kubernetes-deployment.md](/ru/agenteye/kubernetes-deployment) для конфигурации загрузки и шагов восстановления. --- ## Redis (опциональный кеш) -Redis - это **опциональный** shared cache + rate-limit backend, используемый сервером и dashboard. С Redis deployed и `REDIS_URL` установленным на обе services: +Redis является **опциональным** общим кешем + бэкендом ограничения частоты запросов, используемым сервером и приборной панелью. При развёртывании Redis и установке `REDIS_URL` на обоих сервисах: -- **Server** кеширует authenticated API-key lookups, `/events/environments` + `/evaluations/environments` списки, `/events/latency_aggregate` rollup (heaviest query, который dashboard polls), `/sessions` list, и переключает OTP-request rate limiting с Postgres `COUNT(*)` на Redis `INCR + EXPIRE`. -- **Dashboard** кеширует `validateSession()` результаты, таким образом 10-20 authed API calls типичный page load issues все share одну upstream session check. Он также rate-limits OTP-request и OTP-verify в dashboard edge. +- **Сервер** кеширует поиски аутентифицированных ключей API, списки `/events/environments` + `/evaluations/environments`, rollup `/events/latency_aggregate` (самый тяжёлый запрос, который приборная панель опрашивает), список `/sessions` и переключает ограничение частоты запросов OTP с Postgres `COUNT(*)` на Redis `INCR + EXPIRE`. +- **Приборная панель** кеширует результаты `validateSession()`, поэтому 10-20 аутентифицированных вызовов API, которые типичная загрузка страницы выдаёт, все делят один восходящий проверку сеанса. Она также ограничивает частоту запросов OTP-request и OTP-verify на граница приборной панели. -**Обе services gracefully degrade, если Redis unreachable.** Каждый cache call возвращает `Err` в bounded timeout и caller falls back к source of truth (Postgres на сервере, upstream Rust server на dashboard). OTP rate limiting falls back к Postgres `COUNT(*)` path на сервере (security property сохраняется); dashboard's edge OTP limit fails open пока server-side limit все еще holds. Redis being down degrades latency, не correctness. +**Оба сервиса корректно деградируют, если Redis недоступен.** Каждый вызов кеша возвращает `Err` в течение ограниченного тайм-аута и вызывающий возвращается к источнику истины (Postgres на сервере, восходящий Rust сервер на приборной панели). Ограничение частоты запросов OTP возвращается на путь Postgres `COUNT(*)` на сервере (свойство безопасности сохраняется); граница OTP приборной панели открывается при сбое, пока серверная граница всё ещё удерживается. Redis выключение деградирует задержку, а не правильность. -### Configuration +### Конфигурация -Docker-compose bundle уже includes Redis service и wires `REDIS_URL=redis://redis:6379/0` в сервер и dashboard. Чтобы использовать external Redis, установите `REDIS_URL` на вашу endpoint и удалите `redis` service из compose файла. +Поставляемый пакет docker-compose уже включает сервис Redis и подключает `REDIS_URL=redis://redis:6379/0` в сервер и приборную панель. Чтобы использовать внешний Redis, установите `REDIS_URL` на вашу конечную точку и удалите сервис `redis` из файла compose. -### Memory + persistence +### Память + персистентность -Встроенный Redis image запускается с `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. AOF persistence означает, что cache survives container restarts; `everysec` - это правильный durability/perf баланс, потому что потеря последней секунды cache writes безвредна. LRU eviction caps memory growth. +Поставляемый образ Redis работает с `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. AOF персистентность означает, что кеш выживает перезагрузки контейнера; `everysec` это правильный баланс долговечности/производительности, потому что потеря последней секунды кеш-записей безвредна. LRU вытеснение ограничивает рост памяти. -### When NOT to deploy Redis +### Когда НЕ развёртывать Redis -- Single-instance dev/QA. In-process caches на сервере alone deliver большую часть per-replica benefit; Redis adds cross-replica sharing, которую single-instance setups не нуждаются. -- Air-gapped installs, где operational cost запуска один более service outweighs latency win. +- Одноэкземплярная разработка/QA. Внутренние кеши на сервере одного доставляют большую часть преимущества за реплику; Redis добавляет кросс-реплику, совместное использование которых одноэкземплярные настройки не нуждаются. +- Air-gapped установки, где эксплуатационная стоимость запуска ещё одного сервиса перевешивает выигрыш задержки. --- ## Docker Compose (рекомендуется) -`docker-compose.yml` доступен в `agenteye-enterprise/releases` repo. Он brings up Postgres, ClickHouse, Redis, сервер, и dashboard с одной командой. +`docker-compose.yml` доступен в репозитории `agenteye-enterprise/releases`. Он поднимает Postgres, сервер и приборную панель одной командой. ```bash GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ @@ -281,24 +281,24 @@ GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ cd agenteye ``` -**Override defaults via `.env`:** +**Переопределить значения по умолчанию через `.env`:** ``` -# Use URL-safe passwords (no /, +, or = characters). -# Generate with: openssl rand -hex 24 -POSTGRES_PASSWORD=your-db-password -ADMIN_KEY=your-admin-secret +# Используйте пароли, безопасные для URL (без /, +, или = символов). +# Генерируйте с: openssl rand -hex 24 +POSTGRES_PASSWORD=ваш-пароль-бд +ADMIN_KEY=ваш-секрет-администратора -# Dashboard authentication -ADMIN_EMAIL=admin@yourcompany.com -ALLOWED_EMAILS=*@yourcompany.com +# Аутентификация приборной панели +ADMIN_EMAIL=admin@вашакомпания.com +ALLOWED_EMAILS=*@вашакомпания.com -# SMTP for OTP emails (omit to log OTP codes to stdout) -# SMTP_HOST=smtp.yourprovider.com +# SMTP для email OTP (опустите для логирования кодов OTP в stdout) +# SMTP_HOST=smtp.вашпровайдер.com # SMTP_PORT=587 -# SMTP_USERNAME=your-smtp-user -# SMTP_PASSWORD=your-smtp-password -# SMTP_FROM=noreply@yourcompany.com +# SMTP_USERNAME=ваш-smtp-юзер +# SMTP_PASSWORD=ваш-smtp-пароль +# SMTP_FROM=noreply@вашакомпания.com RUST_LOG=info ``` @@ -307,13 +307,13 @@ RUST_LOG=info docker compose up -d ``` -**Stop (keeps data volume):** +**Остановить (сохраняет объём данных):** ```bash docker compose down ``` -**Stop and wipe all data:** +**Остановить и удалить все данные:** ```bash docker compose down -v @@ -321,107 +321,107 @@ docker compose down -v --- -## Operational settings +## Операционные настройки -Небольшой набор operational knobs, которые когда-то были pinned env vars, теперь editable per organization из dashboard's **`//settings`** страницы; каждая org скonfigурирует свой собственный. Changes take effect в течение секунд, без restart и без redeploy. +Маленький набор эксплуатационных рычагов, которые раньше были зафиксированы переменными окружения, теперь редактируется для каждой организации со страницы **`//settings`** приборной панели; каждая организация настраивает свою. Изменения вступают в силу в течение секунд, без перезагрузки и без переразвёртывания. -| Setting | Bootstrap env var | Что он контролирует | +| Настройка | Bootstrap переменная окружения | Что это контролирует | |---|---|---| -| Allowed sign-ins | `ALLOWED_EMAILS` | Emails (или `*@domain.com` wildcards) permitted для receive OTP и be added как users | -| Default user permissions | `DEFAULT_USER_PERMISSIONS` | Comma-separated permission tokens preselected когда admin opens **+ new user**. Каждый token должен быть один из strings listed under [API key permissions](/ru/agenteye/api-keys). Defaults к `standard` preset: read-only access плюс everyday on-call actions (trigger re-evaluations, run queries, ack incidents, use the assistant). | -| Session lifetime | `SESSION_TTL_SECS` | Как долго dashboard login остается valid перед re-auth. Dashboard re-checks upstream session каждые 5 секунд, таким образом permission update на `//users` takes effect на affected user's next request, без relogin. | -| One-time-code lifetime | `OTP_TTL_SECS` | Как долго OTP / magic-link остается usable | -| Alert notification channels | `ALERTS_ENABLED_CHANNELS` | Comma-separated list channel kinds, которые alert dispatcher allowed использовать: `email`, `slack`, `webhook`. Per-alert configuration все еще authored на `//alerts/`, но dispatcher filters каждый outbound delivery через этот set; channel disabled здесь short-circuits с `skipped_disabled` audit row. `dashboard` channel (local audit insert) всегда allowed. Defaults ко всем трем on. | +| Допускаемые входы | `ALLOWED_EMAILS` | Email (или подстановочные знаки `*@domain.com`) разрешены получать OTP и добавляться как пользователи | +| Разрешения пользователя по умолчанию | `DEFAULT_USER_PERMISSIONS` | Токены разрешений через запятую, предварительно выбранные, когда администратор открывает **+ новый пользователь**. Каждый токен должен быть одной из строк, перечисленных под [API key permissions](/ru/agenteye/api-keys). По умолчанию преустановка `standard`: доступ только для чтения плюс повседневные on-call действия (переоценить срабатывание, запустить запросы, подтвердить инциденты, использовать ассистента). | +| Время жизни сеанса | `SESSION_TTL_SECS` | Как долго вход на приборную панель остаётся действительным перед повторной аутентификацией. Приборная панель переоценивает вышестоящий сеанс каждые 5 секунд, поэтому обновление разрешения на `//users` вступает в силу при следующем запросе затронутого пользователя без повторного входа. | +| Время жизни одноразового кода | `OTP_TTL_SECS` | Как долго OTP / волшебная ссылка остаётся пригодной для использования | +| Каналы уведомления оповещений | `ALERTS_ENABLED_CHANNELS` | Список видов каналов через запятую, которые диспетчер оповещений разрешено использовать: `email`, `slack`, `webhook`. Конфигурация для каждого оповещения всё ещё создана на `//alerts/`, но диспетчер фильтрует каждую исходящую доставку через этот набор; отключённый здесь канал сокращает с `skipped_disabled` строкой аудита. Канал `dashboard` (локальная вставка аудита) всегда разрешен. По умолчанию все три. | -### How the bootstrap works +### Как работает bootstrap -Settings хранятся per organization в `org_settings`. На первый boot, сервер seeds default org's missing rows из matching env var (или sensible default, если env var не установлен). После этого, **stored value - это source of truth и env var игнорируется**; изменение env var при позднем restart не будет affect live org's value, и additional orgs start из defaults и скonfigурируют их собственный. +Настройки хранятся для каждой организации в `org_settings`. При первой загрузке сервер заполняет отсутствующие строки организации по умолчанию от соответствующей переменной окружения (или разумное по умолчанию, если переменная окружения не установлена). После этого, **сохранённое значение является источником истины и переменная окружения игнорируется**; изменение переменной окружения при более позднем перезапуске не повлияет на значение живой организации, и дополнительные организации начинают с значений по умолчанию и настраивают свои. Это означает: -- Для fresh deploy, установите env vars как shown выше и default org читает их на first boot. -- Чтобы изменить value позже, log в dashboard и edit его under `//settings`. Change применяется в течение секунд на all server replicas; restart не нужен. -- Startup log line записывает что got seeded vs. что было уже present, таким образом вы можете confirm bootstrap took effect: +- Для свежего развёртывания установите переменные окружения, как показано выше, и организация по умолчанию читает их при первой загрузке. +- Чтобы изменить значение позже, войдите на приборную панель и отредактируйте её под `//settings`. Изменение применяется в течение секунд на всех репликах сервера; перезагрузка не нужна. +- Строка журнала запуска записывает, что получило заполнение против того, что уже присутствовало, поэтому вы можете подтвердить, что bootstrap сработал: ```text INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true ``` -#### Sign-in semantics across organizations +#### Семантика входа между организациями -Session и OTP глобальны пользователю, не к одной org, таким образом два rules reconcile per-org settings в sign-in time: +Сеанс и OTP глобальны пользователю, а не одной организации, поэтому два правила примирения параметров для каждой организации во время входа: -- **Session / OTP lifetime**: strictest (shortest) lifetime среди orgs пользователь belongs к wins. -- **Allowed sign-ins**: gate ORs каждую org's allowlist вместе с org membership: пользователь может request OTP если любая org's allowlist admits их email **или** они уже member любой org. +- **Время жизни сеанса / OTP**: самое строгое (кратчайшее) время жизни среди организаций, которым принадлежит пользователь, выигрывает. +- **Допускаемые входы**: шлюз ИЛИ каждый список разрешений организации вместе с членством в организации: пользователь может запросить OTP, если список разрешений любой организации допускает их email **или** они уже являются членом любой организации. -### Permissions +### Разрешения -Access к `//settings` странице gated двумя permissions: +Доступ к странице `//settings` контролируется двумя разрешениями: -- `settings:read`: see page и current values. -- `settings:write`: save changes. +- `settings:read`: видеть страницу и текущие значения. +- `settings:write`: сохранить изменения. -Bootstrap admin user (seeded из `ADMIN_EMAIL`) gets оба автоматически вместе с каждым другим permission. Grant их другим users из `//users` как needed. +Начальный пользователь администратора (заполняется из `ADMIN_EMAIL`) получает оба автоматически вместе со всеми остальными разрешениями. Предоставьте их другим пользователям из `//users` по мере необходимости. --- -## Organizations (multi-tenancy) +## Организации (мультитенантность) -Single deployment может serve multiple isolated **organizations** (tenants); каждый row данных belongs к ровно одной org и isolation enforced в database engine. Single-tenant install нуждается ничего здесь; все данные lives в built-in `default` org. (Вы можете дать той org friendlier name и URL slug, таким образом это lives в например `/acme` вместо `/default`, путем установки `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` перед first boot, или путем переименования его anytime с `agenteye-orgctl org rename`.) +Одно развёртывание может обслуживать несколько изолированных **организаций** (арендаторы); каждая строка данных принадлежит ровно одной организации и изоляция обеспечивается в engine БД. Одноарендаторная установка не нуждается ни в чём здесь; все данные живут во встроенной организации `default`. (Вы можете дать этой организации более дружественное имя и URL-слаг, поэтому она живёт например в `/acme` вместо `/default`, установив `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` перед первой загрузкой или переименовав её в любое время с `agenteye-orgctl org rename`.) -**Tenant provisioning - это operator-only.** Organizations и их memberships created и managed с **`agenteye-orgctl`** CLI, который ships **inside сервер image** (alongside `agenteye-server`) и runs **inside существующий server pod**; there is **no separate pod/Job, no HTTP API, и no dashboard button**. Это reuses server's `DATABASE_URL`, `CLICKHOUSE_URL`, и `ORG_CH_SECRET`. +**Подготовка арендатора доступна только оператору.** Организации и их членства создаются и управляются CLI **`agenteye-orgctl`**, который поставляется **внутри образа сервера** (рядом с `agenteye-server`) и работает **внутри существующего pod сервера**; там нет **отдельного pod/Job, нет HTTP API и нет кнопки приборной панели**. Он повторно использует `DATABASE_URL` сервера, `CLICKHOUSE_URL` и `ORG_CH_SECRET`. ```bash -# Docker Compose - exec в running server service: +# Docker Compose - exec в работающий сервис сервера: docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp" docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin -# Kubernetes - exec в running server Deployment: +# Kubernetes - exec в работающее развёртывание сервера: kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list ``` -Available verbs: `org create | list | rename | delete | purge` и `member add | list | update | remove`, с builtin permission sets `admin`, `standard`, и `read-only`. Added members get OTP на first dashboard login. +Доступные команды: `org create | list | rename | delete | purge` и `member add | list | update | remove`, со встроенными наборами разрешений `admin`, `standard` и `read-only`. Добавленные члены получат OTP при первом входе на приборную панель. -**Перед созданием second org:** установите strong, stable `ORG_CH_SECRET` (`org create` command отказывает на built-in dev default) и ensure Postgres - **15+**. **Unchanged:** per-org API keys все еще minted в dashboard/API по org members; только org + member lifecycle moved к CLI. Full command reference и worked example: **[enterprise-docs/tenant-management.md](/ru/agenteye/tenant-management)**. +**Перед созданием второй организации:** установите сильный, стабильный `ORG_CH_SECRET` (команда `org create` отказывается работать со встроенным значением по умолчанию для разработки) и убедитесь, что Postgres **15+**. **Без изменений:** ключи API для каждой организации всё ещё чеканятся в приборной панели/API членами организации; только цикл жизни организации + член перешёл на CLI. Полная справка команд и отработанный пример: **[enterprise-docs/tenant-management.md](/ru/agenteye/tenant-management)**. --- -## Context-window fill +## Заполнение окна контекста -Каждый `model_response` event показывает **context-fill pill** — input плюс output tokens как процент той model's context window. Bands - `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%), и `reset context` (75–100%). AgentEye разрешает common model IDs автоматически, таким образом никакая initial configuration не требуется. +Каждое событие `model_response` показывает **таблетку заполнения контекста** — входные плюс выходные токены в процентах от окна контекста этой модели. Диапазоны: `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%) и `reset context` (75–100%). AgentEye автоматически разрешает распространённые ID моделей, поэтому начальная конфигурация не требуется. -Каждый model, который organization отправляет, появляется under **Settings → model context windows**. Users с `settings:write` могут override его window или add private/proxy model (0–1,000,000 tokens); `0` означает уnknown и suppresses pill. Changes apply к newly ingested events. Users с `settings:read` могут view list. +Каждая модель, которую отправляет организация, появляется под **Settings → model context windows**. Пользователи с `settings:write` могут переопределить его окно или добавить приватную/proxy модель (0–1 000 000 токен); `0` означает неизвестно и подавляет таблетку. Изменения применяются к недавно полученным событиям. Пользователи с `settings:read` могут просмотреть список. -New events get fill из момента вы upgrade. Чтобы также populate **historical** events (и per-model list) для existing deployment, run one-off backfill — он ships inside сервер image (как `agenteye-orgctl`) и runs в existing server pod: +Новые события получают заполнение с момента обновления. Чтобы также заполнить **исторические** события (и список для каждой модели) для существующего развёртывания, запустите одноразовую заливку — она поставляется внутри образа сервера (как `agenteye-orgctl`) и работает в существующем pod сервера: ```bash -# preview (prints per-org mutation, changes nothing): +# предпросмотр (печатает мутацию для каждой организации, ничего не меняет): kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window --dry-run -# apply: +# применить: kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window # docker compose: docker compose exec server agenteye-backfill-context-window ``` -Это idempotent (safe к re-run) и re-uses `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` из pod. Re-run это после editing model windows если вы want existing events recomputed. +Это идемпотентно (безопасно для повторного запуска) и повторно использует `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` из pod. Повторно запустите его после редактирования окон модели, если вы хотите переосчитать существующие события. --- -## Production Considerations +## Соображения по продакшену -- **Postgres**: Используйте managed Postgres service или dedicated instance с regular backups. `DATABASE_URL` поддерживает все standard libpq parameters, включая `sslmode=require` для encrypted connections. -- **TLS**: Put сервер и dashboard за reverse proxy (nginx, Caddy, Traefik), который terminates TLS. -- **Firewall**: Server port (default 8080) должен быть reachable только из collector machines и dashboard host, не public internet. -- **Admin key**: Установите `ADMIN_KEY` на strong random secret. После bootstrapping, create dedicated scoped keys для collectors и dashboard вместо использования admin key везде. -- **Image tags**: Pin к version в вашу release manifests (например `server:v0.0.1-beta.48`) в production вместо floating tag избежать unintended upgrades. Current beta builds publish под `beta-latest`; `latest` assigned только к stable releases. -- **Health monitoring**: На Kubernetes readiness probe использует `/ready` (Postgres + ClickHouse reachability), пока liveness остается на `/health`. Для fleet-wide "is AgentEye itself up?" alerting к Slack, enable opt-in Robusta add-on; см. [enterprise-docs/health-monitoring.md](/ru/agenteye/health-monitoring). +- **Postgres**: используйте управляемый сервис Postgres или выделённый экземпляр с регулярными резервными копиями. `DATABASE_URL` поддерживает все стандартные параметры libpq, включая `sslmode=require` для зашифрованных соединений. +- **TLS**: поместите сервер и приборную панель позади обратного прокси (nginx, Caddy, Traefik), который завершает TLS. +- **Брандмауэр**: порт сервера (по умолчанию 8080) должен быть достижим только с машин сборщика и хоста приборной панели, а не из публичного интернета. +- **Ключ администратора**: установите `ADMIN_KEY` на сильный случайный секрет. После bootstrap создавайте выделённые ключи с областью действия для сборщиков и приборной панели, а не используйте ключ администратора везде. +- **Теги образов**: закрепите версию в ваших манифестах релиза (например, `server:v0.0.1-beta.48`) в продакшене, а не плавающий тег, чтобы избежать непредусмотренных обновлений. Текущие бета-сборки публикуются под `beta-latest`; `latest` присваивается только стабильным релизам. +- **Мониторинг здоровья**: на Kubernetes проба готовности использует `/ready` (достижимость Postgres + ClickHouse), пока liveness остаётся на `/health`. Для fleet-широкого оповещения AgentEye себя на Slack включите opt-in дополнение Robusta; см. [enterprise-docs/health-monitoring.md](/ru/agenteye/health-monitoring). --- ## Доступные теги образов -| Tag | Описание | +| Тег | Описание | |-----|-------------| -| `latest` | Последний stable release | -| `beta-latest` | Последний pre-release (beta) | -| `v` | Pinned version, например `v0.0.1-beta.48` (рекомендуется для production) | \ No newline at end of file +| `latest` | Последний стабильный релиз | +| `beta-latest` | Последний пред-релиз (бета) | +| `v` | Фиксированная версия, например `v0.0.1-beta.48` (рекомендуется для продакшена) | \ No newline at end of file diff --git a/docs/ru/agenteye/getting-started.mdx b/docs/ru/agenteye/getting-started.mdx index a3d78f37..81c6e284 100644 --- a/docs/ru/agenteye/getting-started.mdx +++ b/docs/ru/agenteye/getting-started.mdx @@ -1,35 +1,35 @@ --- title: "Начало работы с AgentEye" -description: "Документация AgentEye. Начало работы с AgentEye." +description: "Документация по началу работы с AgentEye." --- -Это руководство проведёт вас через полную настройку AgentEye: развёртывание сервера и панели управления, установку сборщика на машину агента и подключение вашего кода Python-агента. +Это руководство проведёт вас через полную настройку AgentEye: развёртывание сервера и панели управления, установка сборщика на машину агента и инструментирование кода вашего агента на Python. --- ## Что такое AgentEye? -AgentEye — это **самостоятельно развёртываемая платформа наблюдаемости и оценки для AI-агентов**. Она записывает действия ваших агентов — каждый шаг выполнения — и автоматически оценивает качество каждого завершённого прогона, позволяя вам видеть поведение агентов в боевых условиях и перехватывать регрессии до того, как это заметят ваши пользователи. +AgentEye — это **самостоятельно размещаемая платформа наблюдаемости и оценки для AI-агентов**. Она записывает, что делают ваши агенты — каждый шаг выполнения — и автоматически оценивает качество каждого завершённого запуска, чтобы вы могли видеть, как ваши агенты ведут себя в production, и выявлять регрессии до того, как это заметят ваши пользователи. -Данные движутся в одном направлении: ваш код агента генерирует **события** через **Python SDK** → лёгкий демон **сборщика** группирует их и отправляет на **сервер** → события и аналитика хранятся в **ClickHouse** (операционное состояние, такое как организации, пользователи, ключи API, панели управления и сохранённые запросы, находится в **Postgres**) → вы изучаете всё в **панели управления**. +Поток данных идёт в одном направлении: код вашего агента генерирует **события** через **Python SDK** → лёгкий демон **сборщика** группирует их и отправляет на **сервер** → события и аналитика сохраняются в **ClickHouse** (операционное состояние, такое как организации, пользователи, API-ключи, панели управления и сохранённые запросы, находится в **Postgres**) → вы исследуете всё это в **панели управления**. Что вы получаете: -- **События** — неотработанный, пошаговый журнал каждого прогона агента (вызовы инструментов, вызовы модели, хуки, ошибки). -- **Сессии** — события, объединённые в одну строку на прогон, каждая **автоматически оценивается** и получает балл. -- **Оценки** — баллы качества, созданные вашими собственными сервисами оценки, так что падение качества всплывает без ручной проверки. -- **Запросы и панели управления** — сохранённые SQL-запросы ClickHouse к вашим данным, визуализированные в общих, организационных панелях управления. -- **Оповещения и инциденты** — правила по пороговым значениям, которые вас уведомляют (email, Slack, webhook, в панели управления) плюс рабочий процесс инцидентов для их сортировки. -- **CLI и AI-ассистент** — клиент терминала (`agenteye`) и встроенный ассистент для вопросов на простом английском языке. +- **События** — необработанный, пошаговый журнал каждого запуска агента (вызовы инструментов, вызовы модели, хуки, ошибки). +- **Сеансы** — эти события свёрнуты в одну строку на запуск, каждый **автоматически оценивается** и получает оценку. +- **Оценки** — оценки качества, полученные от ваших собственных служб оценки, чтобы снижение качества проявлялось без ручной проверки. +- **Запросы и панели управления** — сохранённый SQL ClickHouse по вашим данным, визуализированный в общих панелях управления с охватом организации. +- **Оповещения и инциденты** — правила по пороговым значениям, которые оповещают вас (по электронной почте, Slack, webhook, на панели управления) и рабочий процесс инцидентов для их классификации. +- **CLI и ассистент AI** — клиент терминала (`agenteye`) и ассистент на панели управления для задания вопросов на простом английском языке. -Вы запускаете всё это в своей инфраструктуре как один стек Docker Compose (это руководство), как производственную установку Kubernetes или как один совместно размещённый pod. Остаток руководства настраивает стек Compose от начала до конца. +Вы запускаете всё это в своей собственной инфраструктуре как единый стек Docker Compose (это руководство), production-установку Kubernetes или отдельный совмещённый pod. Остальная часть этого руководства настраивает стек Compose с начала до конца. --- ## Шаг 1: Аутентификация -Все артефакты AgentEye распространяются из организации GitHub `agenteye-enterprise`. Как разработчик enterprise вы можете сгенерировать свой собственный GitHub PAT. Следуйте [enterprise-docs/github-token.md](/ru/agenteye/github-token) для точных шагов и необходимых разрешений. +Все артефакты AgentEye распространяются из организации GitHub `agenteye-enterprise`. Как корпоративный разработчик, вы можете создать свой собственный GitHub PAT. Следуйте [enterprise-docs/github-token.md](/ru/agenteye/github-token) для точных шагов и необходимых разрешений. ```bash export AGENTEYE_TOKEN= @@ -42,9 +42,9 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin ## Шаг 2: Развёртывание сервера и панели управления -Сервер получает события от сборщиков и делает их доступными для запроса; панель управления — это место, где вы их изучаете. Поступившие события и аналитика хранятся в ClickHouse (требуемое хранилище аналитики), а Postgres хранит операционное состояние, такое как организации, пользователи, ключи API, панели управления и сохранённые запросы. +Сервер получает события от сборщиков и делает их доступными для запросов; панель управления — это место, где вы их исследуете. Принятые события и аналитика находятся в ClickHouse (необходимое хранилище аналитики), а Postgres содержит операционное состояние, такое как организации, пользователи, API-ключи, панели управления и сохранённые запросы. -**Загрузите опубликованный файл композа:** +**Загрузите опубликованный файл compose:** ```bash mkdir -p ./agenteye @@ -57,36 +57,30 @@ cd agenteye **Установите ваши секреты:** -Создайте файл `.env`, чтобы развёртывание не запускалось с учётными данными по умолчанию `admin`. Минимально установите `ADMIN_KEY` и `POSTGRES_PASSWORD`: +Создайте файл `.env`, чтобы развёртывание не использовало учётные данные `admin` по умолчанию. Как минимум установите `ADMIN_KEY` и `POSTGRES_PASSWORD`: ```bash POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -Также экспортируйте `ADMIN_KEY` в вашей текущей оболочке, чтобы более поздние шаги (например, `curl` на Шаге 3) могли ссылаться на него напрямую: - -```bash -export ADMIN_KEY=your-admin-secret -``` - **Запустите стек:** ```bash docker compose up -d ``` -Это включает полный стек, включая требуемое хранилище аналитики ClickHouse и дополнительный кеш Redis, наряду с сервером и панелью управления. ClickHouse должен быть здоров, чтобы сервер запустился. +Это запускает полный стек, включая необходимое хранилище аналитики ClickHouse и опциональный кэш Redis, вместе с сервером и панелью управления. ClickHouse должен быть здоровым, чтобы сервер запустился. -Сервер теперь прослушивает `http://localhost:8080`, а панель управления — `http://localhost:3000`. +Сервер теперь слушает на `http://localhost:8080`, а панель управления на `http://localhost:3000`. -Для производственных развёртываний (пользовательский Postgres, TLS, reverse proxy), см. [enterprise-docs/deployment.md](/ru/agenteye/deployment). +Для production-развёртываний (пользовательский Postgres, TLS, обратный прокси) см. [enterprise-docs/deployment.md](/ru/agenteye/deployment). --- -## Шаг 3: Создание ключа API для сборщика +## Шаг 3: Создание API-ключа для сборщика -Каждый сборщик аутентифицируется с помощью ограниченного ключа API. Используйте `ADMIN_KEY`, который вы установили на Шаге 2, чтобы создать один: +Каждый сборщик аутентифицируется с помощью защищённого API-ключа. Используйте `ADMIN_KEY`, который вы установили на шаге 2, чтобы создать его: ```bash curl -s -X POST http://localhost:8080/keys \ @@ -95,15 +89,15 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -Вы предоставляете значение `key` самостоятельно; используйте его в конфигурации сборщика на Шаге 4. См. [enterprise-docs/api-keys.md](/ru/agenteye/api-keys) для полного управления ключами. +Вы самостоятельно предоставляете значение `key`; используйте его в конфигурации сборщика на шаге 4. См. [enterprise-docs/api-keys.md](/ru/agenteye/api-keys) для полного управления ключами. --- ## Шаг 4: Установка сборщика -На каждой машине, где запускаются ваши AI-агенты, установите демон сборщика. +На каждой машине, которая запускает ваши AI-агенты, установите демон сборщика. -**Загрузите бинарный файл (Linux x86_64):** +**Загрузите двоичный файл (Linux x86_64):** ```bash VERSION=0.0.1-beta.13 @@ -114,7 +108,7 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> Это загружает сборку **Linux x86_64**. Для macOS (Apple Silicon или Intel), Linux arm64 или Docker/systemd/launchd настройки, см. [collector-installation.md](/ru/agenteye/collector-installation), которая содержит ссылки загрузки для каждой платформы — вышеуказанная команда устанавливает бинарный файл Linux, который не будет запускаться в других местах. +> Это загружает сборку **Linux x86_64**. Для macOS (Apple Silicon или Intel), Linux arm64 или Docker / systemd / launchd установки см. [collector-installation.md](/ru/agenteye/collector-installation), которая список загрузки для каждой платформы — команда выше устанавливает двоичный файл Linux, который не будет работать нигде в другом месте. **Настройка:** @@ -134,19 +128,19 @@ EOF agenteye-collector start ``` -Проверьте связь с одноразовой очисткой (выходит после очистки любых ожидающих событий): +Проверьте подключение одноразовой очисткой (выходит после слива всех ожидающих событий): ```bash agenteye-collector flush ``` -Для Docker, systemd и launchd настройки см. [enterprise-docs/collector-installation.md](/ru/agenteye/collector-installation). +Для Docker, systemd и launchd установки см. [enterprise-docs/collector-installation.md](/ru/agenteye/collector-installation). --- ## Шаг 5: Установка Python SDK -На каждой машине, где вы хотите подключить код агента, установите wheel из GitHub Releases. +На каждой машине, где вы хотите инструментировать код агента, установите wheel из GitHub Releases. ```bash VERSION=0.0.1b9 @@ -158,9 +152,9 @@ pip install agenteye-${VERSION}-py3-none-any.whl --- -## Шаг 6: Подключение вашего агента +## Шаг 6: Инструментирование вашего агента -Добавьте события в код вашего агента. Минимально испускайте `agent_start` и `agent_end`: +Добавьте события в код вашего агента. Как минимум выпускайте `agent_start` и `agent_end`: ```python import agenteye @@ -180,7 +174,7 @@ agenteye.event.agent_end( ) ``` -События буферизируются и очищаются в `$AGENTEYE_HOME/events/` (или `~/.agenteye/events/`, если `AGENTEYE_HOME` не установлена) каждые 500 мс. Сборщик их автоматически берёт. +События буферизируются и сбрасываются в `$AGENTEYE_HOME/events/` (или `~/.agenteye/events/`, если `AGENTEYE_HOME` не установлена) каждые 500 мс. Сборщик автоматически их подхватывает. См. [enterprise-docs/python-sdk.md](/ru/agenteye/python-sdk) для полного API событий. @@ -188,48 +182,48 @@ agenteye.event.agent_end( ## Шаг 7: Просмотр событий на панели управления -Откройте `http://your-dashboard-host:3000` и войдите. AgentEye отправляет вам одноразовый код по электронной почте (или ссылку для одного клика), поэтому нет пароля для управления. +Откройте `http://your-dashboard-host:3000` и войдите. AgentEye отправляет вам одноразовый код по электронной почте (или ссылку one-click magic), поэтому нет необходимости управлять паролем. ![Экран входа AgentEye, который отправляет одноразовый код на вашу электронную почту](/agenteye/images/login.png) -После входа страница **События** показывает живой журнал всех поступивших событий. Фильтруйте по `session_id` или `agent_id`, чтобы углубиться в конкретный прогон. +После входа страница **Events** показывает живой журнал всех принятых событий. Фильтруйте по `session_id` или `agent_id` для углубления в конкретный запуск. -![Живой поток событий, раскрашенный по типу события и фильтруемый по окружению, агенту и сессии](/agenteye/images/events-stream.png) +![Живой поток Events, цветовой код по типу события и фильтруется по окружению, агенту и сеансу](/agenteye/images/events-stream.png) -Страница **Сессии** объединяет эти события в одну строку на прогон. AgentEye автоматически оценивает завершённые сессии, так что каждый прогон получает балл, и регрессии качества всплывают без ручной проверки; последний балл оценки появляется на каждой строке с первого взгляда: +Страница **Sessions** сворачивает эти события в одну строку на запуск. AgentEye автоматически оценивает завершённые сеансы, поэтому каждый запуск получает оценку и регрессии качества проявляются без ручной проверки; последний балл оценки появляется на каждой строке с первого взгляда: -![Список сессий, одна строка на прогон, со статусными значками и значками балла оценки](/agenteye/images/sessions-list.png) +![Список сеансов, одна строка на запуск, с пилюлями статуса и значками оценки](/agenteye/images/sessions-list.png) -Чтобы настроить, как оцениваются сессии, см. [enterprise-docs/evaluation-suite.md](/ru/agenteye/evaluation-suite). +Для настройки того, как оцениваются сеансы, см. [enterprise-docs/evaluation-suite.md](/ru/agenteye/evaluation-suite). -Нажмите на любую сессию, чтобы открыть её **граф выполнения**, представление в стиле git того, как агенты, инструменты, хуки и вызовы модели разворачивались во времени, с параллельными подагентами на их собственных полосах и разбивкой по прогону на правой панели: +Нажмите на любой сеанс, чтобы открыть его **граф выполнения**, представление в стиле git того, как агенты, инструменты, хуки и вызовы моделей развёртывались с течением времени, с параллельными подагентами на своих дорожках и разбивкой по запускам в правой колонке: -![Граф выполнения сессии в стиле git рядом с временной шкалой её событий, с панелью разбивки инструмента/модели/хука](/agenteye/images/session-detail.png) +![Граф выполнения сеанса в стиле git рядом с его временной шкалой событий, с панелью разбивки инструмент/модель/хук](/agenteye/images/session-detail.png) --- -## Шаг 8: Изучение, графики и оповещения +## Шаг 8: Исследуйте, отображайте в диаграммах и предупреждайте -С поступлением событий страницы **анализа** превращают неотработанную активность в ответы, так что вы можете измерить поведение агента, поделиться результатами с командой и получить оповещение в момент, когда что-то регрессирует. Страницы панели управления имеют организационную область, поэтому URLs, которые вы видите в адресной строке, имеют префикс с вашим организационным слагом (`//…`). +С потоком событий, страницы **analyze** превращают необработанную активность в ответы, поэтому вы можете измерять поведение агента, делиться находками с командой и получать оповещение в момент, когда что-то регрессирует. Страницы панели управления имеют охват организации, поэтому URL-адреса, которые вы видите в адресной строке, имеют префикс с вашим слагом организации (`//…`). -- **Запросы** (`//queries`): начните с библиотеки сохранённых, повторно используемых запросов над вашими событиями и оценками (встроенные предустановки плюс ваши собственные)… +- **Queries** (`//queries`): начните с библиотеки сохранённых, многократно используемых запросов по вашим событиям и оценкам (встроенные предустановки плюс ваши собственные)… -![Библиотека сохранённых запросов: сетка повторно используемых запросов, как встроенные предустановки, так и пользовательские](/agenteye/images/queries.png) +![Библиотека сохранённых запросов: сетка многократно используемых запросов, как встроенных предустановок, так и пользовательских](/agenteye/images/queries.png) - …затем откройте один в SQL-компоновщике, чтобы его настроить и запустить с живыми результатами: + …затем откройте один в SQL-компоновщике, чтобы настроить его и запустить с живыми результатами: -![Компоновщик SQL-запросов, запускающий сохранённый запрос, с боковой панелью схемы и живой сеткой результатов](/agenteye/images/query-lab.png) +![Композитор SQL-запросов запускает сохранённый запрос с боковой панелью схемы и живой сеткой результатов](/agenteye/images/query-lab.png) -- **Панели управления** (`//dashboards`): закрепите запросы как линейные, столбцовые, области или круговые плитки в общих, организационных панелях управления. +- **Dashboards** (`//dashboards`): закрепите запросы как линейные, столбчатые, площадные или круговые плитки в общие панели управления на уровне организации. -![Панель управления, построенная из сохранённых запросов: линия событий в час, столбцовая диаграмма ошибок по типу, диаграмма площади задержки и токены по модели](/agenteye/images/dashboard-fleet.png) +![Панель управления, построенная из сохранённых запросов: линия событий в час, столбец ошибок по типу, диаграмма площади задержки и токены по модели](/agenteye/images/dashboard-fleet.png) -- **Оповещения** (`//alerts`): повысьте любой порог до правила уведомления, которое уведомляет по email, Slack, webhook или в панель управления. См. [enterprise-docs/alerts.md](/ru/agenteye/alerts). +- **Alerts** (`//alerts`): превратите любой порог в правило оповещения, которое уведомляет по электронной почте, Slack, webhook или на панели управления. См. [enterprise-docs/alerts.md](/ru/agenteye/alerts). --- ## Следующие шаги -- [Развёртывание](/ru/agenteye/deployment): укрепление для производства -- [Ключи API](/ru/agenteye/api-keys): управление доступом -- [Устранение неполадок](/ru/agenteye/troubleshooting): диагностика проблем \ No newline at end of file +- [Развёртывание](/ru/agenteye/deployment): укрепите для production +- [API-ключи](/ru/agenteye/api-keys): управляйте доступом +- [Устранение проблем](/ru/agenteye/troubleshooting): диагностируйте проблемы \ No newline at end of file diff --git a/docs/ru/agenteye/managed-deployment.mdx b/docs/ru/agenteye/managed-deployment.mdx index 5084879b..593ca202 100644 --- a/docs/ru/agenteye/managed-deployment.mdx +++ b/docs/ru/agenteye/managed-deployment.mdx @@ -1,171 +1,171 @@ --- -title: "Управляемое развёртывание в вашем кластере Kubernetes" -description: "Документация по управляемому развёртыванию AgentEye в вашем кластере Kubernetes." +title: "Управляемое развертывание в вашем кластере Kubernetes" +description: "Документация по управляемому развертыванию AgentEye в вашем кластере Kubernetes." --- -AgentEye — это самостоятельно развёртываемая платформа наблюдения и оценки для AI и LLM агентов. Она фиксирует сеансы агентов, вызовы инструментов, запросы к моделям и ошибки, преобразует их в доступные для поиска аналитику и оценки, и отображает результаты в панели управления с опциональным помощником AI только для чтения. +AgentEye — это самостоятельно размещаемая платформа наблюдения и оценки для AI и LLM агентов. Она захватывает сессии агентов, вызовы инструментов, запросы к моделям и ошибки, преобразует их в поддерживающую поиск аналитику и оценки, а результаты отображает на панели управления с необязательным ассистентом только для чтения на основе AI. -В модели управляемого развёртывания вы предоставляете выделенный кластер Kubernetes, а Exosphere запускает полную платформу внутри него, развёртывая, настраивая, управляя, выполняя резервное копирование и обновляя каждый компонент от вашего имени. Ваша команда получает преимущества платформы (видимость агентов, аналитику, оценку и опциональный помощник) без необходимости управлять базами данных, сертификатами и обновлениями. Все данные остаются в вашей облачной учётной записи. +В модели управляемого развертывания вы предоставляете выделенный кластер Kubernetes, а Exosphere запускает полную платформу внутри него, развертывая, настраивая, эксплуатируя, создавая резервные копии и обновляя каждый компонент от вашего имени. Ваша команда получает все преимущества платформы (видимость агентов, аналитику, оценку и необязательного ассистента) без необходимости управлять базами данных, сертификатами или обновлениями. Все данные остаются в вашем облачном аккаунте. --- ## Предварительные требования -- **GitHub PAT** для загрузки образов контейнеров и скачивания артефактов (см. [Настройка GitHub Token](/ru/agenteye/github-token)) +- **GitHub PAT** для получения образов контейнеров и загрузки артефактов (см. [enterprise-docs/github-token.md](/ru/agenteye/github-token)) - **Выделенный кластер Kubernetes** (см. требования ниже) -- **Хранилище для резервных копий** баз данных -- **Сетевая связность**: входящий трафик на порт 443 к балансировщику нагрузки кластера +- **Бакет хранилища** для резервных копий базы данных +- **Сетевое соединение**: входящий трафик на порту 443 к load balancer кластера --- -## Шаг 1: Подготовка выделенного кластера Kubernetes +## Шаг 1: Подготовьте выделенный кластер Kubernetes -Создайте кластер Kubernetes, выделенный для AgentEye. Он не должен быть общим с другими рабочими нагрузками, чтобы полная платформа (сервисы приложения, базы данных, аналитика и кэширование) работала в изоляции без влияния на вашу существующую инфраструктуру. +Создайте кластер Kubernetes, выделенный для AgentEye. Он не должен использоваться совместно с другими рабочими нагрузками, чтобы полная платформа (сервисы приложений, базы данных, аналитика и кеширование) работала изолированно без влияния на вашу существующую инфраструктуру. | Требование | Детали | |---|---| -| **Дистрибутив** | Любой совместимый Kubernetes: EKS, GKE, AKS или самоуправляемый | -| **Версия** | 1.27 или выше | -| **Пул узлов** | Минимум: **3 узла, 4 vCPU / 8 ГБ ОЗУ каждый** (стандартные экземпляры общего назначения) | -| **Хранилище** | Класс StorageClass по умолчанию, который выделяет блочные тома (например `gp3` на AWS, `pd-ssd` на GCP) | -| **Балансировщик нагрузки** | Кластер должен иметь возможность выделять облачные сервисы LoadBalancer (по умолчанию на EKS, GKE, AKS) | +| **Распределение** | Любой соответствующий стандарту Kubernetes: EKS, GKE, AKS или самостоятельно управляемый | +| **Версия** | 1.27 или позже | +| **Пул узлов** | Минимум: **3 узла, по 4 vCPU / 8 ГБ ОЗУ** (стандартные универсальные инстансы) | +| **Хранилище** | StorageClass по умолчанию, который подготавливает блочные тома (например `gp3` на AWS, `pd-ssd` на GCP) | +| **Load Balancer** | Кластер должен иметь возможность подготавливать облачные сервисы LoadBalancer (по умолчанию на EKS, GKE, AKS) | -> Exosphere устанавливает и управляет всем остальным внутри кластера: контроллеры ingress, сертификаты TLS, базы данных, кэширование, мониторинг и все развёртывания приложения. +> Exosphere устанавливает и управляет всем остальным внутри кластера: контроллеры ingress, TLS сертификаты, базы данных, кеширование, мониторинг и все развертывания приложений. --- -## Шаг 2: Предоставление доступа команде AgentEye +## Шаг 2: Предоставьте доступ команде AgentEye -Exosphere требуется доступ cluster-admin (или эквивалентный широкий RBAC) для управления пространствами имён, определениями пользовательских ресурсов, контроллерами ingress и провизионерами хранилища. +Exosphere нужен доступ cluster-admin (или эквивалентный широкий RBAC) для управления пространствами имен, пользовательскими определениями ресурсов, контроллерами ingress и провизионерами хранилища. | Требование | Детали | |---|---| -| **Метод доступа** | Роль IAM (предпочтительно для EKS/GKE), kubeconfig или доступ на основе SSO | -| **VPN / bastion** | Если сервер API Kubernetes приватный, предоставьте учётные данные VPN или доступ к bastion для операционной группы Exosphere | +| **Метод доступа** | IAM роль (предпочтительно для EKS/GKE), kubeconfig или доступ на основе SSO | +| **VPN / bastion** | Если API сервер Kubernetes приватный, предоставьте учетные данные VPN или доступ к bastion для команды операций Exosphere | --- -## Шаг 3: Настройка сетевой связности +## Шаг 3: Настройте сетевое соединение -Ваша сетевая группа должна разрешить входящий трафик на **порт 443** к балансировщикам нагрузки кластера. Развёртывание использует два отдельных балансировщика нагрузки: один для приёма событий (защищённый mTLS) и один для панели управления: +Ваша сетевая команда должна разрешить входящий трафик на **порту 443** к load balancer'ам кластера. Развертывание работает с двумя отдельными load balancer'ами: один для приема событий (защищен mTLS) и один для панели управления: -| Трафик | Источник | Назначение | Безопасность | +| Трафик | Источник | Адресат | Безопасность | |---|---|---|---| -| **Приём событий** | Подсистемы сборщика в ваших кластерах | Балансировщик Ingest LoadBalancer, порт 443 | mTLS (клиентский сертификат) + API ключ | -| **Панель управления** | Браузеры разработчиков | Балансировщик Dashboard LoadBalancer, порт 443 | HTTPS на вашем домене, вход без пароля с OTP по электронной почте | +| **Прием событий** | Collector pods в ваших кластерах | Ingest LoadBalancer, порт 443 | mTLS (сертификат клиента) + API ключ | +| **Панель управления** | Браузеры разработчиков | Dashboard LoadBalancer, порт 443 | HTTPS на вашем домене, вход без пароля по OTP по email | -Конечная точка приёма защищена взаимным TLS; сборщики должны предоставлять действительный клиентский сертификат **и** действительный API ключ при каждом запросе. Панель управления работает на отдельном балансировщике нагрузки и хостнейме с ограничением входа на внесённые в список разрешённые адреса электронной почты и домены. +Endpoint приема защищен взаимной TLS; collectors должны предоставить действительный сертификат клиента **и** действительный API ключ при каждом запросе. Панель управления работает на собственном load balancer'е и имени хоста, с доступом ограниченным допустимыми адресами email/доменами. -**DNS записи (одноразово):** вы создаёте две CNAME записи под доменом, который вы контролируете — одну для конечной точки приёма и одну для панели управления (например `agenteye.your-company.example`) — указывающие на хостнеймы балансировщика нагрузки, которые предоставляет Exosphere. Exosphere затем автоматически выделяет общедоступные доверенные сертификаты TLS для обоих хостнеймов, включая обновления. +**DNS записи (одноразово):** вы создаете две CNAME записи под доменом, который вы контролируете — одну для endpoint'а приема и одну для панели управления (например `agenteye.your-company.example`) — указывающие на имена хостов load balancer'ов, которые предоставит Exosphere. Exosphere затем автоматически подготавливает публично доверенные TLS сертификаты для обоих имен хостов, включая обновления. -> **Примечание о порте 80:** автоматическое выделение сертификатов и их обновление проверяются через HTTP на порту 80 каждого балансировщика нагрузки. Если ваша политика безопасности требует ограничения балансировщика нагрузки панели управления диапазонами корпоративных IP, сообщите об этом Exosphere сначала — мы переключимся на метод проверки на основе DNS (одна дополнительная DNS запись на вашей стороне), чтобы обновления продолжали работать за ограничением. +> **Замечание о порту 80:** автоматическое выдание и обновление сертификатов проверяется по HTTP на порту 80 каждого load balancer'а. Если ваша политика безопасности требует ограничения dashboard load balancer'а корпоративными диапазонами IP, сообщите об этом Exosphere — мы переключимся на метод валидации на основе DNS (одна дополнительная DNS запись с вашей стороны), чтобы обновления продолжали работать за ограничением. -> **Исходящий трафик:** узлы кластера требуют доступ в интернет для загрузки образов контейнеров из `ghcr.io`. Если ваша сеть ограничивает исходящий трафик, добавьте `ghcr.io` в список разрешённых или зеркалируйте образы в ваш внутренний реестр. +> **Исходящий трафик:** узлы кластера нуждаются в доступе в интернет для получения образов контейнеров из `ghcr.io`. Если ваша сеть ограничивает исходящий трафик, добавьте `ghcr.io` в белый список или зеркалируйте образы в ваш внутренний реестр. --- -## Шаг 4: Предоставление хранилища для резервных копий +## Шаг 4: Предоставьте бакет хранилища для резервных копий -Резервные копии баз данных хранятся в облачном хранилище, которым вы владеете. +Резервные копии базы данных сохраняются в облачном бакете хранилища, который вы владеете. | Требование | Детали | |---|---| | **Сервис** | S3 (AWS), GCS (GCP) или Azure Blob Storage | -| **Доступ** | Предоставьте доступ на запись узлам кластера через роль IAM для сервисных учётных записей (IRSA на EKS, Workload Identity на GKE) или предоставьте учётные данные | -| **Хранение** | Вы контролируете политику жизненного цикла хранилища (период хранения, правила архивации). Exosphere пишет резервные копии; вы решаете, как долго их хранить | +| **Доступ** | Предоставьте доступ на запись узлам кластера через IAM роль для сервисных аккаунтов (IRSA на EKS, Workload Identity на GKE) или предоставьте учетные данные | +| **Хранение** | Вы контролируете политику жизненного цикла бакета (период хранения, правила архивирования). Exosphere пишет резервные копии; вы решаете, как долго их хранить | -Одна ежедневная резервная копия выгружает PostgreSQL (состояние отношений) и ClickHouse (события и оценки) в один сжатый архив и загружает его в ваше хранилище. Резервные копии также выполняются перед каждым обновлением. +Одна ежедневная резервная копия сохраняет PostgreSQL (состояние реляционных данных) и ClickHouse (события и оценки) в один сжатый архив и загружает его в ваш бакет. Резервные копии также создаются перед каждым обновлением. --- -## Шаг 5: Назначение ответственного +## Шаг 5: Обозначьте контактное лицо -Предоставьте одного человека или канал Slack/Teams на вашей стороне для проблем уровня кластера: здоровье узлов, лимиты облачной учётной записи, изменения сети. Ежедневные операции не требуют участия этого контакта. +Предоставьте одного человека или канал Slack/Teams на вашей стороне для проблем уровня кластера: здоровье узлов, лимиты облачного аккаунта, изменения сети. Ежедневные операции не включают это контактное лицо. --- -## Что мы развёртываем +## Что мы развертываем -Когда Exosphere получит доступ к кластеру, будут развёрнуты и управляться следующие компоненты: +Как только Exosphere получит доступ к кластеру, развертываются и управляются следующие компоненты: | Компонент | Роль | |---|---| -| **AgentEye Server** | HTTP API, который получает события от сборщиков, запускает аналитику и обслуживает данные панели управления | -| **Панель управления** | Веб-интерфейс для просмотра сеансов агентов, вызовов инструментов, запросов к моделям и ошибок; размещает опциональный помощник AI только для чтения | -| **ClickHouse** | Требуемое основное хранилище для полученных событий, аналитики и оценок | -| **PostgreSQL** | Хранилище отношений для организаций, API ключей, пользователей, панелей управления и сохранённых запросов | -| **Redis** | Опциональный общий кэш и бэкенд для ограничения скорости; платформа деградирует корректно при его недоступности | -| **Помощник AI (опционально)** | Внутренний контейнер помощника только для чтения; остаётся отключённым до настройки конечной точки LLM | -| **Контроллеры ingress** | Два балансировщика нагрузки (один для защищённого mTLS приёма, один для панели управления) прерывающие TLS с общедоступными доверенными сертификатами с автоматическим обновлением и принуждающие mTLS на конечной точке приёма | -| **cert-manager** | Автоматизирует выделение сертификатов TLS и выделение клиентских mTLS сертификатов | -| **Мониторинг сертификатов** | Запланированное задание проверяет срок действия сертификатов и отправляет оповещения (например в Slack) по мере приближения обновлений сертификатов | - -Управляемое предложение также работает с конвейером оценки платформы, который оценивает активность агента по вашим критериям оценки. Смотрите [Assistant](/ru/agenteye/assistant) и [Evaluation Suite](/ru/agenteye/evaluation-suite) для информации о возможностях. +| **AgentEye Server** | HTTP API, который получает события от collectors'ов, запускает аналитику и обслуживает данные для панели управления | +| **Dashboard** | Веб-интерфейс для просмотра сессий агентов, вызовов инструментов, запросов к моделям и ошибок; размещает необязательного ассистента только для чтения на основе AI | +| **ClickHouse** | Требуемое хранилище для полученных событий, аналитики и оценок | +| **PostgreSQL** | Реляционное хранилище для организаций, API ключей, пользователей, панелей управления и сохраненных запросов | +| **Redis** | Необязательный общий кеш и backend'ов для ограничения скорости; платформа корректно деградирует, если он недоступен | +| **AI ассистент (необязательно)** | Внутренний контейнер ассистента только для чтения; остается отключенным до момента настройки endpoint'а LLM | +| **Контроллеры Ingress** | Два load balancer'а (один для защищенного mTLS приема, один для панели управления), завершающие TLS с публично доверенными, автоматически обновляемыми сертификатами и применяющие mTLS на endpoint'е приема | +| **cert-manager** | Автоматизирует подготовку TLS сертификатов и выдачу сертификатов mTLS клиентов | +| **Мониторинг сертификатов** | Запланированное задание проверяет истечение срока сертификатов и отправляет оповещения (например в Slack) когда сертификаты приближаются к обновлению | + +Управляемое предложение также включает работу конвейера оценки платформы, который оценивает активность агента в соответствии с вашими критериями оценки. См. [enterprise-docs/assistant.md](/ru/agenteye/assistant) и [enterprise-docs/evaluation-suite.md](/ru/agenteye/evaluation-suite) для информации о том, что обеспечивают эти возможности. --- ## Что мы предоставляем вам -После завершения развёртывания вы получаете: +После завершения развертывания вы получаете: | Элемент | Детали | |---|---| -| **URL панели управления** | Хостнейм под вашим доменом (например `https://agenteye.your-company.example`), обслуживаемый с общедоступным доверенным сертификатом TLS с автоматическим обновлением. Вы создаёте одну CNAME запись на хостнейм балансировщика нагрузки, который мы предоставляем; вход осуществляется через OTP по электронной почте без пароля | -| **Конечная точка сборщика** | Путь `/events` хостнейма приёма (например `https://ingest.your-company.example/events`), защищённый mTLS | -| **Пакет клиентского сертификата** | За кластер: клиентский сертификат, приватный ключ и сертификат CA поставляются как манифест Kubernetes Secret. Применяется один раз за кластер | -| **GitHub PAT** | Для загрузки бинарных файлов сборщика и пакетов Python SDK | -| **API ключи сборщика** | Ограниченные ключи с разрешением `events:add`, по одному на развёртывание сборщика | -| **Руководства по установке** | Пошаговая документация для сборщика и Python SDK | +| **URL панели управления** | Имя хоста под вашим доменом (например `https://agenteye.your-company.example`), обслуживаемое с публично доверенным, автоматически обновляемым TLS сертификатом. Вы создаете одну CNAME запись на имя хоста load balancer'а, который мы предоставим; вход без пароля по OTP | +| **Endpoint сборщика** | Путь `/events` имени хоста приема (например `https://ingest.your-company.example/events`), защищенный mTLS | +| **Пакет сертификата клиента** | За кластер: сертификат клиента, приватный ключ и сертификат CA поставляются как манифест Kubernetes Secret. Примените один раз за кластер | +| **GitHub PAT** | Для загрузки бинарных файлов collector'а и пакетов Python SDK | +| **Collector API ключи** | Ключи, ограниченные областью `events:add`, один за развертывание collector'а | +| **Руководства установки** | Пошаговые документы для collector'а и Python SDK | --- -## Что вы делаете после установки +## Что вы делаете после настройки -Ваша единственная текущая работа — на ваших собственных машинах с агентами, а не на кластере AgentEye: +Ваша единственная постоянная работа — на ваших собственных машинах с агентами, а не в кластере AgentEye: -1. **Установите сборщик** в каждый кластер Kubernetes, работающий с AI агентами: смонтируйте клиентский сертификат и настройте URL конечной точки и API ключ. Смотрите [Collector Installation](/ru/agenteye/collector-installation). -2. **Интегрируйте Python SDK** в код вашего агента. Смотрите [Python SDK](/ru/agenteye/python-sdk). -3. **Откройте панель управления** в браузере для просмотра активности агента. +1. **Установите collector** в каждом кластере Kubernetes, на котором работают AI агенты: установите сертификат клиента и настройте URL endpoint'а и API ключ. См. [enterprise-docs/collector-installation.md](/ru/agenteye/collector-installation). +2. **Интегрируйте Python SDK** в код вашего агента. См. [enterprise-docs/python-sdk.md](/ru/agenteye/python-sdk). +3. **Откройте панель управления** в браузере для просмотра активности агентов. -Никаких операций с кластером, никакого управления базами данных, никаких обновлений сертификатов, никаких обновлений. +Никакие операции с кластером, управление базами данных, обновления сертификатов, никакие обновления. --- ## Безопасность -- **Данные остаются в вашей облачной учётной записи.** Кластер, хранилище и базы данных все работают в вашей среде. Никакие данные не выходят за вашу границу. -- **Вы контролируете доступ.** Кластер находится в вашей учётной записи. Вы можете проверять, мониторить или отозвать доступ Exosphere в любое время. Все операции проходят через журнал аудита вашего облака (CloudTrail, GCP Audit Logs и т.д.). -- **mTLS при приёме событий.** Каждый запрос сборщика требует как действительный клиентский сертификат, так и API ключ. Утёкший ключ бесполезен без сертификата; украденный сертификат бесполезен без действительного ключа. -- **Контроль доступа к панели управления.** Панель управления работает на отдельном балансировщике нагрузки, отдельно от приёма событий, и вход осуществляется через OTP по электронной почте без пароля, ограниченный адресами электронной почты и доменами, которые вы внесли в список разрешённых. Ограничение диапазона источника IP на балансировщике нагрузки доступно по запросу; так как автоматическое обновление сертификата должно достичь балансировщика нагрузки, Exosphere сочетает ограничение с проверкой сертификата на основе DNS, чтобы обновления продолжали работать. -- **Сертификаты за кластер.** Каждый из ваших кластеров получает собственный клиентский сертификат. Если один кластер скомпрометирован, этот сертификат отзывается независимо без влияния на остальные. +- **Данные остаются в вашем облачном аккаунте.** Кластер, хранилище и базы данных работают в вашей среде. Никакие данные не выходят за пределы вашей границы. +- **Вы контролируете доступ.** Кластер находится в вашем аккаунте. Вы можете аудировать, мониторить или отозвать доступ Exosphere в любой момент. Все операции проходят через журнал аудита вашего облака (CloudTrail, GCP Audit Logs и т. д.). +- **mTLS при приеме событий.** Каждый запрос collector'а требует как действительного сертификата клиента, так и API ключа. Утекший ключ бесполезен без сертификата; украденный сертификат бесполезен без действительного ключа. +- **Контроль доступа к панели управления.** Панель управления работает на собственном load balancer'е, отдельно от приема событий, и вход без пароля по OTP ограничен адресами email/доменами, которые вы добавляете в белый список. Белый список диапазонов IP источников на load balancer'е доступен по запросу; поскольку автоматическое обновление сертификатов должно достичь load balancer'а, Exosphere сочетает ограничение с валидацией сертификатов на основе DNS, чтобы обновления продолжали работать. +- **Сертификаты по кластерам.** Каждый из ваших кластеров получает собственный сертификат клиента. Если один кластер скомпрометирован, этот сертификат отозывается независимо без влияния на остальные. --- -## График развёртывания +## Временная шкала развертывания -| Фаза | Длительность | Ваше участие | +| Фаза | Продолжительность | Ваше участие | |---|---|---| | **Подготовка кластера** | 1-2 дня | Подготовьте кластер и предоставьте Exosphere доступ | -| **Настройка платформы** | 1 день | Нет; Exosphere устанавливает все компоненты инфраструктуры | -| **Развёртывание приложения** | 1 день | Нет; Exosphere развёртывает сервер, панель управления и создаёт API ключи | -| **Развёртывание сборщика** | 1-3 дня | Установите сборщики в ваши кластеры (с руководством от Exosphere) | -| **Работа в production** | 1 неделя | Нет; Exosphere мониторит и настраивает | +| **Настройка платформы** | 1 день | Никакое; Exosphere устанавливает все компоненты инфраструктуры | +| **Развертывание приложения** | 1 день | Никакое; Exosphere развертывает сервер, панель управления и создает API ключи | +| **Развертывание collector'а** | 1-3 дня | Установите collector'ов в ваши кластеры (с рекомендациями от Exosphere) | +| **Доработка в production** | 1 неделя | Никакое; Exosphere мониторит и тонко настраивает | -Обычный итог: **~2 недели** от начала до готовности к production. +Типичный итог: **~2 недели** от начала до production-готовности. --- ## Поддержка -По вопросам или проблемам обратитесь в Exosphere на `support@exosphere.host`. +По вопросам или проблемам свяжитесь с Exosphere по адресу `support@exosphere.host`. --- ## Следующие шаги -- [Getting Started](/ru/agenteye/getting-started): сквозное руководство -- [Collector Installation](/ru/agenteye/collector-installation): установка и настройка сборщика +- [Getting Started](/ru/agenteye/getting-started): полное пошаговое руководство +- [Collector Installation](/ru/agenteye/collector-installation): установка и настройка collector'а - [Python SDK](/ru/agenteye/python-sdk): инструментирование кода вашего агента - [API Keys](/ru/agenteye/api-keys): управление доступом и разрешениями -- [Troubleshooting](/ru/agenteye/troubleshooting): часто встречающиеся проблемы и решения \ No newline at end of file +- [Troubleshooting](/ru/agenteye/troubleshooting): типичные проблемы и решения \ No newline at end of file diff --git a/docs/tr/agenteye/audits.mdx b/docs/tr/agenteye/audits.mdx index b5f48779..8b6456a6 100644 --- a/docs/tr/agenteye/audits.mdx +++ b/docs/tr/agenteye/audits.mdx @@ -1,107 +1,106 @@ --- -title: "Denetimler — agentic iyileştirme tespiti" -description: "AgentEye Denetimleri — agentic iyileştirme tespiti belgelendirmesi." +title: "Denetimler — agentic improvement detection" +description: "AgentEye Denetimler — agentic improvement detection belgelendirmesi." --- -Denetimler, agent günlüklerinizi **oturumlarda** tarayarak iyileştirmeye değer şeyleri bulan yinelenen işlerdir. Bir uyarı zaten bildiğiniz bir metriği gerçek zamana yakın şekilde izlerken, bir denetim *araştırır*: belirlediğiniz bir programa göre, pencere üzerinde deterministik bir politika geçişi çalıştırır, ardından bir **AI güvenilirlik agensi** oturumlarınıza bırakılır — agent verileri kendisi sorgular, şüpheli transkriptleri okur ve (yardımcı olduğunda) küçük analiz betikleri çalıştırır, ardından **iyileştirme önerileri** yazılır ve her birinin arkasındaki kanıtlar sunulur. +Denetimler, agent günlüklerinizi **oturumlar arası** analiz ederek iyileştirmeye değer şeyleri bulacak şekilde tasarlanmış yinelenen işlerdir. Bir uyarı zaten bildiğiniz tek bir metriği gerçek zamana yakın izlerken, bir denetim *araştırır*: belirlediğiniz bir zamanlamaya göre deterministic bir politika geçişi çalıştırır, ardından oturumlarınız üzerinde bir **AI güvenilirlik ajanı** serbest bırakır — ajan verileri kendisi sorgular, şüpheli transkriptleri okur ve (yardımcı olduğunda) küçük analiz betikleri çalıştırır, ardından **iyileştirme önerileri** her biri için kanıtlarla sunukça yazar. -Denetimler "agenlarımda neyi düzeltmeliyim veya iyileştirilmeliyim?" sorusuna yanıt vermek için kullanılır — uyarılar ise belirli bir eşik geçildiğinde anında sayfalanmak için kullanılır. Her iyileştirme, arkasındaki tam oturumlar ve sorgularla bağlantılıdır ve bir tıkla tekrarlanan olayları yakalaması için önceden doldurulmuş bir uyarı oluşturulabilir. +Denetimler "ajanlarımda ne düzeltmeliyim veya iyileştirmeliyim?" sorusunun cevabını bulmak için, uyarılar ise belirli bir eşik aşıldığında sayfa almak için kullanılır. Her iyileştirme tam oturumlar ve sorgularla bağlantılıdır ve bir tıklama, tekrarları yakalamak için önceden doldurulmuş bir uyarı oluşturur. -Gösterge paneli yüzeyi **`//audits`** olup (`sidebar` → *analyze* → *audits*), `audits:read` / `audits:write` izinleriyle korunur. +Pano yüzeyi **`//audits`** adresindedir (kenar çubuğu → *analiz et* → *denetimler*), `audits:read` / `audits:write` izinleriyle korunur. --- ## Bir çalıştırma nasıl işler -Her çalıştırmanın iki katmanı vardır — deterministik bir taban ve agentic araştırma. +Her çalıştırmanın iki katmanı vardır — deterministic bir taban ve agentic araştırma. -### 1. Politika geçişi (deterministik) +### 1. Politika geçişi (deterministic) -Herhangi bir model çalışmadan önce, denetim pencere üzerinde küçük bir **SQL politika denetimleri** kataloğunu çalıştırır: bilinen kötü örüntüleri işaretleyen ve *kaç* olay / *hangi* oturumlar eşleştiğini raporlayan sınırlandırılmış toplam sorgular — hiçbir zaman eşleşen metin kendisi değil. Katalog şunları içerir: +Herhangi bir model çalıştırılmadan önce, denetim pencere üzerinde küçük bir **SQL politika kontrolleri** kataloğunu çalıştırır: bilinen kötü desenler için bayrak koyan ve *kaç* olayı / *hangi* oturumların eşleştiğini raporlayan sınırlandırılmış toplam sorgular — hiçbir zaman eşleşen metni kendisini değil. Katalog şunları içerir: -- Olay yüklerindeki **Gizli dizi / kimlik bilgisi sızıntısı** — AWS erişim anahtarları, `sk-…` API anahtarları, PEM özel anahtarları, JWT / taşıyıcı belirteçleri ve `KEY=…` kimlik bilgisi atamaları. -- **İstem enjeksiyonu işaretleri** — "önceki talimatları yoksay", "sistem isteminizi açığa çıkarın" ve benzer olanlar. -- **KKB** — SSN benzeri sayılar (buluşsal). -- **Araç izni reddetmeleri** ve **kaçak araç çağrısı döngüleri**. +- Olay yüklerinde **Gizli / kimlik bilgisi sızıntısı** — AWS erişim anahtarları, `sk-…` API anahtarları, PEM özel anahtarları, JWT / bearer tokenleri ve `KEY=…` kimlik bilgisi atamaları. +- **Prompt-injection işaretçileri** — "önceki talimatları yok say", "sistem isteminizi göster" ve benzerleri. +- **PII** — SSN şeklindeki numaralar (sezgisel). +- **Tool-izin reddi** ve **kaçak tool-call döngüleri**. -Politika isabet etmeleri, bulgular olarak kalıcı hale getirilir (tür `policy`) ve **her zaman yüzeyde görünür** (çalışma başına sınırlama tarafından hiçbir zaman kırpılmaz) ve AI agensi için başlangıç ipuçları olarak verilir. Bu katman modeliin gerektirmediğinden, bir denetim AI agensi kullanılamasa bile en önemli güvenlik sinyallerini üretir. +Politika isabeyleri bulgular (tür `policy`) olarak kalıcılaştırılır ve **her zaman görünür** (çalışma başına sınır tarafından kesilmez), AI ajanına başlangıç ipuçları olarak verilir. Bu katman modele ihtiyaç duymadığından, denetim AI ajanı kullanılamaz olsa bile hala en önemli güvenlik sinyallerini üretir. -### 2. Agentic araştırma (AI) +### 2. Agentic araştırması (AI) -Denetim daha sonra bir **otonom güvenilirlik agensi** çalıştırır (gösterge paneli asistanını güçlendiren aynı Claude Agent SDK hizmeti, denetim özel istemine sahip). Denetimin **kapsamı** (seçili agenler × ortamlar) ve **zaman penceresi** verildiğinde, agent: +Denetim daha sonra bir **otonom güvenilirlik ajanı** çalıştırır (pano asistanını güçlendiren aynı Claude Agent SDK hizmeti, denetime özgü bir istemiyle). Denetimin **kapsamı** (seçilen ajanlar × ortamlar) ve **zaman penceresi** göz önüne alınarak, ajan: - analitik tablolarınıza karşı salt okunur SQL sorguları çalıştırır, -- bir avuç temsili oturum transkriptini okur, -- isteğe bağlı olarak SQL'in ifade edemeyeceği analiz için kilitlenmiş bir in-pod korumalı alanında kısa **Python betikleri** yazar ve çalıştırır (ağ yok, dosya sistemi erişimi yok, gizli diziler temizlendi) — hata kümeleme, dağılımları hesaplama, zaten getirdiği yükleri tarama, -- ve bulduğu her iyi kanıtlanmış **iyileştirme** kaydeder. +- temsili bir avuç oturum transkriptini okur, +- isteğe bağlı olarak SQL'in ifade edemediği analiz için kilitli bir in-pod sandbox'ta kısa **Python betikleri** yazıp çalıştırır (ağ yok, dosya sistemi erişimi yok, gizli diziler temizlenmiş) — hataları kümeleme, dağılımları hesaplama, daha önce getirdiği yükleri süpürme, +- ve bulduğu her iyi kanıtlanmış **iyileştirmeyi** kaydeder. -Birkaç araştırma satırından geçer — hata kümeleme, tabana karşı sapma, transkriptlerde hedef başarısızlığı, araç suistimali, kalite/maliyet dengesi ve kapsama boşlukları — denetimin **duyarlılığında** (düşük / orta / yüksek). Her iyileştirme **kanıt belirtmelidir**: agentin aslında incelediği oturum kimlikleri ve/veya çalıştırdığı SQL. Sunucu alıntı yapılan oturumların var olduğunu doğrular ve **kanıtı kalmayan hiçbir iyileştirmeyi atar**, bu nedenle agent araştırır ancak asla uydurmazı. +Çeşitli araştırma hatları boyunca çalışır — hata kümeleme, baseline'a karşı sapma, transkriptlerde hedef başarısızlığı, araç kötüye kullanımı, kalite/maliyet ödünleşmeleri ve kapsam boşlukları — denetimin **duyarlılığında** (düşük / orta / yüksek). Her iyileştirme **kanıt alıntılayabilmelidir**: ajanın aslında incelediği oturum kimlikleri ve/veya çalıştırdığı SQL. Sunucu alıntılanan oturumların var olduğunu doğrular ve **hiçbir kanıtı olmayan herhangi bir iyileştirmeyi atar**, böylece ajan araştırır ama hiçbir zaman uydurma yapmaz. Her iyileştirme taşır: -- yapılacak somut değişiklik **önerisi** — istemi ince ayarı, araç şeması düzeltmesi, yeniden deneme politikası, koruma, daha fazla eval kapsamı, -- **beklenen etki** ve **çaba** tahmini (düşük / orta / yüksek), -- bir **büyüklük** — `big` (operatör sayfalanmalı), `medium` (çalışma raporuna dahil), veya `small` (gösterge paneli bağlamı), -- stabilir **parmak izi** (sorunun kategorisi + kapsamından, *bu çalıştırmanın oturumlarından değil*) böyle aynı sorun kanıt değişse bile çalıştırmadan çalıştırmaya izlenir, -- ve basit bir deterministik gözlemci tekrarlanan olayları yakalarken, bir tıkla oluşturabileceğiniz **önerilen uyarı**. +- bir **tavsiye** (yapılacak somut değişiklik — istem ince ayarı, tool-şema düzeltmesi, yeniden deneme politikası, bir koruma, daha fazla eval kapsamı), +- bir **beklenen etki** ve bir **çaba** tahmini (düşük / orta / yüksek), +- bir **büyüklük** — `big` (bir operatöre sayfa atılmalı), `medium` (çalıştırma raporuna ait) veya `small` (pano bağlamı), +- sabit bir **parmak izi** (sorunun kategorisi + kapsamından, *bu* çalıştırmanın oturumlarından değil) böylece aynı sorun kanıt değişse bile çalıştırmadan çalıştırmaya izlenir, +- ve, basit bir deterministic izleyici tekrarı yakalayabildiğinde, **önerilen uyarı** bir tıklama ile oluşturabileceğiniz. -> **AI katmanı isteğe bağlı ancak tavsiye edilir.** Denetim ardışık düzeni için hiçbir AI agensi yapılandırılmamışsa, çalıştırmalar yine de çalıştırılır, politika bulguları kalıcı hale getirilir ve agentic katman için sessizce geçmek yerine "analiz kullanılamıyor" dürüstçe rapor edilir. +> **AI katmanı isteğe bağlı ama önerilir.** Denetim işlem hattı için hiçbir AI ajanı yapılandırılmamışsa, çalıştırmalar yine de yürütülür, politika bulgularını kalıcılaştırır ve agentic katman için sessizce geçmek yerine "analiz kullanılamıyor" şeklinde dürüst bir şekilde raporlar. -### Başarısızlık yönetim modları +### Başarısızlık modları -İyileştirmeler, kuruluşunuzun dayanıklı **başarısızlık modu kataloğunda** sınıflandırılır (veya yeni bir mod önerilir). Modlar, örüntülere çalıştırmalar arasında kararlı bir kimlik ve uzun ufuk tekrarlanan olay izlemesi verir. +İyileştirmeler kuruluşunuzun dayanıklı **başarısızlık modu kataloğuna** sınıflandırılır (veya yeni bir mod önerir). Modlar desenlere çalıştırmalar arası sabit bir kimlik ve uzun ufuk tekrarı takibi verir. -## Değerlendirme yaşam döngüsü +## Sıralama yaşam döngüsü -Bulgu sayfasında (`/audits//findings/`): +Bir bulgu sayfasında (`/audits//findings/`): -| İşlem | Etki | +| İşlem | Sonuç | |---|---| -| **kabul et** | Bulguyu görünür tutar ancak önceliğini yarıya indirir. | -| **çöz** | Düzeltilmiş olarak işaretler. Örüntü daha sonra gerçekten geri dönerse, **yeni** olarak yeniden açılır — bu nedenle regresyon sessiz değil, gürültülü olur. | -| **sessiz kılma** / **reddet** | Dayanıklı suppression: örüntünün parmak izi hatırlanır ve çalıştırmalar arasında bile hiçbir zaman yüzeyde görünmez. "Bilinen, kabul edilen" için sessiz kılmayı; "yararlı değil" için reddet'i kullanın. | -| **yeniden aç** | Suppression / çözümü temizler ve örüntüyü yeniden sıralar. | -| **ata** | Bulguyu mülkiyeti için bir operatöre (kuruluş üyesi) yönlendirir. Öncelik ve suppression durumu değişmez. | +| **acknowledge** | Buluşu görünür tutar ama önceliğini yarıya indirir. | +| **resolve** | Düzeltilmiş olarak işaretler. Desen daha sonra gerçekten geri gelirse, **yeni** olarak yeniden açılır — böylece regresyon yüksek sesle duyulur, sessizce geçmişe katlanmaz. | +| **mute** / **dismiss** | Dayanıklı baskılama: desenin parmak izi hatırlanır ve çalıştırmalar arası bile hiçbir zaman yüzeye çıkmaz. Mute "bilinen, kabul edilen" için kullanın; dismiss "faydalı değil" için kullanın. | +| **reopen** | Baskılamayı / çözümü temizler ve deseni yeniden sıralar. | -Düşük sinyalli gürültü, agentic iyileştirmelerde çalışma başına bulgu sınırı (`top_k`) ile audit başına kontrol edilir. Politika bulguları sınırı atlar (güvenlikle ilgilidir ve her zaman gösterilir). Sınır tarafından kesilen her şey, çalıştırma istatistiklerinde sayılır — hiçbir şey sessizce bırakılmaz. +Düşük sinyalli gürültü, agentic iyileştirmelerde çalıştırma başına bulguları sınırlayan bir limit (`top_k`) ile denetim başına kontrol edilir. Politika bulguları sınırı atlar (bunlar güvenlikle ilgilidir ve her zaman gösterilir). Sınır tarafından kesilen her şey çalıştırmanın istatistiklerinde sayılır — hiçbir şey sessizce bırakılmaz. -## Planlama +## Zamanlamandırma -- **Kadans** (`schedule_interval_secs`): saatlik ile haftalık; **günlük varsayılandır**. Denetimler kasıtlı olarak uyarılardan daha kaba — agentic araştırma tam pencereleri tarar ve dakikalar boyunca çalışır. -- **Pencere**: sabit bir geri dönüş (ör. "her çalıştırma son 7 günü tarar") veya **son çalıştırmadan beri** (varsayılan) — her çalıştırma önceki başarılı olanın bıraktığı yerden devam eder, sınır olayları hiçbir zaman kaçırılmayacak şekilde küçük bir örtüşme ile. -- Sonraki çalıştırma, önceki tamamlandıktan sonra tam bir aralık sonra planlanır, bu nedenle yavaş bir çalıştırma aynı denetimin ikinci eşzamanlı çalıştırmasını hiçbir zaman istiflemez. -- Denetim sayfasında **şimdi çalıştır** onu hemen gerekli duruma getirir. +- **Kadans** (`schedule_interval_secs`): saatlik ila haftalık; **günlük varsayılandır**. Denetimler uyarılardan kasıtlı olarak daha kaba taneli — agentic araştırma tüm pencereleri tarar ve dakikalar boyunca çalışır. +- **Pencere**: sabit bir yuvarlanan geri bakış (örn. "her çalıştırma son 7 günü tarar") veya **son çalıştırmadan beri** (varsayılan) — her çalıştırma önceki başarılı olanı aldığı yerden devam eder, küçük bir çakışma ile sınır olayları hiçbir zaman kaçırılmaz. +- Sonraki çalıştırma önceki olanın **tamamlanmasından** sonra tam bir aralık zamanlanır, böylece yavaş bir çalıştırma hiçbir zaman aynı denetimin ikinci eş zamanlı çalıştırmasını yığmaz. +- Denetim sayfasında **Şimdi Çalıştır**, hemen son tarih yapar. ## Model seçimi -Denetim oluştururken, araştırmanın kullandığı modeli operatörünüzün agent hizmeti için yapılandırdığı **model listesinden** seçebilirsiniz. Tek bir model yapılandırılmışsa, seçici bunu başlık olarak gösterir; birkaçı varsa, seçim yaparsınız. Ayarlanmamış olarak bırakmak yapılandırılmış varsayılanı kullanır. +Bir denetim oluştururken, araştırmanın kullandığı modeli **operatörünüzün ajan hizmeti için yapılandırdığı modeller listesinden** seçebilirsiniz. Tek bir model yapılandırıldığında, seçici onu başlık olarak gösterir; birkaçı varsa, seçersiniz. Ayarlanmamışsa yapılandırılan varsayılanı kullanır. ## Bildirimler -Çalıştırma **yeni** bulgular ortaya çıkardığında, denetim kuruluşunuzun yapılandırılmış kanallarını bilgilendirir — uyarı ardışık düzeninin kullandığı aynı `alerts.enabled_channels` geçidi ve ayarları: +Bir çalıştırma **yeni** bulgular açığa çıkardığında, denetim kuruluşunuzun yapılandırılmış kanallarını bilgilendirir — uyarılar işlem hattının kullandığı aynı `alerts.enabled_channels` kapısı ve ayarları: -- **Slack** — önemli (`big`) yeni öğelerin ve derin bağlantının özeti. -- **E-posta** — tasarlanmış **denetim raporu** yeni iyileştirmeleri listeler (üst önem derecesi, her öğe önerileri, derin bağlantı), denetim **e-posta** kanalı ekli olduğunda ve en az bir yeni bulgu olduğunda gönderilir. +- **Slack** — derin bir bağlantıyla anlamlı (`big`) yeni öğelerin özeti. +- **E-posta** — tasarlanmış bir **denetim raporu** yeni iyileştirmeleri (en yüksek önem, her öğe önerileri, derin bağlantı) listeleyen, denetimin bir **e-posta** kanalı ekli olduğunda ve en az bir yeni bulgu olduğunda gönderilen. -Yinelenen ancak bilinen bulgular yeniden bildirim almaz. +Tekrarlanan ama bilinen bulgular yeniden bildirmez. ## Yapılandırma referansı -Denetim tanımları gösterge panelinde (`/audits/new`) veya API aracılığıyla yönetilir. Audit başına ayarlar, program kadansı ve penceresi, kapsamı (`{"environments": [...], "agent_ids": [...]}`), duyarlılığı (`low` / `medium` / `high`), bildirim kanalları, çalıştırma başına bulgu sınırı (`top_k`) ve modeli (via `llm_budget.model`) içerir. Operatör seviyesi sunucu ayarları (zaman aşımları, korumalı alan, agent-hizmeti URL'si) [deployment.md](/tr/agenteye/deployment) adresinde belgelenmiştir. +Denetim tanımları pano (`/audits/new`) veya API aracılığıyla yönetilir. Denetim başına ayarlar, zamanlama kadansını ve penceresini, kapsamı (`{"environments": [...], "agent_ids": [...]}`), duyarlılığı (`low` / `medium` / `high`), bildirim kanallarını, çalıştırma başına bulgular sınırını (`top_k`) ve modeli (via `llm_budget.model`) içerir. Operatör seviyesi sunucu ayarları (zaman aşımları, sandbox, ajan hizmeti URL'si) [deployment.md](/tr/agenteye/deployment) belgesinde yer almaktadır. ## API -Tüm uç noktalar kuruluş kapsamlıdır ve standart taşıyıcı anahtar kimlik doğrulamasını izler (bkz. [api-keys.md](/tr/agenteye/api-keys)). +Tüm uç noktalar org kapsamlı ve standart taşıyıcı anahtarı kimlik doğrulamasını takip eder (bkz. [api-keys.md](/tr/agenteye/api-keys)). -| Uç nokta | İzin | Amaç | +| Uç Nokta | İzin | Amaç | |---|---|---| | `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | Denetim tanımlarını listele / oluştur. | -| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Denetimi incele, düzenle, sil. | -| `POST /audits/:id/run` | `audits:write` | Denetimi hemen gerekli duruma getir. | +| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Bir denetimi incele, düzenle, sil. | +| `POST /audits/:id/run` | `audits:write` | Denetimin hemen son tarih yapmış olması. | | `GET /audits/:id/runs` | `audits:read` | Çalıştırma geçmişi (pencere, durum, istatistikler, bulgu sayıları). | -| `GET /audits/findings` | `audits:read` | Kuruluş geneli bulgular, `audit_id`, `status` ile filtrelenebilir; önceye göre sıralanır. | -| `GET /audits/findings/:fid` | `audits:read` | Tam bulgu detayı (öneri, kanıt, öncelik). | -| `POST /audits/findings/:fid/status` | `audits:write` | Değerlendirme: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | +| `GET /audits/findings` | `audits:read` | Org genelinde bulgular, `audit_id`, `status` ile filtrelenebilir; önceliğe göre sıralanmış. | +| `GET /audits/findings/:fid` | `audits:read` | Tam bulgu detayı (tavsiye, kanıt, öncelik). | +| `POST /audits/findings/:fid/status` | `audits:write` | Sıralama: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | -"Denetim çalıştı ancak hiçbir şey bulunamadı", "kod korumalı alanı devre dışı bırakıldı" ve "denetim e-postası teslim edilmedi" için bkz. [troubleshooting.md](/tr/agenteye/troubleshooting#audits). \ No newline at end of file +"Denetim çalıştı ama hiçbir şey bulamadı", "kod sandbox'u devre dışı", ve "denetim e-postası teslim edilmedi" için bkz. [troubleshooting.md](/tr/agenteye/troubleshooting#audits). \ No newline at end of file diff --git a/docs/tr/agenteye/cli-recipes.mdx b/docs/tr/agenteye/cli-recipes.mdx index 9534c565..ff44e1d8 100644 --- a/docs/tr/agenteye/cli-recipes.mdx +++ b/docs/tr/agenteye/cli-recipes.mdx @@ -1,30 +1,29 @@ --- title: "Ajanlar için CLI tarifleri" -description: "Ajanlar için AgentEye CLI tarifleri belgelendirmesi." +description: "Ajanlar için AgentEye CLI tarifleri belgesi." --- +Oturum, etkinlik ve değerlendirme verilerini (ve yeniden değerlendirmeleri tetikle) doğrudan bir betik veya kodlama ajanından çek. Çıktı olarak temiz JSON sağla ve doğrudan `jq` içine yönlendir. Bu tarifler, AgentEye'ın gözlemlenebilirlik verilerini, terminal kullanıcısı veya bir AI kodlama ajanı (Claude Code, Cursor) tarafından sorgulanabilir ve otomatikleştirilebilir hale getirir — pano aracılığıyla tıklamaya gerek kalmadan. -Oturum, olay ve değerlendirme verilerini (ve yeniden değerlendirmeleri tetikleyin) doğrudan bir betikten veya kodlama ajanından çekin, `jq` içine doğrudan akan temiz JSON çıktısı ile. Bu tarifler, AgentEye'ın gözlenebilirlik verilerini, bir terminal kullanıcısının veya bir AI kodlama ajanının (Claude Code, Cursor) pano üzerinden tıklamadan sorgulayabileceği ve otomatikleştirebileceği bir şeye dönüştürür. - -Aşağıdaki desenler AgentEye CLI'si (`agenteye`) için kopyala-yapıştır hazırlığındadır. Kurulum, kimlik doğrulama ve tam seçenek listesi için [CLI](/tr/agenteye/cli) bölümüne bakın; yerleşik yardım için `agenteye -h` veya `agenteye -h` komutunu çalıştırın. +Aşağıdaki desenler AgentEye CLI (`agenteye`) için kopya-yapıştır şeklinde hazırdır. Kurulum, kimlik doğrulama ve tam seçenek listesi için [CLI](/tr/agenteye/cli) bölümüne bakın; yerleşik yardım için `agenteye -h` veya `agenteye -h` komutlarını çalıştırın. ## Altın kurallar -1. **Global seçenekler komutun *öncesinde* gelir.** `agenteye --json sessions` doğrudur; `agenteye sessions --json` değildir. Global seçenekler şunlardır: `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Çıktıyı ayrıştırdığınız zaman `--json` geçirin.** Veriler **stdout** üzerinden JSON olarak çıkış yapar; insan durumu ve hatalar **stderr** üzerine gider, böylece stdout temiz kalır ve `jq` içine yönlendirilebilir. -3. **Çıkış koduna göre dallanma yapın**, stderr metnine göre değil: `0` tamam · `2` hatalı argümanlar · `3` panoya ulaşılamıyor · `4` giriş yapılmamış veya süresi dolmuş · `5` izin yok. -4. **`-h` ile keşfedin.** Her komut filtrelerini, değer biçimlerini ve JSON şeklini belgelendiren. +1. **Genel seçenekler komuttan *önce* gelir.** `agenteye --json sessions` doğru; `agenteye sessions --json` değildir. Genel seçenekler şunlardır: `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **Çıktıyı ayrıştırırken her zaman `--json` geçirin.** Veriler **stdout** olarak JSON formatında gider; insan durum ve hatalar **stderr** bölümüne gider, böylece stdout `jq` içine yönlendirilmek için temiz kalır. +3. **Çıkış koduna göre dallanın**, stderr metniyle değil: `0` tamam · `2` hatalı bağımsız değişkenler · `3` panoya ulaşamıyorum · `4` giriş yapılmamış veya süresi dolmuş · `5` izin eksik. +4. **`-h` ile keşfet.** Her komut filtrelerini, değer biçimlerini ve JSON şeklini belgeler. ## Tek seferlik kurulum ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # böylece --base-url tekrarlamaz -agenteye login --email you@example.com # e-posta ile gelen kodu yapıştırın; ~24s geçerli +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # --base-url'i tekrar yazmamanız için +agenteye login --email you@example.com # e-postayla gelen kodu yapıştırın; ~24s geçerli ``` -## İş yapmadan önce kimlik doğrulamayı doğrulayın +## İş yapmadan önce kimlik doğrulamayı onaylayın -`whoami` eksik veya süresi dolmuş oturumlarda hata vermez; bunun yerine `logged_in:false` bildirir, böylece bir ajan kimlik doğrulama durumunu güvenli bir şekilde araştırabilir. (Temel URL ayarlanmamışsa veya pano ulaşılamazsa yine de sıfır olmayan çıkış verebilir.) +`whoami` hiçbir zaman eksik veya süresi dolmuş oturumda hata vermez; bunun yerine `logged_in:false` rapor eder, böylece bir ajan kimlik doğrulama durumunu güvenli bir şekilde araştırabilir. (Temel URL ayarlanmamışsa veya pano erişilemezse hala sıfırdan farklı çıkış yapabilir.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -32,107 +31,107 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## Başarısız veya düşük puanlı oturumları bulun +## Başarısız veya düşük puan alan oturumları bul ```bash # son 24 saatte değerlendirmesi hata veren oturumlar agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# bir ajan için yardımcılık açısından <= 0.5 puan alan değerlendirmeler +# yardımcılık konusunda <= 0.5 puan alan değerlendirmeler, bir ajan için agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -Puan filtreleme **`evals`** üzerinde olur, `sessions` üzerinde değil. `--score KEY:MIN..MAX` tekrarlanabilir ve VE-birleştirilir; her iki sınır isteğe bağlıdır (`..0.5` ≤ 0.5 anlamına gelir, `0.9..` ≥ 0.9 anlamına gelir). İstek başına 20'ye kadar puan filtresi geçirebilirsiniz; daha fazla HTTP 400 döndürür. `sessions`, `--env`, `--status`, `--agent-id`, `--session-id` ve zaman aralığı filtrelerini `evals` ile paylaşır, ancak `--score` değerine sahip değildir. +Puan filtreleme **`evals`** konumunda yaşar, `sessions` değildir. `--score KEY:MIN..MAX` tekrarlanabilir ve VE-birleştirilmiştir; her iki sınır da isteğe bağlıdır (`..0.5` anlamı ≤ 0.5, `0.9..` anlamı ≥ 0.9). İstek başına en fazla 20 puan filtresi geçebilirsiniz; daha fazlası HTTP 400 döndürür. `sessions`, `evals` ile `--env`, `--status`, `--agent-id`, `--session-id` ve zaman aralığı filtrelerini paylaşır, ancak `--score` yoktur. -## Bir oturumu baştan sona okuyun +## Bir oturumu baştan sona oku -Tek bir `session show` komutu yoktur — olay izini oturumun değerlendirmesi ile birleştirin: +Tek bir `session show` komutu yok — etkinlik izini oturumun değerlendirmesiyle birleştir: ```bash # oturumun en son değerlendirmesi (durum + puanlar) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# koşudaki her olay (tam tarama için --limit yükseltin) +# çalıştırmadaki her etkinlik (tam tarama için --limit artır) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# bir oturumdaki sadece araç çağrıları +# yalnızca oturumdaki araç çağrıları agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -## Her şeyi getir (sayfalandırma) +## Her şeyi getir (sayfalama) -Sonuçlar en yeniden başa ve imleç-sayfalandırılmış şekildedir. +Sonuçlar en yeniden itibaren ve imleç-sayfalanmıştır. ```bash -# tek çekim: 200 satırlık sayfalarda 500'e kadar satır getir +# tek atış: 200 satır sayfasında 500 satıra kadar getir agenteye --json events --session-id run-001 --limit 500 --all > events.json -# manuel sayfalandırma: sonraki imleci geri besleyin +# manuel sayfalama: sonraki_imleç geri aktar page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## Çıktıyı --fields ile daraltın +## Çıktıyı --fields ile daralt -Bir ajanın okuması gereken şeyi azaltmak için anahtarları (hem tabloda hem de `--json`'de) kısıtlayın. +Bir ajanın okuması gereken şeyi azaltmak için (tablo ve `--json` içinde) anahtarları kısıtla. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Bilinmeyen alan adları geçerli listeyle reddedilir (çıkış `2`) — alan adlarını keşfetmenin ucuz bir yolu. +Bilinmeyen alan adları reddedilir (çıkış `2`) geçerli listeyle birlikte, alan adlarını keşfetmenin ucuz bir yolu. -## Geçerli filtre değerlerini bulun +## Geçerli filtre değerlerini keşfet ```bash -agenteye --json list envs | jq -r '.values[]' # --env için değerler +agenteye --json list envs | jq -r '.values[]' # --env değerleri agenteye --json list tools | jq -r '.values[]' # araç adları; ayrıca ajanlar, modeller, event_types, … -agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX için geçerli KEY +agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX için geçerli ANAHTAR ``` ## Kuruluşunuzu seçin (çok kiracılı) -Birden fazla kuruluşa aitse, oturum açmada etkin kiracıyı seçin (kaydedilir): +Birden fazla kuruluşa aitseniz, etkin kiracıyı giriş sırasında seçin (kaydedilir): ```bash -agenteye login --org acme --email you@corp.com # oturum açma ile aynı adımda kiracıyı ayarla +agenteye login --org acme --email you@corp.com # giriş ile aynı adımda kiracıyı ayarla agenteye --json orgs list | jq -r '.orgs[].org_slug' agenteye --org globex --json sessions --since 24h # bir komut için geçersiz kıl ``` -`--org` olmayan çok kuruluşlu oturum açma sıfır olmayan çıkış verir ve aralarından seçim yapılacak kuruluşları yazdırır. +`--org` olmayan çok kuruluşlu giriş sıfırdan farklı çıkış yapar ve seçilecek kuruluşları yazdırır. -## SDK/toplayıcı için bir API anahtarı sağlayın +## SDK/toplayıcı için bir API anahtarı sağla ```bash -# gizli bir kez yazdırılır — --json ile bu .key alanıdır +# gizli dizi BİR KERE yazdırılır — --json ile .key alanı key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # döndür; iptal etmek için agenteye keys disable ci-bot --yes ``` -## Kaydedilmiş veya geçici bir sorgu çalıştırın +## Kaydedilmiş veya geçici bir sorguyu çalıştır ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' agenteye --json query run errs --arg prod | jq '.rows' # kaydedilmiş bir sorgu + konumsal $1 ``` -## Etkileşimsiz olarak bir olayı ayırıştırın +## Bir olayı etkileşimsiz olarak değerlendir ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> Mutasyonlar `--json` altında veya stdin bir TTY değilse onay istemini otomatik olarak atlar, böylece ajanlar asla takılmaz; başka yerlerde açıkça atlamak için `--yes`/`-y` geçirin. +> Değişimler `--json` altında veya stdin bir TTY olmadığında onay istemini otomatik olarak atlar, böylece ajanlar asla takılmaz; açık olarak başka yerlerde atlamak için `--yes`/`-y` geçirin. -## Bir betik içinde çıkış kodu işleme +## Bir betikteki çıkış kodu işleme ```bash out=$(agenteye --json sessions --since 1h) || code=$? @@ -145,7 +144,7 @@ case "${code:-0}" in esac ``` -## JSON çıktı şekilleri +## JSON çıkış şekilleri | Komut | stdout JSON (`--json` ile) | |---|---| @@ -156,15 +155,15 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` bir kez gösterilir) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` bir kez gösteriliyor) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| oluştur/güncelle/sil (herhangi bir) | kaynak nesnesi veya silmeler için `{"deleted": true, "id"}` | -| başarısızlık (herhangi bir, `--json` ile) | stdout üzerinde `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | +| oluştur/güncelle/sil (herhangi biri) | kaynak nesnesi veya silmeler için `{"deleted": true, "id"}` | +| başarısızlık (herhangi biri, `--json` ile) | stdout üzerinde `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | -- Her **olay** öğesi (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. +- Her **etkinlik** öğesi (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. - Her **değerlendirme** öğesi (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. - Her **oturum** öğesi (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -Her komutun `--fields`, tam olarak kendi öğesinin alan adlarını kabul eder — küme `sessions` ve `evals` arasında farklılık gösterir, bu nedenle biri için geçerli bir ad diğeri tarafından reddedilebilir. \ No newline at end of file +Her komutun `--fields` tam olarak kendi öğesinin alan adlarını kabul eder — set `sessions` ve `evals` arasında farklıdır, bu nedenle biri için geçerli olan ad diğeri tarafından reddedilebilir. \ No newline at end of file diff --git a/docs/tr/agenteye/deployment.mdx b/docs/tr/agenteye/deployment.mdx index da2f5f68..9fa1a28e 100644 --- a/docs/tr/agenteye/deployment.mdx +++ b/docs/tr/agenteye/deployment.mdx @@ -1,164 +1,163 @@ --- title: "Dağıtım" -description: "AgentEye Dağıtım belgelendirmesi." +description: "AgentEye Dağıtım belgeleri." --- -Bu rehber, AgentEye sunucusunun ve panosu'nun üretim ortamında dağıtılmasını kapsar. +Bu kılavuz, AgentEye sunucusu ve panosunun üretim ortamına dağıtılmasını kapsamaktadır. --- -## Mimari Genel Bakış +## Mimari Özeti ``` - [ AI agent makineleri ] [ Sizin altyapınız ] + [ AI agent makineleri ] [ Kendi altyapınız ] Python SDK - | JSONL yazıyor +----------------------+ + | JSONL yazar +----------------------+ v +--->| PostgreSQL 15+ | agenteye-collector --HTTP--+ | | (ilişkisel depo) | | | +----------------------+ v | +--------+ | +----------------------+ | Server |<------+--->| ClickHouse 24+ | - +--------+ | | (etkinlikler / analiz)| + +--------+ | | (etkinlikler / analitikler)| ^ | +----------------------+ API | | | | +----------------------+ - +-----------+ +- - >| Redis 7+ (isteğe bağlı) | + +-----------+ +- - >| Redis 7+ (isteğe bağlı)| | Pano | +----------------------+ +-----------+ ``` -- **Server**: Rust HTTP servisi; etkinlik gruplarını alır, bunları ClickHouse'a yazar ve ilişkisel durumu PostgreSQL'de tutar. -- **Pano**: Next.js web uygulaması; yalnızca sunucu API'si aracılığıyla okur ve yazar. -- **agenteye-collector**: sunucu ana bilgisayarında değil, agent makinelerine dağıtılır. -- **Postgres 15+**: GEREKLI. (Multi-tenant sürümünde 14'ten yükseltildi; org-membership şeması bir sütun listesi `ON DELETE SET NULL` yabancı anahtarı kullanır; bu Postgres 15+ tarafından gereklidir. Bu sürümü dağıtmadan önce Postgres'i yükseltin.) OLTP durumunu depolar: `api_keys`, `users`, `sessions`, `evaluation_jobs` (kuyruk), `dashboards`, `saved_queries`, `otp_codes` ve multi-tenant tabloları `orgs`, `org_memberships`, `org_settings`. -- **ClickHouse 24+**: GEREKLI. Alınan her etkinlik için analitik deposu. Motor: `ReplacingMergeTree`, ay cinsinden bölümlenmiş, `(session_id, ts, dedup_key)` tarafından sıralanmış. Sunucu `CLICKHOUSE_URL` aracılığıyla bağlanır; paket içi `deploy/base/clickhouse/` performans-ayarlı tek-node yapılandırması ile gelir. **Multi-tenant gereksinimi:** paket içi yapılandırma SQL erişim yönetimini ve `users_without_row_policies_can_read_rows=false` etkinleştirir, böylece sunucu kuruluş başına bir salt okunur ClickHouse kullanıcısı + satır politikası oluşturabilir (SQL editörü ve AI ajanı için motor-zorlanan yalıtım sınırı). Kendi ClickHouse yapılandırmanızı sağlarsanız, bu ayarları taşıyın (bkz. `deploy/base/clickhouse/configmap.yaml`). -- **Redis 7+**: *isteğe bağlı* paylaşılan önbellek + oran-sınırlama arka ucu. Sunucu ve pano her ikisi de `REDIS_URL` aracılığıyla bağlanır. Yoksa, her ikisi de Postgres-only yollarına incelikle düşer. Aşağıda **Redis (isteğe bağlı önbellek)** bölümüne bakın. +- **Sunucu**: Rust HTTP hizmeti; etkinlik toplamalarını alır, ClickHouse'a yazar ve ilişkisel durumu PostgreSQL'de tutar. +- **Pano**: Next.js web uygulaması; sunucu API'si aracılığıyla okur ve yazar. +- **agenteye-collector**: sunucu ana bilgisayarında değil, agent makinelerinde dağıtılır. +- **Postgres 15+**: GEREKLI. (14'ten çok kiracılı sürümde yükseltildi; org-üyelik şeması `ON DELETE SET NULL` yabancı anahtarını kullanan bir sütun listesi kullanır ve bu Postgres 15+ gerektirir. Bu sürümü dağıtmadan önce Postgres'i yükseltin.) OLTP durumunu saklar: `api_keys`, `users`, `sessions`, `evaluation_jobs` (sıra), `dashboards`, `saved_queries`, `otp_codes` ve çok kiracılı tablolar `orgs`, `org_memberships`, `org_settings`. +- **ClickHouse 24+**: GEREKLI. Her alınan etkinlik için analitik deposu. Motor: `ReplacingMergeTree`, aya göre bölümlendirilmiş, `(session_id, ts, dedup_key)` ile sıralanmış. Sunucu `CLICKHOUSE_URL` aracılığıyla bağlanır; paketlenmiş `deploy/base/clickhouse/` performans ayarlı tek düğüm yapılandırması içerir. **Çok kiracılı gereksinim:** paketlenmiş yapılandırma SQL erişim yönetimini etkinleştirir ve `users_without_row_policies_can_read_rows=false` ayarını yapar, böylece sunucu kuruluş başına bir salt okunur ClickHouse kullanıcısı ve satır ilkesi oluşturabilir (SQL editörü ve AI ajanı için motor tarafından zorlanmış izolasyon sınırı). Kendi ClickHouse yapılandırmanızı sağlarsanız bu ayarları aktarın (bkz. `deploy/base/clickhouse/configmap.yaml`). +- **Redis 7+**: *isteğe bağlı* paylaşılan önbellek + hız sınırı arka ucu. Sunucu ve pano her ikisi de `REDIS_URL` aracılığıyla bağlanır. Mevcut değilse, her ikisi de Postgres'e yapılan yollarla incelikle düşer. Aşağıda **Redis (isteğe bağlı önbellek)** bölümüne bakın. --- ## Sunucu -### Görüntüyü çek +### Görüntüyü çekin ```bash echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> Mevcut yapılar `beta-latest` altında yayımlanır; `latest` yalnızca kararlı sürümlere atanır. Üretim için spesifik bir `:v` etiketine sabitleyin; bkz. [Mevcut Görüntü Etiketleri](#mevcut-görüntü-etiketleri). +> Mevcut yapılar `beta-latest` altında yayımlanır; `latest` yalnızca kararlı sürümlere atanır. Üretim için belirli bir `:v` etiketine sabitle; bkz. [Kullanılabilir Resim Etiketleri](#available-image-tags). ### Ortam değişkenleri | Değişken | Gerekli | Varsayılan | Açıklama | |---|---|---|---| -| `DATABASE_URL` | Evet | yok | Postgres DSN. `postgres://` şemasına sahip standart libpq bağlantı dizesi biçimi. `?sslmode=require` ve diğer libpq parametrelerini destekler. Şifre `/`, `+` veya `=` içermemelidir; URL-safe şifreler oluşturmak için `openssl rand -hex` kullanın. | -| `ADMIN_KEY` | Hayır | yok | Bootstrap admin API anahtarı. Her başlamada tüm izinlerle yükseltilir. Değeri değiştirerek ve yeniden başlatarak döndürün. | +| `DATABASE_URL` | Evet | yok | Postgres DSN. Şema `postgres://` ile standart libpq bağlantı dizesi biçimi. `?sslmode=require` ve diğer libpq parametrelerini destekler. Parola `/`, `+` veya `=` içeremez; URL-safe parolalar oluşturmak için `openssl rand -hex` kullanın. | +| `ADMIN_KEY` | Hayır | yok | Önyükleme yöneticisi API anahtarı. Her başlangıçta tüm izinlerle güncelleştirilir. Değeri değiştirerek ve yeniden başlatarak döndürün. | | `LISTEN_ADDR` | Hayır | `0.0.0.0:8080` | Bağlanacak TCP adresi | -| `MAX_BODY_BYTES` | Hayır | `134217728` (128 MB) | Maksimum istek gövdesi boyutu | -| `ADMIN_EMAIL` | Hayır | yok | Bootstrap admin kullanıcı e-postası. Her başlamada tüm izinlerle yükseltilir ve korunan olarak işaretlenir: pano/API aracılığıyla devre dışı bırakılamaz veya izinleri değiştirilemez. Bootstrap admin'i döndürmek için `ADMIN_EMAIL` değiştirin ve yeniden başlatın; yeni e-posta korunan olarak yükseltilir ve öncekisi veritabanında el ile temizlenene kadar korumasını tutar. | -| `ALLOWED_EMAILS` | Hayır | yok (hepsi engellenir) | Kullanıcı oluşturma ve oturum açma için izin verilen e-postaların virgülle ayrılmış listesi. Tam adresler (`user@example.com`) ve alan adı joker karakterleri (`*@example.com`) destekler. Ayarlanmazsa, hiçbir kullanıcı oluşturulamaz veya oturum açamaz. **İlk başlangıç seed'i yalnızca**: ilk önyüklemede varsayılan org'un izin listesini seed'ler; bundan sonra her org'un [`//settings`](#operational-settings) sayfası gerçek kaynaktır ve bu env var'ı değiştirmek hiçbir etkiye sahip değildir. | -| `SMTP_HOST` | Hayır | yok | OTP e-postaları göndermek için SMTP sunucusu ana bilgisayar adı. Ayarlanmazsa, OTP kodları stdout'a günlüğe kaydedilir. | +| `MAX_BODY_BYTES` | Hayır | `134217728` (128 MB) | Maksimum istek gövde boyutu | +| `ADMIN_EMAIL` | Hayır | yok | Önyükleme yöneticisi kullanıcı e-postası. Her başlangıçta tüm izinlerle güncelleştirilir ve korumalı olarak işaretlenir: pano/API aracılığıyla devre dışı bırakılamaz veya izinleri değiştirilemez. Önyükleme yöneticisini döndürmek için `ADMIN_EMAIL` değiştirin ve yeniden başlatın; yeni e-posta korumalı olarak güncelleştirilir ve önceki e-posta el ile veritabanından temizleninceye kadar korumayı tutar. | +| `ALLOWED_EMAILS` | Hayır | yok (hepsi engellenir) | Kullanıcı oluşturma ve oturum açma için izin verilen e-postaların virgülle ayrılmış listesi. Tam adresler (`user@example.com`) ve alan adı joker karakterleri (`*@example.com`) destekler. Ayarlanmamışsa, hiçbir kullanıcı oluşturulamaz veya oturum açamaz. **İlk önyükleme tohumlandırması**: varsayılan org'un izin listesini ilk önyüklemede tohurnlanır; bundan sonra her org'un [`//settings`](#operational-settings) sayfası gerçeği kaynağıdır ve bu ortam değişkenini değiştirmek etkisi olmaz. | +| `SMTP_HOST` | Hayır | yok | OTP e-postaları göndermek için SMTP sunucusu ana bilgisayar adı. Ayarlanmamışsa, OTP kodları bunun yerine stdout'a kaydedilir. | | `SMTP_PORT` | Hayır | `587` | SMTP sunucusu portu | -| `SMTP_USERNAME` | Hayır | yok | SMTP kimlik doğrulama kullanıcı adı | -| `SMTP_PASSWORD` | Hayır | yok | SMTP kimlik doğrulama şifresi | -| `SMTP_FROM` | Hayır | yok | OTP e-postaları için gönderici e-posta adresi | -| `SMTP_TLS` | Hayır | STARTTLS | Açıkça kapatmadığınız sürece STARTTLS kullanılır: `false` veya `0` düz metin gönderir (TLS yok); başka herhangi bir değer — ayarlanmamış dahil — STARTTLS'ı etkinleştirir. | -| `DASHBOARD_URL` | Hayır | yerleşik varsayılan | OTP-e-posta magic linkini ve uyarı bildirimlerindeki olay magic-linklerini oluşturmak için kullanılan pano kaynağı. Ayarlanmazsa yerleşik bir varsayılana geri döner (ve yalnızca OTP için, pano tarafından türetilen istek kaynağına). Bölünmüş etki alanı kurulumları için bunu ayarlayın, böylece hem e-posta hem de Slack/olay linkler pano'nuza işaret eder. Aşağıda **E-posta magic-link URL'i** bölümüne bakın; çoğu operatör bunu ayarlamak zorunda değildir. | -| `SESSION_TTL_SECS` | Hayır | `86400` (24 h) | Pano oturumu süresi (saniye cinsinden). **İlk başlangıç seed'i yalnızca**: ilk dağıtımdan sonra [`//settings`](#operational-settings) aracılığıyla org başına düzenleyin. | -| `OTP_TTL_SECS` | Hayır | `600` (10 min) | OTP kodu geçerlilik süresi (saniye cinsinden). **İlk başlangıç seed'i yalnızca**: ilk dağıtımdan sonra [`//settings`](#operational-settings) aracılığıyla org başına düzenleyin. | -| `REDIS_URL` | Hayır | yok | İsteğe bağlı paylaşılan önbellek + oran-sınırlama arka ucu, örn. `redis://redis:6379/0`. Ayarlandığında, sunucu kimlik doğrulaması yapılmış API-key araştırmasını, pano'nun `/models` toplamını, oturumlar listesini ve env-list fasetini önbelleğe alır; ayrıca OTP-istek oran sınırlamasını Postgres COUNT'tan Redis INCR'ye taşır. Ayarlanmazsa veya erişilemezse, sunucu önbellek olmadan çalışır (OTP sınırı Postgres'e geri döner, diğer her önbellek araması gerçek kaynağa düşer). **Redis (isteğe bağlı önbellek)** bölümüne bakın. | -| `CLICKHOUSE_URL` | **Evet** | yok | ClickHouse örneğinin temel URL'i, örn. `http://clickhouse:8123`. Sunucu her başlamada kendi etkinlik şemasını bu veritabanına uygular ve ClickHouse'a erişemezse önyüklemeyi reddeder. **ClickHouse (gerekli analitik depo)** bölümüne bakın. | -| `CLICKHOUSE_DATABASE` | Hayır | `agenteye` | ClickHouse veritabanı (şema) adı. Sunucu başlangıçta mevcut değilse oluşturur. | -| `ORG_CH_SECRET` | Hayır (tek-tenant) / **Evet (multi-org)** | dev varsayılanı | Her kuruluşun kiracı-başına ClickHouse şifresi türetildiği HMAC anahtarı. SQL editörü ve AI ajanının `run_query` org'un kendi salt-okunur ClickHouse kullanıcısı olarak yürütülür; satır politikası motorda kiracı yalıtımını uygular. Tek-tenant dağıtımları yerleşik dev varsayılanında iyiyse önyüklenir; **ikinci bir org sağlamadan önce güçlü, sabit bir değer AYARLAMALISINIZ**, çünkü `agenteye-orgctl org create` CLI yerleşik dev varsayılanında çalışmayı reddeder. Bunu döndürmek, her org'un ClickHouse kullanıcısını yetim bırakır; sonraki başlangıçta yeniden sağlayacaklar (önyükleme-zaman uzlaştırması bunu otomatik olarak iyileştirir). Gizli tutun ve çoğaltmalar arasında değişmeden kalın. Org sağlaması operatör tarafındandır; **Kuruluşlar (multi-tenancy)** bölümüne bakın. | -| `DEFAULT_ORG_NAME` | Hayır | `Default` | Yerleşik varsayılan org için seed'lenmiş görüntülü ad. **İlk başlangıç seed'i yalnızca** ve org hâlâ yeni-geçişlenmiş jenerik kimliğini taşırken, başlangıçta uygulanır, sonra yoksayılır. Org'u yeniden adlandırdığınızda (`agenteye-orgctl org rename`) yeniden ad, yetkili olur ve bu env var'ın başka etkisi yoktur. | -| `DEFAULT_ORG_SLUG` | Hayır | `default` | Yerleşik varsayılan org için URL slug'ı, pano yolu (`//…`). `DEFAULT_ORG_NAME` ile aynı ilk-başlangıç-yalnızca / temiz-yalnızca semantiği. 1-40 küçük alfanumerik, tekil iç tire ve [ayrılmış kelime](#organizations-multi-tenancy) olmayan olmalıdır; geçersiz bir değer yoksayılır (org `default`'u tutar). Tek-tenant kurulumun `/default` yerine örn. `/acme` olarak sunmasına izin verir, herhangi bir sonrası-dağıtım CLI adımı olmadan. | -| `RUST_LOG` | Hayır | `info` | Günlük ayrıntıları (`debug`, `warn`, `error`, `agenteye_server=trace`) | -| `EVALUATOR_ENDPOINT` | Hayır | yok | Evaluator hizmetinizin temel URL'i (örn. `http://evaluator:9000`). Ayarlanmazsa tüm değerlendirme boru hattı no-op olur; hiçbir kuyruk satırı yazılmaz, hiçbir işçi çalışmaz. Bkz. [Evaluation Suite](/tr/agenteye/evaluation-suite). | -| `EVALUATOR_TOKEN` | Hayır | yok | Evaluator olarak `Authorization: Bearer ` gönderilir. **Evaluator hizmetinin yapılandırıldığı aynı değere eşit OLMALIDIR.** İsteğe bağlı, yalnızca evaluator'unuz token olmayan şekilde yapılandırılmışsa. | -| `EVALUATOR_WORKERS` | Hayır | `2` | Eşzamanlılık: her sunucu örneği başına değerlendirmeleri görevlendirenişçi görevlerinin sayısı. Yatay olarak ölçeklenmiş birden fazla sunucu arasında çalışmak için güvenlidir. | -| `EVALUATOR_CLAIM_BATCH` | Hayır | `4` | Tek bir işçinin her tıkta talep ettiği maksimum değerlendirme sayısı. Gruplar **eşzamanlı** olarak gönderilir, bu nedenle evaluator uç noktanız üzerindeki toplam eşzamanlılık `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` dir. | -| `EVALUATOR_POLL_IDLE_SECS` | Hayır | `2` | Hiçbir şey vadesi gelmediğinde bir işçinin gönderim denemeleri arasında uyuduğu süre. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | Hayır | `10` | Evaluator bir `next_poll_secs` başına yanıt döndürmediğinde ve `GET /config` işleminden bir `default_poll_interval_secs` bildirmediğinde `GET /evaluate/{id}` yoklamalar için son yedek kadansı (saniye). | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | Hayır | `30000` | Evaluator'a karşı HTTP isteği başına zaman aşımı (milisaniye). | -| `EVALUATOR_MAX_ATTEMPTS` | Hayır | `5` | Bu kadar başarısız deneyimden sonra bir değerlendirme terminal `error` (veya başarısızlıklar istek zaman aşımı ise `timeout`) olarak kaydedilir. | -| `EVALUATOR_CONFIG_REFRESH_SECS` | Hayır | `300` (5 min) | Sunucunun evaluator'dan `GET /config` işlemini ne sıklıkta yeniden getirdiği. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | Hayır | `3600` (1 h) | Bir oturumun yoklama kuyruğunda kalmadan önce maksimum duvar saati zamanı; bundan sonra AgentEye bunu `timeout` olarak sonlandırır. Evaluator'ın `pending`'i sonsuza kadar döndürmesine karşı korunma. | -| `ALERT_WORKERS` | Hayır | `1` | Eşzamanlılık: her sunucu örneği başına uyarı kurallarını değerlendirenişçi görevlerinin sayısı. Bkz. [Alerts](/tr/agenteye/alerts). | -| `ALERT_CLAIM_BATCH` | Hayır | `16` | Tek bir işçinin her tıkta talep ettiği maksimum uyarı sayısı. | -| `ALERT_POLL_IDLE_SECS` | Hayır | `5` | Kuyruk boş olduğunda bir uyarılar işçisinin uyuduğu süre. | -| `ALERT_REQUEST_TIMEOUT_MS` | Hayır | `15000` | Tetikleme değerlendirmesi başına zaman aşımı (ClickHouse sorguları + giden kanal HTTP). | -| `ALERT_MAX_ATTEMPTS` | Hayır | `5` | Ardışık geçici başarısızlıklar; bundan sonra uyarı üstel geri tepme yerine normal kadansında yeniden zamanlanır. | -| `AUDIT_WORKERS` | Hayır | `1` | Eşzamanlılık: her sunucu örneği başına denetimi gerçekleştirenişçi görevlerinin sayısı. Bkz. [Audits](/tr/agenteye/audits). | -| `AUDIT_CLAIM_BATCH` | Hayır | `1` | Tek bir işçinin her tıkta talep ettiği vadesi gelen maksimum denetim sayısı. Bir ajantik araştırma tek bir uzun döngüdür, bu nedenle varsayılan 1'dir. | -| `AUDIT_POLL_IDLE_SECS` | Hayır | `30` | Denetim vadesi gelmediğinde bir denetimler işçisinin uyuduğu süre. | -| `AUDIT_REQUEST_TIMEOUT_MS` | Hayır | `30000` | ClickHouse'a karşı ilke-sorgusu başına zaman aşımı (milisaniye). | -| `AUDIT_LLM_TIMEOUT_MS` | Hayır | `1440000` | AI yardımcı hizmetine ajantik araştırma çağrısı için zaman aşımı. Tam bir ajan döngüsü dakika boyunca çalışır; bu SUNUCU zaman aşımdan sonra YUKARIDA tut; böylece ajan sunucu vazgeçmeden kısmi bulgularını döndürür. | -| `AUDIT_MAX_ATTEMPTS` | Hayır | `5` | Ardışık geçici başarısızlıklar; bundan sonra denetim üstel geri tepme yerine normal kadansında yeniden zamanlanır. | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | Hayır | — | Denetimin ajantik araştırması AI-yardımcısı `agent` hizmetine çağrı yapar, **yardımcı ile aynı bağlantıyı yeniden kullanarak** — bu nedenle bunları **sunucuda** da ayarlayın (paket içi manifests/compose yapar). Her ikisi de ayarlanmışsa ⇒ denetimler AI araştırmasını çalıştırır; ya ayarlanmamışsa ⇒ denetimler **politika-yalnızca** çalıştırır (belirleyici SQL politikası geçişi hâlâ çalışır), denetim başına `llm_enabled` bayrağından bağımsız olarak. Ajan ayrıca bir LLM yapılandırılmış olmalıdır — bkz. [assistant.md](/tr/agenteye/assistant). | - -**AI yardımcı hizmeti — denetim + sandbox ayarları.** Ajantik araştırma ve pod'daki Python sandbox'u **ajan hizmetinde** ayarlanır (sunucu değil), tümü `AGENTEYE_AUDIT_*` ön eki altında ve tümü isteğe bağlı: - -| Değişken | Varsayılan | Anlam | +| `SMTP_USERNAME` | Hayır | yok | SMTP kimlik doğrulaması kullanıcı adı | +| `SMTP_PASSWORD` | Hayır | yok | SMTP kimlik doğrulaması parolası | +| `SMTP_FROM` | Hayır | yok | OTP e-postaları için gönderen e-posta adresi | +| `SMTP_TLS` | Hayır | STARTTLS | STARTTLS açıkça kapatmadığınız sürece kullanılır: `false` veya `0` düz metin gönderir (TLS yok); diğer herhangi bir değer — ayarlanmamış da dahil olmak üzere — STARTTLS'i etkinleştirir. | +| `DASHBOARD_URL` | Hayır | yerleşik varsayılan | OTP-e-posta sihirli bağlantısı ve uyarı bildirimlerindeki olay sihirli bağlantıları oluşturmak için kullanılan pano kaynağı. Ayarlanmamışsa yerleşik varsayılana geri düşer (ve yalnızca OTP için panosundan türetilen istek kökenine ilk olarak geri düşer). Bölünmüş alan kurulumları için ayarlayın, böylece hem e-posta hem de Slack/olay bağlantıları panonuza işaret eder. **E-posta sihirli bağlantı URL'si** bölümüne bakın; çoğu operatör bunu ayarlamaya gerek duymaz. | +| `SESSION_TTL_SECS` | Hayır | `86400` (24 s) | Pano oturumu süresi saniye cinsinden. **İlk önyükleme tohumlandırması**: ilk dağıtımdan sonra [`//settings`](#operational-settings) aracılığıyla org başına düzenleyin. | +| `OTP_TTL_SECS` | Hayır | `600` (10 dak) | OTP kodu geçerlilik süresi saniye cinsinden. **İlk önyükleme tohumlandırması**: ilk dağıtımdan sonra [`//settings`](#operational-settings) aracılığıyla org başına düzenleyin. | +| `REDIS_URL` | Hayır | yok | İsteğe bağlı paylaşılan önbellek + hız sınırı arka ucu, örn. `redis://redis:6379/0`. Ayarlandığında sunucu kimliği doğrulanmış API anahtarı aramaları, panonun `/models` toplamsı, oturumlar listesi ve ortam listesi grubunu önbelleğe alır; ayrıca OTP istek hız sınırlamasını Postgres COUNT'tan Redis INCR'ye taşır. Ayarlanmamışsa veya ulaşılamıyorsa, sunucu önbellek olmadan çalışır (OTP sınırı Postgres'e geri düşer, her diğer önbellek çağrısı gerçeği kaynağından düşer). Aşağıda **Redis (isteğe bağlı önbellek)** bölümüne bakın. | +| `CLICKHOUSE_URL` | **Evet** | yok | ClickHouse örneğinin temel URL'si, örn. `http://clickhouse:8123`. Sunucu bu veritabanına etkinlik şemasını her başlangıçta uygular ve ClickHouse'a ulaşamıyorsa önyüklemeden kaçınır. Aşağıda **ClickHouse (gerekli analitik deposu)** bölümüne bakın. | +| `CLICKHOUSE_DATABASE` | Hayır | `agenteye` | ClickHouse veritabanı (şema) adı. Sunucu mevcut değilse başlangıçta oluşturur. | +| `ORG_CH_SECRET` | Hayır (tek kiracılı) / **Evet (çok org)** | geliştirme varsayılanı | Her kuruluşun kiracı başına ClickHouse parolasının türetildiği HMAC anahtarı. SQL editörü ve AI ajanın `run_query` kuruluşun kendi salt okunur ClickHouse kullanıcısı olarak çalışır ve satır ilkesi motorun içinde kiracı izolasyonunu zorlar. Tek kiracılı dağıtımlar yerleşik geliştirme varsayılanı iyi önyüklenir; **ikinci bir org sağlamadan önce güçlü, kararlı bir değer ayarlaMALISINIZ** çünkü `agenteye-orgctl org create` CLI yerleşik geliştirme varsayılanında çalışmayı reddeder. Döndürmek her org'un ClickHouse kullanıcısını yetime bırakır ta ki sonraki başlangıç bunları yeniden sağlayıncaya kadar (önyükleme süresi uzlaştırması bunu otomatik olarak iyileştirir). Gizli tutun ve çoğaltmalar arasında değiştirilmeyecek olarak saklayın. Org sağlaması kendisinin operatörü; aşağıda **Kuruluşlar (çok kiracılılık)** bölümüne bakın. | +| `DEFAULT_ORG_NAME` | Hayır | `Default` | Yerleşik varsayılan org için tohumlandırılan görünen ad. **İlk önyükleme tohumlandırması**, ve yalnızca org hala yeni geçiş genel kimliğini taşırken, başlangıçta uygulanır, sonra yok sayılır. Org'u yeniden adlandırdığınızda (`agenteye-orgctl org rename`) yeniden adlandırma yetkilidir ve bu ortam değişkeninin başka etkisi yoktur. | +| `DEFAULT_ORG_SLUG` | Hayır | `default` | Yerleşik varsayılan org için URL slugu, pano yolunda yaşadığı (`//…`). `DEFAULT_ORG_NAME` ile aynı ilk önyükleme yalnızca / ilkel anlamıdır. `default` tuttuğu sürece geçersiz bir değer yok sayılır. Tek kiracılı kurulumun `/default` yerine örn. `/acme` olarak sunulmasını sağlar, post-dağıtım CLI adımı olmadan. | +| `RUST_LOG` | Hayır | `info` | Günlük ayrıntı düzeyi (`debug`, `warn`, `error`, `agenteye_server=trace`) | +| `EVALUATOR_ENDPOINT` | Hayır | yok | Değerlendirici hizmetinizin temel URL'si (örn. `http://evaluator:9000`). Ayarlanmadığında tüm değerlendirme işlem hattı no-op'dir; hiçbir kuyruk satırı yazılmaz, işçi çalışmaz. Bkz. [Değerlendirme Paketi](/tr/agenteye/evaluation-suite). | +| `EVALUATOR_TOKEN` | Hayır | yok | Değerlendirici olarak `Authorization: Bearer ` gönderilir. **Değerlendirici hizmetinin yapılandırıldığı aynı değere eşit OLMALIDIR.** İsteğe bağlı yalnızca değerlendiriciniz belirteç olmadan yapılandırılmışsa. | +| `EVALUATOR_WORKERS` | Hayır | `2` | Eşzamanlılık: sunucu örneği başına değerlendirmeler gönderen işçi görevlerinin sayısı. Yatay olarak ölçeklendirilmiş birden fazla sunucu arasında çalıştırmak güvenlidir. | +| `EVALUATOR_CLAIM_BATCH` | Hayır | `4` | Tek işçinin bir tik başına talep ettiği maksimum değerlendirme sayısı. Toplu işler **eşzamanlı olarak** gönderilir, bu nedenle değerlendirici uç noktası üzerinde toplam eşzamanlılık `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH` olur. | +| `EVALUATOR_POLL_IDLE_SECS` | Hayır | `2` | İşçi hiçbir şey gelmiş olduğunda gönderim denemeleri arasında uyuyacağı süre. | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Hayır | `10` | `GET /evaluate/{id}` yoklaması için son yedek kadansı (saniye), değerlendirici yanı başına `next_poll_secs` döndürmediğinde ve `GET /config` adresinden `default_poll_interval_secs` bildirmediğinde. | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | Hayır | `30000` | Değerlendirici karşısında HTTP istek başına zaman aşımı (milisaniye). | +| `EVALUATOR_MAX_ATTEMPTS` | Hayır | `5` | Bu kadar başarısız denemeden sonra, bir değerlendirme terminal `error` (veya başarısızlıklar istek zaman aşımlarıysa `timeout`) olarak kaydedilir. | +| `EVALUATOR_CONFIG_REFRESH_SECS` | Hayır | `300` (5 dak) | Sunucu değerlendirici'den `GET /config` öğesini yeniden getirir. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Hayır | `3600` (1 saat) | Bir oturumun yoklama sırasında kalabileceği maksimum duvar saati süresi, AgentEye bunu `timeout` olarak sonlandırmadan önce. Sonsuza kadar `pending` döndüren bir değerlendiriciyi korur. | +| `ALERT_WORKERS` | Hayır | `1` | Eşzamanlılık: sunucu örneği başına uyarı kurallarını değerlendiren işçi görevlerinin sayısı. Bkz. [Uyarılar](/tr/agenteye/alerts). | +| `ALERT_CLAIM_BATCH` | Hayır | `16` | Tek işçinin bir tik başına talep ettiği maksimum uyarı sayısı. | +| `ALERT_POLL_IDLE_SECS` | Hayır | `5` | Kuyruk boşken uyarılar işçisinin uyuması gereken süre. | +| `ALERT_REQUEST_TIMEOUT_MS` | Hayır | `15000` | Tetikleyici değerlendirmesi başına zaman aşımı (ClickHouse sorguları + giden kanal HTTP). | +| `ALERT_MAX_ATTEMPTS` | Hayır | `5` | Ardışık geçici başarısızlıklar, bir uyarı üstel geri alma yerine normal kadansında yeniden zamanlanıncaya kadar. | +| `AUDIT_WORKERS` | Hayır | `1` | Eşzamanlılık: sunucu örneği başına denetimleri yürüten işçi görevlerinin sayısı. Bkz. [Denetimler](/tr/agenteye/audits). | +| `AUDIT_CLAIM_BATCH` | Hayır | `1` | Tek işçinin bir tik başına talep ettiği maksimum yürürlükte denetim sayısı. Ajansal bir araştırma tek uzun bir döngüdür, bu nedenle varsayılan 1'dir. | +| `AUDIT_POLL_IDLE_SECS` | Hayır | `30` | Hiçbir denetim yürürlükte olmadığında denetim işçisinin uyuması gereken süre. | +| `AUDIT_REQUEST_TIMEOUT_MS` | Hayır | `30000` | ClickHouse karşısında ilke sorgusu başına zaman aşımı (milisaniye). | +| `AUDIT_LLM_TIMEOUT_MS` | Hayır | `1440000` | AI asistan hizmetine ajansal araştırma çağrısının zaman aşımı. Tam bir ajan döngüsü dakikalar çalışır; bunu sunucunun bırakılmadan önce ajan kısmi bulgularını döndürmesi için ajanın kendi `AGENTEYE_AUDIT_TIMEOUT_MS` değerinin ÜZERİNDE tutun. | +| `AUDIT_MAX_ATTEMPTS` | Hayır | `5` | Ardışık geçici başarısızlıklar, bir denetim üstel geri alma yerine normal kadansında yeniden zamanlanıncaya kadar. | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | Hayır | — | Denetimin ajansal araştırması AI asistan `agent` hizmetini çağırır, **asistan ile aynı bağlantıyı yeniden kullanarak** — bu nedenle bunları ikisini **sunucuda** da ayarlayın (paketlenmiş manifestler/compose yapar). Her ikisi ayarlanmış ⇒ denetimler AI araştırmasını çalıştırır; her ikisi ayarlanmamış ⇒ denetimler **yalnızca ilke** çalıştırır (belirlenimci SQL ilkesi geçişi yine de çalışır), per-denetim `llm_enabled` bayrağından bağımsız olarak. Ajanın da bir LLM yapılandırması olmalıdır — bkz. [assistant.md](/tr/agenteye/assistant). | + +**AI asistan hizmeti — denetim + sanal alan ayarları.** Ajansal araştırma ve pod içi Python sanal alanı **ajan hizmetinde** ayarlanır (sunucu değil), hepsi `AGENTEYE_AUDIT_*` önekinde ve hepsi isteğe bağlı: + +| Değişken | Varsayılan | Anlamı | |---|---|---| -| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Araştırma başına maksimum ajan adımları. | -| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Bir araştırma için duvar saati (20 min). Sunucunun `AUDIT_LLM_TIMEOUT_MS`'nin **altında** kalması gerekir. | -| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Ajan pod'u başına eşzamanlı araştırmalar (sohbet yardımcısının bütçesinden ayrı). | -| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Bubblewrap sandbox'u için betik başına sınırlar. | +| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Araştırma başına maksimum ajan dönüşleri. | +| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Bir araştırma için duvar saati (20 dak). Sunucunun `AUDIT_LLM_TIMEOUT_MS` değerinin **altında** kalmalıdır. | +| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Ajan başına pod başına eşzamanlı araştırmalar (sohbet asistan bütçesinden ayrı). | +| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Bubblewrap sanal alanı için komut başına sınırlar. | -**Sandbox platform gereksinimi.** Denetim kodu sandbox'u ajanın Python'unu bir bubblewrap hapishanesinde çalıştırır; bu **ayrıcalıklı olmayan kullanıcı ad alanlarına** ihtiyaç duyar. Ajan pod'u `clone()` bayraklarına izin vermelidir — `seccompProfile: Unconfined` (k8s) veya `security_opt: [seccomp:unconfined]` (compose) ayarlayın ajan'da. Düğüm kerneli ayrıcalıklı olmayan kullanıcı ad alanlarını devre dışı bırakan yerde (örn. bazı GKE COS görüntüleri), sandbox **preflight başarısız olur ve denetçi otomatik olarak SQL-only'ye düşer** — hata yok, ajan'ın `/health` üzerinde `sandbox_available: false`. +**Sanal alan platform gereksinimiş.** Denetim kodu sanal alanı modelin Python'u bir bubblewrap hapishanesinde çalıştırır, bu **ayrıcalıklı olmayan kullanıcı ad alanları** gerektirir. Ajan pod'u `clone()` bayraklarına izin vermelidir — `seccompProfile: Unconfined` ayarlayın (k8s) veya `security_opt: [seccomp:unconfined]` (compose) ajan'da. Düğüm çekirdeğinin ayrıcalıklı olmayan kullanıcı ad alanlarını devre dışı bıraktığı durumlarda (örn. bazı GKE COS görüntüleri), sanal alan **önyükleme başarısız olur ve denetim otomatik olarak yalnızca SQL'e düşer** — hata yok, ajan'ın `/health` üzerinde yalnızca `sandbox_available: false`. | -### Çalıştır +### Çalıştırma -`DATABASE_URL` ve `CLICKHOUSE_URL`'i ortamınızda ayarlayın (sunucu ClickHouse olmadan önyüklemeyi reddeder), sonra bunları kapsayıcıya geçirin: +Ortamda `DATABASE_URL` ayarlayın, ardından konteynera geçirin: ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest ``` -Sunucu, başlamada otomatik olarak veritabanı geçişlerini çalıştırır; ayrı geçiş adımı gerekli değildir. +Sunucu, başlangıçta veritabanı geçişlerini otomatik olarak çalıştırır; ayrı geçiş adımı gerekmez. -### Sistem durumu kontrolü +### Sağlık kontrolü ``` -GET /health # canlılık - işlem açıktan sonra her zaman {"status":"ok"} -GET /ready # hazırlık - Postgres + ClickHouse erişilebilir olduğunda 200, aksi durumda 503 +GET /health # canlılık - işlem başladıktan sonra her zaman {"status":"ok"} +GET /ready # hazırlık - Postgres + ClickHouse ulaşıldığında 200, aksi takdirde 503 ``` -Kimlik doğrulama gerekli değildir. **Canlılık** yoklamaları için `/health` ve **hazırlık** / yük dengeleyici yoklamaları için `/ready` kullanın. `/ready`, sunucu olmadan sunucu'nun hizmet veremediği sabit bağımlılıkları kontrol eder (Postgres + ClickHouse), bu nedenle çalışan ama veritabanına ulaşamayan sunucu döndürülürü alır ve `NotReady` olarak gösterilir; Redis raporlanır ama hiçbir zaman hazırlığı başarısız kılmaz. Paket içi Kubernetes manifests'inde hazırlık yoklaması `/ready` konumunda ve canlılık `/health` konumunda kalır. Tam resim için [enterprise-docs/health-monitoring.md](/tr/agenteye/health-monitoring) dosyasına bakın; Slack'a Kubernetes-native pod-başarısızlığı uyarısı dahil. +Kimlik doğrulama gerekmez. **Canlılık** yoklamalar için `/health` ve **hazırlık** / yük dengeleyici yoklamaları için `/ready` kullanın. `/ready` sunucunun olmadan hizmet veremeyeceği sert bağımlılıkları kontrol eder (Postgres + ClickHouse), bu nedenle çalışan ancak veritabanına ulaşamayan bir sunucu döndürülmesinin dışında tutulur ve `NotReady` olarak gösterilir; Redis raporlanır ancak asla hazırlığı başarısız yapmaz. Paketlenmiş Kubernetes manifestlerinde hazırlık yoklaması zaten `/ready` adresini işaret eder ve canlılık `/health` üzerinde kalır. Tam resim, Kubernetes-native pod-başarısızlık uyarılarını Slack'e dahil etmek için bkz. [enterprise-docs/health-monitoring.md](/tr/agenteye/health-monitoring). -### E-posta magic-link URL'i +### E-posta sihirli bağlantı URL'si -OTP oturum açma e-postaları tek-dokunuş **pano'yu aç** düğmesi içerir. Tıklamak kullanıcıyı `/login?token=&email=
` konumuna indirir; pano bu çifti bir oturum için değiştirir ve uygulamaya yeniden yönlendirir, el ile kod yeniden girişi olmadan. Sunucu, linki oluşturmak için kullanılan pano kaynağını üç katmanda çözer: +OTP oturum açma e-postaları tek dokunuşla **panoyu aç** düğmesi içerir. Tıklamak kullanıcıyı `/login?token=&email=
` adresine indirir; pano bu çifti bir oturumla değiştirir ve hiçbir manuel kod yeniden girişi olmadan uygulamaya yönlendirir. Sunucu, bağlantı oluşturmak için kullanılan pano kökenini üç katmanda çözer: -1. **`X-AgentEye-Dashboard-Url` başlığı**: pano'nun `/api/auth/otp/request` proxy'si tarafından otomatik olarak kendi genel kaynağından ayarlanır. Aynı-kaynaklı dağıtımda (sunucu ve pano host'u paylaş tek bir girişin arkasında proxy başlıklarını iletebilir), **yapılandırma gerekli değildir**. -2. **`DASHBOARD_URL` env var'ı**: pano'nuz, sunucu'nun OTP istek uç noktasının gördüğü kaynaktan farklı bir kaynakta erişilebiliyorsa (bölünmüş `api.example.com` / `app.example.com`) veya girişiniz genel host'u pano pod'una yayılamıyorsa (bu nedenle `request.nextUrl.origin` `0.0.0.0:3000` gibi bir joker karakteri bind'e çözümlenir), bunu ayarlayın. Örnek: `DASHBOARD_URL=https://app.example.com`. -3. **Varsayılan**: `https://app.befailproof.ai`, yalnızca yukarıdakilerden hiçbiri mevcut değilse kullanılır. +1. **`X-AgentEye-Dashboard-Url` başlığı**: panonun kendi genel kaynağından `/api/auth/otp/request` proxy tarafından otomatik olarak ayarlayır. Aynı kaynak dağıtımında (sunucu ve pano bir ön uç ardında bir ana bilgisayarı paylaşır, proxy başlıklarını iletir), **hiçbir yapılandırma gerekmez**. +2. **`DASHBOARD_URL` ortam değişkeni**: panonuz sunucunun OTP istek uç noktasının gördüğü orijinin farklı bir kaynağında erişilebilirse (bölünmüş `api.example.com` / `app.example.com`), veya ön ucunuz genel ana bilgisayarı pano pod'una yaymıyorsa (bu nedenle `request.nextUrl.origin` aksi takdirde `0.0.0.0:3000` gibi joker bir bağlamaya çözecektir) ayarlayın. Örnek: `DASHBOARD_URL=https://app.example.com`. +3. **Varsayılan**: `https://app.befailproof.ai`, yalnızca yukarıdaki her ikisi yoksa kullanılır. -Başlık değeri doğrulanır: yalnızca `https://*` ve loopback (`http://localhost*`, `http://127.0.0.1*`) kaynakları kabul edilir ve joker karakteri bind adresleri (`0.0.0.0`, `[::]`) `https://` şemasıyla bile reddedilir. Başka herhangi bir şey katman 2'ye düşer. +Başlık değeri doğrulanır: yalnızca `https://*` ve geri döngü (`http://localhost*`, `http://127.0.0.1*`) kaynakları kabul edilir ve joker bağlama adresleri (`0.0.0.0`, `[::]`) `https://` şemasıyla bile reddedilir. Başka bir şey katman 2'ye düşer. -Çalışan küme üzerinde tek satırlı olarak ayarlayın; dosya yok, kustomize yeniden derleme yok: +Çalışan bir kümede tek satırlı olarak ayarlayın; dosya yok, kustomize yeniden derlemesi yok: ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -Bu bir dağıtımı tetikler; yeni pod'lar değeri ilk istekte alır. Override'ın yalnızca Dağıtımda yaşadığını unutmayın; sonraki `kustomize build | kubectl apply` overlay'a karşı, aynı env var'ı overlay'ın `server-env.yaml` yamalamasına eklemediğiniz sürece bunu silecektir. +Bu bir dağıtımı tetikler; yeni pod'lar ilk istekte değeri alır. Geçersiz kılmanın yalnızca Dağıtımda yaşadığını unutmayın; sonraki `kustomize build | kubectl apply` ön ek aşılıya karşı, ön ekinizdeki `server-env.yaml` yama aynı ortam değişkenini eklemediniz sürece bunu silecektir. --- ## Pano -### Görüntüyü çek +### Görüntüyü çekin ```bash docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest @@ -168,16 +167,16 @@ docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest | Değişken | Gerekli | Varsayılan | Açıklama | |---|---|---|---| -| `AGENTEYE_SERVER_URL` | Evet | yok | Sunucunun temel URL'i, örn. `http://localhost:8080` | -| `AGENTEYE_API_KEY` | Evet | yok | Pano'nun sunucu'ya kimlik doğrulamak için kullandığı API anahtarı. Tüm izinleri gerektirir (admin anahtarı önerilir). | -| `AE_LOG_LEVEL` | Hayır | `info` | Sunucu tarafı günlük ayrıntıları: `debug`, `info`, `warn`, `error`. Sorunları tanılarken yukarı yönlü istek/yanıt satırlarını ve oturum-doğrulama izlerini görmek için `debug` olarak ayarlayın. | -| `AE_LOG_JSON` | Hayır | otomatik | `1` JSON-satır başına çıktıyı zorlar; `0` okunabilir çıktıyı zorlar. Ayarlanmazsa, `NODE_ENV=production` ise JSON otomatik olarak etkinleştirilir. JSON üretimde önerilir, böylece günlükler `jq` veya günlük toplayıcı ile düzgün ayrıştırılır. | -| `AE_ANALYTICS_DISABLED` | Hayır | yok | Pano'nun anonim ürün-kullanımı telemetrisini devre dışı bırakmak için `1`/`true` olarak ayarlayın. Aşağıda [Telemetri & gizlilik](#telemetri--gizlilik) bölümüne bakın. | -| `REDIS_URL` | Hayır | yok | İsteğe bağlı paylaşılan önbellek arka ucu, örn. `redis://redis:6379/0`. Ayarlandığında, pano `validateSession()` sonuçlarını çoğaltmalar arasında önbelleğe alır ve gecikme-toplama / env-list proxy rotaları için Next.js getirme önbelleğini paylaşır. Kenar tarafı OTP istek ve doğrulama oran sınırları mevcut olduğunda Redis kullanır (Redis erişilemezse açık kalır; sunucu tarafı sınırı güvenlik yedek saklayıcısıdır). **Redis (isteğe bağlı önbellek)** bölümüne bakın. | -| `AGENTEYE_AGENT_URL` | Hayır | yok | İsteğe bağlı AI-yardımcısı `agent` hizmetinin temel URL'i, örn. `http://agent:9100`. **Ayarlanmamış bırakın ve yardımcıyı tamamen gizleyin**: pano'da yardımcı balonu görünmez. Bkz. [enterprise-docs/assistant.md](/tr/agenteye/assistant). | -| `AGENTEYE_AGENT_TOKEN` | Hayır | yok | Pano'nun `agent` hizmetine sunduğu paylaşılan gizli. Ajan'da yapılandırılan `AGENTEYE_AGENT_TOKEN` ile eşleşmesi gerekir. Bkz. [enterprise-docs/assistant.md](/tr/agenteye/assistant). | +| `AGENTEYE_SERVER_URL` | Evet | yok | Sunucunun temel URL'si, örn. `http://localhost:8080` | +| `AGENTEYE_API_KEY` | Evet | yok | Panonun sunucuda kimlik doğrulaması yapmak için kullandığı API anahtarı. Tüm izinleri gerektirir (yönetici anahtarı önerilir). | +| `AE_LOG_LEVEL` | Hayır | `info` | Sunucu tarafı günlük ayrıntı düzeyi: `debug`, `info`, `warn`, `error`. Sorunları tanılarken yukarı akış istek/yanıt satırlarını ve oturum doğrulaması izlerini görmek için `debug` ayarlayın. | +| `AE_LOG_JSON` | Hayır | otomatik | `1` JSON-per-satır çıktısını zorlar; `0` insan tarafından okunabilir çıktıyı zorlar. Ayarlanmadığında, `NODE_ENV=production` ise JSON otomatik olarak etkinleştirilir. Üretimde JSON önerilir, böylece günlükler `jq` veya bir günlük toplayıcı ile temiz biçimde ayrıştırılır. | +| `AE_ANALYTICS_DISABLED` | Hayır | yok | Panonun anonim ürün kullanımı telemetrisini devre dışı bırakmak için `1`/`true` ayarlayın. Aşağıda [Telemetri & Gizlilik](#telemetry--privacy) bölümüne bakın. | +| `REDIS_URL` | Hayır | yok | İsteğe bağlı paylaşılan önbellek arka ucu, örn. `redis://redis:6379/0`. Ayarlandığında pano çoğaltmalar arasında `validateSession()` sonuçlarını önbelleğe alır ve gecikme toplama / ortam listesi proxy rotaları için Next.js getirme önbelleğini paylaşır. Edge-side OTP istek ve doğrulama hız sınırları mevcut olduğunda Redis'i kullanır (Redis ulaşılamıyorsa açılır; sunucu tarafı sınırı güvenlik yedeklenidir). Aşağıda **Redis (isteğe bağlı önbellek)** bölümüne bakın. | +| `AGENTEYE_AGENT_URL` | Hayır | yok | İsteğe bağlı AI-asistan `agent` hizmetinin temel URL'si, örn. `http://agent:9100`. **Asistanı tamamen gizlemek için ayarlanmış halde bırakın**: pano asistan balonu görünmez. Bkz. [enterprise-docs/assistant.md](/tr/agenteye/assistant). | +| `AGENTEYE_AGENT_TOKEN` | Hayır | yok | Panonun `agent` hizmetine sunduğu paylaşılan gizli. Ajan'da yapılandırılan `AGENTEYE_AGENT_TOKEN` ile eşleşmeli. Bkz. [enterprise-docs/assistant.md](/tr/agenteye/assistant). | -### Çalıştır +### Çalıştırma ```bash docker run -d --restart unless-stopped \ @@ -188,91 +187,91 @@ docker run -d --restart unless-stopped \ ghcr.io/agenteye-enterprise/dashboard:beta-latest ``` -### Telemetri & gizlilik +### Telemetri & Gizlilik -Pano, **anonim ürün-kullanımı analitiğini** Exosphere'ın analitik hizmetine (PostHog) gönderir: hangi pano sayfalarının görüntülendiği ve API anahtarı oluşturma veya oturumun yeniden değerlendirilmesi gibi bir avuç UI eylemi. Bu kullanım sinyali hangi özelliklerin önceliklendirildiğini bilgilendirir. +Pano, **anonim ürün kullanımı analitikleri** Exosphere'in analitik hizmetine (PostHog) gönderir: hangi pano sayfalarının görüntülendiği ve API anahtarı oluşturma veya oturumu yeniden değerlendirme gibi bir avuç UI eylemi. Bu kullanım sinyali hangi özelliklerin önceliklendirildiğini bildiridir. -- **Hiçbir ajan, oturum veya etkinlik verisi altyapınızı asla terk etmez.** Yalnızca pano UI kullanımı raporlanır. Sayfa URL'leri gönderilmeden önce tanımlayıcılardan temizlenir ve operatörler yalnızca opak iç kimliğe göre, asla e-postaya göre tanımlanır. -- Telemetri **varsayılan olarak etkindir**. Tamamen kapatmak için pano konteynerine `AE_ANALYTICS_DISABLED=1` ayarlayın ve yeniden başlatın. -- Analitikler pano'nun kendi `/ingest` yoluna gönderilir, pano bunu PostHog'a (`https://us.i.posthog.com`) ters proxy'ler. İstekleri birinci tarafa almak, tarayıcı ad-bloklayıcılarının bunları bırakmaması anlamına gelir. **Pano konteyner'ı** PostHog'a giden erişime ihtiyaç duyar; engellenmişse, telemetri sessizce hiçbir şey yapmaz ve pano etkilenmez. +- **Agent, oturum veya etkinlik verileri hiçbir zaman altyapınızdan ayrılmaz.** Yalnızca pano UI kullanımı raporlanır. Sayfa URL'leri göndermeden önce tanımlayıcılardan çıkarılır ve operatörler asla e-posta tarafından değil, yalnızca opak bir iç kimliği tarafından tanımlanır. +- Telemetri **varsayılan olarak etkindir**. Tamamen kapatmak için panonun konteynerinde `AE_ANALYTICS_DISABLED=1` ayarlayın ve yeniden başlatın. +- Analitikler panonun kendi `/ingest` yoluna gönderilir, pano PostHog'a ters proxy yapar (`https://us.i.posthog.com`). İstekleri birinci taraf olarak tutmak, tarayıcı reklam engelleyicilerin bunları bırakmaması anlamına gelir. **Pano konteyneri** PostHog'a giden erişime ihtiyaç duyar; engellenmişse telemetri sessizce hiçbir şey yapmaz ve pano etkilenmez. --- -## AI Yardımcısı (isteğe bağlı) +## AI Asistanı (isteğe bağlı) -Pano içi AI yardımcısı, ekibinizin agent verilerini düz dilinde sormalarını sağlar (oturumları özetlemek, `/queries` editörü için SQL taslağı hazırlamak ve kaydedilen sorguları pano kutucuklarına dönüştürmek) pano'yu terk etmeden. Ayrı bir dahili `agent` konteyner'inde (Claude Agent SDK'da) çalışır, yalnızca pano'ya erişebilir ve **bir LLM uç noktası yapılandırıncaya kadar devre dışı kalır**. +Pano içi AI asistanı, ekibinizin Agent veri hakkında düz dilde soru sormasına (oturumları özetleme, `/queries` editörü için SQL taslakları ve kaydedilmiş sorguları pano kutucuklarına dönüştürme) panodan ayrılmadan izin verir. Bağımsız bir dahili `agent` konteynerinde (Claude Agent SDK'da) çalışır, yalnızca pano ulaşabilir ve **bir LLM uç noktası yapılandırana kadar devre dışı kalır**. -Etkinleştirmek için, `agent` hizmetine bir LLM bağlantısı (**Portkey** via `PORTKEY_API_KEY` + model-katalog slug `AGENTEYE_AGENT_MODEL=@/`, doğrudan Anthropic via `ANTHROPIC_API_KEY`, başka bir ağ geçidi via `ANTHROPIC_BASE_URL` veya Bedrock/Vertex), **adanmış** veri anahtarı ve pano ile eşleşen paylaşılan `AGENTEYE_AGENT_TOKEN` ayarlarsınız. Pano kullanıcıları ek olarak `agent:use` iznine ihtiyaç duyar. +Etkinleştirmek için `agent` hizmetinde bir LLM bağlantısı (**Portkey** aracılığıyla `PORTKEY_API_KEY` + model-katalog sonu `AGENTEYE_AGENT_MODEL=@/`, doğrudan Anthropic aracılığıyla `ANTHROPIC_API_KEY`, başka bir ağ geçidi aracılığıyla `ANTHROPIC_BASE_URL` veya Bedrock/Vertex), **ayrılmış** bir veri anahtarı ve panola eşleşen paylaşılan `AGENTEYE_AGENT_TOKEN` ayarlayın. Pano kullanıcıları ek olarak `agent:use` izni gerektirir. -Yardımcının veri anahtarı için el ile hiçbir şey basmazsınız: rastgele gizli seçin, `agent` üzerinde `AGENTEYE_API_KEY` ve `server` üzerinde `AGENT_API_KEY` olarak ayarlayın ve sunucu başlangıçta sabit bir izin setiyle seed'ler. Veri erişimi salt-okunur (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`) ve ek olarak onay geçitli yazma kapsamlarını tutar (`dashboards:write`, `queries:write`, `queries:run`) böylece kaydedilen sorguları ve pano kutucuklarını kullanıcı adına tasarını doğrulayabilir; tüm SQL yine de org'un salt-okunur ClickHouse rolü aracılığıyla çalışır, bu yüzden bu yardımcının yazabileceğini genişletir, ulaşabileceği veri değil. Kapsamlar koddaki fixed'dir ve yapılandırma tarafından genişletilemez. Bu anahtar korunur; API aracılığıyla devre dışı bırakılamaz veya yeniden oluşturulamaz, yalnızca değeri değiştirerek ve yeniden başlatarak döndürülür. Asla admin/pano anahtarını bunu için yeniden kullanmayın. +Asistanın veri anahtarı için elle hiçbir şey basılmaz: rastgele bir gizli seçin, `agent` üzerinde `AGENTEYE_API_KEY` olarak ve `server` üzerinde `AGENT_API_KEY` olarak ayarlayın ve sunucu başlangıçta bunu sabit bir izin kümesi ile tohurnlanır. Veri erişimi salt okunur (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`) ve ek olarak onay geçidi yazarlık kapsamları tutar (`dashboards:write`, `queries:write`, `queries:run`) böylece kullanıcının adına kaydedilmiş sorguları ve pano kutucuklarını taslaklandırabilir ve doğrulayabilir; tüm SQL yine de org'un salt okunur ClickHouse rolü aracılığıyla çalışır, bu nedenle bu asistanın hangi veri yazabileceğini yığar, ulaşabileceği verileri değil. Kapsamlar kodda sabitlenmiş ve yapılandırma tarafından genişletilemez. Bu anahtar korunur; API aracılığıyla devre dışı bırakılamaz veya yeniden oluşturulamaz, yalnızca değeri değiştirerek ve yeniden başlatarak döndürülebilir. Yönetici/pano anahtarını hiçbir zaman bu amaç için yeniden kullanmayın. -Tam kurulum, tam ortam-değişkeni referansı, telemetri seçenekleri ve güvenlik modeli **[enterprise-docs/assistant.md](/tr/agenteye/assistant)** sayfasındadır. +Tam kurulum, tam ortam değişkeni referansı, telemetri seçenekleri ve güvenlik modeli **[enterprise-docs/assistant.md](/tr/agenteye/assistant)** içindedir. --- -## ClickHouse (gerekli analitik depo) +## ClickHouse (gerekli analitik deposu) -ClickHouse, panolarınızı yüksek etkinlik hacimlerinde duyarlı tutar ve `/queries` SQL editörünün etkinlikler, değerlendirmeler ve oturumlar arasında tek bir depoda birleştirilmesine izin verir. Alınan her etkinlik, her terminal değerlendirme sonucu ve türetilmiş oturum başına toplamlar için gerekli kurallı depo olur. PostgreSQL ilişkisel / değiştirilebilir-durum tablolarını tutar (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); analitik yüzey ClickHouse'da yaşar, bu yüzden pano'nuzun toplamları ve kendi SQL sorgularınız veri tabanları arasında tur yapılmadan onu veya katılması yapılmayan tüm deponuzda taraması yapılabilir. Sunucu `CLICKHOUSE_URL` olmadan önyüklemeyi reddeder. +ClickHouse yüksek etkinlik birimlerinde panonuları duyarlı tutar ve `/queries` SQL editörü etkinlikleri, değerlendirmeleri ve oturumları tek mağazada birleştirmeyi sağlar. Bu, her alınan etkinlik, her terminal değerlendirme sonucu ve türetilmiş oturum başına toplamaların gerekli kanonik deposudur. PostgreSQL ilişkisel / değişebilir durum tablolarını tutar (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); analitik yüzey ClickHouse'ta yaşar, böylece panonun açılmış işlemleri ve kendi SQL sorgularınız bunu yerel olarak tarayabilir ve birleştirebilir, veritabanları arası gidiş dönüş olmadan. Sunucu `CLICKHOUSE_URL` olmadan önyüklemeden kaçınır. ### Şema -Üç ClickHouse nesnesi sunucu başlangıcında oluşturulur, tümü idempotent (`CREATE IF NOT EXISTS`): +Üç ClickHouse nesnesi sunucu başlangıcında oluşturulur, tüm idempotenttir (`CREATE IF NOT EXISTS`): -- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, `toYYYYMM(ts)` tarafından bölümlenmiş, `(session_id, ts, dedup_key)` tarafından sıralanmış. Yinelenen eklemeler (collector yeniden denemeleri) birleştirme saatinde tek satıra çöker; sunucu her etkinlik için belirleyici SHA-256 `dedup_key` hesaplar, böylece yeniden denemeler güvenlidir. -- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, `toYYYYMM(finished_at)` tarafından bölümlenmiş, `(session_id, finished_at, dedup_key)` tarafından sıralanmış. Terminal değerlendirme sonucu başına evaluator boru hattı tarafından bir kez yazılır. `events` ile aynı dedup-key modeli. -- **`agenteye.agent_sessions`**: fiziksel bir tablo değil, `agenteye.events` üzerinde bir **VIEW**. Her sütun türetilir (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()` vb.). Olay başına yükseltme ve ayrı geri doldurma yok; görünüm `events` içinde ne varsa otomatik olarak yansıtır. +- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, `toYYYYMM(ts)` ile bölümlendirilmiş, `(session_id, ts, dedup_key)` ile sıralanmış. Yinelenen eklenmeler (toplayıcı yeniden denemeleri) birleştirme zamanında tek satıra çöker; sunucu her etkinlik için belirlenimci bir SHA-256 `dedup_key` hesaplar, böylece yeniden denenmeler güvenlidir. +- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, `toYYYYMM(finished_at)` ile bölümlendirilmiş, `(session_id, finished_at, dedup_key)` ile sıralanmış. Her terminal değerlendirme sonucu için değerlendirici ardışık düzen tarafından bir kez yazılır. `events` ile aynı dedup-anahtar modeli. +- **`agenteye.agent_sessions`**: fiziksel bir tablo değil, `agenteye.events` üzerindeki bir **VIEW**. Her sütun türetilmiş (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, vb.). Etkinlik başına upsert yok ve ayrı backfill yok; görünüm otomatik olarak `events` içinde ne varsa yansıtır. -Kaydedilmiş sorguların `analytics.evaluations` / `analytics.sessions` başvurusunda ileriye yönelik uyumluluğu için, sunucu ayrıca `agenteye.*` tabloları üzerinde görünümlerle `analytics` ClickHouse veritabanı oluşturur; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` doğru şekilde çözümlenebilir. +Öncek uyumluluk için `analytics.evaluations` / `analytics.sessions` başvuran kaydedilmiş sorgularla, sunucu ayrıca `agenteye.*` tablolarında görünümler içeren `analytics` ClickHouse veritabanını oluşturur; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` hepsi doğru şekilde çözülür. ### Yapılandırma -Paket içi docker-compose ve `deploy/base/clickhouse/` AgentEye'ın iş yüküne göre ayarlanan ClickHouse hizmeti ile gelir: +Paketlenmiş docker-compose ve `deploy/base/clickhouse/` AgentEye iş yükü için ayarlanmış bir ClickHouse hizmeti içerir: -- 2 GiB isteme / 4 GiB sınırı hafıza paket içi temel overlay'da (küçük POC/staging düğümlere sığmak için boyutlandırılır); üretim müşterileri yükseltme overlay yapmalıdır — önerilen taban katı 2c / 4Gi istek, 6c / 8Gi sınırıdır. `max_server_memory_usage_to_ram_ratio=0.9` -- 5 GiB işaret önbelleği + 8 GiB sıkıştırılmamış önbellek +- 2 GiB istenen / 4 GiB limit bellek paketlenmiş temel ön ek (küçük POC/hazırlık düğümlerine sığmak için boyutlandırılmış); üretim müşterileri ön ek tekrar olmalıdır — önerilen alt sınır 2c / 4Gi istek, 6c / 8Gi sınırıdır. `max_server_memory_usage_to_ram_ratio=0.9` +- 5 GiB mark önbellek + 8 GiB sıkıştırılmamış önbellek - `background_pool_size=16`, `background_merges_mutations_concurrency_ratio=2` - MergeTree: `parts_to_throw_insert=3000`, `parts_to_delay_insert=1500`, `non_replicated_deduplication_window=1000` - `local_io_method=auto` (desteklenen çekirdeklerde io_uring) -- `fsync_metadata=0`: en az bir kez alım + ReplacingMergeTree dedup nedeniyle kabul edilebilir -- `query_log` etkin, 30 günlük TTL ile; `query_thread_log` kaldırıldı (yüksek QPS'de pahalı) +- `fsync_metadata=0`: at-least-once alım + ReplacingMergeTree dedup nedeniyle kabul edilebilir +- `query_log` 30 günlük TTL etkinleştirilmiş; `query_thread_log` kaldırılmış (yüksek QPS'de pahalı) - `max_execution_time=30` kullanıcı tarafı sorguları için -- 100 GiB PVC StatefulSet şablonunda (müşteri overlay'ları üretim için hızlı SSD depolama sınıfına geçersiz kılmalıdır) +- StatefulSet şablonunda 100 GiB PVC (müşteri ön ekleri üretim için hızlı SSD depolama sınıfına geçersiz kılmalıdır) ### Yedeklemeler -Tam veri setiniz her gece tek bir geri yüklenebilir arşivde yakalanır, böylece bir küme veya depolama kaybı kurtarılabilir. ClickHouse otomatik olarak `agenteye-backup` CronJob'u tarafından yedeklenir; günlük PostgreSQL ve ClickHouse'u tek bir geçişte dökümü yapar. ClickHouse HTTP API'si aracılığıyla okunur: `agenteye.events` ve `agenteye.evaluations` ClickHouse-native biçiminde boşaltılır (görünümler ve satır politikaları başlangıçta sunucu tarafından yeniden oluşturulur, böylece tablo verisi tam resim olur) ve Postgres dökümü ile tek bir sıkıştırılmış arşive birleştirilir ve nesne depolamasına yüklenir. +Tam veri setin tek bir geri yüklenebilir arşivde her gece yakalanır, bu nedenle küme veya depolama kaybı kurtarılabilir. ClickHouse günlük `agenteye-backup` CronJob'u tarafından otomatik olarak yedeklenir, bu da bir geçişte hem PostgreSQL hem de ClickHouse'u döker. ClickHouse HTTP API'si üzerinden okunur: `agenteye.events` ve `agenteye.evaluations` ClickHouse-native biçiminde dökerlenmiştir (görünümler ve satır ilkeleri sunucu başlangıcında yeniden oluşturulur, böylece tablo verileri tam resimdir) ve Postgres dökümü ile nesne depolamaya yüklenen tek bir sıkıştırılmış arşive birleştirilmiş. -Hedef tuş kutusu ve bulut kimlik bilgileri overlay'a göre yapılandırılır. Yükleme yapılandırması ve geri yükleme adımları için [enterprise-docs/kubernetes-deployment.md](/tr/agenteye/kubernetes-deployment) **Yedeklemeler** bölümüne bakın. +Hedef bucket ve bulut kimlik bilgileri ön ek başına yapılandırılır. Yükleme yapılandırması ve geri yükleme adımları için [enterprise-docs/kubernetes-deployment.md](/tr/agenteye/kubernetes-deployment) **Yedeklemeler** bölümüne bakın. --- ## Redis (isteğe bağlı önbellek) -Redis, sunucu ve pano tarafından kullanılan **isteğe bağlı** paylaşılan önbellek + oran-sınırlama arka ucudur. Redis dağıtılmış ve `REDIS_URL` her iki hizmette ayarlandığında: +Redis, sunucu ve pano tarafından kullanılan **isteğe bağlı** bir paylaşılan önbellek + hız sınırı arka ucu. Redis dağıtılırken ve `REDIS_URL` her iki hizmette ayarlandığında: -- **Sunucu** kimlik doğrulaması yapılmış API-key araştırmalarını, `/events/environments` + `/evaluations/environments` listelerini, `/events/latency_aggregate` toplamını (pano'nun yokladığı en ağır sorgu), `/sessions` listesini önbelleğe alır ve OTP-istek oran sınırlamasını Postgres `COUNT(*)` konumundan Redis `INCR + EXPIRE` konumuna geçirir. -- **Pano** `validateSession()` sonuçlarını çoğaltmalar arasında önbelleğe alır, böylece tipik sayfa yüklemesi 10-20 kimlik doğrulaması yapılmış API çağrısının tümü bir yukarı yönlü oturum kontrolünü paylaşır. Ek olarak pano kenarında OTP-istek ve OTP-verify'ı oran sınırlaması yapar. +- **Sunucu** kimliği doğrulanmış API anahtarı aramaları, `/events/environments` + `/evaluations/environments` listeleri, `/events/latency_aggregate` açılmış (panonun yokladığı en ağır sorgu), `/sessions` listesi önbelleğe alır ve OTP istek hız sınırlamasını Postgres `COUNT(*)` adresinden Redis `INCR + EXPIRE` adresine değiştirir. +- **Pano** `validateSession()` sonuçlarını çoğaltmalar arasında önbelleğe alır, böylece tipik sayfa yükü sorunları olan 10-20 authed API çağrısı tüm bir yukarı akış oturumu kontrolü paylaşır. Ayrıca panonun kenarında OTP istek ve OTP doğrulama hız sınırı tutar. -**Her iki hizmet de Redis erişilemezse incelikle düşer.** Her önbellek çağrısı sınırlandırılmış bir zaman aşımı içinde `Err` döndürür ve arayan gerçek kaynağa geri döner (sunucu üzerinde Postgres, pano'da yukarı yönlü Rust sunucu). OTP oran sınırlaması sunucu üzerinde Postgres `COUNT(*)` yoluna geri döner (güvenlik özelliği korunur); pano'nun kenar OTP sınırı açık kalırken sunucu tarafı sınırı hâlâ tutulur. Redis'in aşağı olması gecikmeyi, doğruluğu değil. Sunucu ve pano her iki tarafında gradual cache misses yönlendirmek için `REDIS_URL` set'ini kullanan her mekanizmanın yedeği açık tutmalı, ne Redis ne de kaynak erişilemezse her zaman orijinal veri tarafına dönmelidir. +**Her iki hizmet de Redis ulaşılamıyorsa incelikle düşer.** Her önbellek çağrısı sınırlı bir zaman aşımı içinde `Err` döndürür ve çağıran gerçeği kaynağına geri düşer (sunucuda Postgres, panonun yukarı akış Rust sunucusu). OTP hız sınırı sunucuda Postgres `COUNT(*)` yoluna geri düşer (güvenlik özelliği korunur); panonun kenar OTP sınırı Redis ulaşılamıyorsa açılır, sunucu tarafı sınırı hala tutar. Redis kapalı olduğunda gecikmeyi düşürür, doğruluk değil. ### Yapılandırma -docker-compose paketi zaten bir Redis hizmeti içerir ve `REDIS_URL=redis://redis:6379/0` öğesini sunucu ve pano'ya bağlar. Harici Redis kullanmak için `REDIS_URL`'yi uç noktanıza ayarlayın ve compose dosyasından `redis` hizmetini kaldırın. +docker-compose paket zaten Redis hizmetini ve `REDIS_URL=redis://redis:6379/0` sunucu ve panoyu içerir. Harici Redis kullanmak için `REDIS_URL` uç noktanız olarak ayarlayın ve compose dosyasından `redis` hizmetini kaldırın. -### Hafıza + kalıcılık +### Bellek + kalıcılık -Paket içi Redis görüntüsü `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru` öğesiyle çalışır. AOF kalıcılığı, önbelleğin konteyner yeniden başlamalarından sağ kalması anlamına gelir; `everysec` dayanıklılık/perf dengesi doğrusudr, çünkü son saniye önbellek yazış kaybetme zararsızdır. LRU çıkarma hafıza büyümesini tutar. +Paketlenmiş Redis görüntüsü `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru` ile çalışır. AOF kalıcılığı, önbelleğin kapsayıcı yeniden başlatmalarından kurtulması anlamına gelir; `everysec` doğru dayanıklılık/perf dengesidir çünkü son saniyelik önbellek yazmaları kaybı zararsızdır. LRU tahliye bellek büyümesini sınırlar. -### Redis dağıtılmaması gereken durumlar +### Redis dağıtmamak için -- Tek örnek dev/QA. Sunucu'daki in-process önbellekler tek başına çoğu çoğaltma başına yararı sağlar; Redis tek örnek kurulumların ihtiyaç duymadığı çoğaltmalar arası paylaşım ekler. -- Hava boşluğu konfigürasyonları; bir hizmetin operasyonel maliyeti gecikme kazancından daha ağır görülmektedir. +- Tek örnek geliştirme/QA. Sunucuda işlem içi önbellekler tek başına çoğu per-çoğaltma avantajını teslim eder; Redis, tek örnek kurulumları gereken çapraz çoğaltma paylaşımını ekler. +- Bir hizmeti daha çalıştırmanın operasyonel maliyeti gecikme kazancından daha ağır olan hava geçitli kurulumlar. --- -## Docker Compose (önerilir) +## Docker Compose (önerilen) -`agenteye-enterprise/releases` deposunda bir `docker-compose.yml` mevcuttur. Postgres, ClickHouse, Redis, sunucu ve pano'yu tek bir komutla açar. +`agenteye-enterprise/releases` deposunda bir `docker-compose.yml` mevcuttur. Postgres, sunucusu ve panosu tek komutla getirtir. ```bash GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ @@ -282,19 +281,19 @@ GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ cd agenteye ``` -**Varsayılan değerleri `.env` aracılığıyla geçersiz kılın:** +**`.env` aracılığıyla varsayılanları geçersiz kılın:** ``` -# URL-safe şifreler kullanın (/, +, veya = karakteri yok). -# Şu komutu kullanarak oluşturun: openssl rand -hex 24 +# URL-safe parolalar kullanın (/, +, veya = karakterleri yok). +# Oluştur: openssl rand -hex 24 POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret -# Pano kimlik doğrulaması +# Pano kimlik doğrulması ADMIN_EMAIL=admin@yourcompany.com ALLOWED_EMAILS=*@yourcompany.com -# OTP e-postaları için SMTP (OTP kodlarını stdout'a günlüğe kaydetmek için atla) +# OTP e-postaları için SMTP (OTP kodlarını stdout'a kaydetmek için atla) # SMTP_HOST=smtp.yourprovider.com # SMTP_PORT=587 # SMTP_USERNAME=your-smtp-user @@ -308,13 +307,13 @@ RUST_LOG=info docker compose up -d ``` -**Durdur (veri hacmini tutar):** +**Dur (veri birimini tutar):** ```bash docker compose down ``` -**Durdur ve tüm veriyi sil:** +**Dur ve tüm verileri sil:** ```bash docker compose down -v @@ -322,94 +321,95 @@ docker compose down -v --- -## İşletme ayarları +## İşletimsel ayarlar -Daha önce env var'ları tarafından sabitlenen bir dizi işletme kolu şimdi pano'nun **`//settings`** sayfasından kuruluş başına düzenlenebilir; her org kendi öğesini yapılandırır. Değişiklikler saniyeler içinde etkinleşir, yeniden başlatma veya yeniden dağıtım olmadan. +Ortam değişkenleri tarafından sabitlenmiş küçük bir operasyonel düğme seti artık panonun **`//settings`** sayfasından kuruluş başına düzenlenebilir; her org kendi yapılandırır. Değişiklikler saniyeler içinde etkili hale gelir, yeniden başlatma yok ve yeniden dağıtma yok. -| Ayar | Bootstrap env var | Ne kontrolü yapıyor | +| Ayar | Önyükleme ortam değişkeni | Ne denetler | |---|---|---| -| İzin verilen sign-inler | `ALLOWED_EMAILS` | OTP almaya ve kullanıcı olarak eklenmesine izin verilen e-postalar (veya `*@domain.com` joker karakterleri) | -| Varsayılan kullanıcı izinleri | `DEFAULT_USER_PERMISSIONS` | Yönetici **+ yeni kullanıcı** açtığında önceden seçilen virgülle ayrılmış izin belirteçleri. Her belirteç [API anahtarı izinleri](/tr/agenteye/api-keys) altında listelenen dizelerden biri olmalıdır. Varsayılan olarak `standard` ön ayarına gider: salt-okunur erişim ve günlük on-call eylemleri (yeniden değerlendirmeleri tetikle, sorguları çalıştır, olayları kabul et, yardımcıyı kullan). | -| Oturum ömrü | `SESSION_TTL_SECS` | Pano oturum açması yeniden auth'a kadar ne kadar geçerli kalır? Pano yukarı yönlü oturumu her 5 saniyede yeniden kontrol eder, bu yüzden `//users` işlemindeki izin güncellemesi sonraki istek'te etkilenen kullanıcıya etkinleşir; relogin yok. | -| Tek seferlik kod ömrü | `OTP_TTL_SECS` | OTP / magic-link ne kadar kullanılabilir kalır? | -| Uyarı bildirim kanalları | `ALERTS_ENABLED_CHANNELS` | Uyarı sevkiyatçısının kullanmasına izin verilen kanal türlerinin virgülle ayrılmış listesi: `email`, `slack`, `webhook`. Kanal başına yapılandırma yine de `//alerts/` işleminde yazılır ama sevkiyatçı her giden teslimatı bu set aracılığıyla filtreler; burada devre dışı bırakılan kanal `skipped_disabled` denetim satırıyla kısa devre yapar. `dashboard` kanalı (yerel denetim ekleme) her zaman izinlidir. Varsayılan olarak üçü de açık. | +| İzin verilen oturum açmalar | `ALLOWED_EMAILS` | OTP almalarına izin verilen e-postalar (veya `*@domain.com` joker karakterleri) ve kullanıcı olarak eklenir | +| Varsayılan kullanıcı izinleri | `DEFAULT_USER_PERMISSIONS` | Bir yönetici **+ yeni kullanıcı** açtığında önceden seçilen virgülle ayrılmış izin jetonları. Her jeton [API anahtarı izinleri](/tr/agenteye/api-keys) altında listelenen dizelerden biri olmalıdır. `standard` ön ayarına varsayılan: salt okunur erişim ve günlük gündüz eylem (değerlendirmeleri yeniden tetikleme, sorgular çalıştırma, olayları onaylama, asistanı kullanma). | +| Oturum yaşam süresi | `SESSION_TTL_SECS` | Pano oturum açması yeniden kimlik doğrulamadan önce ne kadar geçerli kalır. Pano yukarı akış oturumunu her 5 saniyede yeniden kontrol eder, bu nedenle `//users` üzerindeki izin güncellemesi etkilenen kullanıcının sonraki isteğinde, yeniden oturum açılmadan etkili olur. | +| Tek kullanımlık kod yaşam süresi | `OTP_TTL_SECS` | OTP / sihirli bağlantı ne kadar süreyle kullanılabilir kalır | +| Uyarı bildirim kanalları | `ALERTS_ENABLED_CHANNELS` | Uyarı göndericisinin kullanmasına izin verilen kanal türlerinin virgülle ayrılmış listesi: `email`, `slack`, `webhook`. Per-uyarı yapılandırması hala `//alerts/` üzerinde yazılır, ancak göndericisi bu küme aracılığıyla her giden teslimi filtreler; burada devre dışı bırakılan bir kanal `skipped_disabled` denetim satırı ile kısa devreye girer. `dashboard` kanalı (yerel denetim ekleme) her zaman izin verilir. Üçünün tümü açılmış olarak varsayılan ayarlar. | -### Bootstrap'ın işleyişi +### Önyükleme nasıl çalışır -Ayarlar kuruluş başına `org_settings`'te saklanır. İlk önyüklemede, sunucu varsayılan org'un eksik satırlarını eşleşen env var'dan (veya env var'ı ayarlanmazsa makul bir varsayılandan) seed'ler. Bundan sonra, **saklanan değer gerçek kaynaktır ve env var'ı yoksayılır**; daha sonraki yeniden başlatmada env var'ı değiştirmek canlı org'un değerini etkilemez ve ek org'lar varsayılan yerlerde başlar ve kendi değerlerini yapılandırır. +Ayarlar kuruluş başına `org_settings` içinde depolanır. İlk önyüklemede, sunucu varsayılan org'un eksik satırlarını eşleşen ortam değişkeninden (veya ortam değişkeni ayarlanmadığında akla yatkın bir varsayılandan) tohurnlanır. Bundan sonra, **depolanmış değer gerçeği kaynağı ve ortam değişkeni yok sayılır**; ortam değişkenini daha sonraki yeniden başlatmada değiştirmek canlı org'un değerini etkilemez ve ek org'lar varsayılanlardan başlayıp kendi yapılandırır. -Bu şu anlama gelir: +Bu anlamına gelir: -- Yeni bir dağıtım için, yukarıdaki env var'ları ayarlayın; varsayılan org ilk başlamada bunları okur. -- Daha sonra bir değer değiştirmek için pano'ya giriş yapın ve `//settings` altında düzenleyin. Değişiklik saniyeler içinde tüm sunucu çoğaltmalarında uygulanır; yeniden başlatma gerekmez. -- Başlangıç günlüğü satırı, seed'lenmiş vs. zaten mevcut olan şeyler kaydedilir, böylece bootstrap'ın etkinleştiğini doğrulayabilirsiniz: +- Yeni bir dağıtım için, ortam değişkenlerini yukarıda gösterildiği gibi ayarlayın ve varsayılan org ilk önyüklemede onları okur. +- Bir değeri daha sonra değiştirmek için panonuya giriş yapın ve `//settings` altında düzenleyin. Değişiklik saniyeler içinde tüm sunucu çoğaltmaları arasında etkili olur; yeniden başlatma gerekmez. +- Bir başlangıç günlük satırı ne tohurnlandığını ve ne zaten var olduğunu kaydeder, böylece önyüklemenin etkili olduğunu doğrulayabilirsiniz: ```text INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true ``` -#### Kuruluşlar arasında sign-in semantiği +#### Kuruluşlar arasında oturum açma anlambilimi -Oturum ve OTP, tek org'a değil, kullanıcıya genel olarak geçerlidir, bu yüzden sign-in zamanında iki kural org başına ayarlarla uzlaştırır: +Oturum ve OTP, tek org'a değil küreseldir, bu nedenle iki kural oturum açma zamanında per-org ayarlarını uzlaştırır: -- **Oturum / OTP ömrü**: kuruluşlar arasında en kesin (en kısa) ömür kazanır. -- **İzin verilen sign-inler**: kapı her org'un izin listesini org üyeliğiyle birleştirir: bir kullanıcı, herhangi bir org'un izin listesi e-postalarını kabul EDER veya zaten herhangi bir org'un üyesi EDER ise OTP talep edebilir. +- **Oturum / OTP yaşam süresi**: en katı (en kısa) yaşam süresi kullanıcının ait olduğu org'lar arasında kazanır. +- **İzin verilen oturum açmalar**: kapı VEYA'lar her org'un izin listesi kuruluş üyeliğiyle: bir kullanıcı herhangi bir org'un izin listesi e-postalarını kabul ederse OTP isteyebilir **veya** zaten herhangi bir org'un üyeleri. ### İzinler -Bir `//settings` sayfasına erişim iki izin tarafından geçitlenedbilir: +`//settings` sayfasına erişim iki izin tarafından kapılır: -- `settings:read`: sayfayı ve geçerli değerleri görün. -- `settings:write`: değişiklikleri kaydedin. +- `settings:read`: sayfayı görmek ve geçerli değerleri. +- `settings:write`: değişiklikleri kaydet. -Bootstrap admin kullanıcısı (`ADMIN_EMAIL`'den seed'lenen) diğer her izin ile birlikte her ikisini otomatik olarak alır. Gerektiğinde `//users`'ten başka kullanıcılara verin. +Önyükleme yöneticisi kullanıcısı (önyükleme `ADMIN_EMAIL` adresinde) otomatik olarak her diğer izinle birlikte her ikisini alır. Gerektiğinde diğer kullanıcılara `//users` adresinden verin. --- -## Kuruluşlar (multi-tenancy) +## Kuruluşlar (çok kiracılılık) -Tek bir dağıtım, birden çok yalıtılmış **kuruluşları** (kiracıları) hizmet verebilir; veri satırının her biri tam olarak bir org'a aittir ve yalıtım veritabanı motorunda uygulanır. Tek-tenant kurulumun burada hiçbir şeye ihtiyacı yoktur; tüm veri yerleşik `default` org'unda yaşar. (Org'a daha uygun bir ad ve URL slug verebilirsiniz, böylece `/default` yerine örn. `/acme` konumunda yaşar; ilk önyüklemeden önce `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` ayarlayarak veya `agenteye-orgctl org rename` öğesiyle istediğiniz zaman yeniden adlandırarak yapabilirsiniz.) +Tek bir dağıtım birden fazla izole **kuruluş** (kiracı) sunabilir; her veri satırı tam olarak bir org'a aittir ve izolasyon veritabanı motorunda uygulanır. Tek kiracılı kurulum buna gerek duymaz; tüm veriler yerleşik `default` org'da yaşar. (Bu org'a daha uygun bir ad ve URL sunu verebilirsiniz, böylece `default` yerine örn. `/acme` adresinde yaşar, ilk önyüklemeden önce `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` ayarlayarak veya herhangi bir zamanda `agenteye-orgctl org rename` ile yeniden adlandırarak.) -**Kiracı sağlaması operatör tarafındandır.** Kuruluşlar ve üyelikleri **`agenteye-orgctl`** CLI'ı ile oluşturulur ve yönetilir; sunucu görüntüsünün içinde (`agenteye-server` ile birlikte) gemi gelir ve **mevcut sunucu pod'u içinde** çalışır; **ayrı pod/Job, HTTP API yok ve pano düğmesi yok**. Sunucu'nun `DATABASE_URL`, `CLICKHOUSE_URL` ve `ORG_CH_SECRET` öğelerini yeniden kullanır. +**Kiracı sağlaması yalnızca operatördür.** Kuruluşlar ve üyelikleri **`agenteye-orgctl`** CLI ile oluşturulur ve yönetilir, bu **sunucu görüntüsünün içinde gemi** (`agenteye-server` yanında) ve **mevcut sunucu pod içinde** çalışır; **ayrı pod/Job, HTTP API ve pano düğmesi yok**. Sunucunun `DATABASE_URL`, `CLICKHOUSE_URL` ve `ORG_CH_SECRET` yeniden kullanır. ```bash -# Docker Compose - çalışan sunucu hizmetine exec girin: +# Docker Compose - çalışan sunucu hizmetine exec: docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp" docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin -# Kubernetes - çalışan sunucu Dağıtımına exec girin: +# Kubernetes - çalışan sunucu Dağıtımı içine exec: kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list ``` -Mevcut fiiller: `org create | list | rename | delete | purge` ve `member add | list | update | remove`, yerleşik izin setiyle `admin`, `standard` ve `read-only`. Eklenen üyeler, ilk pano oturum açmada OTP alırlar. +Kullanılabilir fiiller: `org create | list | rename | delete | purge` ve `member add | list | update | remove`, yerleşik izin kümesi `admin`, `standard` ve `read-only` ile. Eklenen üyeler ilk pano girişinde OTP alır. -**İkinci org oluşturmadan önce:** güçlü, sabit bir `ORG_CH_SECRET` ayarlayın (org oluşturma komutu yerleşik dev varsayılanında çalışmayı reddeder) ve Postgres'in **15+** olduğundan emin olun. **Değişmez:** org başına API anahtarları yine de pano/API tarafından org üyeleri tarafından basılır; yalnızca org + üye yaşam döngüsü CLI'ye taşındı. Tam komut referansı ve işlenmiş örnek: **[enterprise-docs/tenant-management.md](/tr/agenteye/tenant-management)**. +**İkinci bir org oluşturmadan önce:** güçlü, kararlı `ORG_CH_SECRET` ayarlayın (`org create` komutu yerleşik geliştirme varsayılanında çalışmayı reddeder) ve Postgres'in **15+** olmasını sağlayın. **Değiştirilmemiş:** per-org API anahtarları hala pano/API tarafından org üyeleri tarafından basılır; yalnızca org + üyesi yaşam döngüsü CLI'ye taşındı. Tam komut referansı ve çalışılan örnek: **[enterprise-docs/tenant-management.md](/tr/agenteye/tenant-management)**. --- -## Bağlam penceresini doldur +## Bağlam penceresi doldurma -Her `model_response` etkinliği bir **bağlam dolum hapı** gösterir — bu modelin bağlam penceresinin yüzdesi olarak giriş artı çıktı belirteçleri. Bantlar `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%) ve `reset context` (75–100%) öğeleridir. AgentEye yaygın model kimliklerini otomatik olarak çözer, böylece ilk yapılandırma gerekmez. +Her `model_response` etkinliği bir **bağlam dolgu hapı** gösterir — o modelin bağlam penceresinin yüzdesi olarak giriş artı çıkış jetonları. Bantlar `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%) ve `reset context` (75–100%) olur. AgentEye yaygın model kimliklerini otomatik olarak çözer, bu nedenle hiçbir ilk yapılandırma gerekmez. -Kuruluş'un gönderdiği her model **Settings → model context windows** altında görünür. `settings:write` sahip kullanıcıları penceresi geçersiz kılabilir veya özel/proxy model ekleyebilir (0–1,000,000 belirteç); `0` "bilinmiyor" anlamına gelir ve hapı bastırır. Değişiklikler yeni alınan etkinliklere uygulanır. `settings:read` kullanan kullanıcılar listeyi görüntüleyebilir. +Bir kuruluşun gönderdiği her model Ayarlar → model bağlam pencereleri altında görünür. `settings:write` izni olan kullanıcılar pencereyi geçersiz kılabilir veya özel/proxy model ekleyebilir (0–1.000.000 jeton); `0` "bilinmiyor" anlamına gelir ve hapı bastırır. Değişiklikler yeni alınan etkinliklere uygulanır. `settings:read` izni olan kullanıcılar listeyi görüntüleyebilir. -Yeni etkinlikler yükseltme anından itibaren dolum alır. Mevcut dağıtım için **geçmiş** etkinlikleri (ve model başına listeyi) doldururmak için, tek seferlik geri doldurmayı çalıştırın — sunucu görüntüsünün içinde gemi gelir (`agenteye-orgctl` gibi) ve mevcut sunucu pod'u içinde çalışır: +Yeni etkinlikler yükseltmede anı alır. Ayrıca mevcut dağıtım için **tarihsel** etkinlikleri doldurmak için (ve per-model listeyi), bir kez çalıştırılan backfill çalıştırın — sunucu görüntüsünün içinde gemi (`agenteye-orgctl` gibi) ve mevcut sunucu pod'unda çalışır: ```bash -# ön izleme (org başına mutasyonu yazdırır, hiçbir şey değiştirmez): +# ön izleme (per-org mutasyonu yazdırır, hiçbir şey değişmez): kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window --dry-run -# uygulamak: +# uygula: kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window # docker compose: docker compose exec server agenteye-backfill-context-window ``` -Idempotent'tir (yeniden çalıştırılması güvenlidir) ve pod'dan `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` öğelerini yeniden kullanır. Model pencereleri düzenledikten sonra mevcut etkinliklerin yeniden hesaplanmasını isterse yeniden çalıştırın. +Eğersiz (yeniden çalıştırmak güvenlidir) ve pod'dan `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL` yeniden kullanır. Model pencereleri düzenledikten sonra varolan etkinlikleri yeniden hesaplamak istiyorsanız yeniden çalıştırın. --- ## Üretim Hususları -- **Postgres**: Yönetilen Postgres hizmeti veya düzenli yedeklemeler ile adanmış örnek kullanın. `DATABASE_URL`, `sslmode=require` dahil tüm standart libpq parametrelerini destekler, şifrelenmiş bağlantılar için. -- **TLS**: Sunucu ve pano'yu TLS'yi sonlandıran ters proxy'nin (nginx, Caddy, Traefik) arkasına yerleştirin. -- **Güvenlik duvarı**: Sunucu portu (varsayılan 8080) yalnızca collector makinelerine ve pano ana bilgisayarından erişilebilir olmalıdır; genel internet'ten değ \ No newline at end of file +- **Postgres**: Yönetilen Postgres hizmetini veya düzenli yedeklemeleri olan ayrılmış bir örneği kullanın. `DATABASE_URL` `sslmode=require` dahil olmak üzere tüm standart libpq parametrelerini destekler, şifreli bağlantılar için. +- **TLS**: Sunucu ve panoyu TLS'yi sonlandıran ters proxy'nin (nginx, Caddy, Traefik) ardına koyun. +- **Güvenlik duvarı**: Sunucu portu (varsayılan 8080) yalnızca toplayıcı makinelerinden ve pano ana bilgisayarından erişilebilir olmalıdır, genel İnternet'ten değil. +- **Yönetici anahtarı**: `ADMIN_KEY` güçlü rastgele gizli ayarlayın. Önyüklemeden sonra, yönetici anahtarını her yerde kullanmak yerine toplayıcılar ve pano için ayrılmış kapsamlı anahtarlar oluştu \ No newline at end of file diff --git a/docs/tr/agenteye/getting-started.mdx b/docs/tr/agenteye/getting-started.mdx index f4a9ee29..7d0cc072 100644 --- a/docs/tr/agenteye/getting-started.mdx +++ b/docs/tr/agenteye/getting-started.mdx @@ -1,39 +1,40 @@ --- -title: "AgentEye'a Başlarken" -description: "AgentEye'a Başlarken belgelendirmesi." +title: "AgentEye ile Başlayın" +description: "AgentEye ile Başlayın belgesi." --- -Bu kılavuz, tam bir AgentEye kurulumunu adım adım anlatır: sunucuyu ve panoyu dağıtmak, aracı makinesine toplayıcıyı yüklemek ve Python aracı kodunuzu işaretlemek. + +Bu kılavuz, tüm AgentEye kurulumunda size yol gösterir: sunucuyu ve panoyu dağıtma, collector'ı bir agent makinesine yükleme ve Python agent kodunuzu enstrümentasyon yapma. --- ## AgentEye Nedir? -AgentEye, **yapay zeka ajanları için kendi altyapınızda çalıştırılan gözlemlenebilirlik ve değerlendirme platformudur**. Ajanlarınızın ne yaptığını — bir çalışmanın her adımını — kaydeder ve tamamlanan her çalışmanın kalitesini otomatik olarak puanlar; böylece ajanlarınızın üretim ortamında nasıl davrandığını görebilir ve kullanıcılarınız sorunları fark etmeden gerilemeyi yakalayabilirsiniz. +AgentEye, **AI ajanları için kendi barındırılan gözlemlenebilirlik ve değerlendirme platformudur**. Ajanlarınızın ne yaptığını — bir çalıştırmanın her adımını — kaydeder ve tamamlanan her çalıştırmanın kalitesini otomatik olarak puanlandırır, böylece ajanlarınızın üretimde nasıl davrandığını görebilir ve kullanıcılarınız bunu fark etmeden önce gerileme yakalayabilirsiniz. -Veriler tek yönde akar: aracı kodunuz **olay**ları **Python SDK** aracılığıyla yayınlar → hafif **toplayıcı** daemon bunları toplu olarak paketler ve **sunucuya** gönderir → olaylar ve analizler **ClickHouse**'da saklanır (kuruluşlar, kullanıcılar, API anahtarları, panolar ve kaydedilmiş sorgular gibi işletimsel durum **Postgres**'de yaşar) → her şeyi **panoda** keşfedersiniz. +Veri tek yönde akar: agent kodunuz **olaylar** gönderir **Python SDK** aracılığıyla → hafif bir **collector** daemon bunları toplar ve **sunucuya** gönderir → olaylar ve analitiğer **ClickHouse**'da saklanır (kuruluşlar, kullanıcılar, API anahtarları, panolar ve kaydedilmiş sorgular gibi operasyonel durum **Postgres**'te yaşar) → **panosunda** her şeyi keşfedersiniz. -Ne elde edersiniz: +Neler elde edersiniz: -- **Olaylar** — her aracı çalışmasının ham, adım adım izi (araç çağrıları, model çağrıları, kancalar, hatalar). -- **Oturumlar** — bu olaylar bir satıra toplu halde, her biri **otomatik olarak değerlendirilmiş** ve puanlanmış. -- **Değerlendirmeler** — kendi değerlendirici hizmetleriniz tarafından üretilen kalite puanları; kalite düşüşü manuel inceleme olmadan yüzeye çıkar. -- **Sorgular & panolar** — verileriniz üzerinde kaydedilmiş ClickHouse SQL, paylaşılan, kuruluş kapsamlı panolara grafik halinde yerleştirilmiş. -- **Uyarılar & olaylar** — sizi sayfalayan eşik kuralları (e-posta, Slack, webhook, panoda) artı bunları sınıflandırmak için bir olay iş akışı. -- **CLI & yapay zeka asistanı** — bir terminal istemcisi (`agenteye`) ve panoda düz İngilizce'de soru sormak için bir asistan. +- **Olaylar** — her agent çalıştırmasının ham, adım adım izi (araç çağrıları, model çağrıları, hook'lar, hatalar). +- **Oturumlar** — bu olaylar çalıştırma başına bir satıra toplandı, her biri **otomatik olarak değerlendirildi** ve puanlandırıldı. +- **Değerlendirmeler** — kendi değerlendirici hizmetleriniz tarafından üretilen kalite puanları, böylece kalite düşüşleri manuel inceleme olmadan ortaya çıkar. +- **Sorgular ve panolar** — verileriniz üzerinde kaydedilmiş ClickHouse SQL, paylaşılan, kuruluş kapsamlı panolara çizelgeler halinde dönüştürülür. +- **Uyarılar ve olaylar** — sizi sayfalayan eşik kuralları (e-posta, Slack, webhook, panonun içinde) ve bunları sınıflandırmak için bir olay iş akışı. +- **CLI ve AI asistanı** — terminal istemcisi (`agenteye`) ve sorulara düz İngilizce ile yanıt vermek için panonun içinde bir asistan. -Tüm bunları kendi altyapınızda çalıştırırsınız — tek bir Docker Compose yığını olarak (bu kılavuz), bir üretim Kubernetes kurulumu olarak veya tek bir ortak konumlandırılmış pod olarak. Bu kılavuzun geri kalanı Compose yığınını baştan sona kurar. +Tüm bunları kendi altyapınızda çalıştırırsınız, tek bir Docker Compose yığını (bu kılavuz), production Kubernetes kurulumu veya tek bir ortak bulundurulan pod olarak. Bu kılavuzun geri kalanı Compose yığınını sondan sona kurar. --- ## Adım 1: Kimlik Doğrulama -Tüm AgentEye yapıtları `agenteye-enterprise` GitHub kuruluşundan dağıtılır. Bir kurumsal geliştirici olarak kendi GitHub PAT'ınızı oluşturabilirsiniz. Tam adımlar ve gerekli izinler için [enterprise-docs/github-token.md](/tr/agenteye/github-token) bölümünü izleyin. +Tüm AgentEye yapıları `agenteye-enterprise` GitHub kuruluşundan dağıtılır. Bir enterprise geliştirici olarak kendi GitHub PAT'inizi oluşturabilirsiniz. Tam adımlar ve gerekli izinler için [enterprise-docs/github-token.md](/tr/agenteye/github-token) adresini izleyin. ```bash export AGENTEYE_TOKEN= -# Docker'ı GHCR'a karşı kimlik doğrulaması yapın +# Docker'ı GHCR'a karşı kimlik doğrulama echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin ``` @@ -41,7 +42,7 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin ## Adım 2: Sunucuyu ve Panoyu Dağıtın -Sunucu, toplayıcılardan olayları alır ve bunları sorgulanabilir hale getirir; pano onları keşfettiğiniz yerdir. Alınan olaylar ve analizler ClickHouse'da yaşar (gerekli analitik deposu), Postgres ise kuruluşlar, kullanıcılar, API anahtarları, panolar ve kaydedilmiş sorgular gibi işletimsel durumu tutar. +Sunucu, collectors'lardan olaylar alır ve bunları sorgulanabilir hale getirir; pano onları keşfettiğiniz yerdir. Alınan olaylar ve analitiğer ClickHouse'da yaşar (gerekli analitiğer deposu), Postgres ise kuruluşlar, kullanıcılar, API anahtarları, panolar ve kaydedilmiş sorgular gibi operasyonel durumu tutar. **Yayınlanan compose dosyasını indirin:** @@ -54,38 +55,32 @@ curl -fsSL \ cd agenteye ``` -**Sırlarınızı ayarlayın:** +**Gizli anahtarlarınızı ayarlayın:** -Dağıtımın varsayılan `admin` kimlik bilgileriyle çalışmaması için bir `.env` dosyası oluşturun. En az `ADMIN_KEY` ve `POSTGRES_PASSWORD` ayarlayın: +Dağıtım varsayılan `admin` kimlik bilgileriyle çalışmayacak şekilde bir `.env` dosyası oluşturun. En azından `ADMIN_KEY` ve `POSTGRES_PASSWORD` ayarlayın: ```bash POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -Ayrıca `ADMIN_KEY` dosyasını mevcut kabuğunuzda dışa aktarın; böylece sonraki adımlar (ör. Adım 3 `curl`) buna doğrudan başvurabilir: - -```bash -export ADMIN_KEY=your-admin-secret -``` - **Yığını başlatın:** ```bash docker compose up -d ``` -Bu, gerekli ClickHouse analitik deposu ve isteğe bağlı Redis önbelleği ile sunucu ve panoyu içeren tam yığını başlatır. Sunucunun başlaması için ClickHouse sağlıklı olmalıdır. +Bu, gerekli ClickHouse analitiğer deposu ve isteğe bağlı bir Redis önbelleğinin yanı sıra sunucu ve panoyu içeren tam yığını başlatır. ClickHouse sunucunun başlaması için sağlıklı olması gerekir. -Sunucu şimdi `http://localhost:8080` adresinde ve pano `http://localhost:3000` adresinde dinliyor. +Sunucu artık `http://localhost:8080` adresinde dinliyor ve pano `http://localhost:3000` adresinde. -Üretim dağıtımları için (özel Postgres, TLS, ters proxy), bkz. [enterprise-docs/deployment.md](/tr/agenteye/deployment). +Production dağıtımları için (özel Postgres, TLS, ters proxy), [enterprise-docs/deployment.md](/tr/agenteye/deployment) adresine bakın. --- -## Adım 3: Toplayıcı için bir API Anahtarı Oluşturun +## Adım 3: Collector için bir API Anahtarı Oluşturun -Her toplayıcı kapsamlı bir API anahtarı ile kimlik doğrulaması yapar. Adım 2'de ayarladığınız `ADMIN_KEY` kullanarak bir tane oluşturun: +Her collector, kapsamlı bir API anahtarı ile kimlik doğrulama yapar. Adım 2'de ayarladığınız `ADMIN_KEY` öğesini kullanarak bir tane oluşturun: ```bash curl -s -X POST http://localhost:8080/keys \ @@ -94,15 +89,15 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -`key` değerini kendiniz sağlarsınız; Adım 4'teki toplayıcı yapılandırmasında kullanırsınız. Tam anahtar yönetimi için [enterprise-docs/api-keys.md](/tr/agenteye/api-keys) bölümüne bakın. +`key` değerini kendiniz sağlarsınız; Adım 4'teki collector yapılandırmasında kullanın. Tam anahtar yönetimi için [enterprise-docs/api-keys.md](/tr/agenteye/api-keys) adresine bakın. --- -## Adım 4: Toplayıcıyı Yükleyin +## Adım 4: Collector'ı Yükleyin -AI ajanlarınızı çalıştıran her makinede toplayıcı daemon'u yükleyin. +AI ajanlarınızı çalıştıran her makineye collector daemon'ı yükleyin. -**İkili dosyasını indirin (Linux x86_64):** +**İkili dosyayı indirin (Linux x86_64):** ```bash VERSION=0.0.1-beta.13 @@ -113,7 +108,7 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> Bu, **Linux x86_64** derlemesini indirir. macOS (Apple Silicon veya Intel), Linux arm64 veya Docker / systemd / launchd kurulumu için [collector-installation.md](/tr/agenteye/collector-installation) bölümüne bakın; bu, her platform için indirmeyi listeler — yukarıdaki komut başka bir yerde çalışmayacak olan bir Linux ikilisini yükler. +> Bu, **Linux x86_64** derlemesini indirir. macOS (Apple Silicon veya Intel), Linux arm64 veya Docker / systemd / launchd kurulumu için, her platform için indirme sağlayan [collector-installation.md](/tr/agenteye/collector-installation) adresine bakın — yukarıdaki komut başka yerlerde çalışmayacak bir Linux ikili dosyasını yükler. **Yapılandırın:** @@ -127,25 +122,25 @@ cat > ~/.agenteye/config.json </…`). +Olaylar aktığında, **analiz** sayfaları ham etkinliği cevaplara dönüştürür, böylece ajan davranışını ölçebilir, bulguları ekip genelinde paylaşabilir ve bir şey geriledikleri anda sayfaya alınabilirsiniz. Pano sayfaları kuruluş kapsamlıdır, bu nedenle adres çubuğunda gördüğünüz URL'ler kuruluş slug'ınız (`//…`) ile başına getirilir. -- **Sorgular** (`//queries`): olaylarınız ve değerlendirmelerinizin üzerinde kaydedilmiş, yeniden kullanılabilir sorguların bir kütüphanesinden başlayın (yerleşik ön ayarlar artı kendi sorgualarınız)… +- **Sorgular** (`//queries`): olaylarınız ve değerlendirmeleriniz üzerindeki kaydedilmiş, yeniden kullanılabilir sorgulardan oluşan bir kitaplıktan başlayın (yerleşik ön ayarlar artı kendi sorgularınız)… -![Kaydedilmiş sorguların kütüphanesi: yerleşik ön ayarlar ve özel olanlardan oluşan yeniden kullanılabilir sorguların ızgarası](/agenteye/images/queries.png) +![Kaydedilmiş sorgular kitaplığı: yeniden kullanılabilir sorgulardan oluşan bir ızgara, hem yerleşik ön ayarlar hem de özel olanlar](/agenteye/images/queries.png) - …ardından bir satırda SQL bestecisinde açın ve canlı sonuçlarla ince ayar yapın ve çalıştırın: + …ardından bunu SQL bestecisinde açın, değiştirin ve canlı sonuçlarla çalıştırın: -```python +```bash +agenteye-collector start ``` -- **Panolar** (`//dashboards`): sorguları satır, çubuk, alan veya pasta kutucukları olarak paylaşılan, kuruluş genelindeki panolara sabitleyin. +- **Panolar** (`//dashboards`): sorguları satır, çubuk, alan veya pasta kutucuklara sabitle paylaşılan, kuruluş genelindeki panolara. -![Kaydedilmiş sorgulardan oluşturulmuş bir pano: saat başına olaylar satırı, tür başına hatalar çubuğu, gecikme alan grafiği ve model başına token'lar](/agenteye/images/dashboard-fleet.png) +![Kaydedilmiş sorgulardan oluşturulan bir pano: saatlik olaylar satırı, tür başına hatalar çubuğu, gecikme alan grafiği ve modele göre tokenler](/agenteye/images/dashboard-fleet.png) -- **Uyarılar** (`//alerts`): herhangi bir eşiği e-posta, Slack, webhook veya panoda bildiren bir sayfalama kuralına dönüştürün. Bkz. [enterprise-docs/alerts.md](/tr/agenteye/alerts). +- **Uyarılar** (`//alerts`): herhangi bir eşiği e-posta, Slack, webhook veya panonun içi ile bildirim yapan sayfalama kuralına yükseltin. [enterprise-docs/alerts.md](/tr/agenteye/alerts) adresine bakın. --- ## Sonraki Adımlar -- [Dağıtım](/tr/agenteye/deployment): üretim için kilitlenme -- [API Anahtarları](/tr/agenteye/api-keys): erişimi yönetin -- [Sorun Giderme](/tr/agenteye/troubleshooting): sorunları tanılayın \ No newline at end of file +- [Dağıtım](/tr/agenteye/deployment): production için sertleştirin +- [API Anahtarları](/tr/agenteye/api-keys): erişim yönetimi +- [Sorun Giderme](/tr/agenteye/troubleshooting): sorunları tanıla \ No newline at end of file diff --git a/docs/tr/agenteye/managed-deployment.mdx b/docs/tr/agenteye/managed-deployment.mdx index 41b69bf6..eb408c9b 100644 --- a/docs/tr/agenteye/managed-deployment.mdx +++ b/docs/tr/agenteye/managed-deployment.mdx @@ -1,171 +1,172 @@ --- -title: "Kubernetes Kümenizi Üzerinde Yönetilen Dağıtım" -description: "AgentEye Kubernetes Kümenizi Üzerinde Yönetilen Dağıtım belgeleri." +--- +title: "Kubernetes Kümenizde Yönetilen Dağıtım" +description: "Kubernetes Kümenizde AgentEye Yönetilen Dağıtım belgelendirmesi." --- -AgentEye, yapay zeka ve LLM ajanları için kendi kendine barındırılan gözlemlenebilirlik ve değerlendirme platformudur. Ajan oturumlarını, araç çağrılarını, model isteklerini ve hataları yakalar, bunları aranabilir analitik ve değerlendirmelere dönüştürür ve sonuçları opsiyonel salt okunur yapay zeka asistanı ile bir panoda sunar. +AgentEye, AI ve LLM ajanları için kendi kendini barındıran bir gözlemlenebilirlik ve değerlendirme platformudur. Ajan oturumlarını, araç çağrılarını, model isteklerini ve hataları yakalar, bunları aranabilir analizlere ve değerlendirmelere dönüştürür ve sonuçları isteğe bağlı salt okunur bir yapay zeka asistanı ile bir panoyla ortaya çıkarır. -Yönetilen dağıtım modelinde, adanmış bir Kubernetes kümesi sağlarsınız ve Exosphere platform'un tamamını bu küme içinde çalıştırır, her bileşeni sizin adınıza dağıtır, yapılandırır, işletir, yedekler ve yükseltir. Ekibiniz platform'un değerini (ajan görünürlüğü, analitik, değerlendirme ve opsiyonel asistan) veritabanlarını, sertifikaları veya yükseltmeleri işletmek zorunda kalmadan elde eder. Tüm veriler bulut hesabınız içinde kalır. +Yönetilen dağıtım modelinde, siz özel bir Kubernetes kümesi sağlar ve Exosphere tüm platformu kümenin içinde çalıştırarak her bir bileşeni dağıtır, yapılandırır, işletir, yedekler ve günceller. Ekibiniz platformun değerini (ajan görünürlüğü, analiz, değerlendirme ve isteğe bağlı asistan) veritabanlarını, sertifikaları veya güncellemeleri işletmeden alır. Tüm veriler bulut hesabınız içinde kalır. --- -## Önkoşullar +## Ön Koşullar -- Konteyner görüntülerini çekmek ve yapıtları indirmek için **GitHub PAT** (bkz. [GitHub Token Kurulumu](/tr/agenteye/github-token)) -- **Adanmış bir Kubernetes kümesi** (aşağıdaki gereksinimlere bakın) -- Veritabanı yedekleri için **depolama bucket'ı** -- **Ağ bağlantısı**: kümenin yük dengeleyicisine gelen port 443 +- Konteyner görüntülerini çekmek ve yapıtları indirmek için bir **GitHub PAT** (bkz. [enterprise-docs/github-token.md](/tr/agenteye/github-token)) +- Bir **özel Kubernetes kümesi** (aşağıdaki gereksinimlere bakınız) +- Veritabanı yedekleri için bir **depolama demeti** +- **Ağ bağlantısı**: kümenin yük dengeleyicisine 443 numaralı bağlantı noktasında gelen trafik --- -## Adım 1: Adanmış Kubernetes Kümesi Hazırlayın +## Adım 1: Özel Bir Kubernetes Kümesi Sağlayın -AgentEye'a adanmış bir Kubernetes kümesi oluşturun. Bu küme diğer iş yükleriyle paylaşılmamalıdır, böylece tam platform (uygulama hizmetleri, veritabanları, analitik ve caching) mevcut altyapınızı etkilemeden izolasyon içinde çalışır. +AgentEye'a adanmış bir Kubernetes kümesi oluşturun. Bu küme diğer iş yükleri ile paylaşılmamalıdır, böylece tüm platform (uygulama hizmetleri, veritabanları, analiz ve önbelleğe alma) mevcut altyapınızı etkilemeden izolasyon içinde çalışır. -| Gereksinim | Ayrıntılar | +| Gereksinim | Detaylar | |---|---| -| **Dağıtım** | Herhangi bir uyumlu Kubernetes: EKS, GKE, AKS veya kendi kendine yönetilen | +| **Dağıtım** | Herhangi bir uyumlu Kubernetes: EKS, GKE, AKS veya kendi kendini yönetilen | | **Sürüm** | 1.27 veya sonrası | -| **Node havuzu** | Minimum: **3 düğüm, her biri 4 vCPU / 8 GB RAM** (standart genel amaçlı örnekler) | -| **Depolama** | Blok hacimler sağlayan varsayılan StorageClass (AWS'de `gp3`, GCP'de `pd-ssd` gibi) | -| **Yük Dengeleyici** | Küme, bulut LoadBalancer hizmetleri sağlayabilmelidir (EKS, GKE, AKS'de varsayılan) | +| **Düğüm havuzu** | Minimum: **3 düğüm, her biri 4 vCPU / 8 GB RAM** (standart genel amaçlı örnekler) | +| **Depolama** | Blok birimler sağlayan bir varsayılan StorageClass (örneğin AWS'de `gp3`, GCP'de `pd-ssd`) | +| **Yük Dengeleyici** | Küme, bulut LoadBalancer hizmetlerini sağlayabilmelidir (EKS, GKE, AKS'de varsayılan) | -> Exosphere küme içinde diğer her şeyi yükler ve yönetir: ingress denetleyicileri, TLS sertifikaları, veritabanları, caching, izleme ve tüm uygulama dağıtımları. +> Exosphere, kümenin içinde diğer her şeyi yükler ve yönetir: giriş kontrolörleri, TLS sertifikaları, veritabanları, önbelleğe alma, izleme ve tüm uygulama dağıtımları. --- -## Adım 2: AgentEye Ekibine Erişim Verin +## Adım 2: AgentEye Ekibine Erişim İzni Verin -Exosphere'in ad alanlarını, özel kaynak tanımlarını, ingress denetleyicilerini ve depolama sağlayıcılarını yönetmek için cluster-admin erişimine (veya eşdeğer geniş RBAC'ye) ihtiyacı vardır. +Exosphere'in ad alanlarını, özel kaynak tanımlarını, giriş kontrolörlerini ve depolama sağlayıcılarını yönetmek için cluster-admin erişimine (veya eşdeğer geniş RBAC) ihtiyacı vardır. -| Gereksinim | Ayrıntılar | +| Gereksinim | Detaylar | |---|---| | **Erişim yöntemi** | IAM rolü (EKS/GKE için tercih edilen), kubeconfig veya SSO tabanlı erişim | -| **VPN / bastion** | Kubernetes API sunucusu özel ise, Exosphere işletim ekibine VPN kimlik bilgilerini veya bastion erişimini sağlayın | +| **VPN / bastion** | Kubernetes API sunucusu özel ise, Exosphere operasyon ekibine VPN kimlik bilgileri veya bastion erişimi sağlayın | --- ## Adım 3: Ağ Bağlantısını Yapılandırın -Ağ ekibinizin kümenin yük dengeleyicilerine **port 443**'te gelen trafiğe izin vermesi gerekir. Dağıtım iki ayrı yük dengeleyici çalıştırır: biri etkinlik alımı (mTLS korumalı) için, diğeri pano için: +Ağ ekibinizin kümenin yük dengeleyicilerine **443 numaralı bağlantı noktasında** gelen trafiğe izin vermesi gerekir. Dağıtım iki ayrı yük dengeleyici çalıştırır: biri olay alımı (mTLS korumalı) için ve biri pano için: | Trafik | Kaynak | Hedef | Güvenlik | |---|---|---|---| -| **Etkinlik alımı** | Kümelerinizde Toplayıcı podları | Alım LoadBalancer'ı, port 443 | mTLS (istemci sertifikası) + API anahtarı | -| **Pano** | Geliştirici tarayıcıları | Pano LoadBalancer'ı, port 443 | HTTPS sizin alan adınızda, parolasız email OTP oturum açma | +| **Olay alımı** | Kümelerinizde bulunan Collector podları | Ingest LoadBalancer, 443 numaralı bağlantı noktası | mTLS (istemci sertifikası) + API anahtarı | +| **Pano** | Geliştirici tarayıcıları | Dashboard LoadBalancer, 443 numaralı bağlantı noktası | Etki alanınızda HTTPS, şifresiz e-posta OTP oturum açması | -Alım uç noktası karşılıklı TLS ile korunur; toplayıcılar her istekte geçerli bir istemci sertifikası **ve** geçerli bir API anahtarı sunmalıdır. Pano kendi yük dengeleyicisinde ve hostname'de çalışır ve oturum açma, beyaz listeye alınmış e-posta adresleri/etki alanlarıyla sınırlıdır. +Alım uç noktası karşılıklı TLS tarafından korunur; toplayıcılar her istekte geçerli bir istemci sertifikası **ve** geçerli bir API anahtarı sunmalıdır. Pano kendi yük dengeleyicisinde ve ana bilgisayar adında çalışır, oturum açma izin verilenler listenize alınan e-posta adreslerine/alanlara kısıtlanır. -**DNS kayıtları (bir kez):** kontrol ettiğiniz bir etki alanı altında iki CNAME kaydı oluşturursunuz — biri alım uç noktası için biri pano için (örn. `agenteye.your-company.example`) — Exosphere'in sağladığı yük dengeleyici hostname'lerine işaret ederek. Exosphere, otomatik olarak yenilemeler dahil olmak üzere her iki hostname için de halka açık güvenilen TLS sertifikaları sağlar. +**DNS kayıtları (tek seferlik):** kontrol ettiğiniz bir etki alanı altında iki CNAME kaydı oluşturursunuz — biri alım uç noktası için ve biri pano için (örneğin `agenteye.your-company.example`) — Exosphere tarafından sağlanan yük dengeleyici ana bilgisayar adlarına işaret ederek. Exosphere daha sonra otomatik olarak her iki ana bilgisayar adı için de genel olarak güvenilir TLS sertifikaları sağlar; yenilemeler de dahildir. -> **Port 80 notu:** otomatik sertifika verme ve yenileme, her yük dengeleyicinin port 80'inde HTTP üzerinden doğrulama yapar. Güvenlik duruşunuz pano yük dengeleyicisini şirket IP aralıklarıyla kısıtlamayı gerektiriyorsa, önce Exosphere'e söyleyin — sertifika doğrulamayı DNS tabanlı bir yönteme değiştiririz (sizin tarafınızda bir ek DNS kaydı) böylece yenilemeler sınırlama arkasında çalışmaya devam eder. +> **80 numaralı bağlantı noktası notu:** otomatik sertifika verme ve yenileme, her yük dengeleyicinin 80 numaralı bağlantı noktasında HTTP üzerinde doğrulama yapar. Güvenlik politikanız pano yük dengeleyicisini kurumsal IP aralıklarına kısıtlamayı gerektiriyorsa, önce Exosphere'e söyleyin — sertifika doğrulamayı DNS tabanlı bir yönteme geçiririz (sizin tarafınızda bir ek DNS kaydı), böylece yenilemeler kısıtlama arkasında çalışmaya devam eder. -> **Giden:** Küme düğümlerinin `ghcr.io`'dan konteyner görüntülerini çekmek için internet erişimine ihtiyacı vardır. Ağınız giden trafiği kısıtlarsa, `ghcr.io`'yu beyaz listeye alın veya görüntüleri dahili kayıt defterinize yansıtın. +> **Giden trafik:** Küme düğümleri, konteyner görüntülerini `ghcr.io` adresinden çekmek için İnternet erişimine ihtiyaç duyar. Ağınız giden trafiği kısıtlıyorsa, `ghcr.io` adresini beyaz listeye alın veya görüntüleri iç kayıt defterinize yansıtın. --- -## Adım 4: Yedekleme Depolama Bucket'ı Sağlayın +## Adım 4: Bir Yedekleme Depolama Demeti Sağlayın -Veritabanı yedekleri, sizin sahip olduğunuz bir bulut depolama bucket'ında depolanır. +Veritabanı yedekleri, sahip olduğunuz bir bulut depolama demetinde saklanır. -| Gereksinim | Ayrıntılar | +| Gereksinim | Detaylar | |---|---| | **Hizmet** | S3 (AWS), GCS (GCP) veya Azure Blob Storage | -| **Erişim** | IAM rolü aracılığıyla küme düğümlerine yazma erişimi verin (EKS'de IRSA, GKE'de Workload Identity) veya kimlik bilgileri sağlayın | -| **Saklama** | Bucket'ın yaşam döngüsü ilkesini (saklama süresi, arşivleme kuralları) siz kontrol edersiniz. Exosphere yedekleri yazar; ne kadar süre tutacağınıza siz karar verirsiniz | +| **Erişim** | IAM rolü aracılığıyla hizmet hesaplarına küme düğümlerinin yazma erişimini verin (EKS'de IRSA, GKE'de Workload Identity) veya kimlik bilgileri sağlayın | +| **Bekletme** | Demetin yaşam döngüsü politikasını kontrol edersiniz (bekletme süresi, arşivleme kuralları). Exosphere yedekleri yazar; ne kadar süre tutacağınızı siz karar verirsiniz | -Tek bir günlük yedekleme PostgreSQL'i (ilişkisel durum) ve ClickHouse'u (etkinlikler ve değerlendirmeler) tek sıkıştırılmış bir arşive döker ve bucket'ınıza yükler. Yedeklemeler ayrıca her yükseltmeden önce çalışır. +Günlük bir yedekleme, PostgreSQL (ilişkisel durum) ve ClickHouse'u (olaylar ve değerlendirmeler) tek bir sıkıştırılmış arşive döker ve demetinize yükler. Yedeklemeler ayrıca her yükseltmeden önce çalışır. --- -## Adım 5: İletişim Kişisi Belirleyin +## Adım 5: İletişim Kişisini Belirleyin -Küme düzeyinde sorunlar için (düğüm durumu, bulut hesap sınırları, ağ değişiklikleri) sizin tarafınızdan bir kişi veya Slack/Teams kanalı sağlayın. Günlük işlemlerde bu kişi ile iletişim gerekmez. +Küme düzeyindeki sorunlar için kendi tarafınızdan bir kişi veya Slack/Teams kanalı sağlayın: düğüm durumu, bulut hesabı sınırları, ağ değişiklikleri. Günlük işlemler bu iletişim kişisini içermez. --- -## Ne Dağıtıyoruz +## Dağıtılanlar -Exosphere küme erişimi aldığında, aşağıdaki bileşenler sizin için dağıtılır ve yönetilir: +Exosphere'in küme erişimi olduktan sonra, aşağıdaki bileşenler sizin için dağıtılır ve yönetilir: | Bileşen | Rol | |---|---| -| **AgentEye Server** | Toplayıcılardan etkinlikleri alan, analitik çalıştıran ve pano'ya veri sunan HTTP API | -| **Pano** | Ajan oturumlarını, araç çağrılarını, model isteklerini ve hataları görüntülemek için web arayüzü; opsiyonel salt okunur yapay zeka asistanını barındırır | -| **ClickHouse** | Alınan etkinlikler, analitik ve değerlendirmeler için gerekli kanonik depo | -| **PostgreSQL** | Kuruluşlar, API anahtarları, kullanıcılar, panolar ve kaydedilen sorgular için ilişkisel depo | -| **Redis** | Opsiyonel paylaşılan önbellek ve hız sınırı arka ucu; kullanılamıyorsa platform incelikle bozulur | -| **Yapay zeka asistanı (opsiyonel)** | Dahili salt okunur asistan konteyneri; LLM uç noktası yapılandırılana kadar devre dışı kalır | -| **Ingress denetleyicileri** | İki yük dengeleyici (biri mTLS korumalı alım için, biri pano için) TLS'yi halka açık güvenilen, otomatik yenilenen sertifikalarla sonlandıran ve alım uç noktasında mTLS uygulayan | -| **cert-manager** | TLS sertifikası sağlamasını ve mTLS istemci sertifikası verişini otomatikleştirir | -| **Sertifika izleme** | Zamanlanmış bir iş sertifika süresini kontrol eder ve sertifikalar yenileme yaklaştığında uyarılar gönderir (ör. Slack'e) | - -Yönetilen teklif ayrıca platform'un değerlendirme hattını işletir ve bu hatt, ajan aktivitesini değerlendirme kriterlerinize göre puanlar. Ne sunan bu yetenekler için [Asistan](/tr/agenteye/assistant) ve [Değerlendirme Paketi](/tr/agenteye/evaluation-suite)'ne bakın. +| **AgentEye Server** | Toplayıcılardan olayları alan, analiz çalıştıran ve verileri panoya sunan HTTP API'si | +| **Pano** | Ajan oturumlarını, araç çağrılarını, model isteklerini ve hataları görüntülemek için web arayüzü; isteğe bağlı salt okunur yapay zeka asistanını barındırır | +| **ClickHouse** | Alınan olaylar, analiz ve değerlendirmeler için gerekli kanonik depo | +| **PostgreSQL** | Kuruluşlar, API anahtarları, kullanıcılar, panolar ve kaydedilmiş sorgular için ilişkisel depo | +| **Redis** | İsteğe bağlı paylaşılan önbellek ve hız sınırlama arka ucu; kullanılamıyorsa platform düzgün bir şekilde bozulur | +| **Yapay zeka asistanı (isteğe bağlı)** | İç salt okunur asistan konteyner; bir LLM uç noktası yapılandırılıncaya kadar devre dışı kalır | +| **Giriş kontrolörleri** | İki yük dengeleyici (biri mTLS korumalı alım için, biri pano için) genel olarak güvenilir, otomatik olarak yenilenen sertifikalar ile TLS sonlandırarak ve alım uç noktasında mTLS'i uygulayan | +| **cert-manager** | TLS sertifika sağlamayı ve mTLS istemci sertifika vermeyi otomatikleştirir | +| **Sertifika izleme** | Planlı bir iş sertifika süresini kontrol eder ve sertifikalar yenilemeye yaklaştığında uyarılar gönderir (örneğin Slack'e) | + +Yönetilen teklif ayrıca platformun değerlendirme boru hattını işletir, bu da ajan aktivitesini değerlendirme kriterlerinize karşı puanlar. Bkz. [enterprise-docs/assistant.md](/tr/agenteye/assistant) ve [enterprise-docs/evaluation-suite.md](/tr/agenteye/evaluation-suite) bu yeteneklerin neleri sağladığı için. --- -## Size Sağlananlar +## Siz Ne Alırsınız -Dağıtım tamamlandıktan sonra aşağıdakileri alırsınız: +Dağıtım tamamlandıktan sonra şunları alırsınız: -| Öğe | Ayrıntılar | +| Öğe | Detaylar | |---|---| -| **Pano URL'si** | Alan adınız altında bir hostname (ör. `https://agenteye.your-company.example`), halka açık güvenilen, otomatik yenilenen TLS sertifikası ile sunulan. Sağladığımız yük dengeleyici hostname'ine bir CNAME oluşturursunuz; oturum açma parolasız email OTP'dir | -| **Toplayıcı uç noktası** | Alım hostname'inin `/events` yolu (ör. `https://ingest.your-company.example/events`), mTLS korumalı | -| **İstemci sertifikası paketi** | Küme başına: istemci sert., özel anahtar ve CA sertifikası Kubernetes Secret manifest'i olarak teslim edilir. Küme başına bir kez uygulayın | +| **Pano URL'si** | Etki alanınız altında bir ana bilgisayar adı (örneğin `https://agenteye.your-company.example`), genel olarak güvenilir, otomatik olarak yenilenen bir TLS sertifikası ile sunulan. Sağladığımız yük dengeleyici ana bilgisayar adına bir CNAME oluşturursunuz; oturum açma şifresiz e-posta OTP'dir | +| **Toplayıcı uç noktası** | Alım ana bilgisayar adının `/events` yolu (örneğin `https://ingest.your-company.example/events`), mTLS korumalı | +| **İstemci sertifika paketi** | Küme başına: istemci sert, özel anahtar ve CA sert bir Kubernetes Secret manifestinde sunulan. Küme başına bir kere uygulayın | | **GitHub PAT** | Toplayıcı ikili dosyalarını ve Python SDK paketlerini indirmek için | -| **Toplayıcı API anahtarları** | `events:add` izniyle kapsamlı anahtarlar, toplayıcı dağıtımı başına bir adet | +| **Toplayıcı API anahtarları** | `events:add` izni ile kapsamlı anahtarlar, her toplayıcı dağıtımı için birer tane | | **Kurulum kılavuzları** | Toplayıcı ve Python SDK için adım adım belgeler | --- -## Kurulumdan Sonra Yapacağınız İşler +## Kurulumdan Sonra Yapacaklarınız -Tek devam eden çalışmanız AgentEye kümesinde değil kendi ajan makinelerinizde: +Tek devam eden iş, AgentEye kümesi değil, kendi ajan makinelerinizde: -1. **Toplayıcıyı yükleyin** yapay zeka ajanları çalıştıran her Kubernetes kümesinde: istemci sertifikasını monte edin ve uç nokta URL'sini ve API anahtarını yapılandırın. Bkz. [Toplayıcı Kurulumu](/tr/agenteye/collector-installation). -2. **Python SDK'yı entegre edin** ajan kodunuza. Bkz. [Python SDK](/tr/agenteye/python-sdk). -3. **Pano'yu açın** tarayıcınızda ajan aktivitesini görüntülemek için. +1. **Toplayıcıyı yükleyin** AI ajanlarının çalıştırıldığı her Kubernetes kümesinde: istemci sertifikasını monte edin ve uç nokta URL'sini ve API anahtarını yapılandırın. Bkz. [enterprise-docs/collector-installation.md](/tr/agenteye/collector-installation). +2. **Python SDK'yı entegre edin** ajan kodunuza. Bkz. [enterprise-docs/python-sdk.md](/tr/agenteye/python-sdk). +3. **Tarayıcıda panolu açın** ajan aktivitesini görüntülemek için. -Küme işletimi yok, veritabanı yönetimi yok, sertifika yenileme yok, yükseltme yok. +Küme işlemleri yok, veritabanı yönetimi yok, sertifika yenilemeleri yok, yükseltmeler yok. --- ## Güvenlik -- **Veriler bulut hesabınızda kalır.** Küme, depolama ve veritabanları tümü ortamınızda çalışır. Hiçbir veri sınırınızı terk etmez. -- **Erişimi siz kontrol edersiniz.** Küme hesabınızdadır. Herhangi bir zamanda Exosphere'in erişimini denetleyebilir, izleyebilir veya iptal edebilirsiniz. Tüm işlemler bulutunuzun denetim günlüğünden geçer (CloudTrail, GCP Audit Logs vb.). -- **Etkinlik alımında mTLS.** Her toplayıcı isteği hem geçerli bir istemci sertifikası hem de API anahtarı gerektirir. Sızan anahtar sert. olmadan işe yaramaz; çalınan sert. geçerli anahtar olmadan işe yaramaz. -- **Pano erişim kontrolü.** Pano kendi yük dengeleyicisinde, etkinlik alımından ayrı olarak çalışır ve oturum açma, beyaz listeye alınmış e-posta adresleri/etki alanlarıyla sınırlı parolasız email OTP'dir. Yük dengeleyicide IP kaynak aralığı beyaz listesi istekle kullanılabilir; otomatik sertifika yenileme yük dengeleyiciye ulaşması gerektiğinden, Exosphere kısıtlamayı DNS tabanlı sertifika doğrulaması ile eşleştirir böylece yenilemeler çalışmaya devam eder. -- **Küme başına sertifikalar.** Kümelerinizin her biri kendi istemci sertifikasını alır. Bir küme tehlikeye girerse, bu sertifika bağımsız olarak iptal edilir ve diğerlerini etkilemez. +- **Veriler bulut hesabınızda kalır.** Küme, depolama ve veritabanları tümü ortamınızda çalışır. Hiç veri sınırınızı terk etmez. +- **Siz erişimi kontrol edersiniz.** Küme hesabınızdadır. Exosphere'in erişimini dilediğiniz zaman denetleyebilir, izleyebilir veya iptal edebilirsiniz. Tüm işlemler bulutunuzun denetim günlüğüne gider (CloudTrail, GCP Audit Logs, vb.). +- **Olay alımında mTLS.** Her toplayıcı isteği geçerli bir istemci sertifikası ve bir API anahtarı gerektirir. Sızan bir anahtar sert olmadan işe yaramaz; çalıntı bir sert geçerli bir anahtar olmadan işe yaramaz. +- **Pano erişim denetimi.** Pano kendi yük dengeleyicisinde çalışır, olay alımından ayrı olarak çalışır ve oturum açma, izin verilenler listenize alınan e-posta adreslerine/alanlara kısıtlanmış şifresiz e-posta OTP'dir. Yük dengeleyicide bir IP kaynak aralığı beyaz listesi istekte mevcuttur; otomatik sertifika yenileme yük dengeleyiciye ulaşması gerektiğinden, Exosphere kısıtlamayı DNS tabanlı sertifika doğrulaması ile eşleştirir, böylece yenilemeler çalışmaya devam eder. +- **Küme başına sertifikalar.** Kümelerinizin her biri kendi istemci sertifikasını alır. Bir küme tehlikeye atılırsa, o sertifika bağımsız olarak iptal edilir, diğerleri etkilenmez. --- ## Dağıtım Zaman Çizelgesi -| Aşama | Süre | Sizin katılımınız | +| Aşama | Süre | Katılımınız | |---|---|---| -| **Küme hazırlama** | 1-2 gün | Kümeyi hazırlayın ve Exosphere'e erişim verin | -| **Platform kurulumu** | 1 gün | Hiçbiri; Exosphere tüm altyapı bileşenlerini yükler | -| **Uygulama dağıtımı** | 1 gün | Hiçbiri; Exosphere sunucuyu, pano'yu dağıtır ve API anahtarları oluşturur | -| **Toplayıcı dağıtımı** | 1-3 gün | Kümelerinizde toplayıcıları yükleyin (Exosphere'in rehberliğiyle) | -| **Üretim deneme** | 1 hafta | Hiçbiri; Exosphere izler ve ayarlar | +| **Küme sağlama** | 1-2 gün | Kümeyi sağlayın ve Exosphere'e erişim verin | +| **Platform kurulumu** | 1 gün | Yok; Exosphere tüm altyapı bileşenlerini kurar | +| **Uygulama dağıtımı** | 1 gün | Yok; Exosphere sunucu, pano dağıtır ve API anahtarları oluşturur | +| **Toplayıcı dağıtımı** | 1-3 gün | Kümelerinizde toplayıcıları yükleyin (Exosphere'den rehberlik ile) | +| **Üretim çalışması** | 1 hafta | Yok; Exosphere izler ve ayarlar | -Tipik toplam: Kickoff'tan üretime hazır'a kadar **~2 hafta**. +Tipik toplam: **~2 hafta** başlangıçtan üretim hazırı olmaya kadar. --- ## Destek -Sorular veya sorunlar için Exosphere'e `support@exosphere.host` adresinde ulaşın. +Sorular veya sorunlar için Exosphere'e `support@exosphere.host` adresinden iletişim kurun. --- ## Sonraki Adımlar -- [Başlangıç](/tr/agenteye/getting-started): uçtan uca kılavuz +- [Başlangıç](/tr/agenteye/getting-started): uçtan uca anlatım - [Toplayıcı Kurulumu](/tr/agenteye/collector-installation): toplayıcıyı yükleyin ve yapılandırın -- [Python SDK](/tr/agenteye/python-sdk): ajan kodunuzu çalıştırın -- [API Anahtarları](/tr/agenteye/api-keys): erişimi ve izinleri yönetin -- [Sorun Giderme](/tr/agenteye/troubleshooting): yaygın sorunlar ve çözümleri \ No newline at end of file +- [Python SDK](/tr/agenteye/python-sdk): ajan kodunuzu enstrüman edin +- [API Anahtarları](/tr/agenteye/api-keys): erişim ve izinleri yönetin +- [Sorun Giderme](/tr/agenteye/troubleshooting): yaygın sorunlar ve düzeltmeler \ No newline at end of file diff --git a/docs/vi/agenteye/audits.mdx b/docs/vi/agenteye/audits.mdx index d9a87968..141ed257 100644 --- a/docs/vi/agenteye/audits.mdx +++ b/docs/vi/agenteye/audits.mdx @@ -1,107 +1,106 @@ --- title: "Audits — phát hiện cải tiến agentic" -description: "AgentEye Audits — tài liệu phát hiện cải tiến agentic." +description: "AgentEye Audits — tài liệu về phát hiện cải tiến agentic." --- -Audits là những công việc lặp lại khai thác các nhật ký agent của bạn **trên các phiên** để tìm những điều đáng cải tiến. Trong khi alert theo dõi một số liệu mà bạn đã biết gần như thời gian thực, audit *điều tra*: theo lịch bạn đặt, nó chạy một đợt chính sách xác định trên cửa sổ thời gian, sau đó thả một **agent tin cậy AI** lỏng lẻo trên các phiên của bạn — agent truy vấn dữ liệu, đọc các bản ghi đáng nghi, và (khi cần thiết) chạy các script phân tích nhỏ, sau đó viết ra **khuyến nghị cải tiến** với bằng chứng đằng sau mỗi cái. +Audits là những công việc lặp lại khai thác nhật ký agent của bạn **trên các phiên** để tìm những thứ đáng cải tiến. Trong khi alert theo dõi một chỉ số bạn đã biết gần như thời gian thực, audit *điều tra*: theo lịch trình bạn đặt, nó chạy một lượt chính sách xác định trên cửa sổ thời gian, sau đó thả một **agent đáng tin cậy AI** lỏng lẻo trên các phiên của bạn — agent truy vấn dữ liệu, đọc các bản ghi nghi ngờ, và (khi hữu ích) chạy các script phân tích nhỏ, sau đó viết **khuyến nghị cải tiến** với bằng chứng đằng sau mỗi một. -Sử dụng audits để trả lời "tôi nên sửa hoặc cải tiến cái gì trong agents của mình?" — và alerts để được báo sớm nhất khi một ngưỡng cụ thể bị vượt qua. Mỗi cải tiến liên kết đến những phiên chính xác và truy vấn đằng sau nó, và chỉ cần một cú nhấp chuột tạo alert được điền sẵn để bắt các lần tái diễn. +Sử dụng audits để trả lời "tôi nên sửa hoặc cải tiến gì trong agents?" — và alerts để được thông báo ngay khi một ngưỡng cụ thể bị vượt quá. Mọi cải tiến đều liên kết đến các phiên và truy vấn chính xác đằng sau nó, và một lần nhấp sẽ tạo alert được điền sẵn để bắt lỗi lặp lại. -Bề mặt bảng điều khiển là **`//audits`** (thanh bên → *analyze* → *audits*), được kiểm soát bởi các quyền `audits:read` / `audits:write`. +Bề mặt dashboard là **`//audits`** (thanh bên → *analyze* → *audits*), được kiểm soát bởi các quyền `audits:read` / `audits:write`. --- ## Cách một lần chạy hoạt động -Mỗi lần chạy có hai tầng — một mặt nền xác định và một cuộc điều tra agentic. +Mỗi lần chạy có hai lớp — nền xác định và điều tra agentic. -### 1. Đợt chính sách (xác định) +### 1. Lượt kiểm tra chính sách (xác định) -Trước khi bất kỳ mô hình nào chạy, audit thực hiện một danh mục nhỏ **kiểm tra chính sách SQL** trên cửa sổ: các truy vấn tổng hợp có giới hạn báo cờ các mẫu xấu đã biết và báo cáo *bao nhiêu* sự kiện / *sự kiện nào* phiên phù hợp — không bao giờ là văn bản phù hợp. Danh mục bao gồm: +Trước khi bất kỳ model nào chạy, audit thực hiện một danh mục nhỏ **kiểm tra chính sách SQL** trên cửa sổ: các truy vấn tổng hợp có giới hạn đánh dấu các mẫu xấu đã biết và báo cáo *bao nhiêu* sự kiện / *phiên nào* trùng khớp — không bao giờ là văn bản đã trùng khớp. Danh mục bao gồm: -- **Rò rỉ bí mật / thông tin xác thực** trong tải trọng sự kiện — khóa truy cập AWS, `sk-…` khóa API, khóa riêng PEM, mã thông báo JWT / bearer, và các gán thông tin xác thực `KEY=…`. -- **Chỉ báo tiêm dấu nhắc** — "ignore previous instructions", "reveal your system prompt", và những cái tương tự. -- **PII** — số có hình dạng SSN (heuristic). -- **Các quyền công cụ từ chối** và **các vòng lặp gọi công cụ chạy trốn**. +- **Rò rỉ bí mật / thông tin xác thực** trong tải trọng sự kiện — AWS access keys, `sk-…` API keys, PEM private keys, JWT / bearer tokens, và `KEY=…` credential assignments. +- **Dấu hiệu injection prompt** — "ignore previous instructions", "reveal your system prompt", và các dấu hiệu tương tự. +- **PII** — các số có hình dạng SSN (heuristic). +- **Từ chối quyền tool** và **vòng lặp tool-call chạy trốn**. -Các đợt chính sách được duy trì dưới dạng các phát hiện (kind `policy`) **luôn luôn bề mặt** (chúng không bao giờ bị cắt bởi tận cùng mỗi lần chạy), và chúng được trao cho agent AI như những dẫn đầu bắt đầu. Vì tầng này không cần mô hình, một audit vẫn tạo ra những tín hiệu bảo mật quan trọng nhất của nó ngay cả khi agent AI không khả dụng. +Các kết quả kiểm tra chính sách được duy trì dưới dạng findings (loại `policy`) **luôn xuất hiện** (chúng không bao giờ bị cắt bởi giới hạn mỗi lần chạy), và chúng được giao cho agent AI dưới dạng những dẫn chứng khởi đầu. Vì lớp này không cần model, audit vẫn tạo ra những tín hiệu bảo mật quan trọng nhất ngay cả khi agent AI không khả dụng. -### 2. Cuộc điều tra agentic (AI) +### 2. Điều tra agentic (AI) -Audit sau đó chạy một **agent tin cậy tự chủ** (dịch vụ Agents SDK Claude tương tự cung cấp trợ lý bảng điều khiển, với một lời nhắc dành riêng cho audit). Với **phạm vi** audit (các agent đã chọn × môi trường) và **cửa sổ thời gian**, agent: +Audit sau đó chạy một **agent đáng tin cậy tự chủ** (dịch vụ Agents SDK Claude giống như cái cung cấp trợ lý dashboard, với prompt cụ thể cho audit). Với **phạm vi** của audit (agent đã chọn × môi trường) và **cửa sổ thời gian**, agent: -- chạy các truy vấn SQL chỉ đọc trên các bảng phân tích của bạn, -- đọc một vài bản ghi phiên đại diện, -- tùy chọn viết và chạy các **script Python trong hộp cát trong pod bị khóa** (không mạng, không truy cập tệp hệ thống, bí mật được làm sạch) để phân tích SQL không thể biểu thị — phân cụm lỗi, tính toán phân phối, quét tải trọng nó đã tìm nạp, -- và ghi lại mỗi **cải tiến** được chứng thực tốt nó tìm thấy. +- chạy các truy vấn SQL chỉ đọc trên bảng phân tích của bạn, +- đọc một số phiên transcript đại diện, +- tùy chọn viết và chạy các **script Python ngắn trong sandbox in-pod bị khóa** (không network, không filesystem access, secrets đã scrubbed) cho phân tích mà SQL không thể biểu diễn — clustering errors, computing distributions, sweeping payloads nó đã fetch, +- và ghi lại mỗi **cải tiến** có bằng chứng tốt mà nó tìm thấy. -Nó hoạt động thông qua nhiều dòng điều tra — phân cụm lỗi, dịch chuyển so với đường cơ sở, thất bại mục tiêu trong bản ghi, sử dụng công cụ sai, đánh đổi chất lượng/chi phí, và khoảng trống trong phạm vi — tại **độ nhạy** audit (thấp / trung bình / cao). Mỗi cải tiến **phải trích dẫn bằng chứng**: các id phiên mà agent thực tế kiểm tra và/hoặc SQL nó chạy. Máy chủ xác nhận rằng các phiên được trích dẫn tồn tại và **loại bỏ bất kỳ cải tiến nào không có bằng chứng tồn tại**, vì vậy agent điều tra nhưng không bao giờ phát minh ra. +Nó hoạt động thông qua các dòng điều tra — error clustering, drift so với baseline, goal failure trong transcripts, misuse tool, quality/cost trade-offs, và coverage gaps — ở **sensitivity** của audit (low / medium / high). Mọi cải tiến **phải trích dẫn bằng chứng**: các session ids mà agent thực tế đã kiểm tra và/hoặc SQL mà nó chạy. Server xác thực rằng các phiên được trích dẫn tồn tại và **loại bỏ bất kỳ cải tiến nào không có bằng chứng tồn tại**, vì vậy agent điều tra nhưng không bao giờ phát minh. -Mỗi cải tiến mang: +Mỗi cải tiến mang theo: -- một **khuyến nghị** (thay đổi cụ thể cần thực hiện — điều chỉnh lời nhắc, sửa lược đồ công cụ, chính sách thử lại, guardrail, phạm vi đánh giá nhiều hơn), -- một **tác động dự kiến** và ước tính **nỗ lực** (thấp / trung bình / cao), -- một **độ lớn** — `big` (một nhà khai thác nên được báo sớm), `medium` (thuộc báo cáo chạy), hoặc `small` (ngữ cảnh bảng điều khiển), -- một **dấu vân tay** ổn định (từ danh mục + phạm vi của vấn đề, *không phải* các phiên của lần chạy này) để vấn đề tương tự được theo dõi từng lần chạy ngay cả khi bằng chứng thay đổi, -- và, nơi một trình quan sát xác định đơn giản có thể bắt tái diễn, một **alert được đề xuất** bạn có thể tạo trong một cú nhấp chuột. +- một **khuyến nghị** (thay đổi cụ thể cần thực hiện — một tweak prompt, một fix schema tool, một retry policy, một guardrail, coverage eval nhiều hơn), +- một **tác động dự kiến** và ước tính **effort** (low / medium / high), +- một **magnitude** — `big` (một operator nên được thông báo), `medium` (thuộc về report lần chạy), hoặc `small` (dashboard context), +- một **fingerprint** ổn định (từ category + scope của issue, *không* sessions của lần chạy này) để vấn đề tương tự được theo dõi từ lần chạy này sang lần chạy khác ngay cả khi bằng chứng thay đổi, +- và, khi một watcher xác định đơn giản có thể bắt sự lặp lại, một **alert được đề xuất** bạn có thể tạo trong một lần nhấp. -> **Tầng AI là tùy chọn nhưng được khuyến nghị.** Nếu không có agent AI được cấu hình cho đường ống audit, các lần chạy vẫn thực hiện, duy trì các phát hiện chính sách, và thành thật báo cáo "phân tích không khả dụng" cho tầng agentic thay vì im lặng qua. +> **Lớp AI là optional-but-recommended.** Nếu không có agent AI được định cấu hình cho pipeline audit, các lần chạy vẫn thực hiện, vẫn duy trì các findings chính sách, và thành thật báo cáo "analysis unavailable" cho lớp agentic thay vì im lặng trôi qua. ### Chế độ lỗi -Cải tiến phân loại vào **danh mục chế độ lỗi** bền của tổ chức bạn (hoặc đề xuất một chế độ mới). Các chế độ cung cấp các mẫu một danh tính ổn định trên các lần chạy và theo dõi tái diễn chân trời dài. +Cải tiến được phân loại vào **catalog chế độ lỗi** bền chặt của tổ chức bạn (hoặc đề xuất một chế độ mới). Modes cung cấp một danh tính ổn định các mẫu trên các lần chạy và theo dõi recurrence horizon dài. -## Chu kỳ triage +## Vòng đời triage -Trên trang phát hiện (`/audits//findings/`): +Trên trang finding (`/audits//findings/`): | Hành động | Hiệu ứng | |---|---| -| **acknowledge** | Giữ phát hiện hiển thị nhưng giảm ưu tiên của nó một nửa. | -| **resolve** | Đánh dấu nó đã sửa chữa. Nếu mẫu thực sự quay trở lại sau này, nó mở lại là **new** — vì vậy một regression là lớn tiếng, không im lặng được gập vào lịch sử. | -| **mute** / **dismiss** | Duy trì loại bỏ: dấu vân tay của mẫu được nhớ và không bao giờ bề mặt lại, ngay cả trên các lần chạy. Sử dụng mute cho "known, accepted"; dismiss cho "not useful". | -| **reopen** | Xóa loại bỏ / giải quyết và xếp hạng mẫu lại. | -| **assign** | Định tuyến phát hiện cho một nhà khai thác (thành viên tổ chức) để sở hữu. Ưu tiên và trạng thái loại bỏ không thay đổi. | +| **acknowledge** | Giữ cho finding hiển thị nhưng giảm nửa ưu tiên của nó. | +| **resolve** | Đánh dấu đã được sửa. Nếu mẫu thực sự quay trở lại sau này, nó tái mở dưới dạng **new** — vì vậy một regression là rõ ràng, không được im lặng gộp vào lịch sử. | +| **mute** / **dismiss** | Durable suppression: fingerprint của mẫu được ghi nhớ và không bao giờ xuất hiện lại, ngay cả trên các lần chạy. Sử dụng mute cho "known, accepted"; dismiss cho "not useful". | +| **reopen** | Xóa suppression / resolution và xếp hạng mẫu lại. | -Tiếng ồn tín hiệu thấp được kiểm soát trên audit với một tận cùng phát hiện trên mỗi lần chạy (`top_k`) trên các cải tiến agentic. Phát hiện chính sách bỏ qua tận cùng (chúng liên quan đến bảo mật và luôn hiển thị). Bất cứ điều gì bị cắt bởi tận cùng được tính trong thống kê lần chạy — không có gì bị thả im lặng. +Nhiễu tín hiệu thấp được kiểm soát trên mỗi audit với giới hạn findings mỗi lần chạy (`top_k`) trên các cải tiến agentic. Policy findings bỏ qua giới hạn (chúng liên quan đến bảo mật và luôn được hiển thị). Bất cứ thứ gì bị cắt bởi giới hạn được tính trong thống kê của lần chạy — không có gì được im lặng bỏ qua. -## Lên lịch +## Lập lịch -- **Cadence** (`schedule_interval_secs`): hàng giờ đến hàng tuần; **daily là mặc định**. Audits cố ý thô hơn alerts — một cuộc điều tra agentic quét các cửa sổ toàn bộ và chạy trong nhiều phút. -- **Window**: một lookback lăn cố định (ví dụ: "mỗi lần chạy quét 7 ngày cuối cùng") hoặc **since-last-run** (mặc định) — mỗi lần chạy chọn từ nơi lần chạy thành công trước đó kết thúc, với một sự chồng chéo nhỏ để các sự kiện ranh giới không bao giờ bị bỏ lỡ. -- Lần chạy tiếp theo được lên lịch một khoảng thời gian đầy đủ sau khi lần chạy trước **hoàn thành**, vì vậy một lần chạy chậm không bao giờ xếp chồng một lần chạy thứ hai đồng thời của cùng một audit. -- **Run now** trên trang audit làm cho nó do ngay lập tức. +- **Cadence** (`schedule_interval_secs`): từng giờ đến hàng tuần; **daily là mặc định**. Audits được cố ý là thô hơn alerts — một điều tra agentic quét cả cửa sổ và chạy trong vài phút. +- **Window**: hoặc là một lookback rolling cố định (ví dụ "mỗi lần chạy quét 7 ngày cuối cùng") hoặc **since-last-run** (mặc định) — mỗi lần chạy chọn từ nơi lần chạy thành công trước đó kết thúc, với một overlap nhỏ để các sự kiện biên không bao giờ bị bỏ lỡ. +- Lần chạy tiếp theo được lên lịch một interval đầy đủ sau khi lần chạy trước đó **hoàn thành**, vì vậy một lần chạy chậm không bao giờ xếp chồng một lần chạy đồng thời thứ hai cùng một audit. +- **Run now** trên trang audit làm cho nó đến hạn ngay lập tức. -## Lựa chọn mô hình +## Lựa chọn model -Khi tạo audit, bạn có thể chọn mô hình nào cuộc điều tra sử dụng, từ **danh sách các mô hình mà nhà khai thác đã cấu hình** cho dịch vụ agent. Với một mô hình được cấu hình, bộ chọn hiển thị nó như một chú thích; với nhiều hơn, bạn chọn. Để nó không được đặt sử dụng mặc định được cấu hình. +Khi tạo audit, bạn có thể chọn model nào điều tra sử dụng, từ **danh sách các model mà operator của bạn đã định cấu hình** cho dịch vụ agent. Với một model được định cấu hình, picker hiển thị nó dưới dạng một chú thích; với nhiều, bạn chọn. Để nó unset sử dụng mặc định được định cấu hình. ## Thông báo -Khi một lần chạy bề mặt **new** phát hiện, audit thông báo cho các kênh được cấu hình của tổ chức bạn — cùng một cổng `alerts.enabled_channels` và cài đặt đường ống alerts sử dụng: +Khi một lần chạy xuất hiện **new** findings, audit thông báo cho các kênh được định cấu hình của tổ chức bạn — cổng `alerts.enabled_channels` giống nhau và cài đặt mà pipeline alerts sử dụng: -- **Slack** — tóm tắt các mục đáng kể (`big`) mới với một liên kết sâu. -- **Email** — một **báo cáo audit** được thiết kế liệt kê các cải tiến mới (mức độ nghiêm trọng cao nhất, khuyến nghị mỗi mục, liên kết sâu), được gửi khi audit có một kênh **email** được đính kèm và có ít nhất một phát hiện mới. +- **Slack** — một tóm tắt các mục new significant (`big`) với deep link. +- **Email** — một **audit report** được thiết kế liệt kê các cải tiến new (severity cao nhất, khuyến nghị mỗi item, deep link), được gửi khi audit có một **email** channel đính kèm và có ít nhất một finding new. -Các phát hiện lặp lại nhưng đã biết không gửi thông báo lại. +Recurring-but-known findings không tái thông báo. -## Tài liệu tham khảo cấu hình +## Tham chiếu cấu hình -Các định nghĩa audit được quản lý trong bảng điều khiển (`/audits/new`) hoặc thông qua API. Các cài đặt trên audit bao gồm cadence lịch biểu và window, phạm vi (`{"environments": [...], "agent_ids": [...]}`), độ nhạy (`low` / `medium` / `high`), các kênh thông báo, tận cùng phát hiện trên mỗi lần chạy (`top_k`), và mô hình (thông qua `llm_budget.model`). Các cài đặt máy chủ cấp độ nhà khai thác (hết giờ, hộp cát, URL dịch vụ agent) được tài liệu trong [deployment.md](/vi/agenteye/deployment). +Các định nghĩa audit được quản lý trong dashboard (`/audits/new`) hoặc qua API. Cài đặt mỗi audit bao gồm cadence lịch trình và window, phạm vi (`{"environments": [...], "agent_ids": [...]}`), sensitivity (`low` / `medium` / `high`), các kênh thông báo, giới hạn findings mỗi lần chạy (`top_k`), và model (qua `llm_budget.model`). Cài đặt server cấp operator (timeouts, sandbox, URL dịch vụ agent) được tài liệu trong [deployment.md](/vi/agenteye/deployment). ## API -Tất cả các điểm cuối được phạm vi tổ chức và tuân theo auth khóa bearer tiêu chuẩn (xem [api-keys.md](/vi/agenteye/api-keys)). +Tất cả endpoints được scoped org và tuân theo auth bearer-key tiêu chuẩn (xem [api-keys.md](/vi/agenteye/api-keys)). -| Điểm cuối | Quyền | Mục đích | +| Endpoint | Permission | Mục đích | |---|---|---| | `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | Liệt kê / tạo định nghĩa audit. | | `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | Kiểm tra, chỉnh sửa, xóa một audit. | -| `POST /audits/:id/run` | `audits:write` | Làm cho audit do ngay lập tức. | -| `GET /audits/:id/runs` | `audits:read` | Lịch sử chạy (window, trạng thái, thống kê, số lượng phát hiện). | -| `GET /audits/findings` | `audits:read` | Các phát hiện toàn tổ chức, có thể lọc theo `audit_id`, `status`; sắp xếp theo ưu tiên. | -| `GET /audits/findings/:fid` | `audits:read` | Chi tiết phát hiện đầy đủ (khuyến nghị, bằng chứng, ưu tiên). | +| `POST /audits/:id/run` | `audits:write` | Làm audit đến hạn ngay lập tức. | +| `GET /audits/:id/runs` | `audits:read` | Lịch sử chạy (window, status, stats, finding counts). | +| `GET /audits/findings` | `audits:read` | Org-wide findings, có thể lọc theo `audit_id`, `status`; sắp xếp theo ưu tiên. | +| `GET /audits/findings/:fid` | `audits:read` | Chi tiết finding đầy đủ (khuyến nghị, bằng chứng, ưu tiên). | | `POST /audits/findings/:fid/status` | `audits:write` | Triage: `{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`. | -Đối với "audit chạy nhưng không tìm thấy gì", "hộp cát mã bị vô hiệu hóa", và "email audit không được gửi", xem [troubleshooting.md](/vi/agenteye/troubleshooting#audits). \ No newline at end of file +Để "audit chạy nhưng không tìm thấy gì", "code sandbox bị vô hiệu", và "audit email không được gửi", xem [troubleshooting.md](/vi/agenteye/troubleshooting#audits). \ No newline at end of file diff --git a/docs/vi/agenteye/cli-recipes.mdx b/docs/vi/agenteye/cli-recipes.mdx index 684b45ee..62243779 100644 --- a/docs/vi/agenteye/cli-recipes.mdx +++ b/docs/vi/agenteye/cli-recipes.mdx @@ -1,29 +1,29 @@ --- -title: "Công thức CLI cho agents" -description: "Tài liệu công thức CLI AgentEye cho agents." +title: "CLI recipes cho agents" +description: "AgentEye CLI recipes cho agents documentation." --- -Kéo dữ liệu phiên, sự kiện và đánh giá (cũng như kích hoạt lại đánh giá) trực tiếp từ một script hoặc coding agent, với JSON sạch trên stdout có thể ống trực tiếp vào `jq`. Những công thức này biến dữ liệu quan sát của AgentEye thành thứ mà người dùng terminal hoặc coding agent AI (Claude Code, Cursor) có thể truy vấn và tự động hóa, mà không cần nhấp qua bảng điều khiển. +Trích xuất dữ liệu phiên, sự kiện và đánh giá (và kích hoạt đánh giá lại) trực tiếp từ một script hoặc coding agent, với JSON sạch trên stdout có thể pipe trực tiếp vào `jq`. Những recipes này biến dữ liệu observability của AgentEye thành điều mà một terminal user hoặc AI coding agent (Claude Code, Cursor) có thể truy vấn và tự động hóa, mà không cần click vào dashboard. -Các mẫu dưới đây đã sẵn sàng để sao chép-dán cho CLI AgentEye (`agenteye`). Để cài đặt, xác thực và danh sách tùy chọn đầy đủ, xem [CLI](/vi/agenteye/cli); chạy `agenteye -h` hoặc `agenteye -h` để xem trợ giúp tích hợp. +Các patterns dưới đây đã sẵn sàng copy-paste cho AgentEye CLI (`agenteye`). Để cài đặt, xác thực và danh sách option đầy đủ xem [CLI](/vi/agenteye/cli); chạy `agenteye -h` hoặc `agenteye -h` để xem trợ giúp tích hợp. -## Các quy tắc vàng +## Golden rules -1. **Các tùy chọn toàn cầu đi *trước* lệnh.** `agenteye --json sessions` là đúng; `agenteye sessions --json` là không đúng. Các tùy chọn toàn cầu là `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. -2. **Truyền `--json` bất cứ khi nào bạn phân tích đầu ra.** Dữ liệu đi đến **stdout** dưới dạng JSON; trạng thái của con người và lỗi đi đến **stderr**, vì vậy stdout vẫn sạch để ống vào `jq`. -3. **Phân nhánh dựa trên mã thoát**, không phải văn bản stderr: `0` ok · `2` đối số không tốt · `3` không thể tiếp cận bảng điều khiển · `4` không đăng nhập hoặc hết hạn · `5` thiếu quyền. -4. **Khám phá bằng `-h`.** Mỗi lệnh ghi lại các bộ lọc, định dạng giá trị và hình dạng JSON của nó. +1. **Global options đứng *trước* lệnh.** `agenteye --json sessions` là đúng; `agenteye sessions --json` là sai. Các globals là `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`. +2. **Luôn truyền `--json` khi bạn phân tích output.** Dữ liệu đi tới **stdout** như JSON; trạng thái cho con người và lỗi đi tới **stderr**, vì vậy stdout luôn sạch để pipe vào `jq`. +3. **Branch dựa trên exit code**, không phải text stderr: `0` ok · `2` tham số xấu · `3` không thể kết nối tới dashboard · `4` chưa đăng nhập hoặc hết hạn · `5` thiếu quyền. +4. **Khám phá bằng `-h`.** Mỗi lệnh tài liệu hóa các filters, định dạng giá trị và JSON shape của nó. -## Thiết lập một lần +## One-time setup ```bash -export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # để bạn không lặp lại --base-url -agenteye login --email you@example.com # dán mã được gửi qua email; hợp lệ ~24h +export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # so you don't repeat --base-url +agenteye login --email you@example.com # paste the emailed code; valid ~24h ``` -## Xác nhận xác thực trước khi thực hiện công việc +## Confirm auth before doing work -`whoami` không bao giờ gặp lỗi khi phiên bị thiếu hoặc hết hạn; nó báo cáo `logged_in:false` thay thế, vì vậy agent có thể dễ dàng kiểm tra trạng thái xác thực. (Nó vẫn có thể thoát với mã khác không phải là 0 nếu không có URL cơ sở được đặt hoặc bảng điều khiển không thể tiếp cận.) +`whoami` không bao giờ lỗi trên phiên missing hoặc hết hạn; nó báo cáo `logged_in:false` thay vào đó, vì vậy một agent có thể probe auth state một cách an toàn. (Nó vẫn có thể exit non-zero nếu không có base URL được đặt hoặc dashboard không thể tiếp cận.) ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then @@ -31,107 +31,107 @@ if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then fi ``` -## Tìm phiên thất bại hoặc điểm số thấp +## Find failing or low-scoring sessions ```bash -# phiên trong 24h qua có đánh giá gặp lỗi +# sessions in the last 24h whose evaluation errored agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# đánh giá có điểm số <= 0.5 về tính hữu ích, cho một agent +# evaluations scoring <= 0.5 on helpfulness, for one agent agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -Lọc điểm số nằm trên **`evals`**, không phải `sessions`. `--score KEY:MIN..MAX` có thể lặp lại và kết hợp bằng AND; mỗi ràng buộc là tùy chọn (`..0.5` có nghĩa là ≤ 0.5, `0.9..` có nghĩa là ≥ 0.9). Bạn có thể truyền tối đa 20 bộ lọc điểm số cho mỗi yêu cầu; nhiều hơn trả về HTTP 400. `sessions` chia sẻ các bộ lọc `--env`, `--status`, `--agent-id`, `--session-id` và phạm vi thời gian với `evals`, nhưng không có `--score`. +Score filtering nằm trên **`evals`**, không phải `sessions`. `--score KEY:MIN..MAX` có thể lặp lại và được kết hợp AND; cả hai ranh giới đều optional (`..0.5` có nghĩa là ≤ 0.5, `0.9..` có nghĩa là ≥ 0.9). Bạn có thể truyền tới 20 score filters trên mỗi yêu cầu; nhiều hơn thế trả về HTTP 400. `sessions` chia sẻ các filter `--env`, `--status`, `--agent-id`, `--session-id` và time-range với `evals`, nhưng không có `--score`. -## Đọc một phiên từ đầu đến cuối +## Read one session end-to-end -Không có lệnh `session show` duy nhất — kết hợp dấu vết sự kiện với đánh giá của phiên: +Không có lệnh `session show` duy nhất — kết hợp event trail với evaluation của phiên: ```bash -# đánh giá mới nhất của phiên (trạng thái + điểm số) +# the session's latest evaluation (status + scores) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# mỗi sự kiện trong lần chạy (tăng --limit để quét toàn bộ) +# every event in the run (raise --limit for a full sweep) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# chỉ các lệnh gọi công cụ trong một phiên +# just the tool calls in a session agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -## Tìm nạp mọi thứ (phân trang) +## Fetch everything (pagination) -Kết quả là mới nhất trước tiên và được phân trang bằng con trỏ. +Results là newest-first và cursor-paginated. ```bash -# một lần: tìm nạp tối đa 500 hàng trong các trang 200 hàng +# one shot: fetch up to 500 rows in 200-row pages agenteye --json events --session-id run-001 --limit 500 --all > events.json -# phân trang thủ công: đưa next_cursor vào lại +# manual paging: feed next_cursor back in page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` -## Giảm bớt đầu ra bằng --fields +## Slim the output with --fields -Hạn chế các khóa (trong cả bảng và `--json`) để giảm những gì agent phải đọc. +Hạn chế các keys (cả trong table và `--json`) để giảm những gì một agent phải đọc. ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -Tên trường không xác định bị từ chối (thoát `2`) với danh sách hợp lệ, một cách rẻ tiền để khám phá tên trường. +Tên fields không xác định bị từ chối (exit `2`) với danh sách hợp lệ, một cách rẻ để khám phá tên fields. -## Khám phá các giá trị bộ lọc hợp lệ +## Discover valid filter values ```bash -agenteye --json list envs | jq -r '.values[]' # giá trị cho --env -agenteye --json list tools | jq -r '.values[]' # tên công cụ; cũng agents, models, event_types, … -agenteye --json list score_filters | jq -r '.values[]' # KEY hợp lệ cho --score KEY:MIN..MAX +agenteye --json list envs | jq -r '.values[]' # values for --env +agenteye --json list tools | jq -r '.values[]' # tool names; also agents, models, event_types, … +agenteye --json list score_filters | jq -r '.values[]' # valid KEY for --score KEY:MIN..MAX ``` -## Chọn org của bạn (đa người thuê) +## Pick your org (multi-tenant) -Nếu bạn thuộc về nhiều hơn một org, hãy chọn tenant hoạt động tại lúc đăng nhập (nó được lưu): +Nếu bạn thuộc về nhiều hơn một org, chọn active tenant khi đăng nhập (nó được lưu): ```bash -agenteye login --org acme --email you@corp.com # đặt tenant trong cùng bước với đăng nhập +agenteye login --org acme --email you@corp.com # set the tenant in the same step as login agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # ghi đè cho một lệnh +agenteye --org globex --json sessions --since 24h # override for one command ``` -Đăng nhập đa org mà không có `--org` thoát với mã khác không phải là 0 và in các org để chọn từ. +Multi-org login không có `--org` exit non-zero và in các orgs để chọn. -## Cấp khóa API cho SDK/bộ sưu tập +## Provision an API key for the SDK/collector ```bash -# bí mật được in MỘT LẦN — với --json nó là trường .key +# the secret is printed ONCE — with --json it's the .key field key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') -agenteye keys regenerate ci-bot --yes # xoay; agenteye keys disable ci-bot --yes để thu hồi +agenteye keys regenerate ci-bot --yes # rotate; agenteye keys disable ci-bot --yes to revoke ``` -## Chạy một truy vấn đã lưu hoặc ad-hoc +## Run a saved or ad-hoc query ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # truy vấn đã lưu + một $1 vị trí +agenteye --json query run errs --arg prod | jq '.rows' # a saved query + a positional $1 ``` -## Phân loại một sự cố không tương tác +## Triage an incident non-interactively ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> Các đột biến tự động bỏ qua lời nhắc xác nhận của chúng dưới `--json` hoặc khi stdin không phải TTY, vì vậy agents không bao giờ bị treo; truyền `--yes`/`-y` để bỏ qua nó một cách rõ ràng nơi khác. +> Mutations tự động bỏ qua confirmation prompt của họ dưới `--json` hoặc khi stdin không phải TTY, vì vậy agents không bao giờ hang; pass `--yes`/`-y` để bỏ qua một cách rõ ràng ở nơi khác. -## Xử lý mã thoát trong một script +## Exit-code handling in a script ```bash out=$(agenteye --json sessions --since 1h) || code=$? @@ -144,9 +144,9 @@ case "${code:-0}" in esac ``` -## Hình dạng đầu ra JSON +## JSON output shapes -| Lệnh | JSON stdout (với `--json`) | +| Command | stdout JSON (with `--json`) | |---|---| | `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` hoặc `{"logged_in": false}` | | `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` | @@ -155,15 +155,15 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` hiển thị một lần) | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` shown once) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| tạo/cập nhật/xóa (bất kỳ) | đối tượng tài nguyên, hoặc `{"deleted": true, "id"}` cho xóa | -| lỗi (bất kỳ, với `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` trên stdout | +| create/update/delete (any) | the resource object, or `{"deleted": true, "id"}` for deletes | +| failure (any, with `--json`) | `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` on stdout | -- Mỗi mục **sự kiện** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. -- Mỗi mục **đánh giá** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. -- Mỗi mục **phiên** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. +- Mỗi item **event** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. +- Mỗi item **evaluation** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. +- Mỗi item **session** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. -`--fields` của mỗi lệnh chấp nhận chính xác tên trường của mục riêng của nó — tập hợp khác nhau giữa `sessions` và `evals`, vì vậy tên hợp lệ cho tên này có thể bị từ chối bởi cái kia. \ No newline at end of file +`--fields` của mỗi lệnh chấp nhận chính xác tên fields của item của nó — tập hợp khác nhau giữa `sessions` và `evals`, vì vậy một tên hợp lệ cho một cái có thể bị từ chối bởi cái kia. \ No newline at end of file diff --git a/docs/vi/agenteye/deployment.mdx b/docs/vi/agenteye/deployment.mdx index aee19a3f..4c17937f 100644 --- a/docs/vi/agenteye/deployment.mdx +++ b/docs/vi/agenteye/deployment.mdx @@ -3,8 +3,7 @@ title: "Triển khai" description: "Tài liệu triển khai AgentEye." --- - -Hướng dẫn này bao gồm triển khai server AgentEye và dashboard trong môi trường production. +Hướng dẫn này đề cập đến việc triển khai máy chủ AgentEye và bảng điều khiển trong sản xuất. --- @@ -30,135 +29,134 @@ Hướng dẫn này bao gồm triển khai server AgentEye và dashboard trong m +-----------+ ``` -- **Server**: Dịch vụ HTTP viết bằng Rust; nhận các batch sự kiện, ghi chúng vào ClickHouse, và duy trì trạng thái quan hệ trong PostgreSQL. -- **Dashboard**: Ứng dụng web Next.js; đọc và ghi độc quyền thông qua API của server. -- **agenteye-collector**: được triển khai trên các máy agent, không phải trên host server. -- **Postgres 15+**: YÊU CẦU. (Được nâng lên từ 14 trong bản phát hành multi-tenant; schema thành viên tổ chức sử dụng `ON DELETE SET NULL` foreign key danh sách cột, yêu cầu Postgres 15+. Nâng cấp Postgres trước khi triển khai phiên bản này.) Lưu trữ trạng thái OLTP: `api_keys`, `users`, `sessions`, `evaluation_jobs` (hàng đợi), `dashboards`, `saved_queries`, `otp_codes`, cộng với các bảng multi-tenant `orgs`, `org_memberships`, `org_settings`. -- **ClickHouse 24+**: YÊU CẦU. Kho lưu trữ phân tích cho mọi sự kiện được nhập. Engine: `ReplacingMergeTree`, được phân vùng theo tháng, sắp xếp theo `(session_id, ts, dedup_key)`. Server kết nối qua `CLICKHOUSE_URL`; bản triển khai đi kèm `deploy/base/clickhouse/` cung cấp cấu hình nút đơn được điều chỉnh hiệu suất. **Yêu cầu multi-tenant:** cấu hình đi kèm cho phép quản lý quyền truy cập SQL + `users_without_row_policies_can_read_rows=false` để server có thể tạo một người dùng ClickHouse chỉ đọc + chính sách hàng cho mỗi tổ chức (ranh giới cách ly được engine thực thi cho trình soạn thảo SQL và agent AI). Nếu bạn cung cấp cấu hình ClickHouse của riêng mình, hãy chuyển những cài đặt này (xem `deploy/base/clickhouse/configmap.yaml`). -- **Redis 7+**: *tùy chọn* bộ nhớ cache được chia sẻ + backend giới hạn tốc độ. Server và dashboard đều kết nối qua `REDIS_URL`. Nếu không có, cả hai đều suy giảm một cách duyên dáng thành các đường dẫn chỉ Postgres. Xem **Redis (cache tùy chọn)** dưới đây. +- **Server**: Dịch vụ HTTP Rust; nhận các lô sự kiện, ghi chúng vào ClickHouse và duy trì trạng thái quan hệ trong PostgreSQL. +- **Dashboard**: Ứng dụng web Next.js; đọc và ghi độc quyền thông qua API máy chủ. +- **agenteye-collector**: triển khai trên các máy agent, không phải trên máy chủ. +- **Postgres 15+**: REQUIRED. (Được nâng cấp từ 14 trong bản phát hành đa thuê; lược đồ thành viên tổ chức sử dụng khóa ngoại `ON DELETE SET NULL` danh sách cột, chỉ có trong Postgres 15+. Nâng cấp Postgres trước khi triển khai phiên bản này.) Lưu trữ trạng thái OLTP: `api_keys`, `users`, `sessions`, `evaluation_jobs` (hàng đợi), `dashboards`, `saved_queries`, `otp_codes`, cộng với các bảng đa thuê `orgs`, `org_memberships`, `org_settings`. +- **ClickHouse 24+**: REQUIRED. Kho lưu trữ phân tích cho mỗi sự kiện nhập. Công cụ: `ReplacingMergeTree`, được phân vùng theo tháng, sắp xếp theo `(session_id, ts, dedup_key)`. Máy chủ kết nối qua `CLICKHOUSE_URL`; `deploy/base/clickhouse/` được đóng gói với một cấu hình nút đơn được điều chỉnh hiệu suất. **Yêu cầu đa thuê:** cấu hình được đóng gói cho phép quản lý quyền truy cập SQL + `users_without_row_policies_can_read_rows=false` để máy chủ có thể tạo một người dùng ClickHouse chỉ đọc + chính sách hàng cho mỗi tổ chức (ranh giới cô lập do công cụ thực thi cho trình chỉnh sửa SQL và agent AI). Nếu bạn cung cấp cấu hình ClickHouse của riêng mình, hãy chuyển các cài đặt này (xem `deploy/base/clickhouse/configmap.yaml`). +- **Redis 7+**: *tùy chọn* bộ đệm chung + phía sau giới hạn tốc độ. Máy chủ và bảng điều khiển đều kết nối qua `REDIS_URL`. Nếu không có, cả hai sẽ giảm thành graceful thành các đường Postgres. Xem **Redis (bộ đệm tùy chọn)** dưới đây. --- ## Server -### Tải image +### Lấy hình ảnh ```bash echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> Bản dựng hiện tại được phát hành dưới `beta-latest`; `latest` chỉ được gán cho các bản phát hành ổn định. Để production, hãy chọn một tag phiên bản cụ thể `:v`; xem [Available Image Tags](#available-image-tags). +> Các bản dựng hiện tại xuất bản dưới `beta-latest`; `latest` chỉ được gán cho các bản phát hành ổn định. Đối với sản xuất, hãy ghim một thẻ phiên bản cụ thể `:v`; xem [Available Image Tags](#available-image-tags). ### Biến môi trường -| Variable | Required | Default | Description | +| Biến | Bắt buộc | Mặc định | Mô tả | |---|---|---|---| -| `DATABASE_URL` | Yes | none | Postgres DSN. Chuỗi kết nối tiêu chuẩn libpq với scheme `postgres://`. Hỗ trợ `?sslmode=require` và các tham số libpq khác. Mật khẩu không được chứa `/`, `+`, hoặc `=`; sử dụng `openssl rand -hex` để tạo mật khẩu an toàn URL. | -| `ADMIN_KEY` | No | none | Khóa API admin bootstrap. Được upsert với tất cả các quyền trên mỗi lần khởi động. Xoay bằng cách thay đổi giá trị và khởi động lại. | -| `LISTEN_ADDR` | No | `0.0.0.0:8080` | Địa chỉ TCP để bind | -| `MAX_BODY_BYTES` | No | `134217728` (128 MB) | Kích thước phần thân yêu cầu tối đa | -| `ADMIN_EMAIL` | No | none | Email người dùng admin bootstrap. Được upsert với tất cả các quyền trên mỗi lần khởi động và đánh dấu bảo vệ: không thể bị vô hiệu hóa hoặc có quyền sửa đổi qua dashboard/API. Để xoay admin bootstrap, hãy thay đổi `ADMIN_EMAIL` và khởi động lại; email mới được upsert dưới dạng bảo vệ, và email trước đó giữ sự bảo vệ của nó cho đến khi được xóa thủ công trong cơ sở dữ liệu. | -| `ALLOWED_EMAILS` | No | none (all blocked) | Danh sách email được phép tách bằng dấu phẩy để tạo người dùng và đăng nhập. Hỗ trợ các địa chỉ chính xác (`user@example.com`) và ký tự đại diện miền (`*@example.com`). Nếu không được đặt, không có người dùng nào có thể được tạo hoặc đăng nhập. **Chỉ seed khởi động đầu tiên**: seed danh sách cho phép tổ chức mặc định trên khởi động đầu tiên; sau đó trang [`//settings`](#operational-settings) của từng tổ chức là nguồn quy chuẩn và thay đổi biến env này không có tác dụng. | -| `SMTP_HOST` | No | none | Tên máy chủ SMTP để gửi email OTP. Nếu không được đặt, mã OTP được ghi nhật ký vào stdout thay thế. | -| `SMTP_PORT` | No | `587` | Cổng máy chủ SMTP | -| `SMTP_USERNAME` | No | none | Tên người dùng xác thực SMTP | -| `SMTP_PASSWORD` | No | none | Mật khẩu xác thực SMTP | -| `SMTP_FROM` | No | none | Địa chỉ email người gửi cho email OTP | -| `SMTP_TLS` | No | STARTTLS | STARTTLS được sử dụng trừ khi bạn tắt nó một cách rõ ràng: `false` hoặc `0` gửi plaintext (không TLS); bất kỳ giá trị nào khác — bao gồm không được đặt — cho phép STARTTLS. | -| `DASHBOARD_URL` | No | built-in default | Nguồn gốc dashboard được sử dụng để xây dựng cả liên kết phép thuật OTP-email và các liên kết phép thuật sự cố trong thông báo cảnh báo. Nếu không được đặt, nó sẽ quay về mặc định tích hợp (và, chỉ dành cho OTP, quay về nguyên gốc request phát sinh từ dashboard trước tiên). Đặt điều này cho các thiết lập miền phân chia để cả email và liên kết Slack/sự cố chỉ tới dashboard của bạn. Xem **Email magic-link URL** dưới đây; hầu hết các operator không cần đặt điều này. | -| `SESSION_TTL_SECS` | No | `86400` (24 h) | Thời lượng phiên dashboard tính bằng giây. **Chỉ seed khởi động đầu tiên**: chỉnh sửa cho mỗi tổ chức qua [`//settings`](#operational-settings) sau khi triển khai đầu tiên. | -| `OTP_TTL_SECS` | No | `600` (10 min) | Thời gian hiệu lực mã OTP tính bằng giây. **Chỉ seed khởi động đầu tiên**: chỉnh sửa cho mỗi tổ chức qua [`//settings`](#operational-settings) sau khi triển khai đầu tiên. | -| `REDIS_URL` | No | none | Backend bộ nhớ cache + giới hạn tốc độ được chia sẻ tùy chọn, ví dụ `redis://redis:6379/0`. Khi được đặt, server cache các tìm kiếm khóa API được xác thực, `/models` aggregate của dashboard, danh sách phiên, và facet danh sách env; nó cũng chuyển giới hạn tốc độ OTP-request từ Postgres COUNT sang Redis INCR. Nếu không được đặt hoặc không thể truy cập, server chạy mà không cache (giới hạn OTP quay về Postgres, mọi lệnh gọi cache khác đi xuống nguồn quy chuẩn). Xem **Redis (cache tùy chọn)** dưới đây. | -| `CLICKHOUSE_URL` | **Yes** | none | URL cơ sở của phiên bản ClickHouse, ví dụ `http://clickhouse:8123`. Server áp dụng schema sự kiện của nó cho cơ sở dữ liệu này trên mỗi lần khởi động và từ chối khởi động nếu không thể tiếp cận ClickHouse. Xem **ClickHouse (kho lưu trữ phân tích bắt buộc)** dưới đây. | -| `CLICKHOUSE_DATABASE` | No | `agenteye` | Tên cơ sở dữ liệu (schema) ClickHouse. Server tạo nó trên khởi động nếu nó không tồn tại. | -| `ORG_CH_SECRET` | No (single-tenant) / **Yes (multi-org)** | dev default | Khóa HMAC từ đó mật khẩu ClickHouse của mỗi tổ chức được lấy. Trình soạn thảo SQL và `run_query` của agent AI thực thi như người dùng ClickHouse chỉ đọc của tổ chức, người dùng có chính sách hàng thực thi cách ly tenant trong engine. Các triển khai single-tenant khởi động tốt trên mặc định dev tích hợp; **trước khi cung cấp tổ chức thứ hai, bạn PHẢI đặt giá trị mạnh, ổn định**, vì CLI `agenteye-orgctl org create` từ chối chạy trên mặc định dev tích hợp. Xoay nó gây mồ côi mọi người dùng ClickHouse của tổ chức cho đến khi khởi động tiếp theo cung cấp lại chúng (hòa giải thời gian khởi động tự động chữa bệnh này). Giữ nó bí mật và không thay đổi trên các bản sao. Cung cấp tổ chức chính nó là chỉ operator; xem **Organizations (multi-tenancy)** dưới đây. | -| `DEFAULT_ORG_NAME` | No | `Default` | Tên hiển thị được seed cho tổ chức mặc định tích hợp. **Chỉ seed khởi động đầu tiên**, và chỉ khi tổ chức vẫn mang danh tính chung vừa di chuyển của nó, được áp dụng trên khởi động, sau đó bị bỏ qua. Khi bạn đổi tên tổ chức (`agenteye-orgctl org rename`), tên đổi là quyền lực và biến env này không còn có tác dụng. | -| `DEFAULT_ORG_SLUG` | No | `default` | Slug URL cho tổ chức mặc định tích hợp, đường dẫn dashboard nó sống (`//…`). Cùng ngữ nghĩa khởi động đầu tiên / nguyên bản như `DEFAULT_ORG_NAME`. Phải là 1-40 chữ số nhỏ với dấu gạch ngang bên trong đơn và không phải [từ dành riêng](#organizations-multi-tenancy); một giá trị không hợp lệ bị bỏ qua (tổ chức giữ `default`). Cho phép cài đặt single-tenant trình bày dưới dạng ví dụ `/acme` thay vì `/default` mà không có bất kỳ bước CLI sau khi triển khai nào. | -| `RUST_LOG` | No | `info` | Mức độ chi tiết nhật ký (`debug`, `warn`, `error`, `agenteye_server=trace`) | -| `EVALUATOR_ENDPOINT` | No | none | URL cơ sở của dịch vụ evaluator của bạn (ví dụ `http://evaluator:9000`). Khi không được đặt, toàn bộ pipeline đánh giá là no-op; không có hàng hàng đợi được ghi, không có worker chạy. Xem [Evaluation Suite](/vi/agenteye/evaluation-suite). | -| `EVALUATOR_TOKEN` | No | none | Được gửi dưới dạng `Authorization: Bearer ` tới evaluator. **Phải bằng cùng giá trị mà dịch vụ evaluator được cấu hình.** Tùy chọn chỉ khi evaluator của bạn được cấu hình mà không có token. | -| `EVALUATOR_WORKERS` | No | `2` | Đồng thời: số tác vụ worker trên mỗi phiên bản server gửi đi các đánh giá. An toàn để chạy trên nhiều server được mở rộng theo chiều ngang. | -| `EVALUATOR_CLAIM_BATCH` | No | `4` | Số đánh giá tối đa một worker yêu cầu trên mỗi tick. Batch được gửi **đồng thời**, vì vậy đồng thời tổng cộng trên endpoint evaluator của bạn là `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | -| `EVALUATOR_POLL_IDLE_SECS` | No | `2` | Một worker ngủ bao lâu giữa các nỗ lực gửi đi khi không có gì đúng hạn. | -| `EVALUATOR_POLLING_INTERVAL_SECS` | No | `10` | Fallback cuối cùng (giây) cho `GET /evaluate/{id}` polls khi evaluator không trả về `next_poll_secs` trên mỗi phản hồi và không quảng cáo `default_poll_interval_secs` từ `GET /config`. | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | No | `30000` | Timeout per-HTTP-request chống lại evaluator (milliseconds). | -| `EVALUATOR_MAX_ATTEMPTS` | No | `5` | Sau nhiều nỗ lực thất bại này, một đánh giá được ghi nhận là terminal `error` (hoặc `timeout` nếu các lỗi là timeout yêu cầu). | -| `EVALUATOR_CONFIG_REFRESH_SECS` | No | `300` (5 min) | Thường xuyên server tái tìm nạp `GET /config` từ evaluator. | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | No | `3600` (1 h) | Thời gian tường tối đa một phiên có thể ở lại trong hàng đợi polling trước khi AgentEye chấm dứt nó dưới dạng `timeout`. Đảm bảo chống lại một evaluator trả về `pending` mãi mãi. | -| `ALERT_WORKERS` | No | `1` | Đồng thời: số tác vụ worker trên mỗi phiên bản server đánh giá các quy tắc cảnh báo. Xem [Alerts](/vi/agenteye/alerts). | -| `ALERT_CLAIM_BATCH` | No | `16` | Số cảnh báo tối đa một worker yêu cầu trên mỗi tick. | -| `ALERT_POLL_IDLE_SECS` | No | `5` | Một worker cảnh báo ngủ bao lâu khi hàng đợi trống. | -| `ALERT_REQUEST_TIMEOUT_MS` | No | `15000` | Timeout đánh giá kích hoạt per-trigger (ClickHouse queries + outbound channel HTTP). | -| `ALERT_MAX_ATTEMPTS` | No | `5` | Lỗi tạm thời liên tiếp trước khi cảnh báo lên lịch ở tần suất bình thường thay vì backoff theo cấp số nhân. | -| `AUDIT_WORKERS` | No | `1` | Đồng thời: số tác vụ worker trên mỗi phiên bản server thực thi kiểm toán. Xem [Audits](/vi/agenteye/audits). | -| `AUDIT_CLAIM_BATCH` | No | `1` | Số kiểm toán đúng hạn tối đa một worker yêu cầu trên mỗi tick. Một cuộc điều tra agentic là một vòng lặp dài, vì vậy mặc định là 1. | -| `AUDIT_POLL_IDLE_SECS` | No | `30` | Một worker kiểm toán ngủ bao lâu khi không có kiểm toán nào đúng hạn. | -| `AUDIT_REQUEST_TIMEOUT_MS` | No | `30000` | Timeout per-policy-query chống lại ClickHouse (milliseconds). | -| `AUDIT_LLM_TIMEOUT_MS` | No | `1440000` | Timeout cho cuộc gọi cuộc điều tra agentic tới dịch vụ trợ lý AI. Một vòng agent đầy đủ chạy trong nhiều phút; giữ điều này TRÊN `AGENTEYE_AUDIT_TIMEOUT_MS` của agent để agent trả về các phát hiện một phần của nó trước khi server từ bỏ. | -| `AUDIT_MAX_ATTEMPTS` | No | `5` | Lỗi tạm thời liên tiếp trước khi kiểm toán lên lịch ở tần suất bình thường thay vì backoff theo cấp số nhân. | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | No | — | Cuộc điều tra agentic của kiểm toán gọi dịch vụ trợ lý AI `agent`, **sử dụng lại kết nối tương tự như trợ lý** — vì vậy hãy đặt hai cái này trên **server** cũng (các bản rõ ràng/compose do làm việc). Cả hai đặt ⇒ kiểm toán chạy cuộc điều tra AI; hoặc có thể không được đặt ⇒ kiểm toán chạy **policy-only** (lôi SQL xác định chính sách vẫn chạy), bất kể cờ `llm_enabled` của mỗi kiểm toán. Agent cũng phải có LLM được cấu hình — xem [assistant.md](/vi/agenteye/assistant). | - -**Dịch vụ trợ lý AI — cài đặt kiểm toán + sandbox.** Cuộc điều tra agentic và hộp cát Python trong pod của nó được điều chỉnh trên **dịch vụ agent** (không phải server), tất cả trên `AGENTEYE_AUDIT_*` tiền tố và tất cả tùy chọn: - -| Variable | Default | Meaning | +| `DATABASE_URL` | Có | không | DSN Postgres. Chuỗi kết nối libpq tiêu chuẩn với lược đồ `postgres://`. Hỗ trợ `?sslmode=require` và các tham số libpq khác. Mật khẩu không được chứa `/`, `+`, hoặc `=`; hãy sử dụng `openssl rand -hex` để tạo mật khẩu an toàn URL. | +| `ADMIN_KEY` | Không | không | Khóa API quản trị viên bootstrap. Được upsert với tất cả các quyền trên mỗi lần khởi động. Xoay bằng cách thay đổi giá trị và khởi động lại. | +| `LISTEN_ADDR` | Không | `0.0.0.0:8080` | Địa chỉ TCP để ràng buộc | +| `MAX_BODY_BYTES` | Không | `134217728` (128 MB) | Kích thước yêu cầu tối đa của nội dung | +| `ADMIN_EMAIL` | Không | không | Email người dùng quản trị viên bootstrap. Được upsert với tất cả các quyền trên mỗi lần khởi động và được đánh dấu được bảo vệ: không thể bị tắt hoặc có quyền được sửa đổi qua bảng điều khiển/API. Để xoay quản trị viên bootstrap, hãy thay đổi `ADMIN_EMAIL` và khởi động lại; email mới được upsert được bảo vệ, và email trước đó giữ lại bảo vệ cho đến khi xóa thủ công trong cơ sở dữ liệu. | +| `ALLOWED_EMAILS` | Không | không (tất cả bị chặn) | Danh sách được phân tách bằng dấu phẩy của các email được phép để tạo và đăng nhập người dùng. Hỗ trợ các địa chỉ chính xác (`user@example.com`) và ký tự đại diện miền (`*@example.com`). Nếu không được đặt, không có người dùng nào có thể được tạo hoặc đăng nhập. **Chỉ hạt giống khởi động đầu tiên**: hạt giống danh sách cho phép org mặc định trên khởi động đầu tiên; sau đó trang [`//settings`](#operational-settings) của mỗi org là nguồn sự thật và việc thay đổi biến env này không có hiệu lực. | +| `SMTP_HOST` | Không | không | Tên máy chủ SMTP để gửi email OTP. Nếu không được đặt, mã OTP được ghi vào stdout thay thế. | +| `SMTP_PORT` | Không | `587` | Cổng máy chủ SMTP | +| `SMTP_USERNAME` | Không | không | Tên người dùng xác thực SMTP | +| `SMTP_PASSWORD` | Không | không | Mật khẩu xác thực SMTP | +| `SMTP_FROM` | Không | không | Địa chỉ email người gửi cho email OTP | +| `SMTP_TLS` | Không | STARTTLS | STARTTLS được sử dụng trừ khi bạn tắt nó rõ ràng: `false` hoặc `0` gửi plaintext (không TLS); bất kỳ giá trị nào khác — bao gồm không được đặt — cho phép STARTTLS. | +| `DASHBOARD_URL` | Không | mặc định được xây dựng trong | Gốc bảng điều khiển được sử dụng để xây dựng cả liên kết phép thuật email OTP và liên kết phép thuật sự cố trong thông báo cảnh báo. Nếu không được đặt, nó quay trở lại mặc định được xây dựng sẵn (và chỉ dành cho OTP, quay trở lại gốc nguồn được bảng điều khiển lấy trước tiên). Đặt điều này cho các cài đặt miền tách để cả email và liên kết Slack/sự cố đều trỏ tới bảng điều khiển của bạn. Xem **Email magic-link URL** dưới đây; hầu hết các nhà khai thác không cần đặt điều này. | +| `SESSION_TTL_SECS` | Không | `86400` (24 h) | Thời lượng phiên bảng điều khiển tính bằng giây. **Chỉ hạt giống khởi động đầu tiên**: chỉnh sửa theo org qua [`//settings`](#operational-settings) sau bản triển khai đầu tiên. | +| `OTP_TTL_SECS` | Không | `600` (10 min) | Khoảng thời gian hiệu lực mã OTP tính bằng giây. **Chỉ hạt giống khởi động đầu tiên**: chỉnh sửa theo org qua [`//settings`](#operational-settings) sau bản triển khai đầu tiên. | +| `REDIS_URL` | Không | không | Bộ đệm chung tùy chọn + phía sau giới hạn tốc độ, ví dụ `redis://redis:6379/0`. Khi được đặt, máy chủ lưu vào bộ đệm các lần tra cứu khóa API được xác thực, tổng hợp `/models` của bảng điều khiển, danh sách phiên và khía cạnh danh sách env; nó cũng chuyển giới hạn tốc độ yêu cầu OTP từ COUNT Postgres sang INCR Redis. Nếu không được đặt hoặc không thể truy cập được, máy chủ chạy mà không có bộ đệm (giới hạn OTP quay trở lại Postgres, mọi cuộc gọi bộ đệm khác quay trở lại nguồn sự thật). Xem **Redis (bộ đệm tùy chọn)** dưới đây. | +| `CLICKHOUSE_URL` | **Có** | không | URL cơ sở của instance ClickHouse, ví dụ `http://clickhouse:8123`. Máy chủ áp dụng lược đồ sự kiện của nó vào cơ sở dữ liệu này trên mỗi lần khởi động và từ chối khởi động nếu nó không thể truy cập ClickHouse. Xem **ClickHouse (kho lưu trữ phân tích bắt buộc)** dưới đây. | +| `CLICKHOUSE_DATABASE` | Không | `agenteye` | Tên cơ sở dữ liệu ClickHouse (lược đồ). Máy chủ tạo nó trên khởi động nếu nó không tồn tại. | +| `ORG_CH_SECRET` | Không (đơn thuê) / **Có (đa org)** | mặc định dev | Khóa HMAC từ đó mật khẩu ClickHouse mỗi tổ chức được dẫn xuất. Trình chỉnh sửa SQL và agent `run_query` chạy như người dùng ClickHouse chỉ đọc của tổ chức, có chính sách hàng của tổ chức thực thi cô lập tenancy trong công cụ. Các bản triển khai đơn thuê khởi động tốt trên mặc định dev được xây dựng sẵn; **trước khi cung cấp một tổ chức thứ hai, bạn PHẢI đặt một giá trị mạnh, ổn định**, vì CLI `agenteye-orgctl org create` từ chối chạy trên mặc định dev được xây dựng sẵn. Xoay nó làm cho mỗi người dùng ClickHouse của tổ chức trở nên mồ côi cho đến khi khởi động tiếp theo cung cấp lại chúng (đối sánh thời gian khởi động chữa lành điều này tự động). Giữ nó bí mật và không thay đổi trên các bản sao. Cung cấp tổ chức chỉ dành cho toán tử; xem **Organizations (multi-tenancy)** dưới đây. | +| `DEFAULT_ORG_NAME` | Không | `Default` | Tên hiển thị được hạt giống cho org mặc định được xây dựng sẵn. **Chỉ hạt giống khởi động đầu tiên**, và chỉ khi tổ chức vẫn mang danh tính chung được di chuyển mới của nó, áp dụng trên khởi động, sau đó bị bỏ qua. Khi bạn đổi tên tổ chức (`agenteye-orgctl org rename`), việc đổi tên là quyền chính thức và biến env này không còn hiệu lực. | +| `DEFAULT_ORG_SLUG` | Không | `default` | Slug URL cho org mặc định được xây dựng sẵn, đường dẫn bảng điều khiển nó nằm tại (`//…`). Ngữ nghĩa khởi động đầu tiên / nguyên bản giống như `DEFAULT_ORG_NAME`. Phải là 1-40 chữ cái thường alphanumeric với dấu gạch nối bên trong duy nhất và không phải là [từ được dự trữ](#organizations-multi-tenancy); một giá trị không hợp lệ bị bỏ qua (tổ chức giữ `default`). Cho phép một lần cài đặt đơn thuê hiển thị như ví dụ `/acme` thay vì `/default` mà không có bước CLI sau bản triển khai. | +| `RUST_LOG` | Không | `info` | Mức độ chi tiết nhật ký (`debug`, `warn`, `error`, `agenteye_server=trace`) | +| `EVALUATOR_ENDPOINT` | Không | không | URL cơ sở của dịch vụ evaluator của bạn (ví dụ `http://evaluator:9000`). Khi không được đặt, toàn bộ đường dẫn đánh giá là không hoạt động; không có hàng hàng đợi được viết, không có công nhân chạy. Xem [Evaluation Suite](/vi/agenteye/evaluation-suite). | +| `EVALUATOR_TOKEN` | Không | không | Được gửi dưới dạng `Authorization: Bearer ` cho evaluator. **Phải bằng giá trị tương tự mà dịch vụ evaluator được cấu hình.** Tùy chọn chỉ nếu evaluator của bạn được cấu hình không có token. | +| `EVALUATOR_WORKERS` | Không | `2` | Đồng thời: số tác vụ công nhân cho mỗi instance máy chủ điều phối các đánh giá. An toàn để chạy trên nhiều máy chủ được mở rộng theo chiều ngang. | +| `EVALUATOR_CLAIM_BATCH` | Không | `4` | Số lượng tối đa đánh giá mà một công nhân duy nhất yêu cầu trên mỗi tick. Các lô được điều phối **đồng thời**, do đó tổng đồng thời trên điểm cuối evaluator của bạn là `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`. | +| `EVALUATOR_POLL_IDLE_SECS` | Không | `2` | Một công nhân ngủ bao lâu giữa các nỗ lực điều phối khi không có gì đến hạn. | +| `EVALUATOR_POLLING_INTERVAL_SECS` | Không | `10` | Fallback cadence cuối cùng (giây) cho các cuộc thăm dò `GET /evaluate/{id}` khi evaluator không trả về `next_poll_secs` mỗi phản hồi và không quảng cáo `default_poll_interval_secs` từ `GET /config`. | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | Không | `30000` | Hết thời gian chờ mỗi yêu cầu HTTP chống lại evaluator (mili giây). | +| `EVALUATOR_MAX_ATTEMPTS` | Không | `5` | Sau nhiều nỗ lực thất bại này, một đánh giá được ghi lại là kết thúc `error` (hoặc `timeout` nếu các lỗi là hết thời gian chờ yêu cầu). | +| `EVALUATOR_CONFIG_REFRESH_SECS` | Không | `300` (5 min) | Tần suất máy chủ tìm nạp lại `GET /config` từ evaluator. | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | Không | `3600` (1 h) | Thời gian đồng hồ treo tối đa một phiên có thể ở trong hàng đợi thăm dò trước khi AgentEye kết thúc nó dưới dạng `timeout`. Bảo vệ chống lại một evaluator trả về `pending` mãi mãi. | +| `ALERT_WORKERS` | Không | `1` | Đồng thời: số tác vụ công nhân cho mỗi instance máy chủ đánh giá quy tắc cảnh báo. Xem [Alerts](/vi/agenteye/alerts). | +| `ALERT_CLAIM_BATCH` | Không | `16` | Số lượng cảnh báo tối đa mà một công nhân duy nhất yêu cầu trên mỗi tick. | +| `ALERT_POLL_IDLE_SECS` | Không | `5` | Một công nhân cảnh báo ngủ bao lâu khi hàng đợi trống. | +| `ALERT_REQUEST_TIMEOUT_MS` | Không | `15000` | Hết thời gian chờ đánh giá kích hoạt mỗi lần (truy vấn ClickHouse + HTTP kênh gửi đi). | +| `ALERT_MAX_ATTEMPTS` | Không | `5` | Các lỗi tạm thời liên tiếp trước khi một cảnh báo lập lịch ở cadence bình thường thay vì backoff lũy thừa. | +| `AUDIT_WORKERS` | Không | `1` | Đồng thời: số tác vụ công nhân cho mỗi instance máy chủ thực thi kiểm toán. Xem [Audits](/vi/agenteye/audits). | +| `AUDIT_CLAIM_BATCH` | Không | `1` | Số lượng kiểm toán đến hạn tối đa mà một công nhân duy nhất yêu cầu trên mỗi tick. Một cuộc điều tra agentic là một vòng lặp dài, vì vậy mặc định là 1. | +| `AUDIT_POLL_IDLE_SECS` | Không | `30` | Một công nhân kiểm toán ngủ bao lâu khi không có kiểm toán nào đến hạn. | +| `AUDIT_REQUEST_TIMEOUT_MS` | Không | `30000` | Hết thời gian chờ truy vấn chính sách mỗi lần chống lại ClickHouse (mili giây). | +| `AUDIT_LLM_TIMEOUT_MS` | Không | `1440000` | Hết thời gian chờ cho cuộc gọi điều tra agentic tới dịch vụ trợ lý AI. Một vòng agent đầy đủ chạy trong nhiều phút; giữ điều này PHÍA TRÊN `AGENTEYE_AUDIT_TIMEOUT_MS` của agent để agent trả về các phát hiện một phần của nó trước khi máy chủ từ bỏ. | +| `AUDIT_MAX_ATTEMPTS` | Không | `5` | Các lỗi tạm thời liên tiếp trước khi một kiểm toán lập lịch ở cadence bình thường thay vì backoff lũy thừa. | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | Không | — | Cuộc điều tra agentic của kiểm toán gọi dịch vụ `agent` trợ lý AI, **tái sử dụng kết nối tương tự như trợ lý** — vì vậy hãy đặt cả hai trên **máy chủ** cũng vậy (các kê khai được đóng gói/soạn thảo). Cả hai bộ ⇒ kiểm toán chạy điều tra AI; bộ không được đặt ⇒ kiểm toán chạy **chỉ chính sách** (vượt qua chính sách SQL xác định vẫn chạy), bất kể cờ `llm_enabled` mỗi kiểm toán. Agent cũng phải có LLM được cấu hình — xem [assistant.md](/vi/agenteye/assistant). | + +**Dịch vụ trợ lý AI — cài đặt kiểm toán + hộp cát.** Cuộc điều tra agentic và hộp cát Python trong pod của nó được điều chỉnh trên **dịch vụ agent** (không phải máy chủ), tất cả trên tiền tố `AGENTEYE_AUDIT_*` và tất cả tùy chọn: + +| Biến | Mặc định | Ý nghĩa | |---|---|---| -| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Số bước agent tối đa cho mỗi cuộc điều tra. | -| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Tường tối đa cho một cuộc điều tra (20 phút). Phải ở **dưới** `AUDIT_LLM_TIMEOUT_MS` của server. | -| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Các cuộc điều tra đồng thời trên mỗi pod agent (tách biệt khỏi ngân sách của trợ lý trò chuyện). | -| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Giới hạn per-script cho hộp cát bubblewrap. | +| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | Tối đa agent quay trên mỗi điều tra. | +| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | Đồng hồ treo cho một cuộc điều tra (20 phút). Phải ở **dưới** `AUDIT_LLM_TIMEOUT_MS` của máy chủ. | +| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | Các cuộc điều tra đồng thời cho mỗi pod agent (riêng biệt với ngân sách của trợ lý trò chuyện). | +| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | Giới hạn mỗi tập lệnh cho hộp cát bubblewrap. | -**Yêu cầu nền tảng Sandbox.** Hộp cát mã kiểm toán chạy Python của mô hình bên trong nhà tù bubblewrap, yêu cầu **không gian người dùng không được phép**. Pod agent phải cho phép các cờ `clone()` — đặt `seccompProfile: Unconfined` (k8s) hoặc `security_opt: [seccomp:unconfined]` (compose) trên agent. Khi hạt nhân nút vô hiệu hóa không gian người dùng không được phép (ví dụ như một số hình ảnh GKE COS), hộp cát **bỏ qua trước và độc lập tự động giảm xuống chỉ SQL** — không lỗi, chỉ là `sandbox_available: false` trên `/health` của agent. +**Yêu cầu nền tảng hộp cát.** Hộp cát mã kiểm toán chạy Python của mô hình bên trong một牢房 bubblewrap, cần **không gian tên người dùng không đặc quyền**. Pod agent phải cho phép cờ `clone()` — đặt `seccompProfile: Unconfined` (k8s) hoặc `security_opt: [seccomp:unconfined]` (soạn thảo) trên agent. Khi nhân nút tắt không gian tên người dùng không đặc quyền (ví dụ: một số hình ảnh GKE COS), hộp cát **kiểm tra trước không thành công và kiểm toán giảm xuống chỉ SQL tự động** — không có lỗi, chỉ là `sandbox_available: false` trên `/health` của agent. ### Chạy -Đặt `DATABASE_URL` và `CLICKHOUSE_URL` trong môi trường của bạn (server từ chối khởi động mà không có ClickHouse), sau đó chuyển chúng vào container: +Đặt `DATABASE_URL` trong môi trường của bạn, sau đó chuyển nó vào container: ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest ``` -Server chạy các di chuyển cơ sở dữ liệu tự động trên khởi động; không cần bước di chuyển riêng biệt. +Máy chủ chạy các di chuyển cơ sở dữ liệu tự động khi khởi động; không cần bước di chuyển riêng. ### Kiểm tra sức khỏe ``` -GET /health # liveness - luôn {"status":"ok"} khi quy trình khởi động xong +GET /health # liveness - luôn {"status":"ok"} khi quy trình lên GET /ready # readiness - 200 khi Postgres + ClickHouse có thể truy cập được, nếu không 503 ``` -Không cần xác thực. Sử dụng `/health` cho **liveness** probes và `/ready` cho **readiness** / load-balancer probes. `/ready` kiểm tra các phụ thuộc cứng mà server không thể phục vụ mà không có (Postgres + ClickHouse), vì vậy một server đang chạy nhưng không thể tiếp cận cơ sở dữ liệu của nó bị loại khỏi vòng quay và hiển thị là `NotReady`; Redis được báo cáo nhưng không bao giờ thất bại readiness. Trên các bản kê khai Kubernetes đi kèm, probe readiness đã chỉ tới `/ready` và liveness ở `/health`. Xem [enterprise-docs/health-monitoring.md](/vi/agenteye/health-monitoring) để có hình ảnh đầy đủ, bao gồm cảnh báo sự cố pod hỗ trợ Kubernetes-native để Slack. +Không cần xác thực. Sử dụng `/health` cho **liveness** probes và `/ready` cho **readiness** / load-balancer probes. `/ready` kiểm tra các phụ thuộc cứng mà máy chủ không thể phục vụ mà không có (Postgres + ClickHouse), vì vậy một máy chủ đang chạy nhưng không thể truy cập cơ sở dữ liệu của nó bị đưa ra khỏi vòng quay và hiển thị là `NotReady`; Redis được báo cáo nhưng không bao giờ không thể sẵn sàng. Trên các kê khai Kubernetes được đóng gói, probe sẵn sàng đã trỏ tại `/ready` và liveness ở `/health`. Xem [enterprise-docs/health-monitoring.md](/vi/agenteye/health-monitoring) để có hình ảnh đầy đủ, bao gồm cảnh báo pod-failure hỗ trợ Kubernetes gốc opt-in tới Slack. ### Email magic-link URL -Email đăng nhập OTP chứa nút **mở dashboard** một lần nhấn. Nhấp vào nó đưa người dùng tới `/login?token=&email=
`; dashboard trao đổi cặp đó cho một phiên và chuyển hướng tới ứng dụng, không cần nhập lại mã thủ công. Server giải quyết dashboard origin được sử dụng để xây dựng liên kết trong ba tầng: +Email đăng nhập OTP chứa một nút **mở bảng điều khiển** một lần chạm. Nhấp vào nó hạ cánh người dùng trên `/login?token=&email=
`; bảng điều khiển trao đổi cặp đó cho một phiên và chuyển hướng tới ứng dụng, không cần nhập lại mã thủ công. Máy chủ giải quyết gốc bảng điều khiển được sử dụng để xây dựng liên kết trong ba tiers: -1. **`X-AgentEye-Dashboard-Url` header**: được đặt tự động bởi dashboard `/api/auth/otp/request` proxy từ gốc công khai của nó. Trong triển khai cùng gốc (server và dashboard chia sẻ một host đằng sau một ingress chuyển tiếp proxy headers), **không cần cấu hình**. -2. **`DASHBOARD_URL` env var**: đặt điều này nếu dashboard của bạn có thể truy cập trên một gốc khác so với gốc mà endpoint yêu cầu OTP của server nhìn thấy (chia `api.example.com` / `app.example.com`), hoặc nếu ingress của bạn không truyền host công khai vào pod dashboard (vì vậy `request.nextUrl.origin` sẽ giải quyết thành một bind ký tự đại diện như `0.0.0.0:3000`). Ví dụ: `DASHBOARD_URL=https://app.example.com`. -3. **Default**: `https://app.befailproof.ai`, chỉ được sử dụng nếu không có cái nào ở trên. +1. **Tiêu đề `X-AgentEye-Dashboard-Url`**: đặt tự động bằng proxy `/api/auth/otp/request` của bảng điều khiển từ gốc công khai của riêng nó. Trong một bản triển khai cùng gốc (máy chủ và bảng điều khiển chia sẻ một máy chủ đằng sau một ingress chuyển tiếp tiêu đề proxy), **không cần cấu hình**. +2. **Biến `DASHBOARD_URL` env**: đặt điều này nếu bảng điều khiển của bạn có thể truy cập được trên một gốc khác so với gốc mà điểm cuối yêu cầu OTP của máy chủ nhìn thấy (chia `api.example.com` / `app.example.com`), hoặc nếu ingress của bạn không truyền máy chủ công khai vào pod bảng điều khiển (vì vậy `request.nextUrl.origin` sẽ khác cách giải quyết một ràng buộc ký tự đại diện như `0.0.0.0:3000`). Ví dụ: `DASHBOARD_URL=https://app.example.com`. +3. **Mặc định**: `https://app.befailproof.ai`, được sử dụng chỉ nếu không có cái nào ở trên. -Giá trị header được xác thực: chỉ `https://*` và loopback (`http://localhost*`, `http://127.0.0.1*`) origins được chấp nhận, và địa chỉ bind ký tự đại diện (`0.0.0.0`, `[::]`) bị từ chối ngay cả với scheme `https://`. Bất cứ điều gì khác sẽ rơi vào tầng 2. +Giá trị tiêu đề được xác thực: chỉ `https://*` và loopback (`http://localhost*`, `http://127.0.0.1*`) origins được chấp nhận, và địa chỉ ràng buộc ký tự đại diện (`0.0.0.0`, `[::]`) bị từ chối ngay cả với lược đồ `https://`. Bất cứ điều gì khác sẽ rơi qua tier 2. -Đặt nó trên một cụm đang chạy bằng một lệnh một dòng; không có tệp, không xây dựng lại kustomize: +Đặt nó trên một cụm đang chạy với một lệnh một dòng; không có tệp, không xây dựng lại kustomize: ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -Điều này kích hoạt một rollout; các pod mới nhận giá trị này trên yêu cầu đầu tiên. Lưu ý rằng ghi đè chỉ sống trên Deployment; một `kustomize build | kubectl apply` tiếp theo chống lại overlay sẽ xóa nó trừ khi bạn thêm cùng env var vào `server-env.yaml` patch của overlay. +Điều này kích hoạt một bản khởi động lại; các pod mới nhận giá trị khi yêu cầu đầu tiên. Lưu ý rằng ghi đè chỉ nằm trên Triển khai; một `kustomize build | kubectl apply` tiếp theo chống lại lớp phủ sẽ xóa nó trừ khi bạn thêm cùng biến env vào bản vá `server-env.yaml` của lớp phủ. --- -## Dashboard +## Bảng điều khiển -### Tải image +### Lấy hình ảnh ```bash docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest @@ -166,16 +164,16 @@ docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest ### Biến môi trường -| Variable | Required | Default | Description | +| Biến | Bắt buộc | Mặc định | Mô tả | |---|---|---|---| -| `AGENTEYE_SERVER_URL` | Yes | none | URL cơ sở của server, ví dụ `http://localhost:8080` | -| `AGENTEYE_API_KEY` | Yes | none | Khóa API mà dashboard sử dụng để xác thực với server. Cần tất cả các quyền (khóa admin được khuyến cáo). | -| `AE_LOG_LEVEL` | No | `info` | Mức độ chi tiết nhật ký phía máy chủ: `debug`, `info`, `warn`, `error`. Đặt thành `debug` để xem dòng yêu cầu/phản hồi thượng nguồn và theo dõi xác thực phiên khi chẩn đoán vấn đề. | -| `AE_LOG_JSON` | No | auto | `1` bắt buộc JSON-per-line output; `0` bắt buộc human-readable output. Khi không được đặt, JSON được bật tự động nếu `NODE_ENV=production`. JSON được khuyến cáo trong production để logs phân tích sạch với `jq` hoặc một aggregator nhật ký. | -| `AE_ANALYTICS_DISABLED` | No | none | Đặt thành `1`/`true` để vô hiệu hóa telemetry sử dụng sản phẩm ẩn danh của dashboard. Xem [Telemetry & privacy](#telemetry--privacy) dưới đây. | -| `REDIS_URL` | No | none | Backend bộ nhớ cache được chia sẻ tùy chọn, ví dụ `redis://redis:6379/0`. Khi được đặt, dashboard cache `validateSession()` kết quả trên các bản sao và chia sẻ bộ nhớ cache Next.js tìm nạp cho các bản lộ trình proxy aggregate tiên phong / env-list. Giới hạn tốc độ OTP yêu cầu edge-side và xác minh cũng sử dụng Redis khi có (thất bại mở nếu Redis không thể truy cập được; giới hạn phía máy chủ là bảo mật backstop). Xem **Redis (cache tùy chọn)** dưới đây. | -| `AGENTEYE_AGENT_URL` | No | none | URL cơ sở của dịch vụ trợ lý AI `agent` tùy chọn, ví dụ `http://agent:9100`. **Để lại không được đặt để ẩn trợ lý hoàn toàn**: không có bong bóng trợ lý xuất hiện trong dashboard. Xem [enterprise-docs/assistant.md](/vi/agenteye/assistant). | -| `AGENTEYE_AGENT_TOKEN` | No | none | Bí mật được chia sẻ mà dashboard trình bày cho dịch vụ `agent`. Phải khớp với `AGENTEYE_AGENT_TOKEN` được cấu hình trên agent. Xem [enterprise-docs/assistant.md](/vi/agenteye/assistant). | +| `AGENTEYE_SERVER_URL` | Có | không | URL cơ sở của máy chủ, ví dụ `http://localhost:8080` | +| `AGENTEYE_API_KEY` | Có | không | Khóa API mà bảng điều khiển sử dụng để xác thực với máy chủ. Cần tất cả các quyền (khóa quản trị viên được khuyến nghị). | +| `AE_LOG_LEVEL` | Không | `info` | Mức độ chi tiết nhật ký phía máy chủ: `debug`, `info`, `warn`, `error`. Đặt thành `debug` để xem các yêu cầu/phản hồi hạ lưu và dấu vết xác thực phiên khi chẩn đoán vấn đề. | +| `AE_LOG_JSON` | Không | tự động | `1` buộc đầu ra JSON mỗi dòng; `0` buộc đầu ra có thể đọc được bởi con người. Khi không được đặt, JSON được bật tự động nếu `NODE_ENV=production`. JSON được khuyến nghị trong sản xuất để nhật ký phân tích sạch sẽ với `jq` hoặc một bộ lưu trữ nhật ký. | +| `AE_ANALYTICS_DISABLED` | Không | không | Đặt thành `1`/`true` để tắt telemetry sử dụng sản phẩm ẩn danh của bảng điều khiển. Xem [Telemetry & privacy](#telemetry--privacy) dưới đây. | +| `REDIS_URL` | Không | không | Phía sau bộ đệm chung tùy chọn, ví dụ `redis://redis:6379/0`. Khi được đặt, bảng điều khiển lưu vào bộ đệm kết quả `validateSession()` trên các bản sao và chia sẻ bộ đệm tìm nạp Next.js cho các tuyến proxy tổng hợp độ trễ / danh sách env. Giới hạn tốc độ yêu cầu OTP và xác minh cạnh cũng sử dụng Redis khi có (mở không thành công nếu Redis không thể truy cập được; giới hạn phía máy chủ là backstop bảo mật). Xem **Redis (bộ đệm tùy chọn)** dưới đây. | +| `AGENTEYE_AGENT_URL` | Không | không | URL cơ sở của dịch vụ `agent` trợ lý AI tùy chọn, ví dụ `http://agent:9100`. **Để nó không được đặt để ẩn trợ lý hoàn toàn**: không có bong bóng trợ lý hiển thị trong bảng điều khiển. Xem [enterprise-docs/assistant.md](/vi/agenteye/assistant). | +| `AGENTEYE_AGENT_TOKEN` | Không | không | Bí mật chung mà bảng điều khiển trình bày cho dịch vụ `agent`. Phải khớp với `AGENTEYE_AGENT_TOKEN` được cấu hình trên agent. Xem [enterprise-docs/assistant.md](/vi/agenteye/assistant). | ### Chạy @@ -190,89 +188,89 @@ docker run -d --restart unless-stopped \ ### Telemetry & privacy -Dashboard gửi **phân tích sử dụng sản phẩm ẩn danh** tới dịch vụ phân tích Exosphere (PostHog): những trang dashboard nào được xem và một số hành động UI như tạo khóa API hoặc tái đánh giá phiên. Tín hiệu sử dụng này thông báo cho những tính năng nào được ưu tiên. +Bảng điều khiển gửi **phân tích sử dụng sản phẩm ẩn danh** tới dịch vụ phân tích Exosphere (PostHog): những trang bảng điều khiển nào được xem và một số hành động UI như tạo khóa API hoặc đánh giá lại phiên. Tín hiệu sử dụng này thông báo cho các tính năng nào được ưu tiên. -- **Không có dữ liệu agent, phiên hoặc sự kiện nào bao giờ rời khỏi cơ sở hạ tầng của bạn.** Chỉ sử dụng UI dashboard được báo cáo. URL trang được loại bỏ các định danh trước khi gửi, và các operator được xác định chỉ bằng id nội bộ opaque, không bao giờ bằng email. -- Telemetry **được bật theo mặc định**. Để tắt nó hoàn toàn, hãy đặt `AE_ANALYTICS_DISABLED=1` trên container dashboard và khởi động lại. -- Analytics được gửi tới đường dẫn `/ingest` của dashboard riêng, mà dashboard reverse-proxy tới PostHog (`https://us.i.posthog.com`). Giữ các yêu cầu first-party có nghĩa là trình chặn quảng cáo trình duyệt không thả chúng. **Container dashboard** cần truy cập outbound tới PostHog; nếu bị chặn, telemetry im lặng không làm gì và dashboard không bị ảnh hưởng. +- **Dữ liệu agent, phiên hoặc sự kiện không bao giờ rời khỏi cơ sở hạ tầng của bạn.** Chỉ sử dụng UI bảng điều khiển được báo cáo. URL trang được loại bỏ các định danh trước khi gửi, và các toán tử được xác định chỉ bằng một id nội bộ opaque, không bao giờ bằng email. +- Telemetry **được bật theo mặc định**. Để tắt nó hoàn toàn, hãy đặt `AE_ANALYTICS_DISABLED=1` trên container bảng điều khiển và khởi động lại. +- Phân tích được gửi tới đường dẫn `/ingest` của bảng điều khiển, mà bảng điều khiển reverse-proxy tới PostHog (`https://us.i.posthog.com`). Giữ yêu cầu bên thứ nhất có nghĩa là trình chặn quảng cáo trình duyệt không thả chúng. **Container bảng điều khiển** cần quyền truy cập gửi đi tới PostHog; nếu nó bị chặn, telemetry im lặng không làm gì và bảng điều khiển không bị ảnh hưởng. --- -## AI Assistant (tùy chọn) +## Trợ lý AI (tùy chọn) -Một trợ lý AI trong dashboard cho phép nhóm của bạn đặt câu hỏi về dữ liệu agent của họ bằng ngôn ngữ thường (tóm tắt phiên, soạn thảo SQL cho trình soạn thảo `/queries`, và biến các truy vấn lưu thành các tile dashboard) mà không cần rời dashboard. Nó chạy dưới dạng container `agent` nội bộ riêng (trên Claude Agent SDK) mà chỉ dashboard có thể tiếp cận, và ở **bị vô hiệu cho đến khi bạn cấu hình endpoint LLM**. +Một trợ lý AI trong bảng điều khiển cho phép nhóm của bạn đặt câu hỏi về dữ liệu agent của họ bằng ngôn ngữ tự nhiên (tóm tắt phiên, dự thảo SQL cho trình chỉnh sửa `/queries` và chuyển các truy vấn lưu thành các ô bảng điều khiển) mà không cần rời khỏi bảng điều khiển. Nó chạy như một container `agent` nội bộ riêng biệt (trên Agents SDK) mà chỉ bảng điều khiển có thể truy cập, và ở **bị tắt cho đến khi bạn cấu hình điểm cuối LLM**. -Để bật nó, bạn đặt trên dịch vụ `agent`, kết nối LLM (**Portkey** via `PORTKEY_API_KEY` + slug danh mục mô hình `AGENTEYE_AGENT_MODEL=@/`, Anthropic trực tiếp qua `ANTHROPIC_API_KEY`, gateway khác qua `ANTHROPIC_BASE_URL`, hoặc Bedrock/Vertex), khóa dữ liệu **chuyên dụng**, và `AGENTEYE_AGENT_TOKEN` được chia sẻ khớp dashboard. Người dùng dashboard cũng cần quyền `agent:use`. +Để bật nó, bạn đặt, trên dịch vụ `agent`, kết nối LLM (**Portkey** qua `PORTKEY_API_KEY` + slug danh mục mô hình `AGENTEYE_AGENT_MODEL=@/`, Anthropic trực tiếp qua `ANTHROPIC_API_KEY`, cổng khác qua `ANTHROPIC_BASE_URL`, hoặc Bedrock/Vertex), khóa dữ liệu **chuyên dụng**, và `AGENTEYE_AGENT_TOKEN` chung khớp với bảng điều khiển. Người dùng bảng điều khiển cần thêm quyền `agent:use`. -Đối với khóa dữ liệu của trợ lý, bạn không tạo bất cứ thứ gì bằng tay: chọn một bí mật ngẫu nhiên, đặt nó là `AGENTEYE_API_KEY` trên `agent` **và** là `AGENT_API_KEY` trên `server`, và server seed nó trên khởi động với một tập quyền cố định. Truy cập dữ liệu của nó là chỉ đọc (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), và nó còn giữ phạm vi tác giả được phê duyệt cổng (`dashboards:write`, `queries:write`, `queries:run`) để nó có thể soạn thảo và xác thực các truy vấn lưu và xây dựng các tile dashboard thay mặt người dùng; tất cả SQL vẫn chạy qua vai trò chỉ đọc ClickHouse của tổ chức, vì vậy điều này mở rộng những gì trợ lý có thể tác giả, không phải dữ liệu nào nó có thể truy cập. Các phạm vi được sửa chữa trong mã và không thể mở rộng bằng cấu hình. Khóa đó được bảo vệ; không thể bị vô hiệu hóa hoặc tái tạo qua API, chỉ xoay bằng cách thay đổi giá trị và khởi động lại. Không bao giờ sử dụng lại khóa admin/dashboard cho điều này. +Đối với khóa dữ liệu của trợ lý, bạn không mint bất cứ điều gì bằng tay: chọn một bí mật ngẫu nhiên, đặt nó là `AGENTEYE_API_KEY` trên `agent` **và** là `AGENT_API_KEY` trên `server`, và máy chủ hạt giống nó khi khởi động với một bộ quyền cố định. Truy cập dữ liệu của nó chỉ đọc (`events:read`, `evaluations:read`, `dashboards:read`, `queries:read`), và nó còn giữ các phạm vi tác giả phê duyệt (`dashboards:write`, `queries:write`, `queries:run`) để nó có thể dự thảo và xác thực các truy vấn lưu và xây dựng các ô bảng điều khiển thay mặt người dùng; tất cả SQL vẫn chạy qua vai trò ClickHouse chỉ đọc của tổ chức, vì vậy điều này mở rộng những gì trợ lý có thể tác giả, không phải dữ liệu nó có thể truy cập. Các phạm vi được cố định trong mã và không thể mở rộng bằng cấu hình. Khóa đó được bảo vệ; nó không thể bị tắt hoặc tái tạo qua API, chỉ được xoay bằng cách thay đổi giá trị và khởi động lại. Không bao giờ sử dụng lại khóa quản trị viên/bảng điều khiển cho điều này. -Thiết lập đầy đủ, tham khảo biến môi trường hoàn chỉnh, tùy chọn telemetry, và mô hình bảo mật nằm trong **[enterprise-docs/assistant.md](/vi/agenteye/assistant)**. +Thiết lập đầy đủ, tham chiếu biến môi trường hoàn chỉnh, các tùy chọn telemetry và mô hình bảo mật nằm trong **[enterprise-docs/assistant.md](/vi/agenteye/assistant)**. --- ## ClickHouse (kho lưu trữ phân tích bắt buộc) -ClickHouse giữ dashboard của bạn đáp ứng ở khối lượng sự kiện cao và cho phép trình soạn thảo SQL `/queries` tham gia trên các sự kiện, đánh giá, và phiên trong một kho lưu trữ duy nhất. Nó là kho lưu trữ quy chuẩn bắt buộc cho mọi sự kiện được nhập, mọi kết quả đánh giá terminal, và các tổng hợp per-session dẫn xuất. PostgreSQL giữ các bảng trạng thái quan hệ / có thể thay đổi (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); bề mặt phân tích sống trong ClickHouse để rollups của dashboard và các truy vấn SQL của riêng bạn có thể quét và tham gia nó một cách bản địa, mà không có các vòng lặp cross-database. Server từ chối khởi động mà không có `CLICKHOUSE_URL`. +ClickHouse giữ cho bảng điều khiển của bạn phản hồi nhanh ở thể tích sự kiện cao và cho phép trình chỉnh sửa SQL `/queries` tham gia trên các sự kiện, đánh giá và phiên trong một cửa hàng duy nhất. Đó là kho lưu trữ quy chuẩn bắt buộc cho mỗi sự kiện nhập, mỗi kết quả đánh giá thiết bị đầu cuối và các tổng hợp mỗi phiên được dẫn xuất. PostgreSQL giữ các bảng trạng thái quan hệ / có thể thay đổi (api_keys, users, otp_codes, evaluation_jobs, dashboards, saved_queries); bề mặt phân tích nằm trong ClickHouse vì vậy bảng điều khiển của bạn cuộn lên và các truy vấn SQL riêng của bạn có thể quét và tham gia nó một cách bản địa, không có các cuộc đi học liên cơ sở dữ liệu. Máy chủ từ chối khởi động mà không có `CLICKHOUSE_URL`. -### Schema +### Lược đồ -Ba đối tượng ClickHouse được tạo trên khởi động server, tất cả idempotent (`CREATE IF NOT EXISTS`): +Ba đối tượng ClickHouse được tạo khi khởi động máy chủ, tất cả idempotent (`CREATE IF NOT EXISTS`): -- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, được phân vùng theo `toYYYYMM(ts)`, được sắp xếp theo `(session_id, ts, dedup_key)`. Các chèn trùng lặp (collector thử lại) sụp đổ thành một hàng duy nhất tại thời gian hợp nhất; server tính toán `dedup_key` SHA-256 xác định cho mỗi sự kiện để thử lại an toàn. -- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, được phân vùng theo `toYYYYMM(finished_at)`, được sắp xếp theo `(session_id, finished_at, dedup_key)`. Được viết một lần mỗi kết quả đánh giá terminal bởi pipeline evaluator. Mô hình dedup-key giống như `events`. -- **`agenteye.agent_sessions`**: một **VIEW** trên `agenteye.events`, không phải một bảng vật lý. Mỗi cột được dẫn xuất (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, v.v.). Không có per-event upsert và không có backfill riêng biệt; chế độ xem tự động phản ánh bất cứ cái gì nằm trong `events`. +- **`agenteye.events`**: `ReplacingMergeTree(ingested_at)`, được phân vùng theo `toYYYYMM(ts)`, sắp xếp theo `(session_id, ts, dedup_key)`. Các bản chèn trùng (bộ sưu tập thử lại) sụp đổ thành một hàng tại thời gian hợp nhất; máy chủ tính toán `dedup_key` SHA-256 xác định cho mỗi sự kiện để các lần thử lại an toàn. +- **`agenteye.evaluations`**: `ReplacingMergeTree(ingested_at)`, được phân vùng theo `toYYYYMM(finished_at)`, sắp xếp theo `(session_id, finished_at, dedup_key)`. Được viết một lần cho mỗi kết quả đánh giá thiết bị đầu cuối bởi đường dẫn đánh giá. Cùng mô hình dedup-key như `events`. +- **`agenteye.agent_sessions`**: một **VIEW** trên `agenteye.events`, không phải bảng vật lý. Mỗi cột được dẫn xuất (`started_at = min(ts)`, `last_event_at = max(ts)`, `ended_at = max(if event_type='agent_end', ts, NULL)`, `event_count = count()`, v.v.). Không upsert mỗi sự kiện và không backfill riêng; chế độ xem tự phản ánh bất cứ điều gì nằm trong `events`. -Để tương thích ngược với các truy vấn lưu tham khảo `analytics.evaluations` / `analytics.sessions`, server cũng tạo cơ sở dữ liệu ClickHouse `analytics` với các chế độ xem trên các bảng `agenteye.*`; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` tất cả giải quyết chính xác. +Để tương thích ngược với các truy vấn lưu tham chiếu `analytics.evaluations` / `analytics.sessions`, máy chủ cũng tạo cơ sở dữ liệu ClickHouse `analytics` với các chế độ xem trên các bảng `agenteye.*`; `analytics.events`, `analytics.evaluations`, `analytics.agent_sessions`, `analytics.sessions` tất cả được giải quyết chính xác. -### Configuration +### Cấu hình -Bộ docker-compose đi kèm và `deploy/base/clickhouse/` cung cấp dịch vụ ClickHouse được điều chỉnh cho khối lượng công việc của AgentEye: +Docker-compose được đóng gói và `deploy/base/clickhouse/` cung cấp dịch vụ ClickHouse được điều chỉnh cho khối lượng công việc của AgentEye: -- 2 GiB yêu cầu / 4 GiB giới hạn bộ nhớ trong overlay cơ sở được vận chuyển (được định kích để phù hợp với các nút nhỏ POC/staging); khách hàng production nên overlay lên — sàn được khuyến cáo là 2c / 4Gi yêu cầu, 6c / 8Gi giới hạn. `max_server_memory_usage_to_ram_ratio=0.9` -- 5 GiB đánh dấu bộ nhớ cache + 8 GiB bộ nhớ cache không nén +- Bộ nhớ 2 GiB được yêu cầu / giới hạn 4 GiB trong lớp phủ cơ sở được gửi (kích thước phù hợp với các nút POC/staging nhỏ); khách hàng sản xuất nên lớp phủ lên — tầng được đề xuất là yêu cầu 2c / 4Gi, giới hạn 6c / 8Gi. `max_server_memory_usage_to_ram_ratio=0.9` +- Bộ nhớ cache 5 GiB + bộ đệm không nén 8 GiB - `background_pool_size=16`, `background_merges_mutations_concurrency_ratio=2` - MergeTree: `parts_to_throw_insert=3000`, `parts_to_delay_insert=1500`, `non_replicated_deduplication_window=1000` -- `local_io_method=auto` (io_uring trên hạt nhân được hỗ trợ) +- `local_io_method=auto` (io_uring trên các nhân được hỗ trợ) - `fsync_metadata=0`: chấp nhận được vì nhập ít nhất một lần + dedup ReplacingMergeTree -- `query_log` được bật với TTL 30 ngày; `query_thread_log` bị loại bỏ (đắt ở QPS cao) +- `query_log` được bật với TTL 30 ngày; `query_thread_log` bị xóa (đắt tiền ở QPS cao) - `max_execution_time=30` cho các truy vấn phía người dùng -- 100 GiB PVC tại mẫu StatefulSet (overlay khách hàng NÊN ghi đè thành lớp lưu trữ SSD nhanh cho production) +- 100 GiB PVC ở mẫu StatefulSet (lớp phủ khách hàng NÊN ghi đè thành lớp lưu trữ SSD nhanh cho sản xuất) -### Backups +### Sao lưu -Tập dữ liệu đầy đủ của bạn được chụp nightly trong một kho lưu trữ có thể khôi phục duy nhất, vì vậy mất cụm hoặc lưu trữ có thể khôi phục. ClickHouse được sao lưu tự động bởi `agenteye-backup` CronJob hàng ngày, đó sao lưu cả PostgreSQL và ClickHouse trong một lần vượt. ClickHouse được đọc trên API HTTP của nó: `agenteye.events` và `agenteye.evaluations` được dump ở định dạng ClickHouse-native (các chế độ xem và chính sách hàng được server tái tạo trên khởi động, vì vậy dữ liệu bảng là bức tranh hoàn chỉnh) và đóng gói với dump Postgres vào một kho lưu trữ được nén duy nhất được tải lên kho lưu trữ đối tượng của bạn. +Tập dữ liệu đầy đủ của bạn được chụp mỗi đêm trong một kho lưu trữ có thể khôi phục duy nhất, vì vậy mất cụm hoặc lưu trữ có thể phục hồi được. ClickHouse được sao lưu tự động bởi CronJob `agenteye-backup` hàng ngày, sao lưu cả PostgreSQL và ClickHouse trong một lần vượt qua. ClickHouse được đọc qua API HTTP của nó: `agenteye.events` và `agenteye.evaluations` được kết xuất ở định dạng gốc ClickHouse (các chế độ xem và chính sách hàng được tái tạo bởi máy chủ khi khởi động, vì vậy dữ liệu bảng là hình ảnh hoàn chỉnh) và được đóng gói với bản kết xuất Postgres vào một kho lưu trữ nén duy nhất được tải lên lưu trữ đối tượng của bạn. -Bộ nhớ đích và thông tin xác thực cloud được cấu hình cho mỗi overlay. Xem phần **Backups** của [enterprise-docs/kubernetes-deployment.md](/vi/agenteye/kubernetes-deployment) để cấu hình tải lên và các bước khôi phục. +Nhóm đích và thông tin xác thực đám mây được cấu hình cho mỗi lớp phủ. Xem phần **Sao lưu** của [enterprise-docs/kubernetes-deployment.md](/vi/agenteye/kubernetes-deployment) để có cấu hình tải lên và các bước khôi phục. --- -## Redis (cache tùy chọn) +## Redis (bộ đệm tùy chọn) -Redis là một **optional** bộ nhớ cache được chia sẻ + backend giới hạn tốc độ được sử dụng bởi server và dashboard. Với Redis được triển khai và `REDIS_URL` được đặt trên cả hai dịch vụ: +Redis là một **tùy chọn** bộ đệm chung + phía sau giới hạn tốc độ được sử dụng bởi máy chủ và bảng điều khiển. Với Redis được triển khai và `REDIS_URL` được đặt trên cả hai dịch vụ: -- **Server** cache các tìm kiếm khóa API được xác thực, danh sách `/events/environments` + `/evaluations/environments`, rollup `/events/latency_aggregate` (truy vấn nặng nhất mà dashboard polls), danh sách `/sessions`, và chuyển đổi giới hạn tốc độ yêu cầu OTP từ Postgres `COUNT(*)` sang Redis `INCR + EXPIRE`. -- **Dashboard** cache `validateSession()` kết quả để 10-20 API gọi được xác thực một tải trang điển hình chia sẻ một kiểm tra phiên thượng nguồn duy nhất. Nó cũng giới hạn tốc độ yêu cầu OTP và xác minh OTP tại dashboard edge. +- **Server** lưu vào bộ đệm tra cứu khóa API được xác thực, danh sách `/events/environments` + `/evaluations/environments`, kết tập `/events/latency_aggregate` (truy vấn nặng nhất mà bảng điều khiển thăm dò), danh sách `/sessions` và chuyển đổi giới hạn tốc độ yêu cầu OTP từ `COUNT(*)` Postgres thành `INCR + EXPIRE` Redis. +- **Dashboard** lưu vào bộ đệm kết quả `validateSession()` để 10-20 lệnh gọi API được xác thực một tải trang điển hình tất cả chia sẻ một kiểm tra phiên thượng lưu. Nó cũng giới hạn tốc độ yêu cầu OTP và xác minh OTP tại cạnh bảng điều khiển. -**Cả hai dịch vụ đều suy giảm duyên dáng nếu Redis không thể truy cập được.** Mỗi lệnh gọi bộ nhớ cache trả về `Err` trong khoảng thời gian bị giới hạn và người gọi quay về nguồn quy chuẩn (Postgres trên server, Rust server thượng nguồn trên dashboard). Giới hạn tốc độ OTP quay về đường dẫn `COUNT(*)` Postgres trên server (thuộc tính bảo mật được bảo tồn); giới hạn OTP edge của dashboard thất bại mở trong khi giới hạn phía máy chủ vẫn giữ. Redis bị hỏng hóc giảm độ trễ, không phải tính đúng. +**Cả hai dịch vụ giảm xuống gracefully nếu Redis không thể truy cập được.** Mỗi cuộc gọi bộ đệm trả về `Err` trong hết thời gian chờ ràng buộc và người gọi quay trở lại nguồn sự thật (Postgres trên máy chủ, máy chủ Rust thượng lưu trên bảng điều khiển). Giới hạn tốc độ OTP quay trở lại đường dẫn `COUNT(*)` Postgres trên máy chủ (thuộc tính bảo mật được bảo tồn); giới hạn cạnh OTP của bảng điều khiển không thành công mở trong khi giới hạn phía máy chủ vẫn giữ. Redis bị dừng làm giảm độ trễ, không phải tính đúng. -### Configuration +### Cấu hình -Gói docker-compose đi kèm đã bao gồm dịch vụ Redis và dây `REDIS_URL=redis://redis:6379/0` vào server và dashboard. Để sử dụng Redis bên ngoài, hãy đặt `REDIS_URL` thành điểm cuối của bạn và loại bỏ dịch vụ `redis` khỏi tệp compose. +Gói docker-compose đã bao gồm dịch vụ Redis và dây `REDIS_URL=redis://redis:6379/0` vào máy chủ và bảng điều khiển. Để sử dụng Redis bên ngoài, hãy đặt `REDIS_URL` thành điểm cuối của bạn và xóa dịch vụ `redis` khỏi tệp soạn thảo. -### Memory + persistence +### Bộ nhớ + tính bền vững -Hình ảnh Redis đi kèm chạy với `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. Tính bền vững AOF có nghĩa là bộ nhớ cache sống sót sau khi khởi động lại container; `everysec` là cân bằng độ bền/hiệu suất phù hợp vì mất giây cuối cùng của ghi bộ nhớ cache là vô hại. Loại bỏ LRU giới hạn mức tăng bộ nhớ. +Hình ảnh Redis được đóng gói chạy với `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru`. Tính bền vững AOF có nghĩa là bộ đệm tồn tại khởi động lại container; `everysec` là cân bằng độ bền/hiệu suất đúng vì mất giây cuối cùng của ghi bộ đệm là vô hại. Trục xuất LRU giới hạn tăng trưởng bộ nhớ. -### When NOT to deploy Redis +### Khi KHÔNG triển khai Redis -- Single-instance dev/QA. Các bộ nhớ cache trong quy trình trên server một mình cung cấp hầu hết lợi ích per-replica; Redis thêm chia sẻ cross-replica mà các thiết lập single-instance không cần. -- Cài đặt được cách ly không khí nơi chi phí hoạt động của việc chạy một dịch vụ hơn nữa vượt quá chiến thắng độ trễ. +- Dev/QA instance đơn lẻ. Bộ đệm trong quy trình trên máy chủ một mình cung cấp hầu hết lợi ích mỗi bản sao; Redis thêm chia sẻ xuyên bản sao mà thiết lập đơn instance không cần. +- Cài đặt không kết nối trong đó chi phí hoạt động chạy một dịch vụ khác vượt quá lợi thế độ trễ. --- -## Docker Compose (được khuyến cáo) +## Docker Compose (được khuyến nghị) -Một `docker-compose.yml` có sẵn trong kho lưu trữ `agenteye-enterprise/releases`. Nó đưa lên Postgres, ClickHouse, Redis, server, và dashboard bằng một lệnh duy nhất. +Một `docker-compose.yml` có sẵn trong repo `agenteye-enterprise/releases`. Nó nâng Postgres, máy chủ và bảng điều khiển với một lệnh duy nhất. ```bash GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ @@ -290,7 +288,7 @@ cd agenteye POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret -# Xác thực dashboard +# Xác thực bảng điều khiển ADMIN_EMAIL=admin@yourcompany.com ALLOWED_EMAILS=*@yourcompany.com @@ -308,7 +306,7 @@ RUST_LOG=info docker compose up -d ``` -**Dừng (giữ khối lượng dữ liệu):** +**Dừng (giữ âm lượng dữ liệu):** ```bash docker compose down @@ -322,75 +320,44 @@ docker compose down -v --- -## Operational settings +## Cài đặt hoạt động -Một tập nhỏ các khóp hoạt động từng được ghim bằng biến env hiện có thể chỉnh sửa cho mỗi tổ chức từ trang **`//settings`** của dashboard; mỗi tổ chức cấu hình của chính nó. Các thay đổi có hiệu lực trong vài giây, không cần khởi động lại và không cần triển khai lại. +Một bộ nhỏ các nút hoạt động từng được ghim bởi biến env hiện có thể được chỉnh sửa cho mỗi tổ chức từ trang **`//settings`** của bảng điều khiển; mỗi tổ chức cấu hình của riêng nó. Các thay đổi có hiệu lực trong vòng vài giây, không cần khởi động lại và không cần triển khai lại. -| Setting | Bootstrap env var | What it controls | +| Cài đặt | Khởi động env var | Nó điều khiển gì | |---|---|---| -| Allowed sign-ins | `ALLOWED_EMAILS` | Email (hoặc ký tự đại diện `*@domain.com`) được phép nhận OTP và được thêm dưới dạng người dùng | -| Default user permissions | `DEFAULT_USER_PERMISSIONS` | Mã quyền tách bằng dấu phẩy được chọn trước khi admin mở **+ người dùng mới**. Mỗi mã thông báo phải là một trong các chuỗi được liệt kê dưới [API key permissions](/vi/agenteye/api-keys). Mặc định cho preset `standard`: truy cập chỉ đọc cộng với các hành động on-call hàng ngày (kích hoạt lại đánh giá, chạy truy vấn, thừa nhận sự cố, sử dụng trợ lý). | -| Session lifetime | `SESSION_TTL_SECS` | Đăng nhập dashboard kéo dài bao lâu trước khi re-auth. Dashboard kiểm tra lại phiên thượng nguồn mỗi 5 giây, vì vậy cập nhật quyền trên `//users` có hiệu lực trên yêu cầu tiếp theo của người dùng bị ảnh hưởng, không có relogin. | -| One-time-code lifetime | `OTP_TTL_SECS` | OTP / magic-link kéo dài bao lâu trước khi có thể sử dụng | -| Alert notification channels | `ALERTS_ENABLED_CHANNELS` | Danh sách tách bằng dấu phẩy của các loại kênh mà bộ phân phối cảnh báo được phép sử dụng: `email`, `slack`, `webhook`. Cấu hình per-alert vẫn được tác giả trên `//alerts/`, nhưng bộ phân phối lọc mọi gửi outbound qua tập hợp này; kênh được vô hiệu hóa ở đây ngắn mạch với hàng tính toán `skipped_disabled`. Kênh `dashboard` (chèn kiểm toán cục bộ) luôn được phép. Mặc định cho cả ba. | +| Cho phép đăng nhập | `ALLOWED_EMAILS` | Email (hoặc ký tự đại diện `*@domain.com`) được phép nhận OTP và được thêm dưới dạng người dùng | +| Quyền người dùng mặc định | `DEFAULT_USER_PERMISSIONS` | Mã thông báo quyền được phân tách bằng dấu phẩy được chọn trước khi quản trị viên mở **+ người dùng mới**. Mỗi mã thông báo phải là một trong các chuỗi được liệt kê dưới [API key permissions](/vi/agenteye/api-keys). Mặc định là cài đặt `standard`: truy cập chỉ đọc cộng với các hành động hàng ngày (kích hoạt lại đánh giá, chạy truy vấn, ack sự cố, sử dụng trợ lý). | +| Thời lượng phiên | `SESSION_TTL_SECS` | Bảng điều khiển đăng nhập ở mức độ hợp lệ bao lâu trước khi xác thực lại. Bảng điều khiển tái kiểm tra phiên thượng lưu cứ 5 giây một lần, vì vậy cập nhật quyền trên `//users` có hiệu lực trên yêu cầu tiếp theo của người dùng bị ảnh hưởng, không cần đăng nhập lại. | +| Thời lượng mã thời gian | `OTP_TTL_SECS` | OTP / magic-link có thể sử dụng được bao lâu | +| Kênh thông báo cảnh báo | `ALERTS_ENABLED_CHANNELS` | Danh sách các loại kênh được phân tách bằng dấu phẩy mà trình điều phối cảnh báo được phép sử dụng: `email`, `slack`, `webhook`. Cấu hình mỗi cảnh báo vẫn được tác giả trên `//alerts/`, nhưng trình điều phối lọc mọi lần gửi đi thông qua bộ này; một kênh bị tắt tại đây các lệnh lắp tắt ngắn với hàng kiểm toán `skipped_disabled`. Kênh `dashboard` (chèn kiểm toán cục bộ) luôn được phép. Mặc định thành cả ba. | -### How the bootstrap works +### Quá trình khởi động hoạt động -Các cài đặt được lưu trữ cho mỗi tổ chức trong `org_settings`. Trên khởi động đầu tiên, server seed các hàng còn thiếu của tổ chức mặc định từ biến env phù hợp (hoặc mặc định hợp lý nếu biến env không được đặt). Sau đó, **giá trị được lưu trữ là nguồn quy chuẩn và biến env bị bỏ qua**; thay đổi biến env trên lần khởi động sau này sẽ không ảnh hưởng đến giá trị tổ chức trực tiếp, và các tổ chức bổ sung bắt đầu từ mặc định và cấu hình của riêng chúng. +Cài đặt được lưu trữ cho mỗi tổ chức trong `org_settings`. Trên khởi động đầu tiên, máy chủ hạt giống các hàng bị thiếu của tổ chức mặc định từ biến env phù hợp (hoặc mặc định hợp lý nếu biến env không được đặt). Sau đó, **giá trị được lưu trữ là nguồn sự thật và biến env bị bỏ qua**; thay đổi biến env trên lần khởi động sau sẽ không ảnh hưởng đến giá trị của tổ chức trực tiếp, và các tổ chức bổ sung bắt đầu từ các mặc định và cấu hình của chính chúng. Điều này có nghĩa: -- Đối với triển khai mới, hãy đặt biến env như được hiển thị ở trên và tổ chức mặc định đọc chúng trên khởi động đầu tiên. -- Để thay đổi một giá trị sau này, hãy đăng nhập vào dashboard và chỉnh sửa nó dưới `//settings`. Thay đổi áp dụng trong vài giây trên tất cả các bản sao server; không cần khởi động lại. -- Dòng nhật ký khởi động ghi những gì được seed so với những gì đã có, vì vậy bạn có thể xác nhận bootstrap đã có tác dụng: +- Đối với triển khai mới, hãy đặt biến env như hiển thị ở trên và tổ chức mặc định đọc chúng trên khởi động đầu tiên. +- Để thay đổi giá trị sau đó, hãy đăng nhập vào bảng điều khiển và chỉnh sửa nó dưới `//settings`. Thay đổi áp dụng trong vòng vài giây trên tất cả các bản sao máy chủ; không cần khởi động lại. +- Dòng nhật ký khởi động ghi lại những gì đã được hạt giống so với những gì đã có, vì vậy bạn có thể xác nhận rằng khởi động có hiệu lực: ```text INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true ``` -#### Sign-in semantics across organizations +#### Ngữ nghĩa đăng nhập trên các tổ chức -Phiên và OTP là toàn cục cho người dùng, không phải cho một tổ chức duy nhất, vì vậy hai quy tắc hòa giải các cài đặt per-org tại thời điểm đăng nhập: +Một phiên và OTP là toàn cầu cho người dùng, không chỉ một tổ chức duy nhất, vì vậy hai quy tắc điều hòa cài đặt mỗi tổ chức tại thời gian đăng nhập: -- **Session / OTP lifetime**: thời gian tồn tại nghiêm ngặt nhất (ngắn nhất) giữa các tổ chức người dùng thuộc về chiến thắng. -- **Allowed sign-ins**: cổng HOẶC danh sách cho phép của mỗi tổ chức với thành viên tổ chức: người dùng có thể yêu cầu OTP nếu danh sách cho phép của bất kỳ tổ chức nào thừa nhận email của họ **hoặc** họ đã là thành viên của bất kỳ tổ chức nào. +- **Thời lượng phiên / OTP**: thời lượng (ngắn nhất) nghiêm ngặt nhất trong những tổ chức mà người dùng thuộc về win. +- **Cho phép đăng nhập**: cổng ORs mỗi danh sách cho phép của tổ chức với thành viên tổ chức: người dùng có thể yêu cầu OTP nếu bất kỳ danh sách cho phép của tổ chức nào thừa nhận email của họ **hoặc** họ đã là thành viên của bất kỳ tổ chức nào. -### Permissions +### Quyền -Truy cập trang `//settings` được kiểm soát bởi hai quyền: +Truy cập vào trang `//settings` được bảo vệ bằng hai quyền: -- `settings:read`: xem trang và giá trị hiện tại. +- `settings:read`: xem trang và các giá trị hiện tại. - `settings:write`: lưu các thay đổi. -Người dùng admin bootstrap (được seed từ `ADMIN_EMAIL`) nhận cả hai tự động cùng với mọi quyền khác. Cấp chúng cho người dùng khác từ `//users` khi cần. - ---- - -## Organizations (multi-tenancy) - -Một triển khai duy nhất có thể phục vụ nhiều **tổ chức** bị cô lập (tenant); mỗi hàng dữ liệu thuộc về chính xác một tổ chức và cách ly được thực thi trong engine cơ sở dữ liệu. Cài đặt single-tenant không cần gì ở đây; tất cả dữ liệu sống trong tổ chức `default` tích hợp. (Bạn có thể cho tổ chức đó một tên thân thiện hơn và slug URL, vì vậy nó sống ở ví dụ `/acme` thay vì `/default`, bằng cách đặt `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG` trước khởi động đầu tiên, hoặc bằng cách đổi tên nó bất kỳ lúc nào với `agenteye-orgctl org rename`.) - -**Cung cấp tenant chỉ operator.** Các tổ chức và thành viên của chúng được tạo và quản lý bằng CLI **`agenteye-orgctl`**, được cung cấp **bên trong hình ảnh server** (cùng với `agenteye-server`) và chạy **bên trong pod server hiện có**; không có pod/Job riêng biệt, không có API HTTP, và không có nút dashboard. Nó sử dụng lại `DATABASE_URL`, `CLICKHOUSE_URL`, và `ORG_CH_SECRET` của server. - -```bash -# Docker Compose - exec vào dịch vụ server chạy: -docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp" -docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin - -# Kubernetes - exec vào Deployment server chạy: -kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list -``` - -Động từ có sẵn: `org create | list | rename | delete | purge` và `member add | list | update | remove`, với tập quyền tích hợp `admin`, `standard`, và `read-only`. Các thành viên được thêm nhận OTP trên lần đăng nhập dashboard đầu tiên. - -**Trước khi tạo một tổ chức thứ hai:** đặt một `ORG_CH_SECRET` mạnh, ổn định (lệnh `org create` từ chối chạy trên mặc định dev tích hợp) và đảm bảo Postgres là **15+**. **Không thay đổi:** các khóa API per-org vẫn được tạo trong dashboard/API bởi các thành viên tổ chức; chỉ vòng đời tổ chức + thành viên chuyển đến CLI. Tham khảo lệnh đầy đủ và ví dụ đã làm: **[enterprise-docs/tenant-management.md](/vi/agenteye/tenant-management)**. - ---- - -## Context-window fill - -Mỗi sự kiện `model_response` hiển thị một **context-fill pill** — mã thông báo đầu vào cộng với đầu ra dưới dạng phần trăm của cửa sổ bối cảnh của mô hình đó. Các ban nhạc là `healthy` (0–24%), `watch` (25–49%), `compacting` (50–74%), và `reset context` (75–100%). AgentEye giải quyết các ID mô hình phổ biến tự động, vì vậy không cần cấu hình ban đầu. - -Mỗi mô hình một tổ chức gửi xuất hiện dưới **Settings → model context windows**. Người dùng có `settings:write` có thể ghi đè cửa sổ của nó hoặc thêm mô hình riêng/proxy (0–1.000.000 token); `0` có nghĩa là "unknown" và làm im lặng viên ngọc. Các thay đổi áp dụng cho các sự kiện được nhập mới. Người dùng có `settings:read` có thể xem danh sách. - -Các sự kiện mới nhận được lượng đầy từ lúc bạn nâng cấp. Để cũng điền **lịch sử** sự kiện (và danh sách per-model) cho triển khai hiện có, hãy chạy backfill một lần — nó được cung cấp bên trong hình ảnh server (giống như `agen \ No newline at end of file +Người dùng admin bootstrap (hạt giống từ `ADMIN_EMAIL`) tự động nhận được cả hai cùng với mọi quyền khác. Cấp chúng cho người dùng khác từ `//users` khi cần thiết \ No newline at end of file diff --git a/docs/vi/agenteye/getting-started.mdx b/docs/vi/agenteye/getting-started.mdx index 36171ac0..79594de6 100644 --- a/docs/vi/agenteye/getting-started.mdx +++ b/docs/vi/agenteye/getting-started.mdx @@ -1,35 +1,35 @@ --- -title: "Bắt đầu với AgentEye" -description: "Tài liệu Bắt đầu với AgentEye." +title: "Bắt Đầu với AgentEye" +description: "Tài liệu Bắt Đầu với AgentEye." --- -Hướng dẫn này sẽ đưa bạn qua toàn bộ quá trình thiết lập AgentEye: triển khai máy chủ và bảng điều khiển, cài đặt bộ thu thập trên máy chạy agent, và tích hợp mã Python agent của bạn. +Hướng dẫn này sẽ hướng dẫn bạn qua một quá trình thiết lập AgentEye hoàn chỉnh: triển khai máy chủ và bảng điều khiển, cài đặt trình thu thập dữ liệu trên máy agent, và thêm công cụ theo dõi vào mã agent Python của bạn. --- ## AgentEye là gì? -AgentEye là một **nền tảng quan sát và đánh giá tự lưu trữ cho các AI agent**. Nó ghi lại những gì các agent của bạn làm — từng bước của một lần chạy — và tự động chấm điểm chất lượng của mỗi lần chạy hoàn thành, để bạn có thể thấy cách các agent của bạn hoạt động trong môi trường sản xuất và phát hiện các suy thoái trước khi người dùng của bạn làm. +AgentEye là một **nền tảng theo dõi và đánh giá được tự lưu trữ cho các AI agent**. Nó ghi lại những gì agent của bạn làm — mọi bước của một lần chạy — và tự động đánh giá chất lượng của mỗi lần chạy hoàn thành, giúp bạn thấy cách agent của bạn hoạt động trong môi trường production và phát hiện những suy giảm trước khi người dùng của bạn phát hiện. -Dữ liệu chảy theo một hướng: mã agent của bạn phát ra **events** thông qua **Python SDK** → một daemon **bộ thu thập** nhẹ nhàng phân loại và gửi chúng đến **máy chủ** → events và phân tích được lưu trữ trong **ClickHouse** (trạng thái hoạt động như các tổ chức, người dùng, API keys, bảng điều khiển và các truy vấn đã lưu sống trong **Postgres**) → bạn khám phá mọi thứ trong **bảng điều khiển**. +Dữ liệu chảy theo một hướng: mã agent của bạn phát ra **các sự kiện** thông qua **Python SDK** → một daemon **trình thu thập** nhẹ nhàng gom lô và gửi chúng đến **máy chủ** → các sự kiện và phân tích được lưu trữ trong **ClickHouse** (trạng thái hoạt động như tổ chức, người dùng, khóa API, bảng điều khiển và các truy vấn đã lưu sống trong **Postgres**) → bạn khám phá mọi thứ trong **bảng điều khiển**. Những gì bạn nhận được: -- **Events** — dấu vết thô, từng bước của mỗi lần chạy agent (lệnh gọi công cụ, lệnh gọi mô hình, hooks, lỗi). -- **Sessions** — những events đó được tổng hợp thành một hàng cho mỗi lần chạy, mỗi cái được **tự động đánh giá** và chấm điểm. -- **Evaluations** — điểm chất lượng do các dịch vụ đánh giá của riêng bạn tạo ra, để các sụt giảm chất lượng hiển thị mà không cần xem xét thủ công. -- **Queries & dashboards** — SQL ClickHouse đã lưu trên dữ liệu của bạn, được vẽ biểu đồ thành các bảng điều khiển được chia sẻ, phạm vi tổ chức. -- **Alerts & incidents** — quy tắc ngưỡng trang bạn (email, Slack, webhook, trong bảng điều khiển) cộng với quy trình xử lý sự cố để phân loại chúng. -- **CLI & AI assistant** — máy khách terminal (`agenteye`) và trợ lý trong bảng điều khiển để đặt câu hỏi bằng tiếng Anh đơn giản. +- **Các sự kiện** — đường dẫu thô, từng bước của mỗi lần chạy agent (các lệnh gọi công cụ, lệnh gọi mô hình, hook, lỗi). +- **Các phiên** — những sự kiện đó được tập hợp thành một hàng cho mỗi lần chạy, mỗi cái được **tự động đánh giá** và chấm điểm. +- **Các đánh giá** — điểm chất lượng được tạo ra bởi các dịch vụ đánh giá của riêng bạn, vì vậy những sự suy giảm chất lượng sẽ được phát hiện mà không cần kiểm tra thủ công. +- **Các truy vấn và bảng điều khiển** — SQL ClickHouse đã lưu trên dữ liệu của bạn, được vẽ thành các bảng điều khiển được chia sẻ và được phạm vi tổ chức. +- **Cảnh báo và sự cố** — các quy tắc ngưỡng sẽ gửi thông báo cho bạn (email, Slack, webhook, trong bảng điều khiển) cộng với quy trình làm việc sự cố để phân loại chúng. +- **CLI và trợ lý AI** — một ứng dụng khách terminal (`agenteye`) và một trợ lý trong bảng điều khiển để đặt câu hỏi bằng tiếng Anh thuần. -Bạn chạy tất cả nó trong cơ sở hạ tầng của riêng mình, dưới dạng một ngăn xếp Docker Compose duy nhất (hướng dẫn này), cài đặt Kubernetes sản xuất, hoặc một pod đặt cùng nhau duy nhất. Phần còn lại của hướng dẫn này thiết lập ngăn xếp Compose từ đầu đến cuối. +Bạn chạy tất cả chúng trong cơ sở hạ tầng của riêng mình, dưới dạng một ngăn xếp Docker Compose (hướng dẫn này), một bộ cài đặt production Kubernetes, hoặc một pod đơn lẻ cùng địa phương. Phần còn lại của hướng dẫn này thiết lập ngăn xếp Compose từ đầu đến cuối. --- ## Bước 1: Xác thực -Tất cả các tạo tác AgentEye được phân phối từ tổ chức GitHub `agenteye-enterprise`. Là nhà phát triển doanh nghiệp, bạn có thể tạo PAT GitHub của riêng mình. Làm theo [enterprise-docs/github-token.md](/vi/agenteye/github-token) để biết các bước chính xác và quyền cần thiết. +Tất cả các tạo tác AgentEye được phân phối từ tổ chức GitHub `agenteye-enterprise`. Là một nhà phát triển doanh nghiệp, bạn có thể tạo PAT GitHub của riêng mình. Theo dõi [enterprise-docs/github-token.md](/vi/agenteye/github-token) để thực hiện các bước chính xác và các quyền bắt buộc. ```bash export AGENTEYE_TOKEN= @@ -42,9 +42,9 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin ## Bước 2: Triển khai Máy chủ và Bảng điều khiển -Máy chủ nhận các events từ các bộ thu thập và làm cho chúng có thể truy vấn được; bảng điều khiển là nơi bạn khám phá chúng. Các events được nhập vào và phân tích sống trong ClickHouse (kho phân tích bắt buộc), trong khi Postgres giữ trạng thái hoạt động như các tổ chức, người dùng, API keys, bảng điều khiển và các truy vấn đã lưu. +Máy chủ nhận các sự kiện từ các trình thu thập và làm cho chúng có thể truy vấn được; bảng điều khiển là nơi bạn khám phá chúng. Các sự kiện và phân tích được nạp sống trong ClickHouse (kho lưu trữ phân tích bắt buộc), trong khi Postgres giữ trạng thái hoạt động như các tổ chức, người dùng, khóa API, bảng điều khiển và các truy vấn đã lưu. -**Tải xuống tệp compose được xuất bản:** +**Tải xuống tệp compose đã xuất bản:** ```bash mkdir -p ./agenteye @@ -55,38 +55,32 @@ curl -fsSL \ cd agenteye ``` -**Đặt bí mật của bạn:** +**Đặt các bí mật của bạn:** -Tạo tệp `.env` để triển khai không chạy trên thông tin đăng nhập mặc định `admin`. Ít nhất hãy đặt `ADMIN_KEY` và `POSTGRES_PASSWORD`: +Tạo một tệp `.env` để việc triển khai không chạy trên thông tin đăng nhập `admin` mặc định. Ở mức tối thiểu, hãy đặt `ADMIN_KEY` và `POSTGRES_PASSWORD`: ```bash POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -Cũng xuất `ADMIN_KEY` trong shell hiện tại của bạn để các bước sau này (ví dụ: `curl` Bước 3) có thể tham chiếu nó trực tiếp: - -```bash -export ADMIN_KEY=your-admin-secret -``` - **Khởi động ngăn xếp:** ```bash docker compose up -d ``` -Điều này đưa ngăn xếp đầy đủ lên, bao gồm kho phân tích ClickHouse bắt buộc và bộ nhớ cache Redis tùy chọn, cùng với máy chủ và bảng điều khiển. ClickHouse phải lành mạnh để máy chủ khởi động. +Điều này đưa toàn bộ ngăn xếp lên, bao gồm kho lưu trữ phân tích ClickHouse bắt buộc và bộ đệm Redis tùy chọn, cùng với máy chủ và bảng điều khiển. ClickHouse phải khỏe mạnh để máy chủ khởi động. -Máy chủ hiện đang lắng nghe tại `http://localhost:8080` và bảng điều khiển tại `http://localhost:3000`. +Máy chủ hiện đang lắng nghe ở `http://localhost:8080` và bảng điều khiển ở `http://localhost:3000`. -Để triển khai sản xuất (Postgres tùy chỉnh, TLS, reverse proxy), hãy xem [enterprise-docs/deployment.md](/vi/agenteye/deployment). +Để triển khai production (Postgres tùy chỉnh, TLS, proxy ngược), xem [enterprise-docs/deployment.md](/vi/agenteye/deployment). --- -## Bước 3: Tạo API Key cho Bộ thu thập +## Bước 3: Tạo một Khóa API cho Trình thu thập -Mỗi bộ thu thập xác thực bằng API key có phạm vi. Sử dụng `ADMIN_KEY` bạn đặt ở Bước 2 để tạo một cái: +Mỗi trình thu thập xác thực với một khóa API được xác định phạm vi. Sử dụng `ADMIN_KEY` bạn đặt trong Bước 2 để tạo một khóa: ```bash curl -s -X POST http://localhost:8080/keys \ @@ -95,15 +89,15 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -Bạn cung cấp giá trị `key` tự mình; sử dụng nó trong cấu hình bộ thu thập ở Bước 4. Xem [enterprise-docs/api-keys.md](/vi/agenteye/api-keys) để quản lý key đầy đủ. +Bạn cung cấp giá trị `key` cho chính mình; sử dụng nó trong cấu hình trình thu thập ở Bước 4. Xem [enterprise-docs/api-keys.md](/vi/agenteye/api-keys) để quản lý khóa đầy đủ. --- -## Bước 4: Cài đặt Bộ thu thập +## Bước 4: Cài đặt Trình thu thập -Trên mỗi máy chạy các AI agent của bạn, hãy cài đặt daemon bộ thu thập. +Trên mỗi máy chạy AI agent của bạn, hãy cài đặt daemon trình thu thập. -**Tải xuống tệp nhị phân (Linux x86_64):** +**Tải xuống nhị phân (Linux x86_64):** ```bash VERSION=0.0.1-beta.13 @@ -114,7 +108,7 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> Điều này tải xuống bản dựng **Linux x86_64**. Đối với macOS (Apple Silicon hoặc Intel), Linux arm64, hoặc Docker / systemd / launchd setup, xem [collector-installation.md](/vi/agenteye/collector-installation), liệt kê tải xuống cho mỗi nền tảng — lệnh trên cài đặt một tệp nhị phân Linux sẽ không chạy ở nơi khác. +> Điều này tải xuống bản dựng **Linux x86_64**. Để sử dụng macOS (Apple Silicon hoặc Intel), Linux arm64, hoặc thiết lập Docker / systemd / launchd, xem [collector-installation.md](/vi/agenteye/collector-installation), liệt kê bản tải xuống cho mỗi nền tảng — lệnh trên cài đặt một nhị phân Linux sẽ không chạy ở nơi khác. **Cấu hình:** @@ -134,19 +128,19 @@ EOF agenteye-collector start ``` -Xác minh kết nối với xả một lần (thoát sau khi xả mọi events đang chờ): +Xác minh kết nối với một lần xả nước duy nhất (thoát sau khi thoát bất kỳ sự kiện nào đang chờ xử lý): ```bash agenteye-collector flush ``` -Đối với Docker, systemd và launchd setup, xem [enterprise-docs/collector-installation.md](/vi/agenteye/collector-installation). +Để thiết lập Docker, systemd và launchd, xem [enterprise-docs/collector-installation.md](/vi/agenteye/collector-installation). --- ## Bước 5: Cài đặt Python SDK -Trên mỗi máy nơi bạn muốn tích hợp mã agent, hãy cài đặt wheel từ GitHub Releases. +Trên mỗi máy nơi bạn muốn thêm công cụ theo dõi vào mã agent, hãy cài đặt wheel từ GitHub Releases. ```bash VERSION=0.0.1b9 @@ -158,9 +152,9 @@ pip install agenteye-${VERSION}-py3-none-any.whl --- -## Bước 6: Tích hợp Agent của bạn +## Bước 6: Thêm công cụ theo dõi vào Agent của bạn -Thêm events vào mã agent của bạn. Ít nhất, phát ra `agent_start` và `agent_end`: +Thêm các sự kiện vào mã agent của bạn. Ở mức tối thiểu, phát ra `agent_start` và `agent_end`: ```python import agenteye @@ -180,56 +174,56 @@ agenteye.event.agent_end( ) ``` -Events được lưu đệm và xả đến `$AGENTEYE_HOME/events/` (hoặc `~/.agenteye/events/` nếu `AGENTEYE_HOME` không được đặt) mỗi 500 ms. Bộ thu thập chọn chúng lên tự động. +Các sự kiện được đệm và được xả vào `$AGENTEYE_HOME/events/` (hoặc `~/.agenteye/events/` nếu `AGENTEYE_HOME` không được đặt) mỗi 500 ms. Trình thu thập tự động nhận chúng. -Xem [enterprise-docs/python-sdk.md](/vi/agenteye/python-sdk) để biết đầy đủ API events. +Xem [enterprise-docs/python-sdk.md](/vi/agenteye/python-sdk) để xem API sự kiện đầy đủ. --- -## Bước 7: Xem Events trong Bảng điều khiển +## Bước 7: Xem các sự kiện trong Bảng điều khiển -Mở `http://your-dashboard-host:3000` và đăng nhập. AgentEye gửi cho bạn một mã dùng một lần (hoặc một liên kết ma thuật click đơn lần), vì vậy không có mật khẩu để quản lý. +Mở `http://your-dashboard-host:3000` và đăng nhập. AgentEye gửi cho bạn một mã dùng một lần qua email (hoặc một liên kết magic một cú nhấp), vì vậy không có mật khẩu để quản lý. ![Màn hình đăng nhập AgentEye, gửi mã dùng một lần đến email của bạn](/agenteye/images/login.png) -Khi bạn vào, trang **Events** hiển thị một dấu vết trực tiếp của tất cả các events được nhập vào. Lọc theo `session_id` hoặc `agent_id` để đi sâu vào một lần chạy cụ thể. +Khi bạn vào, trang **Events** hiển thị một đường dẫu trực tiếp của tất cả các sự kiện được nạp. Lọc theo `session_id` hoặc `agent_id` để tìm hiểu chi tiết một lần chạy cụ thể. -![Luồng Events trực tiếp, được tô màu theo loại event và có thể lọc theo môi trường, agent và session](/agenteye/images/events-stream.png) +![Luồng Events trực tiếp, được mã hóa màu theo loại sự kiện và có thể lọc theo môi trường, agent và phiên](/agenteye/images/events-stream.png) -Trang **Sessions** tổng hợp những events đó thành một hàng cho mỗi lần chạy. AgentEye tự động đánh giá các sessions hoàn thành, vì vậy mỗi lần chạy được chấm điểm và các suy thoái chất lượng hiển thị mà không cần xem xét thủ công; điểm đánh giá mới nhất xuất hiện trên mỗi hàng ngay lập tức: +Trang **Sessions** tập hợp những sự kiện đó thành một hàng cho mỗi lần chạy. AgentEye tự động đánh giá các phiên đã hoàn thành, vì vậy mỗi lần chạy được chấm điểm và những suy giảm chất lượng được hiển thị mà không cần kiểm tra thủ công; điểm đánh giá mới nhất xuất hiện trên mỗi hàng một cách sắc nét: -![Danh sách Sessions, một hàng cho mỗi lần chạy, với các huy hiệu trạng thái và huy hiệu điểm đánh giá](/agenteye/images/sessions-list.png) +![Danh sách Sessions, một hàng cho mỗi lần chạy, với huy hiệu trạng thái và huy hiệu điểm đánh giá](/agenteye/images/sessions-list.png) -Để cấu hình cách các sessions được chấm điểm, xem [enterprise-docs/evaluation-suite.md](/vi/agenteye/evaluation-suite). +Để định cấu hình cách các phiên được chấm điểm, xem [enterprise-docs/evaluation-suite.md](/vi/agenteye/evaluation-suite). -Nhấp vào bất kỳ session nào để mở **execution graph** của nó, một khung nhìn theo kiểu git về cách các agents, công cụ, hooks và lệnh gọi mô hình diễn ra theo thời gian, với các sub-agents song song trên các làn riêng của chúng và một bảng phân tích theo lần chạy trong thanh ray bên phải: +Nhấp vào bất kỳ phiên nào để mở **biểu đồ thực thi** của nó, một dạng xem kiểu git về cách agent, công cụ, hook và lệnh gọi mô hình diễn ra theo thời gian, với các sub-agent song song trên các làn của riêng chúng và một bảng phân tích từng lần chạy trong đường ray bên phải: -![Biểu đồ thực thi theo kiểu git của một session cạnh dòng thời gian events của nó, với bảng phân tích tool/model/hook](/agenteye/images/session-detail.png) +![Biểu đồ thực thi kiểu git của phiên bên cạnh dòng thời gian sự kiện của nó, với bảng phân tích công cụ/mô hình/hook](/agenteye/images/session-detail.png) --- ## Bước 8: Khám phá, biểu đồ và cảnh báo -Với các events chảy, các trang **analyze** chuyển hoạt động thô thành câu trả lời, để bạn có thể đo lường hành vi agent, chia sẻ phát hiện trên toàn đội ngũ và nhận trang thông báo khoảnh khắc có gì đó suy thoái. Các trang bảng điều khiển được phạm vi tổ chức, vì vậy các URL bạn thấy trong thanh địa chỉ được đặt tiền tố với slug org của bạn (`//…`). +Với các sự kiện chảy, các trang **phân tích** biến hoạt động thô thành các câu trả lời, vì vậy bạn có thể đo lường hành vi agent, chia sẻ các phát hiện với nhóm và được gọi vào trang thái nếu có gì đó suy giảm. Các trang bảng điều khiển được phạm vi tổ chức, vì vậy các URL bạn thấy trong thanh địa chỉ có tiền tố với slug org của bạn (`//…`). -- **Queries** (`//queries`): bắt đầu từ một thư viện các truy vấn đã lưu, có thể tái sử dụng trên các events và evaluations của bạn (các cài đặt sẵn tích hợp cộng với các truy vấn của riêng bạn)… +- **Queries** (`//queries`): bắt đầu từ một thư viện các truy vấn đã lưu, có thể tái sử dụng trên các sự kiện và đánh giá của bạn (các cài đặt trước tích hợp cộng với các truy vấn tùy chỉnh của bạn)… -![Thư viện truy vấn đã lưu: một lưới các truy vấn có thể tái sử dụng, cả cài đặt sẵn tích hợp và truy vấn tùy chỉnh](/agenteye/images/queries.png) +![Thư viện các truy vấn đã lưu: lưới các truy vấn có thể tái sử dụng, cả cài đặt trước tích hợp và các truy vấn tùy chỉnh](/agenteye/images/queries.png) - …sau đó mở một cái trong nhà soạn SQL để điều chỉnh nó và chạy nó với kết quả trực tiếp: + …rồi mở một trong số chúng trong soạn thảo viên SQL để điều chỉnh nó và chạy nó với kết quả trực tiếp: -![Nhà soạn truy vấn SQL chạy một truy vấn đã lưu, với một thanh bên lược đồ và một lưới kết quả trực tiếp](/agenteye/images/query-lab.png) +![Soạn thảo viên truy vấn SQL chạy một truy vấn đã lưu, với thanh bên lược đồ và lưới kết quả trực tiếp](/agenteye/images/query-lab.png) -- **Dashboards** (`//dashboards`): ghim các truy vấn dưới dạng các tile đường, thanh, diện tích hoặc bánh vào các bảng điều khiển được chia sẻ, toàn org. +- **Dashboards** (`//dashboards`): ghim các truy vấn như ô đường kẻ, thanh, diện tích hoặc hình tròn vào các bảng điều khiển được chia sẻ, toàn org. -![Bảng điều khiển được xây dựng từ các truy vấn đã lưu: một dòng events mỗi giờ, một thanh lỗi theo loại, biểu đồ diện tích độ trễ và tokens theo mô hình](/agenteye/images/dashboard-fleet.png) +![Bảng điều khiển được tạo từ các truy vấn đã lưu: một dòng sự kiện trên giờ, thanh lỗi theo loại, biểu đồ diện tích độ trễ và mã thông báo theo mô hình](/agenteye/images/dashboard-fleet.png) -- **Alerts** (`//alerts`): thăng cấp bất kỳ ngưỡng nào thành quy tắc trang thông báo bằng email, Slack, webhook hoặc trong bảng điều khiển. Xem [enterprise-docs/alerts.md](/vi/agenteye/alerts). +- **Alerts** (`//alerts`): nâng cao bất kỳ ngưỡng nào thành một quy tắc ghi trang thái được thông báo qua email, Slack, webhook hoặc trong bảng điều khiển. Xem [enterprise-docs/alerts.md](/vi/agenteye/alerts). --- ## Các bước tiếp theo -- [Deployment](/vi/agenteye/deployment): củng cố cho sản xuất +- [Deployment](/vi/agenteye/deployment): cứng hóa cho production - [API Keys](/vi/agenteye/api-keys): quản lý quyền truy cập - [Troubleshooting](/vi/agenteye/troubleshooting): chẩn đoán các vấn đề \ No newline at end of file diff --git a/docs/vi/agenteye/managed-deployment.mdx b/docs/vi/agenteye/managed-deployment.mdx index 1f7ff406..5e28d4d6 100644 --- a/docs/vi/agenteye/managed-deployment.mdx +++ b/docs/vi/agenteye/managed-deployment.mdx @@ -1,36 +1,35 @@ --- ---- -title: "Triển khai được quản lý trên Cluster Kubernetes của bạn" -description: "Tài liệu Triển khai được quản lý AgentEye trên Cluster Kubernetes của bạn." +title: "Triển Khai Được Quản Lý trên Kubernetes Cluster của Bạn" +description: "Tài liệu Triển Khai Được Quản Lý AgentEye trên Kubernetes Cluster của Bạn." --- -AgentEye là một nền tảng quan sát và đánh giá tự lưu trữ cho các agent AI và LLM. Nó ghi lại các phiên làm việc của agent, các lệnh gọi công cụ, yêu cầu mô hình và lỗi, chuyển chúng thành phân tích và đánh giá có thể tìm kiếm, và hiển thị kết quả trên bảng điều khiển với trợ lý AI chỉ đọc tùy chọn. +AgentEye là một nền tảng quan sát và đánh giá tự lưu trữ cho các agent AI và LLM. Nó nắm bắt các phiên agent, lệnh gọi công cụ, yêu cầu mô hình và lỗi, chuyển chúng thành phân tích và đánh giá có thể tìm kiếm được, và hiển thị kết quả trên bảng điều khiển với một trợ lý AI chỉ đọc tùy chọn. -Trong mô hình triển khai được quản lý, bạn cung cấp một cluster Kubernetes chuyên dụng và Exosphere chạy toàn bộ nền tảng bên trong nó, triển khai, định cấu hình, vận hành, sao lưu và nâng cấp từng thành phần thay bạn. Nhóm của bạn nhận được giá trị của nền tảng (khả năng hiển thị agent, phân tích, đánh giá và trợ lý tùy chọn) mà không cần vận hành cơ sở dữ liệu, chứng chỉ hoặc nâng cấp. Tất cả dữ liệu được lưu giữ trong tài khoản đám mây của bạn. +Trong mô hình triển khai được quản lý, bạn cung cấp một Kubernetes cluster chuyên dụng và Exosphere chạy toàn bộ nền tảng bên trong, triển khai, cấu hình, vận hành, sao lưu và nâng cấp từng thành phần thay mặt bạn. Nhóm của bạn nhận được giá trị của nền tảng (khả năng hiển thị agent, phân tích, đánh giá và trợ lý tùy chọn) mà không cần vận hành các cơ sở dữ liệu, chứng chỉ hoặc nâng cấp. Tất cả dữ liệu nằm trong tài khoản cloud của bạn. --- ## Điều kiện tiên quyết -- Một **GitHub PAT** để kéo các image container và tải xuống các artifact (xem [GitHub Token Setup](/vi/agenteye/github-token)) -- Một **cluster Kubernetes chuyên dụng** (xem yêu cầu bên dưới) -- Một **storage bucket** cho sao lưu cơ sở dữ liệu -- **Kết nối mạng**: cổng 443 đến bộ cân bằng tải của cluster +- Một **GitHub PAT** để kéo hình ảnh container và tải xuống các tạo phẩm (xem [enterprise-docs/github-token.md](/vi/agenteye/github-token)) +- Một **Kubernetes cluster chuyên dụng** (xem yêu cầu bên dưới) +- Một **bucket lưu trữ** cho sao lưu cơ sở dữ liệu +- **Kết nối mạng**: port 443 vào load balancer của cluster --- -## Bước 1: Cấp phát Cluster Kubernetes chuyên dụng +## Bước 1: Cấp phát một Kubernetes Cluster Chuyên dụng -Tạo một cluster Kubernetes dành riêng cho AgentEye. Nó không nên được chia sẻ với các khối công việc khác, vì vậy toàn bộ nền tảng (dịch vụ ứng dụng, cơ sở dữ liệu, phân tích và bộ nhớ đệm) chạy trong sự cô lập mà không ảnh hưởng đến cơ sở hạ tầng hiện có của bạn. +Tạo một Kubernetes cluster chuyên dụng cho AgentEye. Nó không nên được chia sẻ với các workload khác, vì vậy toàn bộ nền tảng (các dịch vụ ứng dụng, cơ sở dữ liệu, phân tích và bộ nhớ đệm) chạy cách ly mà không ảnh hưởng đến hạ tầng hiện có của bạn. | Yêu cầu | Chi tiết | |---|---| -| **Phân phối** | Bất kỳ Kubernetes nào tuân thủ: EKS, GKE, AKS hoặc tự quản lý | +| **Distribution** | Bất kỳ Kubernetes phù hợp: EKS, GKE, AKS hoặc tự quản lý | | **Phiên bản** | 1.27 hoặc mới hơn | -| **Nhóm nút** | Tối thiểu: **3 nút, 4 vCPU / 8 GB RAM mỗi cái** (các instance mục đích chung tiêu chuẩn) | -| **Lưu trữ** | StorageClass mặc định cấp phát các khối lượng khối (ví dụ: `gp3` trên AWS, `pd-ssd` trên GCP) | -| **Bộ cân bằng tải** | Cluster phải có khả năng cấp phát các dịch vụ LoadBalancer trên đám mây (mặc định trên EKS, GKE, AKS) | +| **Node pool** | Tối thiểu: **3 nút, 4 vCPU / 8 GB RAM mỗi nút** (các instance có mục đích chung tiêu chuẩn) | +| **Lưu trữ** | Một StorageClass mặc định cung cấp khối lượng (ví dụ `gp3` trên AWS, `pd-ssd` trên GCP) | +| **Load Balancer** | Cluster phải có khả năng cung cấp các dịch vụ LoadBalancer cloud (mặc định trên EKS, GKE, AKS) | > Exosphere cài đặt và quản lý mọi thứ khác bên trong cluster: bộ điều khiển ingress, chứng chỉ TLS, cơ sở dữ liệu, bộ nhớ đệm, giám sát và tất cả các triển khai ứng dụng. @@ -38,135 +37,135 @@ Tạo một cluster Kubernetes dành riêng cho AgentEye. Nó không nên đư ## Bước 2: Cấp quyền truy cập cho Nhóm AgentEye -Exosphere cần quyền truy cập cluster-admin (hoặc RBAC rộng tương đương) để quản lý các không gian tên, định nghĩa tài nguyên tùy chỉnh, bộ điều khiển ingress và các nhà cung cấp lưu trữ. +Exosphere cần quyền cluster-admin (hoặc RBAC rộng tương đương) để quản lý không gian tên, định nghĩa tài nguyên tùy chỉnh, bộ điều khiển ingress và những người cấp phát lưu trữ. | Yêu cầu | Chi tiết | |---|---| -| **Phương pháp truy cập** | IAM role (ưu tiên cho EKS/GKE), kubeconfig hoặc truy cập dựa trên SSO | -| **VPN / bastion** | Nếu máy chủ API Kubernetes là riêng tư, cung cấp thông tin đăng nhập VPN hoặc truy cập bastion cho nhóm hoạt động Exosphere | +| **Phương thức truy cập** | Vai trò IAM (ưa thích cho EKS/GKE), kubeconfig hoặc truy cập dựa trên SSO | +| **VPN / bastion** | Nếu máy chủ API Kubernetes là riêng tư, cung cấp thông tin đăng nhập VPN hoặc truy cập bastion cho nhóm vận hành Exosphere | --- -## Bước 3: Định cấu hình Kết nối mạng +## Bước 3: Cấu hình Kết nối Mạng -Nhóm mạng của bạn cần cho phép lưu lượng đến trên **cổng 443** đến các bộ cân bằng tải của cluster. Triển khai chạy hai bộ cân bằng tải riêng biệt: một cho việc nhập sự kiện (bảo vệ bằng mTLS) và một cho bảng điều khiển: +Nhóm mạng của bạn cần cho phép lưu lượng vào trên **port 443** đến các load balancer của cluster. Triển khai chạy hai load balancer riêng biệt: một cho việc nhập sự kiện (được bảo vệ bằng mTLS) và một cho bảng điều khiển: | Lưu lượng | Nguồn | Đích | Bảo mật | |---|---|---|---| -| **Nhập sự kiện** | Pod bộ sưu tập trong các cluster của bạn | Ingress LoadBalancer, cổng 443 | mTLS (chứng chỉ máy khách) + khóa API | -| **Bảng điều khiển** | Trình duyệt nhà phát triển | Dashboard LoadBalancer, cổng 443 | HTTPS trên tên miền của bạn, đăng nhập OTP email không mật khẩu | +| **Nhập sự kiện** | Pod collector trong các cluster của bạn | Ingest LoadBalancer, port 443 | mTLS (chứng chỉ khách hàng) + khóa API | +| **Bảng điều khiển** | Trình duyệt nhà phát triển | Dashboard LoadBalancer, port 443 | HTTPS trên miền của bạn, đăng nhập OTP email không mật khẩu | -Điểm cuối nhập được bảo vệ bằng mutual TLS; các bộ sưu tập phải trình bày một chứng chỉ máy khách hợp lệ **và** một khóa API hợp lệ trên mỗi yêu cầu. Bảng điều khiển chạy trên bộ cân bằng tải và tên máy chủ riêng của nó, với quyền truy cập bị hạn chế đối với các địa chỉ/tên miền email được phép. +Điểm cuối ingestion được bảo vệ bằng TLS lẫn nhau; collector phải trình bày một chứng chỉ khách hàng hợp lệ **và** một khóa API hợp lệ trên mỗi yêu cầu. Bảng điều khiển chạy trên load balancer và tên máy chủ riêng của nó, với đăng nhập hạn chế trong các địa chỉ/miền email của bạn được cho phép. -**Bản ghi DNS (một lần):** bạn tạo hai bản ghi CNAME trong một tên miền mà bạn kiểm soát - một cho điểm cuối nhập và một cho bảng điều khiển (ví dụ: `agenteye.your-company.example`) - trỏ đến các tên máy chủ bộ cân bằng tải mà Exosphere cung cấp. Exosphere sau đó cấp phát tự động các chứng chỉ TLS được tin cậy công khai cho cả hai tên máy chủ, bao gồm cả các lần gia hạn. +**Bản ghi DNS (một lần):** bạn tạo hai bản ghi CNAME dưới một miền bạn kiểm soát — một cho điểm cuối ingestion và một cho bảng điều khiển (ví dụ `agenteye.your-company.example`) — trỏ đến các tên máy chủ load balancer mà Exosphere cung cấp. Exosphere sau đó tự động cấp phát chứng chỉ TLS được tin tưởng công cộng cho cả hai tên máy chủ, bao gồm cả việc gia hạn. -> **Ghi chú cổng 80:** cấp phát chứng chỉ tự động và gia hạn xác thực qua HTTP trên cổng 80 của mỗi bộ cân bằng tải. Nếu tư thế bảo mật của bạn yêu cầu hạn chế bộ cân bằng tải bảng điều khiển đối với các dải IP công ty, hãy cho Exosphere biết trước - chúng tôi chuyển xác thực chứng chỉ thành phương pháp dựa trên DNS (một bản ghi DNS bổ sung ở phía bạn) để các lần gia hạn tiếp tục hoạt động phía sau hạn chế. +> **Ghi chú Port 80:** xác thực cấp phát chứng chỉ tự động và gia hạn xác thực qua HTTP trên port 80 của mỗi load balancer. Nếu tư thế bảo mật của bạn yêu cầu hạn chế load balancer bảng điều khiển trong các phạm vi IP công ty, hãy cho Exosphere biết trước — chúng tôi chuyển xác thực chứng chỉ sang phương pháp dựa trên DNS (một bản ghi DNS bổ sung trên phía bạn) vì vậy việc gia hạn tiếp tục hoạt động đằng sau hạn chế. -> **Đi ra ngoài:** Các nút cluster cần quyền truy cập internet để kéo các image container từ `ghcr.io`. Nếu mạng của bạn hạn chế lưu lượng đi ra, hãy cho phép `ghcr.io` hoặc sao gương các image đến sổ đăng ký nội bộ của bạn. +> **Đi ra ngoài:** Các nút Cluster cần quyền truy cập internet để kéo hình ảnh container từ `ghcr.io`. Nếu mạng của bạn hạn chế lưu lượng đi ra, hãy danh sách trắng `ghcr.io` hoặc sao chép hình ảnh vào sổ đăng ký nội bộ của bạn. --- -## Bước 4: Cung cấp Bucket Lưu trữ Sao lưu +## Bước 4: Cung cấp một Bucket Lưu trữ Sao lưu Sao lưu cơ sở dữ liệu được lưu trữ trong một bucket lưu trữ đám mây mà bạn sở hữu. | Yêu cầu | Chi tiết | |---|---| | **Dịch vụ** | S3 (AWS), GCS (GCP) hoặc Azure Blob Storage | -| **Truy cập** | Cấp quyền truy cập ghi cho các nút cluster thông qua IAM role cho các tài khoản dịch vụ (IRSA trên EKS, Workload Identity trên GKE) hoặc cung cấp thông tin đăng nhập | -| **Giữ lại** | Bạn kiểm soát chính sách vòng đời của bucket (khoảng thời gian giữ lại, quy tắc lưu trữ). Exosphere ghi sao lưu; bạn quyết định thời gian giữ chúng | +| **Truy cập** | Cấp quyền ghi cho các nút của cluster thông qua vai trò IAM cho các tài khoản dịch vụ (IRSA trên EKS, Workload Identity trên GKE) hoặc cung cấp thông tin xác thực | +| **Giữ lại** | Bạn kiểm soát chính sách vòng đời của bucket (thời gian giữ lại, quy tắc lưu trữ). Exosphere ghi sao lưu; bạn quyết định thời gian giữ lại chúng | Một sao lưu hàng ngày duy nhất xả cả PostgreSQL (trạng thái quan hệ) và ClickHouse (sự kiện và đánh giá) vào một kho lưu trữ nén và tải nó lên bucket của bạn. Sao lưu cũng chạy trước mỗi lần nâng cấp. --- -## Bước 5: Chỉ định một Người liên hệ +## Bước 5: Chỉ định một Điểm Liên hệ -Cung cấp một người hoặc kênh Slack/Teams ở phía bạn cho các vấn đề cấp cluster: sức khỏe nút, giới hạn tài khoản đám mây, các thay đổi mạng. Hoạt động hàng ngày không liên quan đến liên hệ này. +Cung cấp một người hoặc kênh Slack/Teams trên phía bạn cho các vấn đề cấp cluster: sức khỏe nút, giới hạn tài khoản đám mây, thay đổi mạng. Hoạt động hàng ngày không liên quan đến liên hệ này. --- -## Những gì chúng tôi triển khai +## Những Gì Chúng Tôi Triển Khai -Khi Exosphere có quyền truy cập cluster, các thành phần sau sẽ được triển khai và quản lý cho bạn: +Khi Exosphere có quyền truy cập cluster, các thành phần sau được triển khai và quản lý cho bạn: | Thành phần | Vai trò | |---|---| -| **AgentEye Server** | API HTTP nhận các sự kiện từ các bộ sưu tập, chạy phân tích và cung cấp dữ liệu cho bảng điều khiển | -| **Bảng điều khiển** | Giao diện web để xem các phiên làm việc của agent, lệnh gọi công cụ, yêu cầu mô hình và lỗi; lưu trữ trợ lý AI chỉ đọc tùy chọn | -| **ClickHouse** | Kho dữ liệu chính yêu cầu cho các sự kiện, phân tích và đánh giá được nhập | -| **PostgreSQL** | Kho dữ liệu quan hệ cho các tổ chức, khóa API, người dùng, bảng điều khiển và các truy vấn đã lưu | -| **Redis** | Bộ nhớ đệm dùng chung tùy chọn và phần phụ trợ giới hạn tốc độ; nền tảng giảm độ che phủ một cách khoan dung nếu nó không khả dụng | -| **Trợ lý AI (tùy chọn)** | Thùng chứa trợ lý chỉ đọc nội bộ; giữ bị vô hiệu cho đến khi một điểm cuối LLM được định cấu hình | -| **Bộ điều khiển ingress** | Hai bộ cân bằng tải (một cho nhập được bảo vệ bằng mTLS, một cho bảng điều khiển) kết thúc TLS với chứng chỉ được tin cậy công khai, tự gia hạn và thực thi mTLS trên điểm cuối nhập | -| **cert-manager** | Tự động hóa cấp phát chứng chỉ TLS và cấp phát chứng chỉ máy khách mTLS | -| **Giám sát chứng chỉ** | Một công việc lên lịch kiểm tra hết hạn chứng chỉ và gửi cảnh báo (ví dụ: tới Slack) khi các chứng chỉ gần gia hạn | - -Việc cung cấp được quản lý cũng vận hành quy trình đánh giá của nền tảng, điều này đánh giá hoạt động của agent theo tiêu chí đánh giá của bạn. Xem [Assistant](/vi/agenteye/assistant) và [Evaluation Suite](/vi/agenteye/evaluation-suite) để biết những khả năng này cung cấp gì. +| **AgentEye Server** | HTTP API nhận các sự kiện từ collector, chạy phân tích và phục vụ dữ liệu cho bảng điều khiển | +| **Bảng điều khiển** | Giao diện web để xem các phiên agent, lệnh gọi công cụ, yêu cầu mô hình và lỗi; lưu trữ trợ lý AI chỉ đọc tùy chọn | +| **ClickHouse** | Kho lưu trữ chính cần thiết cho sự kiện được nhập, phân tích và đánh giá | +| **PostgreSQL** | Kho lưu trữ quan hệ cho các tổ chức, khóa API, người dùng, bảng điều khiển và truy vấn đã lưu | +| **Redis** | Bộ nhớ đệm được chia sẻ tùy chọn và phía sau giới hạn tốc độ; nền tảng giảm độ lành mạnh nếu nó không khả dụng | +| **Trợ lý AI (tùy chọn)** | Container trợ lý chỉ đọc nội bộ; ở trạng thái vô hiệu cho đến khi một điểm cuối LLM được cấu hình | +| **Bộ điều khiển Ingress** | Hai load balancer (một cho ingestion được bảo vệ bằng mTLS, một cho bảng điều khiển) chấm dứt TLS với chứng chỉ được tin tưởng công cộng, tự động gia hạn và thực thi mTLS trên điểm cuối ingestion | +| **cert-manager** | Tự động hóa cấp phát chứng chỉ TLS và phát hành chứng chỉ khách hàng mTLS | +| **Giám sát chứng chỉ** | Một công việc được lên lịch kiểm tra hạn sử dụng chứng chỉ và gửi cảnh báo (ví dụ đến Slack) khi chứng chỉ tiếp cận gia hạn | + +Sản phẩm được quản lý cũng vận hành đường ống đánh giá của nền tảng, nó tính điểm hoạt động của agent dựa trên tiêu chí đánh giá của bạn. Xem [enterprise-docs/assistant.md](/vi/agenteye/assistant) và [enterprise-docs/evaluation-suite.md](/vi/agenteye/evaluation-suite) để biết những khả năng này mang lại gì. --- -## Những gì chúng tôi cung cấp cho bạn +## Những Gì Chúng Tôi Cung cấp cho Bạn -Sau khi triển khai hoàn tất, bạn sẽ nhận được: +Sau khi triển khai hoàn tất, bạn nhận được: | Mục | Chi tiết | |---|---| -| **URL bảng điều khiển** | Một tên máy chủ dưới tên miền của bạn (ví dụ: `https://agenteye.your-company.example`), được cung cấp với chứng chỉ TLS được tin cậy công khai, tự gia hạn. Bạn tạo một CNAME đến tên máy chủ bộ cân bằng tải mà chúng tôi cung cấp; đăng nhập là OTP email không mật khẩu | -| **Điểm cuối bộ sưu tập** | Đường dẫn `/events` của tên máy chủ nhập (ví dụ: `https://ingest.your-company.example/events`), được bảo vệ bằng mTLS | -| **Gói chứng chỉ máy khách** | Mỗi cluster: chứng chỉ máy khách, khóa riêng và chứng chỉ CA được cung cấp dưới dạng kê khai Secret của Kubernetes. Áp dụng nó một lần cho mỗi cluster | -| **GitHub PAT** | Để tải xuống các tệp nhị phân bộ sưu tập và các gói Python SDK | -| **Khóa API bộ sưu tập** | Các khóa được giới hạn phạm vi với quyền `events:add`, một cho mỗi triển khai bộ sưu tập | -| **Hướng dẫn cài đặt** | Tài liệu từng bước cho bộ sưu tập và Python SDK | +| **URL Bảng điều khiển** | Một tên máy chủ dưới miền của bạn (ví dụ `https://agenteye.your-company.example`), được phục vụ với chứng chỉ TLS được tin tưởng công cộng, tự động gia hạn. Bạn tạo một CNAME đến tên máy chủ load balancer mà chúng tôi cung cấp; đăng nhập là email OTP không mật khẩu | +| **Điểm cuối Collector** | Đường dẫn `/events` của tên máy chủ ingestion (ví dụ `https://ingest.your-company.example/events`), được bảo vệ bằng mTLS | +| **Bó chứng chỉ khách hàng** | Cho mỗi cluster: chứng chỉ khách hàng, khóa riêng và chứng chỉ CA được cung cấp dưới dạng kê khai Kubernetes Secret. Áp dụng nó một lần cho mỗi cluster | +| **GitHub PAT** | Để tải xuống các tệp nhị phân collector và gói Python SDK | +| **Khóa API Collector** | Các khóa được phân loại với quyền `events:add`, một cho mỗi triển khai collector | +| **Hướng dẫn cài đặt** | Tài liệu từng bước cho collector và Python SDK | --- -## Những gì bạn làm sau khi thiết lập +## Những Gì Bạn Làm Sau Khi Thiết lập -Công việc đang diễn ra duy nhất của bạn là trên các máy agent của riêng bạn, không phải cluster AgentEye: +Công việc duy nhất của bạn là trên các máy agent của riêng bạn, không phải cluster AgentEye: -1. **Cài đặt bộ sưu tập** trong mỗi cluster Kubernetes chạy các agent AI: gắn chứng chỉ máy khách và định cấu hình URL điểm cuối và khóa API. Xem [Collector Installation](/vi/agenteye/collector-installation). -2. **Tích hợp Python SDK** vào mã agent của bạn. Xem [Python SDK](/vi/agenteye/python-sdk). +1. **Cài đặt collector** trong mỗi Kubernetes cluster chạy các agent AI: gắn chứng chỉ khách hàng và cấu hình URL điểm cuối và khóa API. Xem [enterprise-docs/collector-installation.md](/vi/agenteye/collector-installation). +2. **Tích hợp Python SDK** vào mã agent của bạn. Xem [enterprise-docs/python-sdk.md](/vi/agenteye/python-sdk). 3. **Mở bảng điều khiển** trong trình duyệt của bạn để xem hoạt động của agent. -Không cần vận hành cluster, không cần quản lý cơ sở dữ liệu, không cần gia hạn chứng chỉ, không cần nâng cấp. +Không vận hành cluster, không quản lý cơ sở dữ liệu, không gia hạn chứng chỉ, không nâng cấp. --- ## Bảo mật -- **Dữ liệu được lưu giữ trong tài khoản đám mây của bạn.** Cluster, lưu trữ và cơ sở dữ liệu đều chạy trong môi trường của bạn. Không có dữ liệu nào rời khỏi ranh giới của bạn. -- **Bạn kiểm soát quyền truy cập.** Cluster nằm trong tài khoản của bạn. Bạn có thể kiểm toán, giám sát hoặc thu hồi quyền truy cập của Exosphere bất cứ lúc nào. Tất cả các hoạt động đi qua nhật ký kiểm toán của đám mây của bạn (CloudTrail, GCP Audit Logs, v.v.). -- **mTLS trên nhập sự kiện.** Mỗi yêu cầu bộ sưu tập yêu cầu cả chứng chỉ máy khách hợp lệ và khóa API. Một khóa bị rò rỉ là vô dụng mà không có chứng chỉ; một chứng chỉ bị đánh cắp là vô dụng mà không có khóa hợp lệ. -- **Kiểm soát truy cập bảng điều khiển.** Bảng điều khiển chạy trên bộ cân bằng tải riêng, riêng biệt từ nhập sự kiện, và đăng nhập là OTP email không mật khẩu được hạn chế đối với các địa chỉ/tên miền email được phép. Danh sách cho phép dải nguồn IP trên bộ cân bằng tải có sẵn khi yêu cầu; vì gia hạn chứng chỉ tự động phải tiếp cận bộ cân bằng tải, Exosphere ghép hạn chế với xác thực chứng chỉ dựa trên DNS để các lần gia hạn tiếp tục hoạt động. -- **Chứng chỉ cho mỗi cluster.** Mỗi cluster của bạn nhận chứng chỉ máy khách của riêng nó. Nếu một cluster bị xâm phạm, chứng chỉ đó sẽ bị thu hồi độc lập mà không ảnh hưởng đến những chứng chỉ khác. +- **Dữ liệu nằm trong tài khoản cloud của bạn.** Cluster, lưu trữ và cơ sở dữ liệu đều chạy trong môi trường của bạn. Không có dữ liệu nào rời khỏi ranh giới của bạn. +- **Bạn kiểm soát quyền truy cập.** Cluster ở trong tài khoản của bạn. Bạn có thể kiểm toán, giám sát hoặc thu hồi quyền truy cập của Exosphere bất cứ lúc nào. Tất cả các hoạt động đều thông qua nhật ký kiểm toán của cloud của bạn (CloudTrail, GCP Audit Logs, v.v.). +- **mTLS trên ingestion sự kiện.** Mỗi yêu cầu collector yêu cầu cả chứng chỉ khách hàng hợp lệ và khóa API. Một khóa bị rò rỉ là vô dụng mà không có chứng chỉ; một chứng chỉ bị đánh cắp là vô dụng mà không có một khóa hợp lệ. +- **Kiểm soát truy cập bảng điều khiển.** Bảng điều khiển chạy trên load balancer riêng, tách biệt khỏi ingestion sự kiện, và đăng nhập là email OTP không mật khẩu hạn chế đối với các địa chỉ/miền email bạn cho phép. Danh sách cho phép phạm vi nguồn IP trên load balancer có sẵn theo yêu cầu; vì gia hạn chứng chỉ tự động phải tiếp cận load balancer, Exosphere kết hợp hạn chế với xác thực chứng chỉ dựa trên DNS để việc gia hạn tiếp tục hoạt động. +- **Chứng chỉ theo cluster.** Mỗi cluster của bạn nhận chứng chỉ khách hàng của riêng nó. Nếu một cluster bị xâm phạm, chứng chỉ đó bị thu hồi độc lập mà không ảnh hưởng đến các chứng chỉ khác. --- -## Lịch trình triển khai +## Lịch trình Triển khai | Giai đoạn | Thời lượng | Sự tham gia của bạn | |---|---|---| -| **Cấp phát cluster** | 1-2 ngày | Cấp phát cluster và cấp quyền truy cập cho Exosphere | +| **Cấp phát Cluster** | 1-2 ngày | Cấp phát cluster và cấp quyền truy cập cho Exosphere | | **Thiết lập nền tảng** | 1 ngày | Không có; Exosphere cài đặt tất cả các thành phần cơ sở hạ tầng | | **Triển khai ứng dụng** | 1 ngày | Không có; Exosphere triển khai máy chủ, bảng điều khiển và tạo khóa API | -| **Triển khai bộ sưu tập** | 1-3 ngày | Cài đặt các bộ sưu tập trong các cluster của bạn (với hướng dẫn từ Exosphere) | -| **Chạy sản xuất** | 1 tuần | Không có; Exosphere giám sát và điều chỉnh | +| **Triển khai Collector** | 1-3 ngày | Cài đặt collector trong các cluster của bạn (có hướng dẫn từ Exosphere) | +| **Burn-in sản xuất** | 1 tuần | Không có; Exosphere giám sát và điều chỉnh | -Tổng cộng thường xuyên: **~2 tuần** từ khởi động đến sẵn sàng sản xuất. +Tổng cộng điển hình: **~2 tuần** từ khởi động đến sẵn sàng sản xuất. --- ## Hỗ trợ -Đối với các câu hỏi hoặc vấn đề, hãy liên hệ với Exosphere tại `support@exosphere.host`. +Để có câu hỏi hoặc vấn đề, liên hệ Exosphere tại `support@exosphere.host`. --- ## Các bước tiếp theo -- [Getting Started](/vi/agenteye/getting-started): hướng dẫn toàn bộ -- [Collector Installation](/vi/agenteye/collector-installation): cài đặt và định cấu hình bộ sưu tập -- [Python SDK](/vi/agenteye/python-sdk): công cụ code agent của bạn -- [API Keys](/vi/agenteye/api-keys): quản lý quyền truy cập và quyền -- [Troubleshooting](/vi/agenteye/troubleshooting): các vấn đề chung và cách khắc phục \ No newline at end of file +- [Bắt đầu](/vi/agenteye/getting-started): hướng dẫn end-to-end +- [Cài đặt Collector](/vi/agenteye/collector-installation): cài đặt và cấu hình collector +- [Python SDK](/vi/agenteye/python-sdk): hỗ trợ mã agent của bạn +- [Khóa API](/vi/agenteye/api-keys): quản lý quyền truy cập và quyền +- [Xử lý sự cố](/vi/agenteye/troubleshooting): các vấn đề thường gặp và cách khắc phục \ No newline at end of file diff --git a/docs/zh/agenteye/audits.mdx b/docs/zh/agenteye/audits.mdx index 1beaf9e6..2658427f 100644 --- a/docs/zh/agenteye/audits.mdx +++ b/docs/zh/agenteye/audits.mdx @@ -1,107 +1,106 @@ --- -title: "Audits — 智能改进检测" -description: "AgentEye Audits — 智能改进检测文档。" +title: "审计 — 智能体改进检测" +description: "AgentEye 审计 — 智能体改进检测文档。" --- -Audits 是定期运行的任务，跨会话挖掘 Agent 日志，寻找值得改进的内容。告警监控的是你已知的某个指标（近实时），而 Audit 则是**主动调查**：按你设定的计划，对时间窗口内的数据执行确定性的策略检查，然后让一个 **AI 可靠性 Agent** 对你的会话展开深入分析——该 Agent 自主查询数据、阅读可疑会话记录，必要时运行小型分析脚本，最终输出附有证据支撑的**改进建议**。 +审计是一种周期性任务，它会**跨会话**挖掘您的智能体日志，寻找值得改进的内容。告警负责近实时监控您已知的某个指标，而审计则负责**深度调查**：按照您设定的计划，在时间窗口内执行一次确定性策略扫描，然后让一个 **AI 可靠性智能体**对您的会话展开自主分析——该智能体会自行查询数据、阅读可疑转录记录，必要时运行小型分析脚本，最终输出带有证据支撑的**改进建议**。 -用 Audits 回答「我的 Agent 该修什么、怎么改进」，用告警在某个具体阈值被突破的瞬间收到通知。每条改进建议都链接到背后的具体会话和查询，一键即可创建预填好的告警，防止问题复发。 +使用审计来回答"我应该修复或改进智能体的哪些方面"，使用告警来在某个特定阈值被触发时立即收到通知。每条改进建议都链接到其背后的具体会话和查询，一键即可创建预填好的告警，以便捕获问题复发。 -仪表板入口为 **`//audits`**（侧边栏 → *analyze* → *audits*），需要 `audits:read` / `audits:write` 权限。 +仪表板入口为 **`//audits`**（侧边栏 → *分析* → *审计*），需要 `audits:read` / `audits:write` 权限。 --- -## 一次运行的工作原理 +## 运行机制 -每次运行包含两个层次——确定性的基础层和智能调查层。 +每次运行分为两层——确定性基础层和智能体调查层。 -### 1. 策略检查（确定性） +### 1. 策略扫描（确定性） -在任何模型运行之前，Audit 会对时间窗口内的数据执行一批**SQL 策略检查**：有界的聚合查询，用于标记已知的问题模式，并报告有*多少*事件/*哪些*会话命中——但从不暴露命中的原始文本。检查目录包括： +在任何模型运行之前，审计会在时间窗口内执行一组 **SQL 策略检查**：有界的聚合查询，用于标记已知的异常模式，并报告匹配的事件数量和会话列表——但不会返回匹配的具体文本内容。该检查目录包括： -- **事件载荷中的密钥/凭据泄漏** — AWS 访问密钥、`sk-…` 格式的 API 密钥、PEM 私钥、JWT / Bearer Token，以及 `KEY=…` 形式的凭据赋值。 -- **提示注入标记** — 「ignore previous instructions」「reveal your system prompt」等类似语句。 -- **PII** — 符合 SSN 格式的数字（启发式匹配）。 +- 事件负载中的**密钥 / 凭证泄露** — AWS 访问密钥、`sk-…` 格式的 API 密钥、PEM 私钥、JWT / Bearer Token，以及 `KEY=…` 格式的凭证赋值。 +- **提示词注入标记** — "ignore previous instructions"、"reveal your system prompt" 等类似内容。 +- **PII** — 符合 SSN 格式的数字（启发式识别）。 - **工具权限拒绝**和**工具调用失控循环**。 -策略命中结果作为 findings（类型为 `policy`）持久化保存，**始终展示**（不受每次运行上限的限制），并作为初始线索交给 AI Agent。由于该层无需任何模型，即使 AI Agent 不可用，Audit 仍能产出最重要的安全信号。 +策略命中的结果会以 `policy` 类型的发现持久化，**始终显示**（不受单次运行上限限制），并作为线索提供给 AI 智能体。由于该层不依赖模型，即使 AI 智能体不可用，审计仍能输出最重要的安全信号。 -### 2. 智能调查（AI） +### 2. 智能体调查（AI） -Audit 随后运行一个**自主可靠性 Agent**（与仪表板助手同款的 Claude Agent SDK 服务，但使用针对 Audit 的专用提示词）。Agent 根据 Audit 的**范围**（选定的 Agent × 环境）和**时间窗口**，执行以下操作： +审计随后运行一个**自主可靠性智能体**（与驱动仪表板助手的 Claude Agent SDK 服务相同，但使用审计专用提示词）。根据审计的**范围**（所选智能体 × 环境）和**时间窗口**，该智能体会： -- 对你的分析表执行只读 SQL 查询； -- 阅读少量具有代表性的会话记录； -- 可选地在**隔离的 Pod 内沙箱**（无网络、无文件系统访问、密钥已清除）中编写并运行短小的 **Python 脚本**，处理 SQL 难以表达的分析任务——错误聚类、计算分布、对已抓取的载荷进行扫描； -- 记录每一条有充分证据支撑的**改进建议**。 +- 对您的分析表执行只读 SQL 查询， +- 阅读少量具有代表性的会话转录记录， +- 可选地在**隔离的 Pod 内沙箱**（无网络、无文件系统访问权限、密钥已清除）中编写并运行短小的 **Python 脚本**，用于 SQL 无法直接表达的分析——如聚类错误、计算分布、扫描已获取的负载， +- 并记录其发现的每条有充分证据支撑的**改进建议**。 -Agent 从多条调查线索切入——错误聚类、与基线的偏差、会话记录中的目标失败、工具误用、质量/成本权衡、以及覆盖盲点——深度由 Audit 的**灵敏度**（低 / 中 / 高）决定。每条改进建议**必须引用证据**：Agent 实际检查过的会话 ID 和/或执行过的 SQL。服务器会验证所引用的会话确实存在，并**丢弃所有没有有效证据的改进建议**——Agent 只做调查，不做杜撰。 +智能体会沿多条调查路线展开工作——错误聚类、相对基线的漂移、转录记录中的目标失败、工具误用、质量/成本权衡以及覆盖缺口——调查深度由审计的**灵敏度**（低 / 中 / 高）决定。每条改进建议**必须引用证据**：智能体实际检查过的会话 ID 和/或其运行过的 SQL。服务器会验证引用的会话是否存在，**并丢弃任何无有效证据的改进建议**，因此智能体只负责调查，而不会凭空捏造。 -每条改进建议包含： +每条改进建议包含以下内容： -- **建议**（具体的改进措施——调整提示词、修复工具 schema、调整重试策略、添加护栏、补充评估覆盖）； -- **预期影响**和**工作量**估算（低 / 中 / 高）； -- **重要程度** — `big`（需要立即通知运营人员）、`medium`（纳入本次运行报告）、`small`（仅作为仪表板上下文信息）； -- 一个稳定的**指纹**（由问题的类别 + 范围生成，*而非*本次运行的会话），使同一问题在多次运行间可持续追踪，即使证据在变化； -- 以及，若某个简单的确定性监控器即可捕捉复发，则附带一条**建议告警**，一键即可创建。 +- **建议措施**（具体的改进行动——提示词调整、工具 Schema 修复、重试策略、防护措施、更多评估覆盖）， +- **预期影响**和**工作量**估算（低 / 中 / 高）， +- **严重程度** — `big`（需要通知运维人员）、`medium`（应出现在运行报告中）或 `small`（仅作仪表板上下文）， +- 稳定的**指纹**（基于问题的类别和范围，而非本次运行的会话），使得同一问题可在跨运行中持续追踪，即便证据发生变化， +- 以及针对可通过简单确定性监控捕获复发情况的问题，提供**建议告警**，一键即可创建。 -> **AI 层是可选但推荐的。** 如果 Audit 流水线未配置 AI Agent，运行仍会执行并持久化策略 findings，并在智能层诚实报告「分析不可用」，而非悄然通过。 +> **AI 层为可选但推荐启用。** 如果审计管道未配置 AI 智能体，运行仍会正常执行，持久化策略发现，并如实报告智能体层"分析不可用"，而不是静默通过。 ### 失败模式 -改进建议会归类到你的组织持久化的**失败模式目录**中（或提议新增一种模式）。失败模式为跨运行的模式提供稳定的身份标识，支持长周期的复发追踪。 +改进建议会归类到您组织的持久化**失败模式目录**中（或提议创建新模式）。失败模式为各类问题模式提供了跨运行的稳定标识和长期复发追踪能力。 ## 分类处理生命周期 -在 finding 详情页（`/audits//findings/`）： +在发现详情页（`/audits//findings/`）： | 操作 | 效果 | |---|---| -| **acknowledge（确认）** | 保持 finding 可见，但将其优先级降低一半。 | -| **resolve（解决）** | 标记为已修复。若该模式后来真正复现，会以**新**的状态重新打开——回归问题会被明确提示，而不会悄然折叠进历史记录。 | -| **mute（静音）** / **dismiss（忽略）** | 持久性抑制：记住该模式的指纹，即使跨多次运行也不再展示。mute 用于「已知、已接受」；dismiss 用于「无参考价值」。 | -| **reopen（重新打开）** | 清除抑制/解决状态，重新对该模式排列优先级。 | -| **assign（指派）** | 将 finding 路由给某位运营人员（组织成员）负责跟进，优先级和抑制状态不变。 | +| **确认（acknowledge）** | 保持发现可见，但将其优先级降低一半。 | +| **解决（resolve）** | 标记为已修复。如果该模式后来确实复现，将以**新发现**的形式重新打开——确保回归问题醒目呈现，而非悄悄归入历史记录。 | +| **静音（mute）/ 忽略（dismiss）** | 持久化抑制：该模式的指纹将被记录，此后不再出现，即使跨运行也不例外。静音用于"已知且已接受"的情况，忽略用于"无参考价值"的情况。 | +| **重新打开（reopen）** | 清除抑制 / 解决状态，重新参与排名。 | -低信噪比的噪声通过每次运行的 findings 上限（`top_k`）在每个 Audit 中单独控制，仅限制智能层的改进建议。策略 findings 不受上限约束（与安全相关，始终展示）。被上限截断的内容会计入本次运行的统计数据——没有任何内容被悄然丢弃。 +低价值噪音通过每次审计的单次运行发现上限（`top_k`）进行控制，该上限仅作用于智能体改进建议。策略发现不受此上限限制（属于安全相关内容，始终显示）。被上限截断的内容会计入运行统计数据——不会有任何结果被静默丢弃。 -## 调度 +## 调度设置 -- **频率**（`schedule_interval_secs`）：从每小时到每周；**默认为每天**。Audits 的粒度刻意粗于告警——智能调查需要扫描完整时间窗口，运行时间长达数分钟。 -- **时间窗口**：固定滚动回溯（如「每次运行扫描过去 7 天」）或**自上次运行起**（默认）——每次运行从上一次成功运行结束的地方续接，并保留少量重叠，确保边界事件不被遗漏。 -- 下一次运行在上一次运行**完成**后整整一个间隔后才会调度，因此慢速运行不会导致同一个 Audit 堆叠出第二个并发运行。 -- Audit 页面上的 **Run now** 可立即触发运行。 +- **频率**（`schedule_interval_secs`）：从每小时到每周不等；**默认为每天一次**。审计刻意比告警粗粒度——智能体调查需要扫描完整时间窗口，运行时间可达数分钟。 +- **时间窗口**：固定的滚动回溯周期（例如"每次运行扫描过去 7 天"）或**从上次运行以来**（默认）——每次运行从上一次成功运行结束的位置继续，并保留少量重叠以确保边界事件不被遗漏。 +- 下次运行在上次运行**完成**后整整一个间隔再调度，因此慢速运行不会触发同一审计的并发运行。 +- 在审计页面点击**立即运行**可使其立即执行。 ## 模型选择 -创建 Audit 时，可以从**运营人员为 Agent 服务配置的模型列表**中选择调查使用的模型。只配置了一个模型时，选择器以标题形式展示；配置了多个时，可手动选择。留空则使用已配置的默认模型。 +创建审计时，您可以从**运维人员为智能体服务配置的模型列表**中选择调查所用的模型。若仅配置了单个模型，选择器会以说明文字的形式显示；若配置了多个，则由您自行选择。不选则使用配置的默认值。 ## 通知 -运行产出**新的** findings 时，Audit 会通过你的组织已配置的渠道发送通知——与告警流水线使用相同的 `alerts.enabled_channels` 门控和配置： +当运行发现**新的**问题时，审计会通知您组织配置的渠道——使用与告警管道相同的 `alerts.enabled_channels` 开关和设置： -- **Slack** — 汇总重要（`big`）的新条目，并附带深层链接。 -- **Email** — 一份精心排版的 **Audit 报告**，列出新的改进建议（按严重程度排序、每条附带建议、附深层链接），在 Audit 配置了 **email** 渠道且至少有一条新 finding 时发送。 +- **Slack** — 发送一条包含重要（`big`）新问题摘要及深链接的消息。 +- **Email** — 发送精心排版的**审计报告**，列出新的改进建议（按严重程度排序、含逐条建议及深链接），前提是审计已绑定 **email** 渠道，且至少存在一条新发现。 -反复出现但已知的 findings 不会重复通知。 +已知的重复性发现不会重复通知。 ## 配置参考 -Audit 定义可在仪表板（`/audits/new`）或通过 API 管理。每个 Audit 的配置项包括：调度频率和时间窗口、范围（`{"environments": [...], "agent_ids": [...]}`）、灵敏度（`low` / `medium` / `high`）、通知渠道、每次运行的 findings 上限（`top_k`），以及模型（通过 `llm_budget.model`）。运营人员级别的服务器配置（超时、沙箱、Agent 服务 URL）详见 [deployment.md](/zh/agenteye/deployment)。 +审计定义可在仪表板（`/audits/new`）或通过 API 进行管理。每个审计的可配置项包括：调度频率和时间窗口、范围（`{"environments": [...], "agent_ids": [...]}`）、灵敏度（`low` / `medium` / `high`）、通知渠道、单次运行发现上限（`top_k`），以及模型（通过 `llm_budget.model` 指定）。运维层面的服务器设置（超时、沙箱、智能体服务 URL）请参阅 [deployment.md](/zh/agenteye/deployment)。 ## API -所有端点均以组织为作用域，使用标准 Bearer 密钥认证（参见 [api-keys.md](/zh/agenteye/api-keys)）。 +所有端点均以组织为范围，并遵循标准 Bearer 密钥认证（参见 [api-keys.md](/zh/agenteye/api-keys)）。 | 端点 | 权限 | 用途 | |---|---|---| -| `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | 列出 / 创建 Audit 定义。 | -| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | 查看、编辑、删除某个 Audit。 | -| `POST /audits/:id/run` | `audits:write` | 立即触发该 Audit 运行。 | -| `GET /audits/:id/runs` | `audits:read` | 运行历史（时间窗口、状态、统计数据、findings 数量）。 | -| `GET /audits/findings` | `audits:read` | 组织范围内的 findings，可按 `audit_id`、`status` 筛选，按优先级排序。 | -| `GET /audits/findings/:fid` | `audits:read` | Finding 完整详情（建议、证据、优先级）。 | +| `GET /audits` · `POST /audits` | `audits:read` / `audits:write` | 列出 / 创建审计定义。 | +| `GET` / `PUT` / `DELETE /audits/:id` | read / write / write | 查看、编辑、删除审计。 | +| `POST /audits/:id/run` | `audits:write` | 使审计立即执行。 | +| `GET /audits/:id/runs` | `audits:read` | 运行历史（时间窗口、状态、统计数据、发现数量）。 | +| `GET /audits/findings` | `audits:read` | 组织范围内的发现，可按 `audit_id`、`status` 筛选；按优先级排序。 | +| `GET /audits/findings/:fid` | `audits:read` | 完整发现详情（建议、证据、优先级）。 | | `POST /audits/findings/:fid/status` | `audits:write` | 分类处理：`{"action": "ack" \| "mute" \| "dismiss" \| "resolve" \| "reopen" \| "assign"}`。 | -关于「Audit 运行但未发现任何内容」「代码沙箱被禁用」「Audit 邮件未送达」等问题，请参见 [troubleshooting.md](/zh/agenteye/troubleshooting#audits)。 \ No newline at end of file +如遇"审计已运行但未发现任何问题"、"代码沙箱已禁用"或"审计邮件未送达"等情况，请参阅 [troubleshooting.md](/zh/agenteye/troubleshooting#audits)。 \ No newline at end of file diff --git a/docs/zh/agenteye/cli-recipes.mdx b/docs/zh/agenteye/cli-recipes.mdx index e06d3a42..d3e4b600 100644 --- a/docs/zh/agenteye/cli-recipes.mdx +++ b/docs/zh/agenteye/cli-recipes.mdx @@ -1,19 +1,19 @@ --- -title: "面向 Agent 的 CLI 使用手册" -description: "AgentEye 面向 Agent 的 CLI 使用手册文档。" +title: "面向 Agent 的 CLI 使用指南" +description: "AgentEye 面向 Agent 的 CLI 使用指南文档。" --- -直接在脚本或编码 Agent 中拉取会话、事件和评估数据（并触发重新评估），输出为 stdout 上干净的 JSON，可直接通过管道传入 `jq`。这些手册将 AgentEye 的可观测性数据转化为终端用户或 AI 编码 Agent（Claude Code、Cursor）可查询和自动化的形式，无需点击仪表板。 +直接在脚本或代码 Agent 中拉取会话、事件和评估数据（并触发重新评估），stdout 输出干净的 JSON，可直接通过管道传给 `jq`。这些示例将 AgentEye 的可观测性数据转化为终端用户或 AI 代码 Agent（Claude Code、Cursor）可查询和自动化处理的形式，无需点击仪表板。 -以下示例均可直接复制粘贴用于 AgentEye CLI（`agenteye`）。安装、认证及完整选项列表，请参阅 [CLI](/zh/agenteye/cli)；运行 `agenteye -h` 或 `agenteye -h` 查看内置帮助。 +以下模式可直接复制粘贴用于 AgentEye CLI（`agenteye`）。有关安装、认证和完整选项列表，请参阅 [CLI](/zh/agenteye/cli)；运行 `agenteye -h` 或 `agenteye -h` 查看内置帮助。 ## 黄金法则 -1. **全局选项必须放在命令*之前*。** `agenteye --json sessions` 是正确的；`agenteye sessions --json` 则不对。全局选项包括 `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet`、`--no-color`。 -2. **解析输出时务必传入 `--json`。** 数据以 JSON 格式输出到 **stdout**；人类可读的状态信息和错误输出到 **stderr**，因此 stdout 保持干净，可直接管道传入 `jq`。 -3. **根据退出码判断结果**，而非 stderr 文本：`0` 成功 · `2` 参数错误 · `3` 无法连接仪表板 · `4` 未登录或会话已过期 · `5` 缺少权限。 -4. **用 `-h` 探索命令。** 每个命令都记录了其过滤器、值格式和 JSON 结构。 +1. **全局选项须放在命令*之前*。** `agenteye --json sessions` 是正确的；`agenteye sessions --json` 是错误的。全局选项包括 `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet`、`--no-color`。 +2. **解析输出时务必传入 `--json`。** 数据以 JSON 格式输出到 **stdout**；人类可读的状态信息和错误信息输出到 **stderr**，因此 stdout 保持干净，可直接通过管道传给 `jq`。 +3. **根据退出码分支，而非 stderr 文本：** `0` 成功 · `2` 参数错误 · `3` 无法连接仪表板 · `4` 未登录或已过期 · `5` 权限不足。 +4. **使用 `-h` 探索命令。** 每个命令都记录了其过滤器、值格式和 JSON 结构。 ## 一次性初始化 @@ -22,13 +22,13 @@ export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # 避免重复输 agenteye login --email you@example.com # 粘贴邮件中的验证码；有效期约 24 小时 ``` -## 执行操作前确认认证状态 +## 在执行操作前确认认证状态 -`whoami` 在会话缺失或已过期时不会报错，而是返回 `logged_in:false`，因此 Agent 可以安全地探测认证状态。（如果未设置 base URL 或仪表板不可达，它仍可能以非零退出码退出。） +`whoami` 在会话缺失或过期时不会报错；它会返回 `logged_in:false`，因此 Agent 可以安全地探测认证状态。（如果未设置 base URL 或仪表板不可达，仍可能以非零退出码退出。） ```bash if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then - echo "未认证。请运行：agenteye login" >&2; exit 1 + echo "Not authenticated. Run: agenteye login" >&2; exit 1 fi ``` @@ -38,35 +38,35 @@ fi # 过去 24 小时内评估出错的会话 agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' -# 某个 Agent 的 helpfulness 评分 <= 0.5 的评估 +# 某个 agent 在 helpfulness 指标上得分 <= 0.5 的评估 agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` -评分过滤在 **`evals`** 上，而非 `sessions`。`--score KEY:MIN..MAX` 可重复使用，多个条件取 AND；任一边界均可省略（`..0.5` 表示 ≤ 0.5，`0.9..` 表示 ≥ 0.9）。每次请求最多可传入 20 个评分过滤条件；超出则返回 HTTP 400。`sessions` 与 `evals` 共享 `--env`、`--status`、`--agent-id`、`--session-id` 及时间范围过滤器，但不支持 `--score`。 +分数过滤在 **`evals`** 上，而非 `sessions`。`--score KEY:MIN..MAX` 可重复使用，多个条件以 AND 组合；两端边界均为可选（`..0.5` 表示 ≤ 0.5，`0.9..` 表示 ≥ 0.9）。每次请求最多可传入 20 个分数过滤器；超出将返回 HTTP 400。`sessions` 与 `evals` 共享 `--env`、`--status`、`--agent-id`、`--session-id` 和时间范围过滤器，但不支持 `--score`。 ## 完整读取一个会话 -没有单独的 `session show` 命令——将事件轨迹与会话评估结合使用： +没有单独的 `session show` 命令——将事件记录与会话评估结合使用： ```bash -# 会话的最新评估（状态 + 评分） +# 会话的最新评估（状态 + 分数） agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' -# 运行中的所有事件（增大 --limit 以获取完整数据） +# 运行中的所有事件（增大 --limit 以获取全部数据） agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' -# 仅获取会话中的工具调用 +# 会话中仅工具调用的事件 agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` -## 获取全部数据（分页） +## 获取所有数据（分页） -结果按最新优先排序，并使用游标分页。 +结果按最新优先排列，使用游标分页。 ```bash -# 一次性获取：以每页 200 条的方式最多获取 500 条数据 +# 一次性获取：以每页 200 条的方式最多获取 500 条记录 agenteye --json events --session-id run-001 --limit 500 --all > events.json # 手动分页：将 next_cursor 传回 @@ -77,39 +77,39 @@ cursor=$(echo "$page" | jq -r '.next_cursor // empty') ## 使用 --fields 精简输出 -限制返回的字段（在表格和 `--json` 模式下均有效），以减少 Agent 需要处理的数据量。 +限制返回的字段（在表格和 `--json` 中均生效），减少 Agent 需要读取的内容。 ```bash agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` -未知字段名会被拒绝（退出码 `2`）并返回有效字段列表，这也是探索字段名的便捷方式。 +未知字段名会被拒绝（退出码 `2`），并列出有效字段，这也是探索字段名的便捷方式。 -## 探索有效的过滤器值 +## 发现有效的过滤器值 ```bash -agenteye --json list envs | jq -r '.values[]' # --env 的可用值 -agenteye --json list tools | jq -r '.values[]' # 工具名称；也可查询 agents、models、event_types 等 +agenteye --json list envs | jq -r '.values[]' # --env 的有效值 +agenteye --json list tools | jq -r '.values[]' # 工具名称；也可查 agents、models、event_types 等 agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX 中有效的 KEY ``` ## 选择组织（多租户） -如果您属于多个组织，可在登录时选择当前租户（该设置会被保存）： +如果你属于多个组织，可在登录时选择当前租户（会被保存）： ```bash -agenteye login --org acme --email you@corp.com # 登录的同时设置租户 +agenteye login --org acme --email you@corp.com # 在登录的同时设置租户 agenteye --json orgs list | jq -r '.orgs[].org_slug' -agenteye --org globex --json sessions --since 24h # 仅对单次命令生效的覆盖 +agenteye --org globex --json sessions --since 24h # 仅对当前命令生效的覆盖 ``` -多组织账户在未指定 `--org` 时会以非零退出码退出，并打印可供选择的组织列表。 +多组织账户在未指定 `--org` 时会以非零退出码退出，并打印可选择的组织列表。 -## 为 SDK/收集器创建 API Key +## 为 SDK/采集器创建 API 密钥 ```bash -# Secret 仅打印一次——使用 --json 时为 .key 字段 +# 密钥仅打印一次——使用 --json 时为 .key 字段 key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # 轮换密钥；使用 agenteye keys disable ci-bot --yes 撤销 ``` @@ -118,7 +118,7 @@ agenteye keys regenerate ci-bot --yes # 轮换密钥；使用 agenteye keys d ```bash agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' -agenteye --json query run errs --arg prod | jq '.rows' # 已保存的查询 + 位置参数 $1 +agenteye --json query run errs --arg prod | jq '.rows' # 已保存的查询 + 一个位置参数 $1 ``` ## 非交互式处理告警事件 @@ -126,11 +126,11 @@ agenteye --json query run errs --arg prod | jq '.rows' # 已保存的查询 + ```bash id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" -agenteye incidents assign "$id" you@corp.com +agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` -> 变更操作在使用 `--json` 或 stdin 不是 TTY 时会自动跳过确认提示，因此 Agent 不会卡住；在其他情况下，可显式传入 `--yes`/`-y` 跳过确认。 +> 在 `--json` 模式下或 stdin 非 TTY 时，变更操作会自动跳过确认提示，因此 Agent 不会挂起；在其他情况下可显式传入 `--yes`/`-y` 跳过确认。 ## 脚本中的退出码处理 @@ -138,16 +138,16 @@ agenteye incidents resolve "$id" --yes out=$(agenteye --json sessions --since 1h) || code=$? case "${code:-0}" in 0) echo "$out" | jq '.sessions | length' ;; - 4) echo "会话已过期，请运行 'agenteye login'。" >&2 ;; - 5) echo "缺少权限（请联系管理员获取 evaluations:read 权限）。" >&2 ;; - 3) echo "仪表板不可达，请检查 URL。" >&2 ;; - *) echo "未知错误（退出码 ${code}）。" >&2 ;; + 4) echo "Session expired - run 'agenteye login'." >&2 ;; + 5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;; + 3) echo "Dashboard unreachable - check the URL." >&2 ;; + *) echo "Unexpected error (exit ${code})." >&2 ;; esac ``` ## JSON 输出结构 -| 命令 | stdout JSON（使用 `--json`） | +| 命令 | stdout JSON（使用 `--json`）| |---|---| | `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` 或 `{"logged_in": false}` | | `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` | @@ -156,15 +156,15 @@ esac | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | -| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}`（`key` 仅显示一次） | +| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}`（`key` 仅显示一次）| | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | -| create/update/delete（任意） | 资源对象，或删除时返回 `{"deleted": true, "id"}` | -| 失败（任意，使用 `--json`） | stdout 输出 `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | +| create/update/delete（任意）| 资源对象，或删除时返回 `{"deleted": true, "id"}` | +| 失败（任意，使用 `--json`）| stdout 输出 `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | -- 每条 **event** 记录（`events`）：`id, session_id, agent_id, event_type, ts, payload, environment`。 -- 每条 **evaluation** 记录（`evals`）：`id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`。 -- 每条 **session** 记录（`sessions`）：`session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`。 +- 每个 **event** 条目（`events`）：`id, session_id, agent_id, event_type, ts, payload, environment`。 +- 每个 **evaluation** 条目（`evals`）：`id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`。 +- 每个 **session** 条目（`sessions`）：`session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`。 -每个命令的 `--fields` 仅接受其自身记录中的字段名——`sessions` 和 `evals` 的字段集不同，因此对一个命令有效的字段名可能会被另一个命令拒绝。 \ No newline at end of file +每个命令的 `--fields` 只接受该命令自身条目的字段名——`sessions` 和 `evals` 的字段集不同，因此对一个命令有效的字段名可能被另一个命令拒绝。 \ No newline at end of file diff --git a/docs/zh/agenteye/deployment.mdx b/docs/zh/agenteye/deployment.mdx index 3d11a537..b6d102d5 100644 --- a/docs/zh/agenteye/deployment.mdx +++ b/docs/zh/agenteye/deployment.mdx @@ -4,42 +4,42 @@ description: "AgentEye 部署文档。" --- -本指南涵盖在生产环境中部署 AgentEye 服务端和控制台的相关内容。 +本指南介绍如何在生产环境中部署 AgentEye 服务器和仪表板。 --- ## 架构概览 ``` - [ AI agent 机器 ] [ 您的基础设施 ] + [ AI 代理机器 ] [ 您的基础设施 ] Python SDK | 写入 JSONL +----------------------+ - v +--->| PostgreSQL 15+ | - agenteye-collector --HTTP--+ | | (关系型存储) | - | | +----------------------+ - v | - +--------+ | +----------------------+ - | Server |<------+--->| ClickHouse 24+ | - +--------+ | | (事件 / 分析) | - ^ | +----------------------+ - API | | - | | +----------------------+ - +-----------+ +- - >| Redis 7+（可选） | - | Dashboard | +----------------------+ + v +--->| PostgreSQL 15+ | + agenteye-collector --HTTP--+ | | (关系型存储) | + | | +----------------------+ + v | + +--------+ | +----------------------+ + | Server |<-----+--->| ClickHouse 24+ | + +--------+ | | (事件 / 分析) | + ^ | +----------------------+ + API | | + | | +----------------------+ + +-----------+ +- - >| Redis 7+（可选） | + | Dashboard | +----------------------+ +-----------+ ``` -- **Server**：Rust HTTP 服务；接收事件批次，将其写入 ClickHouse，并在 PostgreSQL 中维护关系型状态。 -- **Dashboard**：Next.js Web 应用；完全通过服务端 API 进行读写操作。 -- **agenteye-collector**：部署在 agent 机器上，而非服务端主机上。 -- **Postgres 15+**：**必需**。（在多租户版本中从 14 升级而来；org-membership 模式使用了列列表 `ON DELETE SET NULL` 外键，这是 Postgres 15+ 的特性。部署此版本前请先升级 Postgres。）存储 OLTP 状态：`api_keys`、`users`、`sessions`、`evaluation_jobs`（队列）、`dashboards`、`saved_queries`、`otp_codes`，以及多租户表 `orgs`、`org_memberships`、`org_settings`。 -- **ClickHouse 24+**：**必需**。用于存储所有摄入事件的分析型存储。引擎：`ReplacingMergeTree`，按月分区，按 `(session_id, ts, dedup_key)` 排序。服务端通过 `CLICKHOUSE_URL` 连接；内置的 `deploy/base/clickhouse/` 提供了针对单节点的性能调优配置。**多租户要求：** 内置配置启用了 SQL 访问管理 + `users_without_row_policies_can_read_rows=false`，使服务端能够为每个组织创建一个只读 ClickHouse 用户 + 行策略（这是 SQL 编辑器和 AI agent 的引擎级隔离边界）。如果您使用自定义 ClickHouse 配置，请保留这些设置（参见 `deploy/base/clickhouse/configmap.yaml`）。 -- **Redis 7+**：*可选*，用作共享缓存 + 速率限制后端。服务端和控制台均通过 `REDIS_URL` 进行连接。若未配置，两者均会优雅降级至仅使用 Postgres 的路径。详见下方 **Redis（可选缓存）** 部分。 +- **Server**：Rust HTTP 服务，接收事件批次，将其写入 ClickHouse，并在 PostgreSQL 中维护关系型状态。 +- **Dashboard**：Next.js Web 应用，通过服务器 API 进行所有读写操作。 +- **agenteye-collector**：部署在代理机器上，而非服务器主机上。 +- **Postgres 15+**：**必需**。（在多租户版本中从 14 升级；org-membership 模式使用了列列表 `ON DELETE SET NULL` 外键，该特性为 Postgres 15+ 专属。部署此版本前请先升级 Postgres。）存储 OLTP 状态：`api_keys`、`users`、`sessions`、`evaluation_jobs`（队列）、`dashboards`、`saved_queries`、`otp_codes`，以及多租户表 `orgs`、`org_memberships`、`org_settings`。 +- **ClickHouse 24+**：**必需**。所有摄取事件的分析存储引擎。引擎类型：`ReplacingMergeTree`，按月分区，按 `(session_id, ts, dedup_key)` 排序。服务器通过 `CLICKHOUSE_URL` 连接；内置的 `deploy/base/clickhouse/` 附带了针对单节点性能调优的配置。**多租户要求：** 内置配置启用了 SQL 访问管理 + `users_without_row_policies_can_read_rows=false`，以便服务器能够为每个组织创建一个只读 ClickHouse 用户及行策略（这是 SQL 编辑器和 AI 代理的引擎层租户隔离边界）。如果您使用自定义 ClickHouse 配置，请保留这些设置（参见 `deploy/base/clickhouse/configmap.yaml`）。 +- **Redis 7+**：*可选*，用作共享缓存 + 限流后端。服务器和仪表板均通过 `REDIS_URL` 连接。如未配置，两者将优雅降级为仅使用 Postgres 的路径。详见下方 **Redis（可选缓存）** 章节。 --- -## 服务端 +## 服务器 ### 拉取镜像 @@ -48,115 +48,114 @@ echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin docker pull ghcr.io/agenteye-enterprise/server:beta-latest ``` -> 当前构建发布于 `beta-latest` 标签下；`latest` 仅在稳定版发布时使用。生产环境中请固定使用具体的 `:v` 标签；参见[可用镜像标签](#available-image-tags)。 +> 当前构建版本发布于 `beta-latest`；`latest` 仅在稳定版本发布时才会更新。生产环境中请固定使用特定的 `:v` 标签，详见 [可用镜像标签](#available-image-tags)。 ### 环境变量 | 变量 | 是否必需 | 默认值 | 说明 | |---|---|---|---| -| `DATABASE_URL` | 是 | 无 | Postgres DSN。使用 `postgres://` scheme 的标准 libpq 连接字符串格式，支持 `?sslmode=require` 及其他 libpq 参数。密码不得包含 `/`、`+` 或 `=` 字符；请使用 `openssl rand -hex` 生成 URL 安全的密码。 | -| `ADMIN_KEY` | 否 | 无 | 引导管理员 API 密钥。每次启动时以全权限进行 upsert 操作。通过修改该值并重启来轮换密钥。 | -| `LISTEN_ADDR` | 否 | `0.0.0.0:8080` | 绑定的 TCP 地址 | -| `MAX_BODY_BYTES` | 否 | `134217728`（128 MB） | 请求体最大大小 | -| `ADMIN_EMAIL` | 否 | 无 | 引导管理员用户邮箱。每次启动时以全权限进行 upsert 并标记为受保护：无法通过控制台/API 禁用或修改其权限。要轮换引导管理员，修改 `ADMIN_EMAIL` 并重启；新邮箱将被 upsert 为受保护状态，旧邮箱在手动清除数据库记录之前仍保留受保护状态。 | -| `ALLOWED_EMAILS` | 否 | 无（全部阻止） | 允许创建用户和登录的邮箱列表，以逗号分隔。支持精确地址（`user@example.com`）和域名通配符（`*@example.com`）。若未设置，则无法创建或登录任何用户。**仅首次启动时生效**：首次启动时写入默认 org 的允许列表；此后每个 org 的允许列表以 [`//settings`](#operational-settings) 页面为准，修改此环境变量不再生效。 | -| `SMTP_HOST` | 否 | 无 | 用于发送 OTP 邮件的 SMTP 服务器主机名。若未设置，OTP 代码将输出到 stdout。 | +| `DATABASE_URL` | 是 | 无 | Postgres DSN。标准 libpq 连接字符串格式，使用 `postgres://` 协议头。支持 `?sslmode=require` 及其他 libpq 参数。密码中不得包含 `/`、`+` 或 `=`；建议使用 `openssl rand -hex` 生成 URL 安全的密码。 | +| `ADMIN_KEY` | 否 | 无 | 初始管理员 API 密钥。每次启动时以完整权限进行 upsert。更换时修改该值并重启服务即可。 | +| `LISTEN_ADDR` | 否 | `0.0.0.0:8080` | TCP 监听地址 | +| `MAX_BODY_BYTES` | 否 | `134217728`（128 MB） | 最大请求体大小 | +| `ADMIN_EMAIL` | 否 | 无 | 初始管理员用户邮箱。每次启动时以完整权限进行 upsert，并标记为受保护状态：无法通过仪表板或 API 禁用或修改其权限。如需更换初始管理员，修改 `ADMIN_EMAIL` 并重启；新邮箱将被 upsert 为受保护状态，旧邮箱的受保护标记将保留，直至手动在数据库中清除。 | +| `ALLOWED_EMAILS` | 否 | 无（全部阻止） | 允许创建用户和登录的邮箱地址列表（逗号分隔）。支持精确地址（`user@example.com`）和域名通配符（`*@example.com`）。未设置时，无法创建或登录任何用户。**仅首次启动时生效**：首次启动时为默认组织的允许列表设置初始值；此后每个组织的 [`//settings`](#operational-settings) 页面为权威配置来源，修改此环境变量不再生效。 | +| `SMTP_HOST` | 否 | 无 | 用于发送 OTP 邮件的 SMTP 服务器主机名。未设置时，OTP 代码将记录到 stdout。 | | `SMTP_PORT` | 否 | `587` | SMTP 服务器端口 | | `SMTP_USERNAME` | 否 | 无 | SMTP 认证用户名 | | `SMTP_PASSWORD` | 否 | 无 | SMTP 认证密码 | | `SMTP_FROM` | 否 | 无 | OTP 邮件的发件人地址 | -| `SMTP_TLS` | 否 | STARTTLS | 除非明确关闭否则使用 STARTTLS：`false` 或 `0` 表示明文传输（无 TLS）；其他任何值（包括未设置）均启用 STARTTLS。 | -| `DASHBOARD_URL` | 否 | 内置默认值 | 控制台来源地址，用于构建 OTP 邮件魔法链接和告警通知中的事件魔法链接。若未设置，将回退到内置默认值（仅 OTP 会优先使用控制台派生的请求来源）。在分域名部署时请设置此项，以确保邮件和 Slack/事件链接均指向您的控制台。详见下方 **邮件魔法链接 URL**；大多数运营人员无需设置此项。 | -| `SESSION_TTL_SECS` | 否 | `86400`（24 小时） | 控制台会话有效期（秒）。**仅首次启动时生效**：首次部署后可通过 [`//settings`](#operational-settings) 按 org 修改。 | -| `OTP_TTL_SECS` | 否 | `600`（10 分钟） | OTP 代码有效期（秒）。**仅首次启动时生效**：首次部署后可通过 [`//settings`](#operational-settings) 按 org 修改。 | -| `REDIS_URL` | 否 | 无 | 可选的共享缓存 + 速率限制后端，例如 `redis://redis:6379/0`。设置后，服务端将缓存已认证的 API 密钥查找、控制台的 `/models` 聚合数据、会话列表和环境列表分面；同时将 OTP 请求速率限制从 Postgres COUNT 切换为 Redis INCR。若未设置或不可达，服务端将在无缓存模式下运行（OTP 限制回退到 Postgres，其他缓存调用直接访问数据源）。详见下方 **Redis（可选缓存）**。 | -| `CLICKHOUSE_URL` | **是** | 无 | ClickHouse 实例的基础 URL，例如 `http://clickhouse:8123`。服务端每次启动时都会对此数据库应用事件模式，若无法连接 ClickHouse 则拒绝启动。详见下方 **ClickHouse（必需的分析存储）**。 | -| `CLICKHOUSE_DATABASE` | 否 | `agenteye` | ClickHouse 数据库（模式）名称。若不存在，服务端将在启动时创建。 | -| `ORG_CH_SECRET` | 否（单租户）/ **是（多 org）** | 开发默认值 | HMAC 密钥，用于派生每个组织的租户专属 ClickHouse 密码。SQL 编辑器和 AI agent 的 `run_query` 以 org 专属只读 ClickHouse 用户身份执行，其行策略在引擎层面强制租户隔离。单租户部署可使用内置开发默认值正常启动；**在配置第二个 org 之前，您必须设置一个强且稳定的值**，因为 `agenteye-orgctl org create` CLI 拒绝在内置开发默认值下运行。轮换该值会导致所有 org 的 ClickHouse 用户失效，直到下次启动时重新配置（启动时的对账会自动修复这一问题）。请保密此值，并在所有副本中保持一致。Org 配置本身仅限运营人员操作；详见下方 **Organizations（多租户）**。 | -| `DEFAULT_ORG_NAME` | 否 | `Default` | 内置默认 org 的显示名称。**仅首次启动时生效**，且仅在 org 仍保持其初始通用身份时于启动时应用，之后被忽略。一旦通过 `agenteye-orgctl org rename` 重命名 org，重命名结果即为权威值，此环境变量不再生效。 | -| `DEFAULT_ORG_SLUG` | 否 | `default` | 内置默认 org 的 URL slug，即其控制台路径（`//…`）。与 `DEFAULT_ORG_NAME` 相同的仅首次启动/初始状态语义。必须为 1-40 个小写字母数字字符，允许单个内部连字符，且不得为[保留字](#organizations-multi-tenancy)；无效值将被忽略（org 保持 `default`）。允许单租户安装以例如 `/acme` 而非 `/default` 的形式呈现，无需任何部署后 CLI 步骤。 | -| `RUST_LOG` | 否 | `info` | 日志详细程度（`debug`、`warn`、`error`、`agenteye_server=trace`） | -| `EVALUATOR_ENDPOINT` | 否 | 无 | 评估器服务的基础 URL（例如 `http://evaluator:9000`）。若未设置，整个评估流水线为空操作；不写入任何队列行，也不运行任何工作进程。参见[评估套件](/zh/agenteye/evaluation-suite)。 | -| `EVALUATOR_TOKEN` | 否 | 无 | 以 `Authorization: Bearer ` 形式发送给评估器。**必须与评估器服务配置的值相同。** 仅当评估器配置为无 token 时才可选。 | -| `EVALUATOR_WORKERS` | 否 | `2` | 并发数：每个服务端实例中调度评估的工作任务数量。可安全地在多个水平扩展的服务端上运行。 | -| `EVALUATOR_CLAIM_BATCH` | 否 | `4` | 单个工作进程每次轮询时最多认领的评估数量。批次**并发**调度，因此您的评估器端点上的总并发数为 `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`。 | -| `EVALUATOR_POLL_IDLE_SECS` | 否 | `2` | 无待处理任务时工作进程在两次调度尝试之间的休眠时间（秒）。 | -| `EVALUATOR_POLLING_INTERVAL_SECS` | 否 | `10` | 当评估器未返回每响应的 `next_poll_secs` 且未通过 `GET /config` 公布 `default_poll_interval_secs` 时，`GET /evaluate/{id}` 轮询的最终回退周期（秒）。 | -| `EVALUATOR_REQUEST_TIMEOUT_MS` | 否 | `30000` | 每次对评估器 HTTP 请求的超时时间（毫秒）。 | -| `EVALUATOR_MAX_ATTEMPTS` | 否 | `5` | 达到此次数的失败尝试后，评估将被记录为终止的 `error` 状态（若失败均为请求超时，则记录为 `timeout`）。 | -| `EVALUATOR_CONFIG_REFRESH_SECS` | 否 | `300`（5 分钟） | 服务端重新从评估器获取 `GET /config` 的频率。 | -| `EVALUATOR_MAX_POLL_DURATION_SECS` | 否 | `3600`（1 小时） | 会话在轮询队列中可停留的最大实际时间，超时后 AgentEye 将其终止为 `timeout` 状态。防止评估器永久返回 `pending` 的情况。 | -| `ALERT_WORKERS` | 否 | `1` | 并发数：每个服务端实例中评估告警规则的工作任务数量。参见[告警](/zh/agenteye/alerts)。 | -| `ALERT_CLAIM_BATCH` | 否 | `16` | 单个工作进程每次轮询时最多认领的告警数量。 | -| `ALERT_POLL_IDLE_SECS` | 否 | `5` | 队列为空时告警工作进程的休眠时间（秒）。 | -| `ALERT_REQUEST_TIMEOUT_MS` | 否 | `15000` | 每次触发评估的超时时间（ClickHouse 查询 + 出站 channel HTTP）。 | -| `ALERT_MAX_ATTEMPTS` | 否 | `5` | 连续瞬态失败达到此次数后，告警以正常周期重新调度，而非指数退避。 | -| `AUDIT_WORKERS` | 否 | `1` | 并发数：每个服务端实例中执行审计的工作任务数量。参见[审计](/zh/agenteye/audits)。 | -| `AUDIT_CLAIM_BATCH` | 否 | `1` | 单个工作进程每次轮询时最多认领的到期审计数量。由于 agentic 调查是一个长循环，默认值为 1。 | -| `AUDIT_POLL_IDLE_SECS` | 否 | `30` | 无待审计任务时审计工作进程的休眠时间（秒）。 | -| `AUDIT_REQUEST_TIMEOUT_MS` | 否 | `30000` | 每次对 ClickHouse 策略查询的超时时间（毫秒）。 | -| `AUDIT_LLM_TIMEOUT_MS` | 否 | `1440000` | 对 AI 助手服务进行 agentic 调查调用的超时时间。完整的 agent 循环需要数分钟；请将此值设置为**高于** agent 自身的 `AGENTEYE_AUDIT_TIMEOUT_MS`，以便 agent 在服务端放弃之前返回其部分发现结果。 | -| `AUDIT_MAX_ATTEMPTS` | 否 | `5` | 连续瞬态失败达到此次数后，审计以正常周期重新调度，而非指数退避。 | -| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | 否 | — | 审计的 agentic 调查调用 AI 助手的 `agent` 服务，**复用与助手相同的连接**——因此这两个变量也需要在**服务端**上设置（内置的 manifests/compose 已完成此配置）。两者均设置 ⇒ 审计运行 AI 调查；任意一个未设置 ⇒ 审计**仅运行策略**（确定性 SQL 策略检查仍然运行），无论每个审计的 `llm_enabled` 标志如何。agent 还必须配置 LLM——参见 [assistant.md](/zh/agenteye/assistant)。 | - -**AI 助手服务——审计与沙箱设置。** Agentic 调查及其 pod 内 Python 沙箱在 **agent 服务**上调整（而非服务端），所有变量均以 `AGENTEYE_AUDIT_*` 为前缀，均为可选： +| `SMTP_TLS` | 否 | STARTTLS | 除非显式关闭，否则默认使用 STARTTLS：`false` 或 `0` 表示明文传输（无 TLS）；其他任意值（包括未设置）均启用 STARTTLS。 | +| `DASHBOARD_URL` | 否 | 内置默认值 | 仪表板来源地址，用于构建 OTP 邮件魔法链接以及告警通知中的事件魔法链接。未设置时回退到内置默认值（仅对 OTP，还会优先使用仪表板派生的请求来源）。对于拆分域名部署，请设置此项以确保邮件和 Slack/事件链接均指向您的仪表板。详见下方 **邮件魔法链接 URL**；大多数运营者无需设置此项。 | +| `SESSION_TTL_SECS` | 否 | `86400`（24 小时） | 仪表板会话有效期（秒）。**仅首次启动时生效**：首次部署后可通过 [`//settings`](#operational-settings) 按组织编辑。 | +| `OTP_TTL_SECS` | 否 | `600`（10 分钟） | OTP 代码有效期（秒）。**仅首次启动时生效**：首次部署后可通过 [`//settings`](#operational-settings) 按组织编辑。 | +| `REDIS_URL` | 否 | 无 | 可选的共享缓存 + 限流后端，例如 `redis://redis:6379/0`。设置后，服务器将缓存已认证的 API 密钥查询、仪表板的 `/models` 聚合、会话列表以及环境列表 facet；同时将 OTP 请求限流从 Postgres COUNT 切换为 Redis INCR。未设置或无法访问时，服务器在无缓存模式下运行（OTP 限流回退到 Postgres，其他所有缓存调用直接访问数据源）。详见下方 **Redis（可选缓存）**。 | +| `CLICKHOUSE_URL` | **是** | 无 | ClickHouse 实例的基础 URL，例如 `http://clickhouse:8123`。服务器在每次启动时将事件模式应用到此数据库，若无法连接 ClickHouse 则拒绝启动。详见下方 **ClickHouse（必需的分析存储）**。 | +| `CLICKHOUSE_DATABASE` | 否 | `agenteye` | ClickHouse 数据库（模式）名称。如不存在，服务器在启动时自动创建。 | +| `ORG_CH_SECRET` | 否（单租户）/ **是（多组织）** | 开发默认值 | HMAC 密钥，用于派生每个组织的专属 ClickHouse 密码。SQL 编辑器和 AI 代理的 `run_query` 以该组织自己的只读 ClickHouse 用户身份执行，其行策略在引擎层强制实现租户隔离。单租户部署可使用内置开发默认值正常启动；**在创建第二个组织之前，必须设置一个强且稳定的值**，因为 `agenteye-orgctl org create` CLI 拒绝在内置开发默认值下运行。轮换此值会导致每个组织的 ClickHouse 用户失效，直到下次启动时重新配置（启动时的自动协调会修复此问题）。请妥善保管，并在各副本间保持一致。组织配置本身仅限运营者操作；详见下方 **组织（多租户）**。 | +| `DEFAULT_ORG_NAME` | 否 | `Default` | 内置默认组织的显示名称。**仅首次启动时生效**，且仅在该组织仍保持初始迁移后的通用标识时适用，启动后即忽略。一旦通过 `agenteye-orgctl org rename` 重命名该组织，重命名结果为权威值，此环境变量不再生效。 | +| `DEFAULT_ORG_SLUG` | 否 | `default` | 内置默认组织的 URL slug，即仪表板中该组织的路径（`//…`）。与 `DEFAULT_ORG_NAME` 具有相同的仅首次启动/初始状态语义。必须为 1-40 个小写字母数字，允许内部单个连字符，且不得为[保留字](#organizations-multi-tenancy)；无效值将被忽略（组织保持 `default`）。允许单租户安装以如 `/acme` 替代 `/default` 展示，无需任何部署后 CLI 操作。 | +| `RUST_LOG` | 否 | `info` | 日志详细级别（`debug`、`warn`、`error`、`agenteye_server=trace`） | +| `EVALUATOR_ENDPOINT` | 否 | 无 | 评估器服务的基础 URL（例如 `http://evaluator:9000`）。未设置时，整个评估流水线为空操作；不写入任何队列行，也不运行任何 worker。详见 [评估套件](/zh/agenteye/evaluation-suite)。 | +| `EVALUATOR_TOKEN` | 否 | 无 | 作为 `Authorization: Bearer ` 发送给评估器。**必须与评估器服务配置的值相同。** 仅在评估器配置为无 token 时可以省略。 | +| `EVALUATOR_WORKERS` | 否 | `2` | 并发数：每个服务器实例中负责分发评估任务的 worker 数量。在多个水平扩展的服务器上并发运行是安全的。 | +| `EVALUATOR_CLAIM_BATCH` | 否 | `4` | 单个 worker 每次循环认领的最大评估数量。批次**并发**分发，因此评估器端点的总并发为 `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`。 | +| `EVALUATOR_POLL_IDLE_SECS` | 否 | `2` | 无待处理任务时，worker 在两次分发尝试之间的休眠时长。 | +| `EVALUATOR_POLLING_INTERVAL_SECS` | 否 | `10` | 当评估器未在响应中返回 `next_poll_secs`，且未通过 `GET /config` 广播 `default_poll_interval_secs` 时，`GET /evaluate/{id}` 轮询的最终回退周期（秒）。 | +| `EVALUATOR_REQUEST_TIMEOUT_MS` | 否 | `30000` | 对评估器的单次 HTTP 请求超时时间（毫秒）。 | +| `EVALUATOR_MAX_ATTEMPTS` | 否 | `5` | 失败次数达到此值后，评估将被记录为终态 `error`（如果失败原因为请求超时，则记录为 `timeout`）。 | +| `EVALUATOR_CONFIG_REFRESH_SECS` | 否 | `300`（5 分钟） | 服务器重新从评估器获取 `GET /config` 的频率。 | +| `EVALUATOR_MAX_POLL_DURATION_SECS` | 否 | `3600`（1 小时） | 会话在轮询队列中可停留的最长实际时间，超时后 AgentEye 将其终止为 `timeout`。防止评估器永久返回 `pending` 的情况。 | +| `ALERT_WORKERS` | 否 | `1` | 并发数：每个服务器实例中负责评估告警规则的 worker 数量。详见 [告警](/zh/agenteye/alerts)。 | +| `ALERT_CLAIM_BATCH` | 否 | `16` | 单个 worker 每次循环认领的最大告警数量。 | +| `ALERT_POLL_IDLE_SECS` | 否 | `5` | 队列为空时告警 worker 的休眠时长。 | +| `ALERT_REQUEST_TIMEOUT_MS` | 否 | `15000` | 单次触发评估超时时间（ClickHouse 查询 + 出站渠道 HTTP）。 | +| `ALERT_MAX_ATTEMPTS` | 否 | `5` | 连续瞬时失败次数达到此值后，告警按正常周期重新调度，而非指数退避。 | +| `AUDIT_WORKERS` | 否 | `1` | 并发数：每个服务器实例中负责执行审计任务的 worker 数量。详见 [审计](/zh/agenteye/audits)。 | +| `AUDIT_CLAIM_BATCH` | 否 | `1` | 单个 worker 每次循环认领的最大到期审计数量。由于代理式调查是一个长循环，默认值为 1。 | +| `AUDIT_POLL_IDLE_SECS` | 否 | `30` | 无到期审计时审计 worker 的休眠时长。 | +| `AUDIT_REQUEST_TIMEOUT_MS` | 否 | `30000` | 对 ClickHouse 的单次策略查询超时时间（毫秒）。 | +| `AUDIT_LLM_TIMEOUT_MS` | 否 | `1440000` | 代理式调查调用 AI 助手服务的超时时间。完整的代理循环需要数分钟；请将此值设置为**高于**代理自身的 `AGENTEYE_AUDIT_TIMEOUT_MS`，以确保代理在服务器放弃之前能够返回部分发现结果。 | +| `AUDIT_MAX_ATTEMPTS` | 否 | `5` | 连续瞬时失败次数达到此值后，审计按正常周期重新调度，而非指数退避。 | +| `AGENTEYE_AGENT_URL` / `AGENTEYE_AGENT_TOKEN` | 否 | — | 审计的代理式调查调用 AI 助手 `agent` 服务，**复用与助手相同的连接**——因此也需要在**服务器**上设置这两个值（内置的 manifests/compose 已完成此配置）。两者均已设置 ⇒ 审计运行 AI 调查；任一未设置 ⇒ 审计**仅运行策略**（确定性 SQL 策略检查仍然执行），忽略每个审计的 `llm_enabled` 标志。代理还必须配置 LLM——详见 [assistant.md](/zh/agenteye/assistant)。 | + +**AI 助手服务——审计与沙盒设置。** 代理式调查及其 Pod 内 Python 沙盒的调优在 **agent 服务**（而非服务器）上配置，均以 `AGENTEYE_AUDIT_*` 为前缀，均为可选项： | 变量 | 默认值 | 含义 | |---|---|---| -| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | 每次调查的最大 agent 轮次。 | -| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | 单次调查的实际时间（20 分钟）。必须**低于**服务端的 `AUDIT_LLM_TIMEOUT_MS`。 | -| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | 每个 agent pod 的并发调查数（与聊天助手的配额相互独立）。 | -| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | bubblewrap 沙箱的每脚本限制。 | +| `AGENTEYE_AUDIT_MAX_STEPS` | `200` | 每次调查的最大代理轮次。 | +| `AGENTEYE_AUDIT_TIMEOUT_MS` | `1200000` | 单次调查的实际耗时上限（20 分钟）。必须**低于**服务器的 `AUDIT_LLM_TIMEOUT_MS`。 | +| `AGENTEYE_AUDIT_MAX_CONCURRENCY` | `1` | 每个 agent Pod 的并发调查数（与聊天助手的配额相互独立）。 | +| `AGENTEYE_AUDIT_SANDBOX_TIMEOUT_MS` / `_MEM_MB` / `_CPU_SECS` / `_OUTPUT_MAX_BYTES` / `_SCRIPT_MAX_BYTES` | `20000` / `768` / `10` / `64000` / `64000` | bubblewrap 沙盒的单脚本限制。 | -**沙箱平台要求。** 审计代码沙箱在 bubblewrap 容器内运行模型的 Python，需要**非特权用户命名空间**。agent pod 必须允许 `clone()` 标志——在 agent 上设置 `seccompProfile: Unconfined`（k8s）或 `security_opt: [seccomp:unconfined]`（compose）。当节点内核禁用非特权用户命名空间时（例如某些 GKE COS 镜像），沙箱**预检失败，审计器自动降级为仅 SQL 模式**——不报错，只是在 agent 的 `/health` 上显示 `sandbox_available: false`。 +**沙盒平台要求。** 审计代码沙盒在 bubblewrap 隔离环境中运行模型的 Python 代码，需要**非特权用户命名空间**支持。Agent Pod 必须允许 `clone()` 标志——在 agent 上设置 `seccompProfile: Unconfined`（k8s）或 `security_opt: [seccomp:unconfined]`（compose）。在内核禁用非特权用户命名空间的节点上（例如某些 GKE COS 镜像），沙盒**预检失败，审计器自动降级为仅 SQL 模式**——不报错，只是在 agent 的 `/health` 接口中显示 `sandbox_available: false`。 ### 运行 -在环境中设置 `DATABASE_URL` 和 `CLICKHOUSE_URL`（服务端未连接 ClickHouse 时拒绝启动），然后传递给容器： +在您的环境中设置 `DATABASE_URL`，然后传递给容器： ```bash docker run -d --restart unless-stopped \ --name agenteye-server \ -e DATABASE_URL="$DATABASE_URL" \ - -e CLICKHOUSE_URL="$CLICKHOUSE_URL" \ -e ADMIN_KEY="$ADMIN_KEY" \ -p 8080:8080 \ ghcr.io/agenteye-enterprise/server:beta-latest ``` -服务端在启动时自动运行数据库迁移，无需单独的迁移步骤。 +服务器在启动时自动运行数据库迁移，无需单独执行迁移步骤。 ### 健康检查 ``` -GET /health # 存活检查 - 进程启动后始终返回 {"status":"ok"} -GET /ready # 就绪检查 - Postgres + ClickHouse 可达时返回 200，否则返回 503 +GET /health # 存活探针 - 进程启动后始终返回 {"status":"ok"} +GET /ready # 就绪探针 - Postgres + ClickHouse 可达时返回 200，否则返回 503 ``` -无需认证。**存活**探针使用 `/health`，**就绪**/负载均衡器探针使用 `/ready`。`/ready` 检查服务端不可缺少的硬依赖（Postgres + ClickHouse），因此正在运行但无法连接数据库的服务端将被移出轮换并显示为 `NotReady`；Redis 会被报告但不会导致就绪检查失败。在内置 Kubernetes manifests 中，就绪探针已指向 `/ready`，存活探针保持在 `/health`。完整说明（包括 Kubernetes 原生 pod 故障告警到 Slack 的可选功能）参见 [enterprise-docs/health-monitoring.md](/zh/agenteye/health-monitoring)。 +无需认证。使用 `/health` 作为**存活**探针，`/ready` 作为**就绪** / 负载均衡探针。`/ready` 检查服务器不可或缺的硬依赖项（Postgres + ClickHouse），因此正在运行但无法连接数据库的服务器将从轮询中移除并显示为 `NotReady`；Redis 状态会在响应中报告，但不会影响就绪判断。内置的 Kubernetes manifests 中就绪探针已指向 `/ready`，存活探针保持指向 `/health`。完整信息（包括可选的 Kubernetes 原生 Pod 故障告警到 Slack）详见 [enterprise-docs/health-monitoring.md](/zh/agenteye/health-monitoring)。 ### 邮件魔法链接 URL -OTP 登录邮件包含一个一键**打开控制台**的按钮。点击后用户将跳转至 `/login?token=&email=
`；控制台将该组合兑换为会话并重定向到应用，无需手动重新输入代码。服务端通过三个层级来解析用于构建链接的控制台来源地址： +OTP 登录邮件包含一个一键**打开仪表板**的按钮。点击后用户跳转至 `/login?token=&email=
`；仪表板将该组合换取会话并重定向到应用，无需手动输入验证码。服务器按以下三个优先级解析用于构建链接的仪表板来源地址： -1. **`X-AgentEye-Dashboard-Url` 请求头**：由控制台的 `/api/auth/otp/request` 代理从其自身的公开来源自动设置。在同域名部署中（服务端与控制台共享主机，位于一个转发代理请求头的 ingress 之后），**无需任何配置**。 -2. **`DASHBOARD_URL` 环境变量**：如果控制台的访问地址与服务端 OTP 请求端点所见的来源不同（分域名 `api.example.com` / `app.example.com`），或者 ingress 未将公开主机名传递给控制台 pod（导致 `request.nextUrl.origin` 解析为类似 `0.0.0.0:3000` 的通配符地址），请设置此项。示例：`DASHBOARD_URL=https://app.example.com`。 +1. **`X-AgentEye-Dashboard-Url` 请求头**：由仪表板的 `/api/auth/otp/request` 代理从其自身公开来源自动设置。在同源部署中（服务器与仪表板共享一个主机，通过一个转发代理请求头的 ingress 托管），**无需任何配置**。 +2. **`DASHBOARD_URL` 环境变量**：如果您的仪表板与服务器 OTP 请求端点所在来源不同（拆分 `api.example.com` / `app.example.com`），或您的 ingress 未将公开主机传递到仪表板 Pod 中（导致 `request.nextUrl.origin` 解析为类似 `0.0.0.0:3000` 的通配绑定地址），请设置此项。示例：`DASHBOARD_URL=https://app.example.com`。 3. **默认值**：`https://app.befailproof.ai`，仅在以上两者均不存在时使用。 -请求头值会经过验证：仅接受 `https://*` 和本地回环（`http://localhost*`、`http://127.0.0.1*`）来源，通配符绑定地址（`0.0.0.0`、`[::]`）即使带有 `https://` scheme 也会被拒绝。不符合条件的值将回退至第 2 层。 +请求头的值会经过验证：仅接受 `https://*` 和回环地址（`http://localhost*`、`http://127.0.0.1*`）来源，即使使用 `https://` 协议头，通配绑定地址（`0.0.0.0`、`[::]`）也会被拒绝。其他任何值均回退到第 2 级。 -通过单行命令在运行中的集群上设置，无需文件，无需重新构建 kustomize： +在运行中的集群上通过一行命令设置，无需修改文件或重新构建 kustomize： ```bash kubectl set env deployment/server -n agenteye \ DASHBOARD_URL=https://app.example.com ``` -此操作将触发滚动更新；新 pod 在首次请求时读取该值。请注意，此覆盖仅存在于 Deployment 上；后续对 overlay 执行 `kustomize build | kubectl apply` 将清除此设置，除非您将相同的环境变量添加到 overlay 的 `server-env.yaml` 补丁中。 +此操作会触发滚动更新；新 Pod 在首次请求时读取该值。请注意，此覆盖仅保存在 Deployment 上；如果后续再次对 overlay 执行 `kustomize build | kubectl apply`，该值将被清除，除非您将相同的环境变量添加到 overlay 的 `server-env.yaml` patch 中。 --- -## 控制台 +## 仪表板 ### 拉取镜像 @@ -168,14 +167,14 @@ docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest | 变量 | 是否必需 | 默认值 | 说明 | |---|---|---|---| -| `AGENTEYE_SERVER_URL` | 是 | 无 | 服务端的基础 URL，例如 `http://localhost:8080` | -| `AGENTEYE_API_KEY` | 是 | 无 | 控制台用于向服务端认证的 API 密钥。需要全部权限（建议使用管理员密钥）。 | -| `AE_LOG_LEVEL` | 否 | `info` | 服务端日志详细程度：`debug`、`info`、`warn`、`error`。设置为 `debug` 可在诊断问题时查看上游请求/响应行和会话验证追踪。 | -| `AE_LOG_JSON` | 否 | 自动 | `1` 强制 JSON 逐行输出；`0` 强制人类可读输出。未设置时，若 `NODE_ENV=production` 则自动启用 JSON。生产环境推荐使用 JSON 格式，以便通过 `jq` 或日志聚合器解析。 | -| `AE_ANALYTICS_DISABLED` | 否 | 无 | 设置为 `1`/`true` 可禁用控制台的匿名产品使用遥测。详见下方[遥测与隐私](#telemetry--privacy)。 | -| `REDIS_URL` | 否 | 无 | 可选的共享缓存后端，例如 `redis://redis:6379/0`。设置后，控制台在多副本间缓存 `validateSession()` 结果，并为延迟聚合/环境列表代理路由共享 Next.js 获取缓存。若 Redis 可达，边缘侧的 OTP 请求和验证速率限制也使用 Redis（Redis 不可达时开放通行；服务端侧限制是安全保障）。详见下方 **Redis（可选缓存）**。 | -| `AGENTEYE_AGENT_URL` | 否 | 无 | 可选 AI 助手 `agent` 服务的基础 URL，例如 `http://agent:9100`。**不设置则完全隐藏助手**：控制台不显示助手气泡。参见 [enterprise-docs/assistant.md](/zh/agenteye/assistant)。 | -| `AGENTEYE_AGENT_TOKEN` | 否 | 无 | 控制台向 `agent` 服务出示的共享密钥。必须与 agent 上配置的 `AGENTEYE_AGENT_TOKEN` 匹配。参见 [enterprise-docs/assistant.md](/zh/agenteye/assistant)。 | +| `AGENTEYE_SERVER_URL` | 是 | 无 | 服务器的基础 URL，例如 `http://localhost:8080` | +| `AGENTEYE_API_KEY` | 是 | 无 | 仪表板用于向服务器进行身份验证的 API 密钥。需要全部权限（建议使用管理员密钥）。 | +| `AE_LOG_LEVEL` | 否 | `info` | 服务器端日志详细级别：`debug`、`info`、`warn`、`error`。设置为 `debug` 可在诊断问题时查看上游请求/响应行和会话验证追踪。 | +| `AE_LOG_JSON` | 否 | 自动 | `1` 强制使用每行 JSON 输出；`0` 强制使用人类可读输出。未设置时，如果 `NODE_ENV=production` 则自动启用 JSON。生产环境建议使用 JSON，以便通过 `jq` 或日志聚合器进行解析。 | +| `AE_ANALYTICS_DISABLED` | 否 | 无 | 设置为 `1`/`true` 可禁用仪表板的匿名产品使用遥测数据。详见下方 [遥测与隐私](#telemetry--privacy)。 | +| `REDIS_URL` | 否 | 无 | 可选的共享缓存后端，例如 `redis://redis:6379/0`。设置后，仪表板将在各副本间缓存 `validateSession()` 结果，并为延迟聚合/环境列表代理路由共享 Next.js fetch 缓存。边缘侧 OTP 请求和验证限流也会在 Redis 可用时使用（Redis 不可访问时失效开放；服务器端限流为安全保障）。详见下方 **Redis（可选缓存）**。 | +| `AGENTEYE_AGENT_URL` | 否 | 无 | 可选 AI 助手 `agent` 服务的基础 URL，例如 `http://agent:9100`。**不设置则完全隐藏助手**：仪表板中不会显示助手气泡。详见 [enterprise-docs/assistant.md](/zh/agenteye/assistant)。 | +| `AGENTEYE_AGENT_TOKEN` | 否 | 无 | 仪表板向 `agent` 服务出示的共享密钥。必须与 agent 上配置的 `AGENTEYE_AGENT_TOKEN` 一致。详见 [enterprise-docs/assistant.md](/zh/agenteye/assistant)。 | ### 运行 @@ -190,89 +189,89 @@ docker run -d --restart unless-stopped \ ### 遥测与隐私 -控制台向 Exosphere 的分析服务（PostHog）发送**匿名产品使用分析数据**：访问了哪些控制台页面，以及少量 UI 操作（如创建 API 密钥或重新评估会话）。此使用信号用于指导功能优先级排序。 +仪表板会向 Exosphere 的分析服务（PostHog）发送**匿名产品使用分析**数据：包括浏览了哪些仪表板页面，以及少量 UI 操作，例如创建 API 密钥或重新评估会话。这些使用信号用于指导功能优先级决策。 -- **任何 agent、会话或事件数据都不会离开您的基础设施。** 仅报告控制台 UI 使用情况。页面 URL 在发送前会去除标识符，运营人员仅以不透明的内部 ID 标识，绝不使用邮箱。 -- 遥测**默认启用**。若要完全关闭，请在控制台容器上设置 `AE_ANALYTICS_DISABLED=1` 并重启。 -- 分析数据发送到控制台自身的 `/ingest` 路径，由控制台反向代理至 PostHog（`https://us.i.posthog.com`）。保持请求为第一方可防止浏览器广告拦截器屏蔽。**控制台容器**需要能够访问 PostHog 的出站网络；若被阻断，遥测将静默失效，控制台不受影响。 +- **您基础设施中的代理、会话或事件数据绝对不会泄露。** 仅上报仪表板 UI 使用情况。页面 URL 在发送前会去除标识符，运营者仅以内部不透明 ID 标识，绝不使用邮箱。 +- 遥测**默认启用**。如需完全关闭，请在仪表板容器上设置 `AE_ANALYTICS_DISABLED=1` 并重启。 +- 分析数据发送至仪表板自身的 `/ingest` 路径，仪表板将其反向代理至 PostHog（`https://us.i.posthog.com`）。使用第一方请求可避免浏览器广告拦截器拦截。**仪表板容器**需要能够访问 PostHog；如被阻止，遥测静默失效，不影响仪表板正常使用。 --- ## AI 助手（可选） -控制台内置的 AI 助手让您的团队可以用自然语言查询 agent 数据（汇总会话、为 `/queries` 编辑器起草 SQL，以及将已保存的查询转化为控制台图块），无需离开控制台。它以独立的内部 `agent` 容器（基于 Claude Agents SDK）运行，仅控制台可访问，**在您配置 LLM 端点之前保持禁用状态**。 +仪表板内置 AI 助手，让您的团队能够用自然语言查询代理数据（汇总会话、为 `/queries` 编辑器生成 SQL，以及将已保存的查询转换为仪表板图块），无需离开仪表板。它以独立的内部 `agent` 容器运行（基于 Claude Agents SDK），仅供仪表板访问，**在配置 LLM 端点之前保持禁用状态**。 -要启用它，您需要在 `agent` 服务上设置 LLM 连接（通过 `PORTKEY_API_KEY` + 模型目录 slug `AGENTEYE_AGENT_MODEL=@/` 使用 **Portkey**，或通过 `ANTHROPIC_API_KEY` 直连 Anthropic，或通过 `ANTHROPIC_BASE_URL` 使用其他网关，或使用 Bedrock/Vertex），以及一个**专用**数据密钥和与控制台匹配的共享 `AGENTEYE_AGENT_TOKEN`。控制台用户还需要 `agent:use` 权限。 +要启用它，需要在 `agent` 服务上设置：LLM 连接（通过 `PORTKEY_API_KEY` + 模型目录 slug `AGENTEYE_AGENT_MODEL=@/` 使用 **Portkey**，通过 `ANTHROPIC_API_KEY` 直连 Anthropic，通过 `ANTHROPIC_BASE_URL` 使用其他网关，或使用 Bedrock/Vertex）、一个**专用**数据密钥，以及与仪表板匹配的共享 `AGENTEYE_AGENT_TOKEN`。仪表板用户还需要 `agent:use` 权限。 -助手的数据密钥无需手动创建：选择一个随机密钥，在 `agent` 上设置为 `AGENTEYE_API_KEY`，同时在 `server` 上设置为 `AGENT_API_KEY`，服务端将在启动时以固定权限集写入该密钥。其数据访问为只读（`events:read`、`evaluations:read`、`dashboards:read`、`queries:read`），并额外持有需审批的创作权限（`dashboards:write`、`queries:write`、`queries:run`），以便代表用户起草和验证已保存的查询并构建控制台图块；所有 SQL 仍通过 org 的只读 ClickHouse 角色运行，因此这扩展了助手的创作范围，而非其可访问的数据范围。这些权限固定在代码中，无法通过配置扩展。该密钥受保护；无法通过 API 禁用或重新生成，只能通过修改值并重启来轮换。请勿将管理员/控制台密钥复用于此用途。 +助手的数据密钥无需手动创建：选取一个随机密钥，将其设置为 `agent` 上的 `AGENTEYE_API_KEY` **以及** `server` 上的 `AGENT_API_KEY`，服务器将在启动时以固定权限集完成初始化。其数据访问权限为只读（`events:read`、`evaluations:read`、`dashboards:read`、`queries:read`），同时持有需审批才能使用的创作权限（`dashboards:write`、`queries:write`、`queries:run`），允许其代表用户起草和验证已保存的查询并构建仪表板图块；所有 SQL 仍通过组织的只读 ClickHouse 角色运行，因此这拓宽了助手的创作范围，而非数据访问范围。这些权限在代码中固定，无法通过配置扩展。该密钥受到保护，无法通过 API 禁用或重新生成，只能通过修改值并重启来轮换。请勿将管理员/仪表板密钥复用于此用途。 -完整设置、完整的环境变量参考、遥测选项和安全模型详见 **[enterprise-docs/assistant.md](/zh/agenteye/assistant)**。 +完整的设置说明、环境变量参考、遥测选项和安全模型详见 **[enterprise-docs/assistant.md](/zh/agenteye/assistant)**。 --- ## ClickHouse（必需的分析存储） -ClickHouse 在高事件量下保持控制台响应，并允许 `/queries` SQL 编辑器在单一存储中跨事件、评估和会话进行联合查询。它是每个摄入事件、每个终止评估结果以及派生的每会话聚合数据的必需权威存储。PostgreSQL 存储关系型/可变状态表（api_keys、users、otp_codes、evaluation_jobs、dashboards、saved_queries）；分析层存储在 ClickHouse 中，以便控制台的汇总统计和您自己的 SQL 查询可以原生扫描和联合，无需跨数据库往返。服务端未设置 `CLICKHOUSE_URL` 时拒绝启动。 +ClickHouse 在高事件量下保持仪表板响应速度，并允许 `/queries` SQL 编辑器在单一存储中跨事件、评估和会话进行联表查询。它是所有摄取事件、所有终态评估结果以及派生的每会话聚合的必需规范存储。PostgreSQL 存储关系型/可变状态表（api_keys、users、otp_codes、evaluation_jobs、dashboards、saved_queries）；分析层面的数据存储在 ClickHouse 中，以便仪表板的汇总和您自定义的 SQL 查询能够原生扫描和联表，无需跨数据库往返。服务器在未设置 `CLICKHOUSE_URL` 时拒绝启动。 ### 模式 -服务端启动时创建三个 ClickHouse 对象，均为幂等操作（`CREATE IF NOT EXISTS`）： +服务器启动时创建三个 ClickHouse 对象，均为幂等操作（`CREATE IF NOT EXISTS`）： -- **`agenteye.events`**：`ReplacingMergeTree(ingested_at)`，按 `toYYYYMM(ts)` 分区，按 `(session_id, ts, dedup_key)` 排序。重复插入（采集器重试）在合并时折叠为单行；服务端为每个事件计算确定性的 SHA-256 `dedup_key`，确保重试安全。 -- **`agenteye.evaluations`**：`ReplacingMergeTree(ingested_at)`，按 `toYYYYMM(finished_at)` 分区，按 `(session_id, finished_at, dedup_key)` 排序。由评估器流水线在每个终止评估结果时写入一次。与 `events` 相同的去重键模型。 -- **`agenteye.agent_sessions`**：基于 `agenteye.events` 的**视图**，非物理表。每列均为派生列（`started_at = min(ts)`、`last_event_at = max(ts)`、`ended_at = max(if event_type='agent_end', ts, NULL)`、`event_count = count()` 等）。无需每事件 upsert，无需单独回填；视图自动反映 `events` 中的所有内容。 +- **`agenteye.events`**：`ReplacingMergeTree(ingested_at)`，按 `toYYYYMM(ts)` 分区，按 `(session_id, ts, dedup_key)` 排序。重复插入（采集器重试）在合并时折叠为单行；服务器为每个事件计算确定性 SHA-256 `dedup_key`，确保重试安全。 +- **`agenteye.evaluations`**：`ReplacingMergeTree(ingested_at)`，按 `toYYYYMM(finished_at)` 分区，按 `(session_id, finished_at, dedup_key)` 排序。由评估流水线在每个终态评估结果后写入一次。与 `events` 采用相同的去重密钥模型。 +- **`agenteye.agent_sessions`**：基于 `agenteye.events` 的**视图**，非物理表。所有列均为派生列（`started_at = min(ts)`、`last_event_at = max(ts)`、`ended_at = max(if event_type='agent_end', ts, NULL)`、`event_count = count()` 等）。无需每事件 upsert，无需单独回填；视图自动反映 `events` 表中的最新数据。 -为与引用 `analytics.evaluations` / `analytics.sessions` 的已保存查询保持向后兼容，服务端还会创建一个 `analytics` ClickHouse 数据库，其中包含基于 `agenteye.*` 表的视图；`analytics.events`、`analytics.evaluations`、`analytics.agent_sessions`、`analytics.sessions` 均可正常解析。 +为了向后兼容引用 `analytics.evaluations` / `analytics.sessions` 的已保存查询，服务器还创建了一个 `analytics` ClickHouse 数据库，其中包含指向 `agenteye.*` 表的视图；`analytics.events`、`analytics.evaluations`、`analytics.agent_sessions`、`analytics.sessions` 均可正常解析。 ### 配置 -内置的 docker-compose 和 `deploy/base/clickhouse/` 提供了针对 AgentEye 工作负载调优的 ClickHouse 服务： +内置的 docker-compose 和 `deploy/base/clickhouse/` 附带了针对 AgentEye 工作负载调优的 ClickHouse 服务： -- 内置基础 overlay 中申请 2 GiB / 限制 4 GiB 内存（适配小型 POC/预发布节点）；生产客户应覆盖配置——推荐最低配置为 2c / 4Gi 申请，6c / 8Gi 限制。`max_server_memory_usage_to_ram_ratio=0.9` -- 5 GiB 标记缓存 + 8 GiB 未压缩缓存 +- 内置 base overlay 中请求 2 GiB / 限制 4 GiB 内存（适合小型 POC/预发布节点）；生产用户应增大配置——推荐最低配置为 2c / 4Gi 请求，6c / 8Gi 限制。`max_server_memory_usage_to_ram_ratio=0.9` +- 标记缓存 5 GiB + 未压缩缓存 8 GiB - `background_pool_size=16`，`background_merges_mutations_concurrency_ratio=2` - MergeTree：`parts_to_throw_insert=3000`，`parts_to_delay_insert=1500`，`non_replicated_deduplication_window=1000` - `local_io_method=auto`（支持的内核上使用 io_uring） -- `fsync_metadata=0`：可接受，因为使用至少一次摄入 + ReplacingMergeTree 去重 -- `query_log` 启用，TTL 30 天；`query_thread_log` 已移除（高 QPS 下开销较大） -- 用户端查询 `max_execution_time=30` -- StatefulSet 模板中 100 GiB PVC（客户 overlay **应**覆盖为生产环境的快速 SSD 存储类） +- `fsync_metadata=0`：可接受，因为使用至少一次摄取 + ReplacingMergeTree 去重 +- 启用 `query_log`，TTL 30 天；移除 `query_thread_log`（高 QPS 下开销较大） +- 用户侧查询 `max_execution_time=30` +- StatefulSet 模板中 PVC 100 GiB（生产环境中客户 overlay **应**覆盖为高速 SSD 存储类） ### 备份 -您的完整数据集每晚在单个可恢复归档中捕获，因此集群或存储故障后可恢复。ClickHouse 由每日 `agenteye-backup` CronJob 自动备份，该任务在一次运行中同时转储 PostgreSQL 和 ClickHouse。ClickHouse 通过其 HTTP API 读取：`agenteye.events` 和 `agenteye.evaluations` 以 ClickHouse 原生格式转储（视图和行策略由服务端在启动时重新创建，因此表数据即为完整数据），与 Postgres 转储一起打包为单个压缩归档并上传至您的对象存储。 +您的完整数据集每晚备份为一个可恢复的归档文件，因此集群或存储丢失后可以恢复。ClickHouse 由每日 `agenteye-backup` CronJob 自动备份，该任务在一次运行中同时转储 PostgreSQL 和 ClickHouse。ClickHouse 通过其 HTTP API 读取：`agenteye.events` 和 `agenteye.evaluations` 以 ClickHouse 原生格式转储（视图和行策略在服务器启动时重新创建，因此表数据即为完整数据），并与 Postgres 转储一起打包为单个压缩归档文件上传到您的对象存储。 -目标存储桶和云凭证按 overlay 配置。上传配置和恢复步骤详见 [enterprise-docs/kubernetes-deployment.md](/zh/agenteye/kubernetes-deployment) 的**备份**部分。 +目标存储桶和云凭证按 overlay 配置。上传配置和恢复步骤详见 [enterprise-docs/kubernetes-deployment.md](/zh/agenteye/kubernetes-deployment) 中的 **备份** 章节。 --- ## Redis（可选缓存） -Redis 是一个**可选**的共享缓存 + 速率限制后端，由服务端和控制台使用。部署 Redis 并在两个服务上设置 `REDIS_URL` 后： +Redis 是服务器和仪表板使用的**可选**共享缓存 + 限流后端。在两个服务上部署 Redis 并设置 `REDIS_URL` 后： -- **服务端**缓存已认证的 API 密钥查找、`/events/environments` + `/evaluations/environments` 列表、`/events/latency_aggregate` 汇总（控制台轮询的最重查询）、`/sessions` 列表，并将 OTP 请求速率限制从 Postgres `COUNT(*)` 切换为 Redis `INCR + EXPIRE`。 -- **控制台**缓存 `validateSession()` 结果，使典型页面加载发出的 10-20 次已认证 API 调用共享一次上游会话检查。同时在控制台边缘限制 OTP 请求和 OTP 验证的速率。 +- **服务器**缓存已认证的 API 密钥查询、`/events/environments` + `/evaluations/environments` 列表、`/events/latency_aggregate` 汇总（仪表板轮询的最重查询）、`/sessions` 列表，并将 OTP 请求限流从 Postgres `COUNT(*)` 切换为 Redis `INCR + EXPIRE`。 +- **仪表板**缓存 `validateSession()` 结果，使典型页面加载发出的 10-20 次已认证 API 调用共享一次上游会话检查。同时在仪表板边缘限制 OTP 请求和验证频率。 -**两个服务在 Redis 不可达时均会优雅降级。** 每次缓存调用在有限超时内返回 `Err`，调用方回退到数据源（服务端的 Postgres，控制台的上游 Rust 服务端）。OTP 速率限制回退到服务端的 Postgres `COUNT(*)` 路径（安全属性得以保留）；控制台的边缘 OTP 限制开放通行，而服务端侧限制仍然有效。Redis 故障只影响延迟，不影响正确性。 +**两个服务在 Redis 不可访问时均能优雅降级。** 每次缓存调用在有限超时内返回 `Err`，调用方回退到数据源（服务器侧为 Postgres，仪表板侧为上游 Rust 服务器）。OTP 限流回退到服务器上的 Postgres `COUNT(*)` 路径（安全属性得以保持）；仪表板的边缘 OTP 限制失效开放，而服务器端限制依然有效。Redis 故障降低延迟，不影响正确性。 ### 配置 -docker-compose 套件已包含 Redis 服务，并将 `REDIS_URL=redis://redis:6379/0` 注入服务端和控制台。若要使用外部 Redis，将 `REDIS_URL` 设置为您的端点，并从 compose 文件中移除 `redis` 服务。 +docker-compose 套件已包含 Redis 服务，并将 `REDIS_URL=redis://redis:6379/0` 注入服务器和仪表板。如需使用外部 Redis，将 `REDIS_URL` 设置为您的端点地址，并从 compose 文件中移除 `redis` 服务即可。 ### 内存与持久化 -内置 Redis 镜像使用 `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru` 运行。AOF 持久化使缓存在容器重启后存活；`everysec` 是正确的持久性/性能平衡，因为丢失最后一秒的缓存写入是无害的。LRU 淘汰策略控制内存增长。 +内置 Redis 镜像以 `--appendonly yes --appendfsync everysec --maxmemory 256mb --maxmemory-policy allkeys-lru` 运行。AOF 持久化确保缓存在容器重启后仍然存在；`everysec` 是合理的持久性/性能平衡点，因为丢失最后一秒的缓存写入是无害的。LRU 淘汰策略限制内存增长。 -### 何时不部署 Redis +### 何时不应部署 Redis -- 单实例开发/QA 环境。服务端的进程内缓存本身已提供了大部分单副本收益；Redis 增加的是单实例不需要的跨副本共享。 -- 运行额外服务的运营成本超过延迟收益的气隙安装环境。 +- 单实例开发/QA 环境。服务器自身的进程内缓存已能提供大部分单副本收益；Redis 增加的是多副本共享能力，单实例场景并不需要。 +- 运营成本超过延迟收益的气隙安装环境（运维一个额外服务的代价高于延迟优化）。 --- ## Docker Compose（推荐） -`agenteye-enterprise/releases` 仓库中提供了 `docker-compose.yml`。通过单个命令即可启动 Postgres、ClickHouse、Redis、服务端和控制台。 +`docker-compose.yml` 可从 `agenteye-enterprise/releases` 仓库获取，通过单条命令即可启动 Postgres、服务器和仪表板。 ```bash GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \ @@ -286,15 +285,15 @@ cd agenteye ``` # 使用 URL 安全的密码（不含 /、+ 或 = 字符）。 -# 生成命令：openssl rand -hex 24 +# 生成方式：openssl rand -hex 24 POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret -# 控制台认证 +# 仪表板认证 ADMIN_EMAIL=admin@yourcompany.com ALLOWED_EMAILS=*@yourcompany.com -# 用于 OTP 邮件的 SMTP（省略则将 OTP 代码输出到 stdout） +# 用于 OTP 邮件的 SMTP（省略则将 OTP 代码记录到 stdout） # SMTP_HOST=smtp.yourprovider.com # SMTP_PORT=587 # SMTP_USERNAME=your-smtp-user @@ -324,25 +323,25 @@ docker compose down -v ## 运营设置 -以前通过环境变量固定的一小部分运营配置项现在可以从控制台的 **`//settings`** 页面按组织编辑；每个 org 独立配置。修改在数秒内生效，无需重启或重新部署。 +以前通过环境变量固定的少量运营配置项，现在可以在仪表板的 **`//settings`** 页面按组织编辑；每个组织独立配置。更改在数秒内生效，无需重启或重新部署。 -| 设置 | 引导环境变量 | 控制内容 | +| 设置项 | 引导环境变量 | 控制内容 | |---|---|---| -| 允许登录 | `ALLOWED_EMAILS` | 允许接收 OTP 并被添加为用户的邮箱（或 `*@domain.com` 通配符） | -| 默认用户权限 | `DEFAULT_USER_PERMISSIONS` | 管理员打开**+ 新用户**时预选的权限 token，以逗号分隔。每个 token 必须是 [API 密钥权限](/zh/agenteye/api-keys) 中列出的字符串之一。默认为 `standard` 预设：只读访问加上日常待命操作（触发重新评估、运行查询、确认事件、使用助手）。 | -| 会话有效期 | `SESSION_TTL_SECS` | 控制台登录在需要重新认证之前的有效时长。控制台每 5 秒重新检查上游会话，因此在 `//users` 上的权限更新在受影响用户的下次请求时生效，无需重新登录。 | -| 一次性代码有效期 | `OTP_TTL_SECS` | OTP / 魔法链接的可用时长 | -| 告警通知渠道 | `ALERTS_ENABLED_CHANNELS` | 告警调度器允许使用的渠道类型，以逗号分隔：`email`、`slack`、`webhook`。每个告警的具体配置仍在 `//alerts/` 中编辑，但调度器会通过此集合过滤所有出站投递；此处禁用的渠道将以 `skipped_disabled` 审计行短路。`dashboard` 渠道（本地审计插入）始终允许。默认三者全部开启。 | +| 允许登录的邮箱 | `ALLOWED_EMAILS` | 允许接收 OTP 并被添加为用户的邮箱地址（或 `*@domain.com` 通配符） | +| 默认用户权限 | `DEFAULT_USER_PERMISSIONS` | 管理员打开**新建用户**时预选的权限令牌（逗号分隔）。每个令牌必须是 [API 密钥权限](/zh/agenteye/api-keys) 中列出的字符串之一。默认为 `standard` 预设：只读访问权限加上日常值班操作（触发重新评估、运行查询、确认事件、使用助手）。 | +| 会话有效期 | `SESSION_TTL_SECS` | 仪表板登录在需要重新认证之前的有效时长。仪表板每 5 秒重新检查上游会话，因此在 `//users` 上的权限更新将在受影响用户的下次请求时立即生效，无需重新登录。 | +| 一次性验证码有效期 | `OTP_TTL_SECS` | OTP / 魔法链接的可用时长 | +| 告警通知渠道 | `ALERTS_ENABLED_CHANNELS` | 告警分发器被允许使用的渠道类型列表（逗号分隔）：`email`、`slack`、`webhook`。每个告警的配置仍在 `//alerts/` 中编辑，但分发器会通过此集合过滤每次出站投递；在此处禁用的渠道会以 `skipped_disabled` 审计行短路。`dashboard` 渠道（本地审计插入）始终允许。默认全部三项启用。 | ### 引导机制说明 -设置以每个组织为单位存储在 `org_settings` 中。首次启动时，服务端从匹配的环境变量（若未设置则使用合理的默认值）写入默认 org 的缺失行。此后，**存储的值是权威来源，环境变量将被忽略**；后续重启时修改环境变量不会影响已有 org 的值，新增的 org 从默认值开始并自行配置。 +设置按组织存储在 `org_settings` 中。首次启动时，服务器从对应的环境变量（或在环境变量未设置时使用合理的默认值）为默认组织填充缺失的行。此后，**存储的值为权威配置来源，环境变量将被忽略**；后续重启时修改环境变量不会影响已有组织的值，新增组织从默认值开始，自行配置。 这意味着： -- 对于全新部署，按上述方式设置环境变量，默认 org 将在首次启动时读取它们。 -- 若要之后修改某个值，请登录控制台并在 `//settings` 下编辑。修改在数秒内在所有服务端副本上生效；无需重启。 -- 启动日志会记录哪些值已写入以及哪些已存在，方便您确认引导是否生效： +- 对于全新部署，按上述方式设置环境变量，默认组织将在首次启动时读取它们。 +- 如需后续修改某个值，登录仪表板并在 `//settings` 下编辑。更改在数秒内对所有服务器副本生效，无需重启。 +- 启动日志会记录已填充的内容与已有内容，以便确认引导是否生效： ```text INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true @@ -350,53 +349,53 @@ docker compose down -v #### 跨组织的登录语义 -会话和 OTP 是全局于用户的，而非单个 org，因此在登录时有两条规则协调每 org 设置： +会话和 OTP 对用户是全局的，而非绑定到单个组织，因此登录时需要按以下两条规则协调各组织的设置： -- **会话 / OTP 有效期**：用户所属的所有 org 中最严格（最短）的有效期胜出。 -- **允许登录**：规则对每个 org 的允许列表与 org 成员资格取 OR：若任意 org 的允许列表接受用户的邮箱，**或**用户已是任意 org 的成员，则该用户可以请求 OTP。 +- **会话/OTP 有效期**：用户所属所有组织中最严格（最短）的有效期生效。 +- **允许登录的邮箱**：门控规则对所有组织的允许列表与组织成员资格进行 OR 运算：如果任一组织的允许列表接受用户的邮箱，**或**用户已经是任一组织的成员，则该用户可以请求 OTP。 ### 权限 -访问 `//settings` 页面需要两个权限： +访问 `//settings` 页面需要两项权限： - `settings:read`：查看页面和当前值。 -- `settings:write`：保存修改。 +- `settings:write`：保存更改。 -引导管理员用户（从 `ADMIN_EMAIL` 写入）自动获得这两个权限以及所有其他权限。可根据需要在 `//users` 中将其授予其他用户。 +引导管理员用户（从 `ADMIN_EMAIL` 初始化）会自动获得这两项权限以及所有其他权限。如需授予其他用户这些权限，请在 `//users` 中操作。 --- -## Organizations（多租户） +## 组织（多租户） -单个部署可服务于多个隔离的 **organizations**（租户）；每行数据归属于且仅归属于一个 org，隔离在数据库引擎层面强制执行。单租户安装无需进行任何配置；所有数据存储在内置的 `default` org 中。（您可以通过在首次启动前设置 `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG`，或随时使用 `agenteye-orgctl org rename` 重命名，为该 org 设置更友好的名称和 URL slug，例如让其位于 `/acme` 而非 `/default`。） +单个部署可以服务多个相互隔离的**组织**（租户）；每行数据恰好属于一个组织，隔离由数据库引擎在底层强制执行。单租户安装无需任何此处的配置；所有数据存储在内置的 `default` 组织中。（您可以通过在首次启动前设置 `DEFAULT_ORG_NAME` / `DEFAULT_ORG_SLUG`，或随时使用 `agenteye-orgctl org rename` 重命名，为该组织指定更友好的名称和 URL slug，使其路径如 `/acme` 而非 `/default`。） -**租户配置仅限运营人员操作。** Organizations 及其成员资格使用 **`agenteye-orgctl`** CLI 创建和管理，该 CLI **内置于服务端镜像**中（与 `agenteye-server` 并列），**在现有服务端 pod 内**运行；**没有独立的 pod/Job、没有 HTTP API，也没有控制台按钮**。它复用服务端的 `DATABASE_URL`、`CLICKHOUSE_URL` 和 `ORG_CH_SECRET`。 +**租户配置仅限运营者操作。** 组织及其成员资格通过 **`agenteye-orgctl`** CLI 创建和管理，该工具**内置于服务器镜像**中（与 `agenteye-server` 并列），在**现有服务器 Pod 内**运行；**没有独立的 Pod/Job、没有 HTTP API、也没有仪表板按钮**。它复用服务器的 `DATABASE_URL`、`CLICKHOUSE_URL` 和 `ORG_CH_SECRET`。 ```bash -# Docker Compose - 进入运行中的服务端服务： +# Docker Compose - 进入运行中的 server 服务： docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp" docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin -# Kubernetes - 进入运行中的服务端 Deployment： +# Kubernetes - 进入运行中的 server Deployment： kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list ``` -可用命令：`org create | list | rename | delete | purge` 和 `member add | list | update | remove`，内置权限集 `admin`、`standard` 和 `read-only`。添加的成员在首次控制台登录时收到 OTP。 +可用命令：`org create | list | rename | delete | purge` 和 `member add | list | update | remove`，内置权限集 `admin`、`standard` 和 `read-only`。新添加的成员在首次登录仪表板时会收到 OTP。 -**在创建第二个 org 之前：** 设置强且稳定的 `ORG_CH_SECRET`（`org create` 命令拒绝在内置开发默认值下运行），并确保 Postgres 为 **15+** 版本。**未变更：** 每 org 的 API 密钥仍由控制台/API 中的 org 成员创建；只有 org + 成员生命周期移至 CLI。完整命令参考和操作示例详见 **[enterprise-docs/tenant-management.md](/zh/agenteye/tenant-management)**。 +**创建第二个组织之前：** 请设置一个强且稳定的 `ORG_CH_SECRET`（`org create` 命令拒绝在内置开发默认值下运行），并确保 Postgres 为 **15+** 版本。**不变的是：** 每组织的 API 密钥仍由组织成员在仪表板/API 中创建；只有组织和成员的生命周期管理移至 CLI。完整命令参考和示例详见 **[enterprise-docs/tenant-management.md](/zh/agenteye/tenant-management)**。 --- -## 上下文窗口填充 +## 上下文窗口填充率 -每个 `model_response` 事件显示一个**上下文填充标签** — 输入加输出 token 占该模型上下文窗口的百分比。区间为 `healthy`（0–24%）、`watch`（25–49%）、`compacting`（50–74%）和 `reset context`（75–100%）。AgentEye 自动解析常见的模型 ID，因此无需初始配置。 +每个 `model_response` 事件显示一个**上下文填充率标签**——输入加输出 token 数占该模型上下文窗口的百分比。划分区间为：`healthy`（0–24%）、`watch`（25–49%）、`compacting`（50–74%）和 `reset context`（75–100%）。AgentEye 会自动解析常见的模型 ID，因此无需初始配置。 -组织发送的每个模型都会出现在 **Settings → model context windows** 下。拥有 `settings:write` 权限的用户可以覆盖其窗口大小或添加私有/代理模型（0–1,000,000 token）；`0` 表示"未知"，会隐藏标签。修改对新摄入的事件生效。拥有 `settings:read` 权限的用户可以查看列表。 +组织发送过的每个模型都会出现在 **设置 → 模型上下文窗口** 中。具有 `settings:write` 权限的用户可以覆盖其窗口大小，或添加私有/代理模型（0–1,000,000 token）；`0` 表示"未知"并隐藏该标签。更改对新摄取的事件生效。具有 `settings:read` 权限的用户可以查看列表。 -升级后的新事件会立即计算填充值。若要同时为现有部署填充**历史**事件（以及每模型列表），请运行一次性回填命令——它内置于服务端镜像中（与 `agenteye-orgctl` 类似），在现有服务端 pod 中运行： +升级后新事件会立即获得填充率。如需同时为现有部署的**历史**事件（以及每模型列表）填充数据，请运行一次性回填工具——它内置于服务器镜像中（与 `agenteye-orgctl` 类似），在现有服务器 Pod 中运行： ```bash -# 预览（打印每 org 的变更，不实际修改）： +# 预览（打印每组织的变更内容，不实际修改）： kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window --dry-run # 应用： kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window @@ -404,18 +403,18 @@ kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window docker compose exec server agenteye-backfill-context-window ``` -该命令是幂等的（可安全重复运行），并复用 pod 中的 `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL`。如果您编辑了模型窗口后希望重新计算现有事件，请再次运行。 +该工具是幂等的（可安全重复运行），并从 Pod 中复用 `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_URL`。如果您编辑了模型窗口并希望重新计算已有事件，可重新运行此工具。 --- ## 生产注意事项 -- **Postgres**：使用托管的 Postgres 服务或专用实例，并定期备份。`DATABASE_URL` 支持所有标准 libpq 参数，包括用于加密连接的 `sslmode=require`。 -- **TLS**：将服务端和控制台放在终止 TLS 的反向代理（nginx、Caddy、Traefik）之后。 -- **防火墙**：服务端端口（默认 8080）应仅对采集器机器和控制台主机可达，而非公共互联网。 -- **管理员密钥**：将 `ADMIN_KEY` 设置为强随机密钥。引导完成后，为采集器和控制台创建专用的作用域密钥，而非在所有地方使用管理员密钥。 -- **镜像标签**：在生产环境中使用发布 manifests 中固定的版本（例如 `server:v0.0.1-beta.48`），而非浮动标签，以避免意外升级。当前 beta 构建发布于 `beta-latest` 标签下；`latest` 仅在稳定版发布时使用。 -- **健康监控**：在 Kubernetes 上，就绪探针使用 `/ready`（Postgres + ClickHouse 可达性），存活探针保持在 `/health`。若要实现全集群范围内"AgentEye 是否正常运行"的 Slack 告警，请启用可选的 Robusta 插件；参见 [enterprise-docs/health-monitoring.md](/zh/agenteye/health-monitoring)。 +- **Postgres**：使用托管 Postgres 服务或具有定期备份的专用实例。`DATABASE_URL` 支持所有标准 libpq 参数，包括用于加密连接的 `sslmode=require`。 +- **TLS**：在服务器和仪表板前面部署反向代理（nginx、Caddy、Traefik）来终止 TLS。 +- **防火墙**：服务器端口（默认 8080）应仅对采集器机器和仪表板主机开放，不得暴露到公网。 +- **管理员密钥**：将 `ADMIN_KEY` 设置为强随机密钥。完成初始化后，为采集器和仪表板创建专用的有限权限密钥，而不是到处使用管理员密钥。 +- **镜像标签**：生产环境中请固定使用发布 manifests 中指定的版本（例如 `server:v0.0.1-beta.48`），而非浮动标签，以避免意外升级。当前 beta 构建版本发布于 `beta-latest`；`latest` 仅在稳定版本发布时才会更新。 +- **健康监控**：在 Kubernetes 上，就绪探针使用 `/ready`（检查 Postgres + ClickHouse 可达性），存活探针保持使用 `/health`。如需对 AgentEye 整体状态的 Slack 告警，请启用可选的 Robusta 插件；详见 [enterprise-docs/health-monitoring.md](/zh/agenteye/health-monitoring)。 --- @@ -423,6 +422,6 @@ docker compose exec server agenteye-backfill-context-window | 标签 | 说明 | |-----|-------------| -| `latest` | 最新稳定版 | -| `beta-latest` | 最新预发布版（beta） | -| `v` | 固定版本，例如 `v0.0.1-beta.48`（推荐用于生产） | \ No newline at end of file +| `latest` | 最新稳定版本 | +| `beta-latest` | 最新预发布版本（beta） | +| `v` | 固定版本，例如 `v0.0.1-beta.48`（生产环境推荐） | \ No newline at end of file diff --git a/docs/zh/agenteye/getting-started.mdx b/docs/zh/agenteye/getting-started.mdx index 2663911d..53f0ab6a 100644 --- a/docs/zh/agenteye/getting-started.mdx +++ b/docs/zh/agenteye/getting-started.mdx @@ -4,47 +4,47 @@ description: "AgentEye 入门指南文档。" --- -本指南将带您完成 AgentEye 的完整配置流程：部署服务端与控制台、在智能体机器上安装收集器，以及为您的 Python 智能体代码添加埋点。 +本指南将带您完成 AgentEye 的全套配置：部署服务器与控制台、在 Agent 机器上安装采集器，以及在 Python Agent 代码中接入埋点。 --- -## 什么是 AgentEye？ +## AgentEye 是什么？ -AgentEye 是一款**面向 AI 智能体的自托管可观测性与评估平台**。它记录智能体的每一个动作——运行过程中的每一步——并自动对每次已完成的运行质量进行评分，帮助您掌握智能体在生产环境中的行为，在用户发现问题之前提前捕获性能退化。 +AgentEye 是一个**自托管的 AI Agent 可观测性与评估平台**。它会记录 Agent 的每一个动作——运行过程中的每一步——并自动对每次已完成的运行进行质量评分，让您清晰掌握 Agent 在生产环境中的行为表现，在用户发现问题之前率先捕获回归。 -数据按单一方向流动：您的智能体代码通过 **Python SDK** 发送**事件** → 轻量级**收集器**守护进程批量将其上报至**服务端** → 事件与分析数据存储在 **ClickHouse** 中（组织、用户、API 密钥、控制台、保存的查询等运营状态存储在 **Postgres** 中）→ 您在**控制台**中浏览所有数据。 +数据单向流转：您的 Agent 代码通过 **Python SDK** 发出**事件** → 轻量级**采集器**守护进程批量上报至**服务器** → 事件与分析数据存储于 **ClickHouse**（组织、用户、API 密钥、控制台、保存的查询等操作状态存储于 **Postgres**）→ 您在**控制台**中查阅一切。 您将获得： -- **事件** — 每次智能体运行的原始逐步记录（工具调用、模型调用、钩子、错误）。 -- **会话** — 将事件聚合为每次运行一行，每行均经过**自动评估与评分**。 -- **评估** — 由您自己的评估服务生成的质量分数，无需人工审查即可发现质量下滑。 -- **查询与控制台** — 基于 ClickHouse SQL 对数据进行保存查询，并绘制为组织范围内的共享控制台。 -- **告警与事件** — 当指标超过阈值时通知您（邮件、Slack、Webhook、控制台内通知），并提供事件处理工作流。 -- **CLI 与 AI 助手** — 终端客户端（`agenteye`）以及控制台内的助手，支持用自然语言提问。 +- **事件** —— 每次 Agent 运行的原始逐步记录（工具调用、模型调用、钩子、错误）。 +- **会话** —— 将事件汇总为每次运行一行，每行均**自动评估**并打分。 +- **评估** —— 由您自己的评估服务产出的质量评分，无需人工审查即可发现质量下降。 +- **查询与控制台** —— 基于您的数据保存 ClickHouse SQL 查询，并以图表形式呈现在组织级共享控制台中。 +- **告警与事故** —— 阈值规则触发通知（邮件、Slack、Webhook、控制台内），并配有事故处理工作流。 +- **CLI 与 AI 助手** —— 终端客户端（`agenteye`）以及控制台内置助手，支持用自然语言提问。 -所有组件均运行在您自己的基础设施上，可以作为单个 Docker Compose 栈（本指南）、生产级 Kubernetes 安装，或单个同地部署的 Pod。本指南将从头到尾搭建 Compose 栈。 +所有组件均运行在您自己的基础设施中，可以是单个 Docker Compose 栈（本指南）、生产级 Kubernetes 部署，或单一的同置 Pod。本指南将端到端地完成 Compose 栈的搭建。 --- -## 第一步：认证 +## 第一步：身份认证 -所有 AgentEye 制品均通过 `agenteye-enterprise` GitHub 组织分发。作为企业开发者，您可以生成自己的 GitHub PAT。请参阅 [enterprise-docs/github-token.md](/zh/agenteye/github-token) 了解详细步骤和所需权限。 +所有 AgentEye 制品均从 `agenteye-enterprise` GitHub 组织分发。作为企业开发者，您可以生成自己的 GitHub PAT。请按照 [enterprise-docs/github-token.md](/zh/agenteye/github-token) 中的步骤和所需权限进行操作。 ```bash export AGENTEYE_TOKEN= -# Authenticate Docker against GHCR +# 向 GHCR 进行 Docker 身份认证 echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin ``` --- -## 第二步：部署服务端与控制台 +## 第二步：部署服务器与控制台 -服务端接收来自收集器的事件并使其可查询；控制台是您浏览数据的界面。摄入的事件与分析数据存储在 ClickHouse（必需的分析存储）中，Postgres 则保存运营状态，如组织、用户、API 密钥、控制台和保存的查询。 +服务器负责接收来自采集器的事件并使其可查询；控制台是您探索数据的地方。采集的事件与分析数据存储于 ClickHouse（必需的分析存储），而 Postgres 保存组织、用户、API 密钥、控制台和已保存查询等操作状态。 -**下载发布的 Compose 文件：** +**下载已发布的 Compose 文件：** ```bash mkdir -p ./agenteye @@ -55,38 +55,32 @@ curl -fsSL \ cd agenteye ``` -**设置密钥：** +**配置密钥：** -创建 `.env` 文件，确保部署不使用默认的 `admin` 凭据。至少需要设置 `ADMIN_KEY` 和 `POSTGRES_PASSWORD`： +创建一个 `.env` 文件，避免使用默认的 `admin` 凭据运行。至少需要设置 `ADMIN_KEY` 和 `POSTGRES_PASSWORD`： ```bash POSTGRES_PASSWORD=your-db-password ADMIN_KEY=your-admin-secret ``` -同时在当前 Shell 中导出 `ADMIN_KEY`，以便后续步骤（如第三步的 `curl`）可以直接引用： - -```bash -export ADMIN_KEY=your-admin-secret -``` - **启动服务栈：** ```bash docker compose up -d ``` -这将启动完整的服务栈，包括必需的 ClickHouse 分析存储、可选的 Redis 缓存，以及服务端和控制台。服务端启动前 ClickHouse 必须处于健康状态。 +这将启动完整的服务栈，包括必需的 ClickHouse 分析存储、可选的 Redis 缓存，以及服务器和控制台。服务器启动前 ClickHouse 必须处于健康状态。 -服务端现在监听 `http://localhost:8080`，控制台监听 `http://localhost:3000`。 +服务器现在监听 `http://localhost:8080`，控制台监听 `http://localhost:3000`。 如需生产部署（自定义 Postgres、TLS、反向代理），请参阅 [enterprise-docs/deployment.md](/zh/agenteye/deployment)。 --- -## 第三步：为收集器创建 API 密钥 +## 第三步：为采集器创建 API 密钥 -每个收集器使用有范围限制的 API 密钥进行认证。使用第二步中设置的 `ADMIN_KEY` 创建一个： +每个采集器使用一个具有特定权限的 API 密钥进行身份认证。使用第二步中设置的 `ADMIN_KEY` 来创建： ```bash curl -s -X POST http://localhost:8080/keys \ @@ -95,13 +89,13 @@ curl -s -X POST http://localhost:8080/keys \ -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}' ``` -`key` 值由您自行提供，在第四步的收集器配置中使用。完整的密钥管理说明请参阅 [enterprise-docs/api-keys.md](/zh/agenteye/api-keys)。 +`key` 的值由您自行提供，在第四步的采集器配置中使用它。完整的密钥管理请参阅 [enterprise-docs/api-keys.md](/zh/agenteye/api-keys)。 --- -## 第四步：安装收集器 +## 第四步：安装采集器 -在运行 AI 智能体的每台机器上安装收集器守护进程。 +在每台运行 AI Agent 的机器上安装采集器守护进程。 **下载二进制文件（Linux x86_64）：** @@ -114,7 +108,7 @@ chmod +x agenteye-collector-linux-x86_64 sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector ``` -> 上述命令下载的是 **Linux x86_64** 构建版本。如需 macOS（Apple Silicon 或 Intel）、Linux arm64，或 Docker / systemd / launchd 安装方式，请参阅 [collector-installation.md](/zh/agenteye/collector-installation)，其中列出了各平台的下载链接——以上命令安装的是 Linux 二进制文件，无法在其他平台上运行。 +> 此命令下载的是 **Linux x86_64** 构建版本。如需 macOS（Apple Silicon 或 Intel）、Linux arm64，或 Docker / systemd / launchd 安装方式，请参阅 [collector-installation.md](/zh/agenteye/collector-installation)，其中列出了各平台的下载方式——上述命令安装的是 Linux 二进制文件，无法在其他平台运行。 **配置：** @@ -134,19 +128,19 @@ EOF agenteye-collector start ``` -通过一次性刷新验证连通性（排空所有待处理事件后退出）： +使用单次刷新验证连通性（刷新完所有待处理事件后退出）： ```bash agenteye-collector flush ``` -Docker、systemd 和 launchd 的安装说明请参阅 [enterprise-docs/collector-installation.md](/zh/agenteye/collector-installation)。 +Docker、systemd 和 launchd 的安装方式请参阅 [enterprise-docs/collector-installation.md](/zh/agenteye/collector-installation)。 --- ## 第五步：安装 Python SDK -在需要对智能体代码进行埋点的每台机器上，从 GitHub Releases 安装 wheel 包。 +在每台需要对 Agent 代码进行埋点的机器上，从 GitHub Releases 安装 wheel 包。 ```bash VERSION=0.0.1b9 @@ -158,9 +152,9 @@ pip install agenteye-${VERSION}-py3-none-any.whl --- -## 第六步：为您的智能体添加埋点 +## 第六步：为您的 Agent 添加埋点 -在智能体代码中添加事件。最低要求是发送 `agent_start` 和 `agent_end`： +在 Agent 代码中添加事件。至少需要发出 `agent_start` 和 `agent_end`： ```python import agenteye @@ -171,7 +165,7 @@ agenteye.event.agent_start( goal="answer the user query", ) -# your agent logic here +# 您的 Agent 逻辑 agenteye.event.agent_end( session_id="run-001", @@ -180,7 +174,7 @@ agenteye.event.agent_end( ) ``` -事件会被缓冲并每 500 毫秒刷新到 `$AGENTEYE_HOME/events/`（若未设置 `AGENTEYE_HOME`，则写入 `~/.agenteye/events/`）。收集器会自动拉取这些文件。 +事件会被缓冲，并每 500 毫秒刷新到 `$AGENTEYE_HOME/events/`（如果未设置 `AGENTEYE_HOME`，则写入 `~/.agenteye/events/`）。采集器会自动采集这些事件。 完整的事件 API 请参阅 [enterprise-docs/python-sdk.md](/zh/agenteye/python-sdk)。 @@ -192,44 +186,44 @@ agenteye.event.agent_end( ![AgentEye 登录界面，向您的邮箱发送一次性验证码](/agenteye/images/login.png) -登录后，**事件**页面会显示所有已摄入事件的实时流。按 `session_id` 或 `agent_id` 筛选，即可深入查看特定运行。 +登录后，**Events** 页面会实时显示所有已采集事件的流水记录。通过 `session_id` 或 `agent_id` 进行筛选，可深入查看特定的运行详情。 -![实时事件流，按事件类型标色，可按环境、智能体和会话筛选](/agenteye/images/events-stream.png) +![按事件类型着色的实时事件流，支持按环境、Agent 和会话筛选](/agenteye/images/events-stream.png) -**会话**页面将这些事件聚合为每次运行一行。AgentEye 会自动评估已完成的会话，因此每次运行都会被评分，质量退化无需人工审查即可浮现；每行一目了然地显示最新评估分数： +**Sessions** 页面将事件汇总为每次运行一行。AgentEye 会自动评估已完成的会话，每次运行都会被评分，质量回归无需人工审查即可浮现；每行一目了然地显示最新的评估分数： -![会话列表，每次运行一行，带有状态标签和评估分数徽章](/agenteye/images/sessions-list.png) +![会话列表，每次运行一行，附有状态标签和评估分数徽章](/agenteye/images/sessions-list.png) -如需配置会话评分方式，请参阅 [enterprise-docs/evaluation-suite.md](/zh/agenteye/evaluation-suite)。 +如需配置会话的评分方式，请参阅 [enterprise-docs/evaluation-suite.md](/zh/agenteye/evaluation-suite)。 -点击任意会话可查看其**执行图**，这是一个类似 git 的视图，展示智能体、工具、钩子和模型调用随时间的展开过程，并行子智能体各占独立泳道，右侧面板提供单次运行的详细分解： +点击任意会话可打开其**执行图谱**——一个类似 Git 的视图，呈现 Agent、工具、钩子和模型调用随时间展开的全过程，并行子 Agent 拥有独立泳道，右侧面板提供每次运行的详细分解： -![会话的类 git 执行图及其事件时间线，旁边是工具/模型/钩子分解面板](/agenteye/images/session-detail.png) +![会话的 Git 风格执行图谱与事件时间轴并排显示，附工具/模型/钩子分解面板](/agenteye/images/session-detail.png) --- -## 第八步：探索、可视化与告警 +## 第八步：探索、图表与告警 -在事件持续流入后，**分析**页面可将原始活动转化为洞察，帮助您衡量智能体行为、在团队间共享发现，并在出现退化时第一时间收到通知。控制台页面以组织为作用域，因此地址栏中的 URL 均以您的组织 slug 为前缀（`//…`）。 +事件数据流入后，**分析**页面将原始活动转化为洞察，帮助您衡量 Agent 行为、在团队间共享发现，并在出现回归时立即收到通知。控制台页面以组织为范围，地址栏中的 URL 带有您的组织标识前缀（`//…`）。 -- **查询**（`//queries`）：从针对事件和评估数据的可复用查询库中出发（包含内置预设和您自定义的查询）…… +- **查询**（`//queries`）：从已保存的可复用查询库（内置预设及您自定义的查询）开始，涵盖您的事件和评估数据…… -![保存的查询库：可复用查询的网格视图，包含内置预设和自定义查询](/agenteye/images/queries.png) +![已保存查询库：一个可复用查询的网格视图，包含内置预设和自定义查询](/agenteye/images/queries.png) - ……然后在 SQL 编辑器中打开某个查询，进行调整并实时查看运行结果： + ……然后在 SQL 编辑器中打开某个查询进行调整，并即时查看运行结果： -![SQL 查询编辑器正在运行一条保存的查询，左侧为 Schema 侧边栏，右侧为实时结果表格](/agenteye/images/query-lab.png) +![SQL 查询编辑器正在运行已保存的查询，左侧为 Schema 面板，右侧为实时结果表格](/agenteye/images/query-lab.png) -- **控制台**（`//dashboards`）：将查询以折线图、柱状图、面积图或饼图的形式固定为图块，组成在整个组织范围内共享的控制台。 +- **控制台**（`//dashboards`）：将查询以折线图、柱状图、面积图或饼图的形式固定到组织级共享控制台中。 -![由保存的查询构建的控制台：每小时事件数折线图、按类型分类的错误柱状图、延迟面积图和按模型统计的 Token 数](/agenteye/images/dashboard-fleet.png) +![由已保存查询构建的控制台：每小时事件数折线图、按类型分类的错误柱状图、延迟面积图和按模型统计的 Token 用量](/agenteye/images/dashboard-fleet.png) -- **告警**（`//alerts`）：将任何阈值提升为告警规则，通过邮件、Slack、Webhook 或控制台内通知进行提醒。请参阅 [enterprise-docs/alerts.md](/zh/agenteye/alerts)。 +- **告警**（`//alerts`）：将任意阈值条件提升为通知规则，通过邮件、Slack、Webhook 或控制台内推送。请参阅 [enterprise-docs/alerts.md](/zh/agenteye/alerts)。 --- ## 后续步骤 -- [部署](/zh/agenteye/deployment)：为生产环境加固 +- [部署](/zh/agenteye/deployment)：加固生产环境 - [API 密钥](/zh/agenteye/api-keys)：管理访问权限 - [故障排查](/zh/agenteye/troubleshooting)：诊断问题 \ No newline at end of file diff --git a/docs/zh/agenteye/managed-deployment.mdx b/docs/zh/agenteye/managed-deployment.mdx index 846db575..6580fcb3 100644 --- a/docs/zh/agenteye/managed-deployment.mdx +++ b/docs/zh/agenteye/managed-deployment.mdx @@ -4,104 +4,104 @@ description: "AgentEye 在您的 Kubernetes 集群上进行托管部署的文档 --- -AgentEye 是一个面向 AI 和 LLM Agent 的自托管可观测性与评估平台。它捕获 Agent 会话、工具调用、模型请求和错误，将其转化为可搜索的分析数据和评估结果，并在仪表板中展示，同时提供可选的只读 AI 助手。 +AgentEye 是一个面向 AI 和 LLM 智能体的自托管可观测性与评估平台。它能够捕获智能体会话、工具调用、模型请求和错误，将其转化为可搜索的分析数据和评估结果，并通过仪表盘展示，同时提供可选的只读 AI 助手。 -在托管部署模式下，您提供一个专用的 Kubernetes 集群，Exosphere 在其中运行完整平台，代您部署、配置、运维、备份和升级每个组件。您的团队无需自行管理数据库、证书或版本升级，即可获得平台的全部价值（Agent 可见性、分析、评估以及可选的助手）。所有数据始终保留在您的云账户内。 +在托管部署模式下，您提供一个专用 Kubernetes 集群，Exosphere 负责在其中运行完整平台，代表您完成每个组件的部署、配置、运维、备份和升级。您的团队无需自行维护数据库、证书或升级，即可享受平台的全部价值（智能体可见性、分析、评估以及可选助手）。所有数据均保留在您的云账户内。 --- -## 前置条件 +## 前提条件 -- 用于拉取容器镜像和下载制品的 **GitHub PAT**（请参阅 [GitHub Token 设置](/zh/agenteye/github-token)） -- 一个**专用 Kubernetes 集群**（请参阅下方要求） +- 用于拉取容器镜像和下载制品的 **GitHub PAT**（详见 [enterprise-docs/github-token.md](/zh/agenteye/github-token)） +- 一个**专用 Kubernetes 集群**（详见下方要求） - 用于数据库备份的**存储桶** -- **网络连通性**：集群负载均衡器的 443 端口入站访问 +- **网络连通性**：集群负载均衡器的 443 端口需对外开放 --- -## 第一步：部署专用 Kubernetes 集群 +## 第一步：准备专用 Kubernetes 集群 -创建一个专用于 AgentEye 的 Kubernetes 集群。该集群不应与其他工作负载共享，以确保整个平台（应用服务、数据库、分析和缓存）在隔离环境中运行，不影响您现有的基础设施。 +创建一个专用于 AgentEye 的 Kubernetes 集群。该集群不应与其他工作负载共享，以确保完整平台（应用服务、数据库、分析和缓存）在隔离环境中运行，不影响您现有的基础设施。 | 要求 | 详情 | |---|---| -| **发行版** | 任何符合标准的 Kubernetes：EKS、GKE、AKS 或自托管 | +| **发行版** | 任何符合标准的 Kubernetes：EKS、GKE、AKS 或自管理 | | **版本** | 1.27 或更高 | -| **节点池** | 最低配置：**3 个节点，每节点 4 vCPU / 8 GB 内存**（标准通用实例） | -| **存储** | 默认 StorageClass，支持块存储卷（例如 AWS 上的 `gp3`、GCP 上的 `pd-ssd`） | +| **节点池** | 最低配置：**3 个节点，每节点 4 vCPU / 8 GB RAM**（标准通用实例） | +| **存储** | 默认 StorageClass，可供应块存储卷（例如 AWS 的 `gp3`、GCP 的 `pd-ssd`） | | **负载均衡器** | 集群必须能够创建云 LoadBalancer 服务（EKS、GKE、AKS 默认支持） | -> Exosphere 会在集群内安装和管理其余所有组件：Ingress 控制器、TLS 证书、数据库、缓存、监控以及所有应用部署。 +> Exosphere 负责在集群内安装和管理其他所有内容：Ingress 控制器、TLS 证书、数据库、缓存、监控以及所有应用部署。 --- ## 第二步：向 AgentEye 团队授予访问权限 -Exosphere 需要 cluster-admin 权限（或同等范围的 RBAC 权限）来管理命名空间、自定义资源定义、Ingress 控制器和存储供应器。 +Exosphere 需要集群管理员权限（或同等的广泛 RBAC 权限），以管理命名空间、自定义资源定义、Ingress 控制器和存储供应器。 | 要求 | 详情 | |---|---| | **访问方式** | IAM 角色（EKS/GKE 首选）、kubeconfig 或基于 SSO 的访问 | -| **VPN / 跳板机** | 如果 Kubernetes API Server 为私有网络，请为 Exosphere 运维团队提供 VPN 凭证或跳板机访问权限 | +| **VPN / 跳板机** | 如果 Kubernetes API Server 为私有模式，请为 Exosphere 运维团队提供 VPN 凭据或跳板机访问权限 | --- ## 第三步：配置网络连通性 -您的网络团队需要允许集群负载均衡器的 **443 端口**入站流量。部署会运行两个独立的负载均衡器：一个用于事件采集（mTLS 保护），一个用于仪表板： +您的网络团队需要允许集群负载均衡器的 **443 端口**接收入站流量。部署将使用两个独立的负载均衡器：一个用于事件采集（mTLS 保护），另一个用于仪表盘： -| 流量类型 | 来源 | 目标 | 安全措施 | +| 流量类型 | 来源 | 目标 | 安全机制 | |---|---|---|---| -| **事件采集** | 您集群中的 Collector Pod | Ingest LoadBalancer，443 端口 | mTLS（客户端证书）+ API Key | -| **仪表板** | 开发者浏览器 | Dashboard LoadBalancer，443 端口 | 您域名上的 HTTPS，无密码邮件 OTP 登录 | +| **事件采集** | 您集群中的 Collector Pod | 采集 LoadBalancer，443 端口 | mTLS（客户端证书）+ API 密钥 | +| **仪表盘** | 开发者浏览器 | 仪表盘 LoadBalancer，443 端口 | 您域名上的 HTTPS，无密码邮件 OTP 登录 | -Ingest 端点受双向 TLS 保护；Collector 每次请求都必须同时提供有效的客户端证书**和**有效的 API Key。仪表板运行在独立的负载均衡器和主机名上，登录仅限于您加入白名单的邮箱地址/域名。 +采集端点受双向 TLS 保护；每次请求时，Collector 必须同时提供有效的客户端证书**和**有效的 API 密钥。仪表盘运行在独立的负载均衡器和主机名上，登录仅限您白名单中的电子邮件地址/域名。 -**DNS 记录（一次性操作）：** 您需要在自己控制的域名下创建两条 CNAME 记录——一条指向 Ingest 端点，一条指向仪表板（例如 `agenteye.your-company.example`）——均指向 Exosphere 提供的负载均衡器主机名。Exosphere 随后会自动为两个主机名申请公开受信任的 TLS 证书，包括自动续期。 +**DNS 记录（一次性配置）：** 您需要在自己控制的域名下创建两条 CNAME 记录——一条指向采集端点，一条指向仪表盘（例如 `agenteye.your-company.example`）——分别指向 Exosphere 提供的负载均衡器主机名。之后，Exosphere 会自动为两个主机名签发公信 TLS 证书，并自动续期。 -> **关于 80 端口：** 自动证书申请和续期需要通过每个负载均衡器的 80 端口进行 HTTP 验证。如果您的安全策略要求将仪表板负载均衡器限制为企业 IP 段，请提前告知 Exosphere——我们会切换为基于 DNS 的证书验证方式（您需额外添加一条 DNS 记录），确保续期在限制策略下仍能正常工作。 +> **80 端口说明：** 自动证书签发和续期需要通过每个负载均衡器的 80 端口进行 HTTP 验证。如果您的安全策略需要将仪表盘负载均衡器限制在企业 IP 范围内，请提前告知 Exosphere——我们会切换为基于 DNS 的证书验证方式（您需在 DNS 侧额外添加一条记录），以确保受限情况下证书续期仍能正常运行。 -> **出站流量：** 集群节点需要访问互联网，以从 `ghcr.io` 拉取容器镜像。如果您的网络限制出站流量，请将 `ghcr.io` 加入白名单，或将镜像同步至内部镜像仓库。 +> **出站流量：** 集群节点需要访问互联网，以从 `ghcr.io` 拉取容器镜像。如果您的网络限制出站流量，请将 `ghcr.io` 加入白名单，或将镜像同步至您的内部镜像仓库。 --- ## 第四步：提供备份存储桶 -数据库备份存储在您自己拥有的云存储桶中。 +数据库备份存储在您拥有的云存储桶中。 | 要求 | 详情 | |---|---| | **服务** | S3（AWS）、GCS（GCP）或 Azure Blob Storage | -| **访问权限** | 通过 IAM 角色（EKS 上的 IRSA，GKE 上的 Workload Identity）为集群节点授予写入权限，或直接提供凭证 | -| **保留策略** | 您控制存储桶的生命周期策略（保留期限、归档规则）。Exosphere 负责写入备份；保留时长由您决定 | +| **访问权限** | 通过 IAM 角色授予集群节点写入权限（EKS 使用 IRSA，GKE 使用 Workload Identity），或提供凭据 | +| **保留策略** | 您自行控制存储桶的生命周期策略（保留期限、归档规则）。Exosphere 负责写入备份，保留时长由您决定 | -每日执行一次全量备份，将 PostgreSQL（关系型状态数据）和 ClickHouse（事件与评估数据）打包为一个压缩归档文件并上传至您的存储桶。每次升级前也会执行备份。 +每日执行一次全量备份，将 PostgreSQL（关系型状态数据）和 ClickHouse（事件与评估数据）一并打包为压缩归档文件并上传至您的存储桶。每次升级前也会自动执行备份。 --- ## 第五步：指定联系人 -请在您方指定一位负责人或 Slack/Teams 频道，用于处理集群层面的问题：节点健康状态、云账户配额、网络变更等。日常运维无需联系此负责人。 +请提供您方一名负责人或 Slack/Teams 频道，用于处理集群级别的问题：节点健康状况、云账户限制、网络变更等。日常运维无需通过此联系人。 --- -## 我们部署的内容 +## 我们部署的组件 Exosphere 获得集群访问权限后，将为您部署并管理以下组件： | 组件 | 职责 | |---|---| -| **AgentEye Server** | HTTP API，接收来自 Collector 的事件，运行分析，并向仪表板提供数据 | -| **仪表板** | Web 界面，用于查看 Agent 会话、工具调用、模型请求和错误；承载可选的只读 AI 助手 | -| **ClickHouse** | 必需的核心存储，用于存储采集的事件、分析数据和评估结果 | -| **PostgreSQL** | 关系型存储，用于组织、API Key、用户、仪表板和保存的查询 | -| **Redis** | 可选的共享缓存和限流后端；不可用时平台可优雅降级 | +| **AgentEye Server** | HTTP API，接收来自 Collector 的事件、运行分析并向仪表盘提供数据 | +| **Dashboard** | Web 界面，用于查看智能体会话、工具调用、模型请求和错误；托管可选的只读 AI 助手 | +| **ClickHouse** | 必需的规范化存储，用于存储采集的事件、分析数据和评估结果 | +| **PostgreSQL** | 关系型存储，用于组织、API 密钥、用户、仪表盘和已保存查询 | +| **Redis** | 可选的共享缓存和限流后端；即使不可用，平台也能优雅降级 | | **AI 助手（可选）** | 内部只读助手容器；在配置 LLM 端点之前保持禁用状态 | -| **Ingress 控制器** | 两个负载均衡器（一个用于 mTLS 保护的 Ingest，一个用于仪表板），使用公开受信任、自动续期的证书终止 TLS，并在 Ingest 端点上强制执行 mTLS | -| **cert-manager** | 自动化 TLS 证书申请及 mTLS 客户端证书签发 | -| **证书监控** | 定时任务，检查证书到期时间，并在证书临近续期时发送告警（例如发送至 Slack） | +| **Ingress 控制器** | 两个负载均衡器（一个用于 mTLS 保护的采集，一个用于仪表盘），使用公信自动续期证书终止 TLS，并在采集端点强制执行 mTLS | +| **cert-manager** | 自动化 TLS 证书签发和 mTLS 客户端证书颁发 | +| **证书监控** | 定时任务，检查证书到期时间，在证书临近续期时发送告警（例如发送至 Slack） | -托管服务还会运行平台的评估流水线，根据您的评估标准对 Agent 活动进行评分。请参阅 [助手](/zh/agenteye/assistant) 和 [评估套件](/zh/agenteye/evaluation-suite) 了解这些功能的详细介绍。 +托管服务还负责运行平台的评估流水线，根据您的评估标准对智能体活动进行评分。详见 [enterprise-docs/assistant.md](/zh/agenteye/assistant) 和 [enterprise-docs/evaluation-suite.md](/zh/agenteye/evaluation-suite)，了解这些功能的具体能力。 --- @@ -109,63 +109,63 @@ Exosphere 获得集群访问权限后，将为您部署并管理以下组件： 部署完成后，您将收到： -| 内容 | 详情 | +| 项目 | 详情 | |---|---| -| **仪表板 URL** | 您域名下的一个主机名（例如 `https://agenteye.your-company.example`），使用公开受信任、自动续期的 TLS 证书。您只需创建一条指向我们提供的负载均衡器主机名的 CNAME；登录方式为无密码邮件 OTP | -| **Collector 端点** | Ingest 主机名的 `/events` 路径（例如 `https://ingest.your-company.example/events`），受 mTLS 保护 | -| **客户端证书包** | 按集群分发：包含客户端证书、私钥和 CA 证书，以 Kubernetes Secret 清单形式交付。每个集群应用一次即可 | +| **仪表盘 URL** | 您域名下的一个主机名（例如 `https://agenteye.your-company.example`），使用公信自动续期 TLS 证书。您只需创建一条指向我们提供的负载均衡器主机名的 CNAME；登录方式为无密码邮件 OTP | +| **Collector 端点** | 采集主机名的 `/events` 路径（例如 `https://ingest.your-company.example/events`），受 mTLS 保护 | +| **客户端证书包** | 按集群分发：客户端证书、私钥和 CA 证书，以 Kubernetes Secret 清单形式交付。每个集群应用一次即可 | | **GitHub PAT** | 用于下载 Collector 二进制文件和 Python SDK 包 | -| **Collector API Key** | 具有 `events:add` 权限的范围密钥，每个 Collector 部署一个 | +| **Collector API 密钥** | 具有 `events:add` 权限的范围密钥，每个 Collector 部署一个 | | **安装指南** | Collector 和 Python SDK 的分步文档 | --- -## 设置完成后您需要做的事 +## 设置完成后您需要做的事情 -您唯一持续性的工作是在自己的 Agent 机器上，而非 AgentEye 集群： +您唯一的后续工作是在您自己的智能体机器上进行，而非 AgentEye 集群： -1. **在每个运行 AI Agent 的 Kubernetes 集群中安装 Collector**：挂载客户端证书，配置端点 URL 和 API Key。请参阅 [Collector 安装](/zh/agenteye/collector-installation)。 -2. **将 Python SDK 集成到您的 Agent 代码中**。请参阅 [Python SDK](/zh/agenteye/python-sdk)。 -3. **在浏览器中打开仪表板**查看 Agent 活动。 +1. 在每个运行 AI 智能体的 Kubernetes 集群中**安装 Collector**：挂载客户端证书，配置端点 URL 和 API 密钥。详见 [enterprise-docs/collector-installation.md](/zh/agenteye/collector-installation)。 +2. 将 **Python SDK 集成**到您的智能体代码中。详见 [enterprise-docs/python-sdk.md](/zh/agenteye/python-sdk)。 +3. 在浏览器中**打开仪表盘**，查看智能体活动。 -无需进行集群运维、数据库管理、证书续期或版本升级。 +无需进行集群运维、数据库管理、证书续期或升级操作。 --- ## 安全性 -- **数据始终保留在您的云账户中。** 集群、存储和数据库均运行在您的环境内，数据不会离开您的边界。 -- **您掌控访问权限。** 集群在您的账户下。您可以随时审计、监控或撤销 Exosphere 的访问权限。所有操作均通过您的云审计日志（CloudTrail、GCP Audit Logs 等）记录。 -- **事件采集使用 mTLS。** 每次 Collector 请求都需要同时提供有效的客户端证书和 API Key。泄露的 API Key 在没有证书的情况下毫无用处；被盗的证书在没有有效 API Key 的情况下同样无效。 -- **仪表板访问控制。** 仪表板运行在独立的负载均衡器上，与事件采集完全分离，登录方式为无密码邮件 OTP，仅限您白名单内的邮箱地址/域名。负载均衡器上的 IP 来源范围白名单可按需提供；由于自动证书续期需要访问负载均衡器，Exosphere 会将该限制与基于 DNS 的证书验证配对使用，确保续期正常工作。 -- **按集群颁发证书。** 您的每个集群都有独立的客户端证书。若某个集群遭到入侵，可单独吊销该证书，不影响其他集群。 +- **数据始终保留在您的云账户中。** 集群、存储和数据库全部在您的环境中运行，数据不会离开您的边界。 +- **您掌控访问权限。** 集群在您的账户中，您可以随时审计、监控或撤销 Exosphere 的访问权限。所有操作均通过您云平台的审计日志记录（CloudTrail、GCP Audit Logs 等）。 +- **事件采集采用 mTLS。** 每次 Collector 请求都需要同时提供有效的客户端证书和 API 密钥。仅凭泄露的密钥无法访问（没有证书无效）；仅凭窃取的证书也无法访问（没有有效密钥无效）。 +- **仪表盘访问控制。** 仪表盘运行在独立的负载均衡器上，与事件采集分离，登录方式为无密码邮件 OTP，仅限您白名单中的电子邮件地址/域名。如需在负载均衡器上配置 IP 来源范围白名单，可按需申请；由于自动证书续期需要访问负载均衡器，Exosphere 会将此限制与基于 DNS 的证书验证配对使用，以确保续期正常运行。 +- **按集群颁发证书。** 您的每个集群都有独立的客户端证书。若某个集群遭到入侵，该证书可独立撤销，不影响其他集群。 --- -## 部署时间线 +## 部署时间表 | 阶段 | 时长 | 您的参与 | |---|---|---| -| **集群部署** | 1-2 天 | 部署集群并向 Exosphere 授予访问权限 | -| **平台搭建** | 1 天 | 无需参与；Exosphere 安装所有基础设施组件 | -| **应用部署** | 1 天 | 无需参与；Exosphere 部署服务器、仪表板并创建 API Key | +| **集群准备** | 1-2 天 | 准备集群并授予 Exosphere 访问权限 | +| **平台搭建** | 1 天 | 无需参与；Exosphere 负责安装所有基础设施组件 | +| **应用部署** | 1 天 | 无需参与；Exosphere 部署服务端、仪表盘并创建 API 密钥 | | **Collector 上线** | 1-3 天 | 在您的集群中安装 Collector（Exosphere 提供指导） | | **生产磨合期** | 1 周 | 无需参与；Exosphere 负责监控和调优 | -典型总耗时：从启动到生产就绪约 **2 周**。 +从启动到生产就绪，典型总耗时：**约 2 周**。 --- ## 支持 -如有问题，请通过 `support@exosphere.host` 联系 Exosphere。 +如有疑问或问题，请通过 `support@exosphere.host` 联系 Exosphere。 --- -## 下一步 +## 后续步骤 -- [快速入门](/zh/agenteye/getting-started)：端到端操作指南 +- [入门指南](/zh/agenteye/getting-started)：端到端完整流程 - [Collector 安装](/zh/agenteye/collector-installation)：安装和配置 Collector -- [Python SDK](/zh/agenteye/python-sdk)：为您的 Agent 代码添加埋点 -- [API Key](/zh/agenteye/api-keys)：管理访问权限和权限设置 -- [故障排查](/zh/agenteye/troubleshooting)：常见问题与解决方案 \ No newline at end of file +- [Python SDK](/zh/agenteye/python-sdk)：为您的智能体代码添加埋点 +- [API 密钥](/zh/agenteye/api-keys)：管理访问权限和权限配置 +- [故障排查](/zh/agenteye/troubleshooting)：常见问题及解决方案 \ No newline at end of file